UITextEntry
A UIControl which provides an editable text input field. Inherits from UIControl.
Properties
| Property Name | Return Type | Description | Tags |
|---|---|---|---|
text | string | The actual text string to show. | Read-Write, Client-Only |
promptText | string | Text to be displayed in the input box when text is empty. | Read-Write |
isInteractable | boolean | Returns whether the control can interact with the cursor (click, hover, etc). | Read-Write |
fontSize | integer | The font size of the control. | Read-Write |
justification | TextJustify | Determines the horizontal alignment of text. Possible values are: TextJustify.LEFT, TextJustify.RIGHT, and TextJustify.CENTER. | Read-Write |
verticalJustification | TextVerticalJustify | Determines the vertical alignment of text. Possible values are: TextVerticalJustify.TOP, TextVerticalJustify.BOTTOM, TextVerticalJustify.CENTER and TextVerticalJustify.BASELINE. | Read-Write |
isHittable | boolean | When set to true, this control can receive input from the cursor and blocks input to controls behind it. When set to false, the cursor ignores this control and can interact with controls behind it. | Read-Write |
Functions
| Function Name | Return Type | Description | Tags |
|---|---|---|---|
GetFontColor() | Color | Returns the color of the Text. | None |
SetFontColor(Color) | None | Sets the color of the Text. | None |
GetBackgroundColor() | Color | Returns the color of the text's background image. | None |
SetBackgroundColor(Color) | None | Sets the color of the text's background image. | None |
GetHoveredColor() | Color | Returns the color of the text's background image when hovering over it. | None |
SetHoveredColor(Color) | None | Sets the color of the text's background image when hovering over it. | None |
GetFocusedColor() | Color | Returns the color of the text's background image when the text has focus. | None |
SetFocusedColor(Color) | None | Sets the color of the text's background image when the text has focus. | None |
GetDisabledColor() | Color | Returns the color of the text's background image when the control is disabled. | None |
SetDisabledColor(Color) | None | Sets the color of the text's background image when the control is disabled. | None |
GetFontSelectionColor() | Color | Returns the highlight color used when selecting text in the control. | None |
SetFontSelectionColor(Color) | None | Sets the highlight color used when selecting text in the control. | None |
SetFont(string fontId) | None | Sets the text to use the specified font asset. | None |
SetImage(string imageId) | None | Sets the image used as the background for the control. | None |
Focus() | None | Gives keyboard focus to the control. | None |
GetCurrentTouchIndex() | integer | Returns the touch index currently interacting with this control. Returns nil if the control is not currently being interacted with. | Client-Only |
Events
| Event Name | Return Type | Description | Tags |
|---|---|---|---|
textCommittedEvent | Event<UITextEntry, string text> | Fired when the control loses focus and text in the control is committed. | Client-Only |
textChangedEvent | Event<UITextEntry, string text> | Fired when text in the control is changed. | Client-Only |
touchStartedEvent | Event<UITextEntry, Vector2 location, integer touchIndex> | Fired when the player starts touching the control on a touch input device. Parameters are the screen location of the touch and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
touchStoppedEvent | Event<UITextEntry, Vector2 location, integer touchIndex> | Fired when the player stops touching the control on a touch input device. Parameters are the screen location from which the touch was released and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
tappedEvent | Event<UITextEntry, Vector2 location, integer touchIndex> | Fired when the player taps the control on a touch input device. Parameters are the screen location of the tap and the touch index with which the tap was performed. | Client-Only |
flickedEvent | Event<UITextEntry, number angle> | Fired when the player performs a quick flicking gesture on the control on a touch input device. The angle parameter indicates the direction of the flick. 0 indicates a flick to the right. Values increase in degrees counter-clockwise, so 90 indicates a flick straight up, 180 indicates a flick to the left, etc. | Client-Only |
pinchStartedEvent | Event<UITextEntry> | Fired when the player begins a pinching gesture on the control on a touch input device. Input.GetPinchValue() may be polled during the pinch gesture to determine how far the player has pinched. | Client-Only |
pinchStoppedEvent | Event<UITextEntry> | Fired when the player ends a pinching gesture on a touch input device. | Client-Only |
rotateStartedEvent | Event<UITextEntry> | Fired when the player begins a rotating gesture on the control on a touch input device. Input.GetRotateValue() may be polled during the rotate gesture to determine how far the player has rotated. | Client-Only |
rotateStoppedEvent | Event<UITextEntry> | Fired when the player ends a rotating gesture on a touch input device. | Client-Only |
Examples
Example using:
textChangedEvent
textCommittedEvent
In this example, a text box entry has a maximum limit for the amount of characters that can be entered by the player. When that limit is reached, no more characters can be entered. This is a good way to restrict the length of a string that can be entered by the player. For example, limiting the length of a pet name so it doesn't exceed space in user intefaces or storage limits.
-- Client script
-- References to the Text Entry Box and Text counter.
local TEXT_ENTRY_BOX = script:GetCustomProperty("TextEntryBox"):WaitForObject()
local COUNTER = script:GetCustomProperty("Counter"):WaitForObject()
-- Max length allowed for this text entry box.
local maxLength = 20
-- Enable cursor interaction and make visible
UI.SetCanCursorInteractWithUI(true)
UI.SetCursorVisible(true)
-- Update the counter text counter
local function UpdateChars()
COUNTER.text = string.format("%s/%s", string.len(TEXT_ENTRY_BOX.text), maxLength)
end
-- Check the length of the text when the text entry box is updated.
local function CheckLength(obj, text)
local len = string.len(text)
if len > maxLength then
TEXT_ENTRY_BOX.text = string.sub(text, 1, maxLength)
end
UpdateChars()
end
-- Connect text entry events
TEXT_ENTRY_BOX.textChangedEvent:Connect(CheckLength)
TEXT_ENTRY_BOX.textCommittedEvent:Connect(CheckLength)
See also: CoreObject.GetCustomProperty | CoreLua.print | UI.SetCursorVisible | UIText.text | UITextEntry.text
Tutorials
Last update: February 10, 2023