TextBox
TextBox : GuiObject
Overview
키보드로 텍스트를 직접 입력할 수 있는 UI 요소입니다. 닉네임이나 쿠폰 코드처럼 플레이어에게 문자열을 입력받을 때 사용합니다.
입력한 내용은 Text 속성에 저장되며, 입력이 끝난 시점은 FocusLost 이벤트로 알 수 있습니다. 입력 전에 보여 줄 안내 문구는 PlaceholderText 속성으로 지정합니다.
주의사항
TextBox는 클라이언트 환경에서만 제어할 수 있습니다. 서버 Script에서 TextBox 고유의 속성, 메서드, 이벤트에 접근하면 오류가 발생합니다. 입력한 값을 서버에서 사용하려면 RemoteEvent로 전달합니다.
SurfaceGui나 BillboardGui 하위에 있는 TextBox는 입력을 받지 않습니다.
Properties
ClearTextOnFocus
boolean
TextBox에 포커스가 맞춰질 때 기존 Text를 지울지 지정합니다.
기본값은 false입니다. true이면 TextBox를 클릭하거나 CaptureFocus()로 포커스를 얻을 때 Text가 빈 문자열이 됩니다. TextEditable이 false이면 지워지지 않습니다.
Code Samples
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")
TextBox.ClearTextOnFocus = trueCursorPosition
number
텍스트 커서의 위치를 바이트 단위로 지정합니다.
1은 Text의 첫 번째 바이트 앞을 의미하며, 편집 중이 아니면 -1입니다. 한 글자가 여러 바이트인 문자가 포함되면 값이 글자 수와 달라질 수 있으며, 문자 중간에 해당하는 값을 지정하면 가까운 문자 경계로 보정됩니다.
Code Samples
FontFace
Font
TextBox에 표시되는 텍스트와 PlaceholderText에 적용할 폰트를 지정합니다.
폰트 패밀리와 굵기, 기울임 여부를 함께 지정합니다.
Code Samples
LineHeight
number
여러 줄 텍스트의 줄 간격 배율을 지정합니다.
기본값은 1이며, 0에서 3 사이의 값을 사용할 수 있습니다. 범위를 벗어난 값은 가장 가까운 값으로 보정되며, 0이면 줄이 서로 겹쳐 표시됩니다.
Code Samples
LocalizedPlaceholderText
string
현재 클라이언트의 로케일을 기준으로 자동 번역된 PlaceholderText를 나타내는 읽기 전용 속성입니다.
TextBox에서는 AutoLocalize 속성이 Text가 아닌 PlaceholderText에 적용되며, AutoLocalize가 true인 경우에만 번역됩니다.
Code Samples
MultiLine
boolean
TextBox에 여러 줄을 입력할 수 있는지 지정합니다.
기본값은 false입니다. false이면 Enter 키를 누를 때 입력이 끝나고 포커스가 해제됩니다. true이면 Enter 키가 줄바꿈으로 입력되며, FocusLost와 ReturnPressedFromOnScreenKeyboard 이벤트가 발생하지 않습니다.
true로 사용할 때는 입력을 확정할 버튼을 따로 두는 것을 권장합니다. false로 바꿔도 이미 입력된 줄바꿈은 유지됩니다.
Code Samples
PlaceholderColor3
Color3
PlaceholderText의 색상을 지정합니다.
기본값은 (127, 127, 127)입니다.
Code Samples
PlaceholderText
string
Text가 빈 문자열일 때 대신 표시할 안내 문구를 지정합니다.
기본값은 "TextBox"입니다. 색상은 PlaceholderColor3로 지정하며, FontFace, TextSize, TextTransparency는 Text와 같은 값이 적용됩니다.
최대 20,000바이트까지 저장할 수 있으며, 이를 넘는 문자열을 대입하면 오류가 발생하고 기존 값이 유지됩니다.
Code Samples
SelectionStart
number
선택한 텍스트 범위의 시작 위치를 바이트 단위로 지정합니다.
선택한 범위가 없으면 -1이며, 편집이 끝나면 CursorPosition과 함께 -1이 됩니다. CursorPosition과 함께 사용해 선택 범위를 읽거나 지정할 수 있습니다.
Code Samples
Text
string
TextBox에 표시할 텍스트를 지정합니다.
플레이어가 입력한 내용도 이 속성에 저장됩니다. 기본값은 빈 문자열이며, 비어 있는 동안에는 PlaceholderText가 표시됩니다.
최대 20,000바이트까지 저장할 수 있으며, 이를 넘는 문자열을 대입하면 오류가 발생하고 기존 값이 유지됩니다.
Code Samples
TextColor3
Color3
입력한 텍스트에 적용되는 색상을 지정합니다.
기본값은 (0, 0, 0)이며, PlaceholderText의 색상은 PlaceholderColor3로 따로 지정합니다.
Code Samples
TextEditable
boolean
플레이어가 입력으로 Text를 바꿀 수 있는지 지정합니다.
기본값은 true입니다. false이면 포커스를 얻을 수 없어 커서가 표시되지 않고, CaptureFocus()를 호출해도 아무 동작도 하지 않습니다. 기존 텍스트를 선택하거나 스크립트로 Text를 바꾸는 것은 가능합니다.
Code Samples
TextScaled
boolean
텍스트가 TextBox의 전체 영역을 채우도록 자동으로 크기를 조정할지 지정합니다.
true이면 TextSize 값은 무시되고 TextWrapped가 true로 바뀝니다. 다시 false로 바꿔도 TextWrapped는 true로 유지되며, true인 상태에서 TextWrapped를 false로 바꾸면 TextScaled도 false가 됩니다.
Code Samples
TextSize
number
텍스트의 크기를 픽셀 단위로 지정합니다.
기본값은 14이며, 1에서 100 사이의 값을 사용할 수 있습니다. 범위를 벗어난 값은 가장 가까운 값으로 보정됩니다.
Code Samples
TextTransparency
number
텍스트와 PlaceholderText의 투명도를 지정합니다.
0은 완전한 불투명 상태를 의미하고, 1은 전혀 보이지 않는 상태를 의미합니다.
Code Samples
TextWrapped
boolean
텍스트가 TextBox의 폭을 넘을 때 여러 줄로 나누어 표시할지 지정합니다.
줄은 공백 문자를 기준으로 나뉩니다.
Code Samples
TextXAlignment
Enum.TextXAlignment
텍스트가 TextBox 영역에서 왼쪽, 가운데, 오른쪽 중 어디에 배치될지를 지정합니다.
기본값은 Center입니다.
Code Samples
TextYAlignment
Enum.TextYAlignment
텍스트가 TextBox 영역에서 위쪽, 가운데, 아래쪽 중 어디에 배치될지를 지정합니다.
기본값은 Center입니다.
Code Samples
Methods
CaptureFocus
TextBox에 포커스를 맞춰 입력을 시작하는 메서드입니다.
포커스를 얻으면 Focused 이벤트가 발생하며, 다른 TextBox에 포커스가 있었다면 그 TextBox의 포커스가 먼저 해제됩니다. TextEditable이나 Visible이 false인 경우, 또는 비활성화된 ScreenGui 하위에 있는 경우에는 아무 동작도 하지 않습니다.
Parameters
Return
void
Code Samples
IsFocused
TextBox에 포커스가 맞춰져 있는지 반환하는 메서드입니다.
Parameters
Return
boolean
포커스가 맞춰져 있으면 true, 그렇지 않으면 false입니다.
Code Samples
ReleaseFocus
TextBox의 포커스를 해제하는 메서드입니다.
포커스가 해제되면 FocusLost 이벤트가 발생하며, 이때 inputThatCausedFocusLoss는 nil입니다. 포커스가 맞춰져 있지 않으면 아무 동작도 하지 않습니다.
Parameters
boolean InSubmitted
(선택 사항) FocusLost 이벤트의 enterPressed로 전달할 값입니다. 생략하면 false입니다.
Return
void
Code Samples
Events
Focused
TextBox가 포커스를 얻을 때 발생하는 이벤트입니다.
플레이어가 TextBox를 클릭하거나 탭할 때, 또는 CaptureFocus()를 호출할 때 발생합니다.
Parameters
Code Samples
FocusLost
TextBox가 포커스를 잃을 때 발생하는 이벤트입니다.
Enter 키를 눌러 입력을 마치거나, TextBox 바깥을 클릭하거나, ReleaseFocus()를 호출할 때 발생합니다. 입력한 Text를 확인하는 데 주로 사용합니다.
Parameters
boolean enterPressed
Enter 키(모바일은 Return 키)를 눌러 포커스가 해제되었으면 true입니다. ReleaseFocus()로 해제한 경우에는 submitted 값이 전달됩니다.
InputObject inputThatCausedFocusLoss
포커스를 해제한 입력 정보입니다. ReleaseFocus() 또는 다른 TextBox의 CaptureFocus()로 해제된 경우에는 nil입니다.
Code Samples
ReturnPressedFromOnScreenKeyboard
TextBox에 포커스가 맞춰진 상태에서 Enter 키를 누를 때 발생하는 이벤트입니다.
모바일에서는 온스크린 키보드의 Return 키나 완료 키를 누를 때 발생하며, FocusLost 이벤트보다 먼저 발생합니다. MultiLine이 true이면 Enter 키가 줄바꿈으로 입력되므로 발생하지 않습니다.
Parameters
Code Samples
See also
GUIInputObjectLast updated