> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/textbox.md).

# 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

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.ClearTextOnFocus = true
```

### CursorPosition

`number`

텍스트 커서의 위치를 바이트 단위로 지정합니다.

1은 Text의 첫 번째 바이트 앞을 의미하며, 편집 중이 아니면 -1입니다. 한 글자가 여러 바이트인 문자가 포함되면 값이 글자 수와 달라질 수 있으며, 문자 중간에 해당하는 값을 지정하면 가까운 문자 경계로 보정됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    TextBox.CursorPosition = #TextBox.Text + 1
end
TextBox.Focused:Connect(OnFocused)
```

### FontFace

`Font`

TextBox에 표시되는 텍스트와 PlaceholderText에 적용할 폰트를 지정합니다.

폰트 패밀리와 굵기, 기울임 여부를 함께 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.FontFace = Font.fromName("Fredoka", Enum.FontWeight.Bold, Enum.FontStyle.Normal)
```

### LineHeight

`number`

여러 줄 텍스트의 줄 간격 배율을 지정합니다.

기본값은 1이며, 0에서 3 사이의 값을 사용할 수 있습니다. 범위를 벗어난 값은 가장 가까운 값으로 보정되며, 0이면 줄이 서로 겹쳐 표시됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.LineHeight = 1.5
```

### LocalizedPlaceholderText

`string`

현재 클라이언트의 로케일을 기준으로 자동 번역된 PlaceholderText를 나타내는 읽기 전용 속성입니다.

TextBox에서는 AutoLocalize 속성이 Text가 아닌 PlaceholderText에 적용되며, AutoLocalize가 true인 경우에만 번역됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

print(TextBox.LocalizedPlaceholderText)
```

### MultiLine

`boolean`

TextBox에 여러 줄을 입력할 수 있는지 지정합니다.

기본값은 false입니다. false이면 Enter 키를 누를 때 입력이 끝나고 포커스가 해제됩니다. true이면 Enter 키가 줄바꿈으로 입력되며, FocusLost와 ReturnPressedFromOnScreenKeyboard 이벤트가 발생하지 않습니다.

true로 사용할 때는 입력을 확정할 버튼을 따로 두는 것을 권장합니다. false로 바꿔도 이미 입력된 줄바꿈은 유지됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.MultiLine = true
```

### PlaceholderColor3

`Color3`

PlaceholderText의 색상을 지정합니다.

기본값은 (127, 127, 127)입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.PlaceholderColor3 = Color3.fromRGB(180, 180, 180)
```

### PlaceholderText

`string`

Text가 빈 문자열일 때 대신 표시할 안내 문구를 지정합니다.

기본값은 "TextBox"입니다. 색상은 PlaceholderColor3로 지정하며, FontFace, TextSize, TextTransparency는 Text와 같은 값이 적용됩니다.

최대 20,000바이트까지 저장할 수 있으며, 이를 넘는 문자열을 대입하면 오류가 발생하고 기존 값이 유지됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.PlaceholderText = "Enter your nickname"
```

### SelectionStart

`number`

선택한 텍스트 범위의 시작 위치를 바이트 단위로 지정합니다.

선택한 범위가 없으면 -1이며, 편집이 끝나면 CursorPosition과 함께 -1이 됩니다. CursorPosition과 함께 사용해 선택 범위를 읽거나 지정할 수 있습니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    TextBox.SelectionStart = 1
    TextBox.CursorPosition = #TextBox.Text + 1
end
TextBox.Focused:Connect(OnFocused)
```

### Text

`string`

TextBox에 표시할 텍스트를 지정합니다.

플레이어가 입력한 내용도 이 속성에 저장됩니다. 기본값은 빈 문자열이며, 비어 있는 동안에는 PlaceholderText가 표시됩니다.

최대 20,000바이트까지 저장할 수 있으며, 이를 넘는 문자열을 대입하면 오류가 발생하고 기존 값이 유지됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.Text = "Player"
```

### TextColor3

`Color3`

입력한 텍스트에 적용되는 색상을 지정합니다.

기본값은 (0, 0, 0)이며, PlaceholderText의 색상은 PlaceholderColor3로 따로 지정합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextColor3 = Color3.fromRGB(255, 255, 255)
```

### TextEditable

`boolean`

플레이어가 입력으로 Text를 바꿀 수 있는지 지정합니다.

기본값은 true입니다. false이면 포커스를 얻을 수 없어 커서가 표시되지 않고, CaptureFocus()를 호출해도 아무 동작도 하지 않습니다. 기존 텍스트를 선택하거나 스크립트로 Text를 바꾸는 것은 가능합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextEditable = false
```

### TextScaled

`boolean`

텍스트가 TextBox의 전체 영역을 채우도록 자동으로 크기를 조정할지 지정합니다.

true이면 TextSize 값은 무시되고 TextWrapped가 true로 바뀝니다. 다시 false로 바꿔도 TextWrapped는 true로 유지되며, true인 상태에서 TextWrapped를 false로 바꾸면 TextScaled도 false가 됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextScaled = true
```

### TextSize

`number`

텍스트의 크기를 픽셀 단위로 지정합니다.

기본값은 14이며, 1에서 100 사이의 값을 사용할 수 있습니다. 범위를 벗어난 값은 가장 가까운 값으로 보정됩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextSize = 24
```

### TextTransparency

`number`

텍스트와 PlaceholderText의 투명도를 지정합니다.

0은 완전한 불투명 상태를 의미하고, 1은 전혀 보이지 않는 상태를 의미합니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextTransparency = 0.5
```

### TextWrapped

`boolean`

텍스트가 TextBox의 폭을 넘을 때 여러 줄로 나누어 표시할지 지정합니다.

줄은 공백 문자를 기준으로 나뉩니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextWrapped = true
```

### TextXAlignment

`Enum.TextXAlignment`

텍스트가 TextBox 영역에서 왼쪽, 가운데, 오른쪽 중 어디에 배치될지를 지정합니다.

기본값은 Center입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextXAlignment = Enum.TextXAlignment.Left
```

### TextYAlignment

`Enum.TextYAlignment`

텍스트가 TextBox 영역에서 위쪽, 가운데, 아래쪽 중 어디에 배치될지를 지정합니다.

기본값은 Center입니다.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextYAlignment = Enum.TextYAlignment.Top
```

## Methods

### CaptureFocus

TextBox에 포커스를 맞춰 입력을 시작하는 메서드입니다.

포커스를 얻으면 Focused 이벤트가 발생하며, 다른 TextBox에 포커스가 있었다면 그 TextBox의 포커스가 먼저 해제됩니다. TextEditable이나 Visible이 false인 경우, 또는 비활성화된 ScreenGui 하위에 있는 경우에는 아무 동작도 하지 않습니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox:CaptureFocus()
```

### IsFocused

TextBox에 포커스가 맞춰져 있는지 반환하는 메서드입니다.

#### Parameters

#### Return

| `boolean` | 포커스가 맞춰져 있으면 true, 그렇지 않으면 false입니다. |
| --------- | ------------------------------------ |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local IsFocused = TextBox:IsFocused()
print("IsFocused : ", IsFocused)
```

### ReleaseFocus

TextBox의 포커스를 해제하는 메서드입니다.

포커스가 해제되면 FocusLost 이벤트가 발생하며, 이때 inputThatCausedFocusLoss는 nil입니다. 포커스가 맞춰져 있지 않으면 아무 동작도 하지 않습니다.

#### Parameters

| `boolean` InSubmitted | (선택 사항) FocusLost 이벤트의 enterPressed로 전달할 값입니다. 생략하면 false입니다. |
| --------------------- | ------------------------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local Submitted = true
TextBox:ReleaseFocus(Submitted)
```

## Events

### Focused

TextBox가 포커스를 얻을 때 발생하는 이벤트입니다.

플레이어가 TextBox를 클릭하거나 탭할 때, 또는 CaptureFocus()를 호출할 때 발생합니다.

#### Parameters

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    print("Focused")
end
TextBox.Focused:Connect(OnFocused)
```

### FocusLost

TextBox가 포커스를 잃을 때 발생하는 이벤트입니다.

Enter 키를 눌러 입력을 마치거나, TextBox 바깥을 클릭하거나, ReleaseFocus()를 호출할 때 발생합니다. 입력한 Text를 확인하는 데 주로 사용합니다.

#### Parameters

| `boolean` enterPressed                 | Enter 키(모바일은 Return 키)를 눌러 포커스가 해제되었으면 true입니다. ReleaseFocus()로 해제한 경우에는 submitted 값이 전달됩니다. |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| `InputObject` inputThatCausedFocusLoss | 포커스를 해제한 입력 정보입니다. ReleaseFocus() 또는 다른 TextBox의 CaptureFocus()로 해제된 경우에는 nil입니다.            |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocusLost(enterPressed, inputThatCausedFocusLoss)
    if enterPressed then
        print("Submitted : ", TextBox.Text)
    end
end
TextBox.FocusLost:Connect(OnFocusLost)
```

### ReturnPressedFromOnScreenKeyboard

TextBox에 포커스가 맞춰진 상태에서 Enter 키를 누를 때 발생하는 이벤트입니다.

모바일에서는 온스크린 키보드의 Return 키나 완료 키를 누를 때 발생하며, FocusLost 이벤트보다 먼저 발생합니다. MultiLine이 true이면 Enter 키가 줄바꿈으로 입력되므로 발생하지 않습니다.

#### Parameters

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnReturnPressed()
    print("ReturnPressedFromOnScreenKeyboard")
end
TextBox.ReturnPressedFromOnScreenKeyboard:Connect(OnReturnPressed)
```

## See also

{% content-ref url="/pages/K1g0tEWDJhh6a6E4UURk" %}
[GUI](https://docs.overdare.com/korean/manual/studio-manual/gui.md)
{% endcontent-ref %}

{% content-ref url="/pages/LYv0TpZ6tsx68rvMhJug" %}
[InputObject](https://docs.overdare.com/korean/development/api-reference/classes/inputobject.md)
{% endcontent-ref %}
