EditBoxes are used to allow the player to type text into a UI component. They inherit from FontInstance as well as Frame in order to provide the needed support for text display, and add methods for entering text, such as positioning a cursor within text, establishing character limits, controlling whether text should be displayed in password-fashion (with bullets substituted for the characters), manipulating an entry history, or controlling and responding to changes in keyboard focus.
The most common use for an EditBox is to accept chat input from the player, but they are also used for commands, configuration, and confirmation, such as requiring you to type "DELETE" before destroying a valuable item, or entering the name of a new macro.
Most EditBoxes are derived from ChatFrameEditBoxTemplate, or use the same textures to create a visible frame around the editable area.
Defined Methods
- EditBox:AddHistoryLine("text") - Adds a line of text to the edit box's stored history
- EditBox:ClearFocus() - Releases keyboard input focus from the edit box
- enabled = EditBox:GetAltArrowKeyMode() - Returns whether arrow keys are ignored by the edit box unless the Alt key is held
- duration = EditBox:GetBlinkSpeed() - Returns the rate at which the text insertion blinks when the edit box is focused
- position = EditBox:GetCursorPosition() - Returns the current cursor position inside edit box
- count = EditBox:GetHistoryLines() - Returns the maximum number of history lines stored by the edit box
- indent = EditBox:GetIndentedWordWrap() - Returns whether long lines of text are indented when wrapping
- language = EditBox:GetInputLanguage() - Returns the currently selected keyboard input language (character set / input method)
- maxBytes = EditBox:GetMaxBytes() - Returns the maximum number of bytes of text allowed in the edit box
- maxLetters = EditBox:GetMaxLetters() - Returns the maximum number of text characters allowed in the edit box
- numLetters = EditBox:GetNumLetters() - Returns the number of text characters in the edit box
- num = EditBox:GetNumber() - Returns the contents of the edit box as a number
- text = EditBox:GetText() - Returns the edit box's text contents
- left, right, top, bottom = EditBox:GetTextInsets() - Returns the insets from the edit box's edges which determine its interactive text area
- position = EditBox:GetUTF8CursorPosition() - Returns the cursor's numeric position in the edit box, taking UTF-8 multi-byte character into account
- enabled = EditBox:HasFocus() - Returns whether the edit box is currently focused for keyboard input
- EditBox:HighlightText([start [, end]]) - Selects all or a portion of the text in the edit box
- EditBox:Insert("text") - Inserts text into the edit box at the current cursor position
- enabled = EditBox:IsAutoFocus() - Returns whether the edit box automatically acquires keyboard input focus
- EditBox:IsCountInvisibleLetters() - This function is not yet documented
- enabled = EditBox:IsInIMECompositionMode() - Returns whether the edit box is in Input Method Editor composition mode
- multiLine = EditBox:IsMultiLine() - Returns whether the edit box shows more than one line of text
- enabled = EditBox:IsNumeric() - Returns whether the edit box only accepts numeric input
- enabled = EditBox:IsPassword() - Returns whether the text entered in the edit box is masked
- EditBox:SetAltArrowKeyMode(enable) - Sets whether arrow keys are ignored by the edit box unless the Alt key is held
- EditBox:SetAutoFocus(enable) - Sets whether the edit box automatically acquires keyboard input focus
- EditBox:SetBlinkSpeed(duration) - Sets the rate at which the text insertion blinks when the edit box is focused
- EditBox:SetCountInvisibleLetters() - This function is not yet documented
- EditBox:SetCursorPosition(position) - Sets the cursor position in the edit box
- EditBox:SetFocus() - Focuses the edit box for keyboard input
- EditBox:SetHistoryLines(count) - Sets the maximum number of history lines stored by the edit box
- EditBox:SetIndentedWordWrap(indent) - Sets whether long lines of text are indented when wrapping
- EditBox:SetMaxBytes(maxBytes) - Sets the maximum number of bytes of text allowed in the edit box
- EditBox:SetMaxLetters(maxLetters) - Sets the maximum number of text characters allowed in the edit box
- EditBox:SetMultiLine(multiLine) - Sets whether the edit box shows more than one line of text
- EditBox:SetNumber(num) - Sets the contents of the edit box to a number
- EditBox:SetNumeric(enable) - Sets whether the edit box only accepts numeric input
- EditBox:SetPassword(enable) - Sets whether the text entered in the edit box is masked
- EditBox:SetText("text") - Sets the edit box's text contents
- EditBox:SetTextInsets(left, right, top, bottom) - Sets the insets from the edit box's edges which determine its interactive text area
- EditBox:ToggleInputLanguage() - Switches the edit box's language input mode
Inherited Methods
- EditBox:AllowAttributeChanges() - Temporarily allows insecure code to modify the frame's attributes during combat
- enabled = EditBox:CanChangeAttribute() - Returns whether secure frame attributes can currently be changed
- canChange = EditBox:CanChangeProtectedState() - Returns whether protected properties of the region can be changed by non-secure scripts
- EditBox:ClearAllPoints() - Removes all anchor points from the region
- animationGroup = EditBox:CreateAnimationGroup(["name" [, "inheritsFrom"]]) - Creates a new AnimationGroup as a child of the region
- fontstring = EditBox:CreateFontString(["name" [, "layer" [, "inherits"]]]) - Creates a new [[docs/widgets/FontString|`FontString`]] as a child of the frame
- texture = EditBox:CreateTexture(["name" [, "layer" [, "inherits"]]]) - Creates a new [[docs/widgets/Texture|`Texture`]] as a child of the frame
- region = EditBox:CreateTitleRegion() - Creates a title region for dragging the frame
- EditBox:DisableDrawLayer("layer") - Prevents display of all child objects of the frame on a specified graphics layer
- EditBox:EnableDrawLayer("layer") - Allows display of all child objects of the frame on a specified graphics layer
- EditBox:EnableJoystick(enable) - Enables or disables joystick interactivity
- EditBox:EnableKeyboard(enable) - Enables or disables keyboard interactivity for the frame
- EditBox:EnableMouse(enable) - Enables or disables mouse interactivity for the frame
- EditBox:EnableMouseWheel(enable) - Enables or disables mouse wheel interactivity for the frame
- alpha = EditBox:GetAlpha() - Returns the opacity of the region relative to its parent
- ... = EditBox:GetAnimationGroups() - Returns a list of animation groups belonging to the region
- value = EditBox:GetAttribute("name") - Returns the value of a secure frame attribute
- backdrop = EditBox:GetBackdrop() - Returns information about the frame's backdrop graphic
- red, green, blue, alpha = EditBox:GetBackdropBorderColor() - Returns the shading color for the frame's border graphic
- red, green, blue, alpha = EditBox:GetBackdropColor() - Returns the shading color for the frame's background graphic
- bottom = EditBox:GetBottom() - Returns the distance from the bottom of the screen to the bottom of the region
- left, bottom, width, height = EditBox:GetBoundsRect() - Returns the position and dimension of the smallest area enclosing the frame and its children
- x, y = EditBox:GetCenter() - Returns the screen coordinates of the region's center
- ... = EditBox:GetChildren() - Returns a list of child frames of the frame
- left, right, top, bottom = EditBox:GetClampRectInsets() - Returns offsets from the frame's edges used when limiting user movement or resizing of the frame
- depth = EditBox:GetDepth() - Returns the 3D depth of the frame (for stereoscopic 3D setups)
- alpha = EditBox:GetEffectiveAlpha() - Returns the overall opacity of the frame
- depth = EditBox:GetEffectiveDepth() - Returns the overall 3D depth of the frame (for stereoscopic 3D configurations)
- scale = EditBox:GetEffectiveScale() - Returns the overall scale factor of the frame
- filename, fontHeight, flags = EditBox:GetFont() - Returns the font instance's basic font properties
- font = EditBox:GetFontObject() - Returns the `Font` object from which the font instance's properties are inherited
- level = EditBox:GetFrameLevel() - Sets the level at which the frame is layered relative to others in its strata
- strata = EditBox:GetFrameStrata() - Returns the general layering strata of the frame
- height = EditBox:GetHeight() - Returns the height of the region
- left, right, top, bottom = EditBox:GetHitRectInsets() - Returns the insets from the frame's edges which determine its mouse-interactable area
- id = EditBox:GetID() - Returns the frame's numeric identifier
- justify = EditBox:GetJustifyH() - Returns the font instance's horizontal text alignment style
- justify = EditBox:GetJustifyV() - Returns the font instance's vertical text alignment style
- left = EditBox:GetLeft() - Returns the distance from the left edge of the screen to the left edge of the region
- maxWidth, maxHeight = EditBox:GetMaxResize() - Returns the maximum size of the frame for user resizing
- minWidth, minHeight = EditBox:GetMinResize() - Returns the minimum size of the frame for user resizing
- name = EditBox:GetName() - Returns the widget object's name
- numChildren = EditBox:GetNumChildren() - Returns the number of child frames belonging to the frame
- numPoints = EditBox:GetNumPoints() - Returns the number of anchor points defined for the region
- numRegions = EditBox:GetNumRegions() - Returns the number of non-Frame child regions belonging to the frame
- type = EditBox:GetObjectType() - Returns the object's widget type
- parent = EditBox:GetParent() - Returns the object's parent object
- point, relativeTo, relativePoint, xOffset, yOffset = EditBox:GetPoint(index) - Returns information about one of the region's anchor points
- left, bottom, width, height = EditBox:GetRect() - Returns the position and dimensions of the region
- ... = EditBox:GetRegions() - Returns a list of non-Frame child regions belonging to the frame
- right = EditBox:GetRight() - Returns the distance from the left edge of the screen to the right edge of the region
- scale = EditBox:GetScale() - Returns the frame's scale factor
- handler = EditBox:GetScript("scriptType") - Returns the widget's handler function for a script
- shadowR, shadowG, shadowB, shadowAlpha = EditBox:GetShadowColor() - Returns the color of the font's text shadow
- xOffset, yOffset = EditBox:GetShadowOffset() - Returns the offset of the font instance's text shadow from its text
- width, height = EditBox:GetSize() - Returns the width and height of the region
- spacing = EditBox:GetSpacing() - Returns the font instance's amount of spacing between lines
- textR, textG, textB, textAlpha = EditBox:GetTextColor() - Returns the font instance's default text color
- region = EditBox:GetTitleRegion() - Returns the frame's TitleRegion object
- top = EditBox:GetTop() - Returns the distance from the bottom of the screen to the top of the region
- width = EditBox:GetWidth() - Returns the width of the region
- hasScript = EditBox:HasScript("scriptType") - Returns whether the widget supports a script handler
- EditBox:Hide() - Hides the region
- EditBox:HookScript("scriptType", handler) - Securely hooks a script handler
- EditBox:IgnoreDepth(enable) - Sets whether the frame's depth property is ignored (for stereoscopic 3D setups)
- enabled = EditBox:IsClampedToScreen() - Returns whether the frame's boundaries are limited to those of the screen
- isDragging = EditBox:IsDragging() - Returns whether the region is currently being dragged
- registered = EditBox:IsEventRegistered("event") - Returns whether the frame is registered for a given [[docs/events|event]]
- enabled = EditBox:IsIgnoringDepth() - Returns whether the frame's depth property is ignored (for stereoscopic 3D setups)
- enabled = EditBox:IsJoystickEnabled() - Returns whether joystick interactivity is enabled for the frame
- enabled = EditBox:IsKeyboardEnabled() - Returns whether keyboard interactivity is enabled for the frame
- enabled = EditBox:IsMouseEnabled() - Returns whether mouse interactivity is enabled for the frame
- isOver = EditBox:IsMouseOver() - Returns whether the mouse cursor is over the given region
- enabled = EditBox:IsMouseWheelEnabled() - Returns whether mouse wheel interactivity is enabled for the frame
- movable = EditBox:IsMovable() - Returns whether the frame can be moved by the user
- isType = EditBox:IsObjectType("type") - Returns whether the object belongs to a given widget type
- isProtected, explicit = EditBox:IsProtected() - Returns whether the region is protected
- enabled = EditBox:IsResizable() - Returns whether the frame can be resized by the user
- shown = EditBox:IsShown() - Returns whether the region is shown
- enabled = EditBox:IsToplevel() - Returns whether the frame is automatically raised to the front when clicked
- enabled = EditBox:IsUserPlaced() - Returns whether the frame is flagged for automatic saving and restoration of position and dimensions
- visible = EditBox:IsVisible() - Returns whether the region is visible
- EditBox:Lower() - Reduces the frame's frame level below all other frames in its strata
- EditBox:Raise() - Increases the frame's frame level above all other frames in its strata
- EditBox:RegisterAllEvents() - Registers the frame for all events
- EditBox:RegisterEvent("event") - Registers the frame for an [[docs/events|event]]
- EditBox:RegisterForDrag(...) - Registers the frame for dragging
- EditBox:SetAllPoints([region]) or EditBox:SetAllPoints(["name"]) - Sets all anchor points of the region to match those of another region
- EditBox:SetAlpha(alpha) - Sets the opacity of the region relative to its parent
- EditBox:SetAttribute("name", value) - Sets a secure frame attribute
- EditBox:SetBackdrop(backdrop) - Sets a backdrop graphic for the frame
- EditBox:SetBackdropBorderColor(red, green, blue [, alpha]) - Sets a shading color for the frame's border graphic
- EditBox:SetBackdropColor(red, green, blue [, alpha]) - Sets a shading color for the frame's background graphic
- EditBox:SetClampRectInsets(left, right, top, bottom) - Sets offsets from the frame's edges used when limiting user movement or resizing of the frame
- EditBox:SetClampedToScreen(enable) - Sets whether the frame's boundaries should be limited to those of the screen
- EditBox:SetDepth(depth) - Sets the 3D depth of the frame (for stereoscopic 3D configurations)
- isValid = EditBox:SetFont("filename", fontHeight, "flags") - Sets the font instance's basic font properties
- EditBox:SetFontObject(object) or EditBox:SetFontObject("name") - Sets the `Font` object from which the font instance's properties are inherited
- EditBox:SetFrameLevel(level) - Sets the level at which the frame is layered relative to others in its strata
- EditBox:SetFrameStrata("strata") - Sets the general layering strata of the frame
- EditBox:SetHeight(height) - Sets the region's height
- EditBox:SetHitRectInsets(left, right, top, bottom) - Sets the insets from the frame's edges which determine its mouse-interactable area
- EditBox:SetID(id) - Sets a numeric identifier for the frame
- EditBox:SetJustifyH("justify") - Sets the font instance's horizontal text alignment style
- EditBox:SetJustifyV("justify") - Sets the font instance's horizontal text alignment style
- EditBox:SetMaxResize(maxWidth, maxHeight) - Sets the maximum size of the frame for user resizing
- EditBox:SetMinResize(minWidth, minHeight) - Sets the minimum size of the frame for user resizing
- EditBox:SetMovable(enable) - Sets whether the frame can be moved by the user
- EditBox:SetParent(frame) or EditBox:SetParent("name") - Makes another frame the parent of this region
- EditBox:SetPoint("point" [, relativeTo [, "relativePoint" [, xOffset [, yOffset]]]]) - Sets an anchor point for the region
- EditBox:SetResizable(enable) - Sets whether the frame can be resized by the user
- EditBox:SetScale(scale) - Sets the frame's scale factor
- EditBox:SetScript("scriptType", handler) - Sets the widget's handler function for a script
- EditBox:SetShadowColor(shadowR, shadowG, shadowB, shadowAlpha) - Sets the color of the font's text shadow
- EditBox:SetShadowOffset(xOffset, yOffset) - Sets the offset of the font instance's text shadow from its text
- EditBox:SetSize(width, height) - Sets the size of the region to the specified values
- EditBox:SetSpacing(spacing) - Sets the font instance's amount of spacing between lines
- EditBox:SetTextColor(textR, textG, textB, textAlpha) - Sets the font instance's default text color
- EditBox:SetToplevel(enable) - Sets whether the frame should automatically come to the front when clicked
- EditBox:SetUserPlaced(enable) - Flags the frame for automatic saving and restoration of position and dimensions
- EditBox:SetWidth(width) - Sets the region's width
- EditBox:Show() - Shows the region
- EditBox:StartMoving() - Begins repositioning the frame via mouse movement
- EditBox:StartSizing() - Begins resizing the frame via mouse movement
- EditBox:StopAnimating() - Stops any active animations involving the region or its children
- EditBox:StopMovingOrSizing() - Ends movement or resizing of the frame initiated with [[docs/widgets/Frame/StartMoving|`:StartMoving()`]] or [[docs/widgets/Frame/StartSizing|`:StartSizing()`]]
- EditBox:UnregisterAllEvents() - Unregisters the frame from any [[docs/events|events]] for which it is registered
- EditBox:UnregisterEvent("event") - Unregisters the frame for an event
Script Handlers
- OnAttributeChanged(self, "name", value) - Run when a frame attribute is changed
- OnChar(self, "text") - Run for each text character typed in the frame
- OnCharComposition(self, "text") - Run when the edit box's input composition mode changes
- OnCursorChanged(self, x, y, width, height) - Run when the position of the text insertion cursor in the edit box changes
- OnDisable(self) - Run when the frame is disabled
- OnDragStart(self, "button") - Run when the mouse is dragged starting in the frame
- OnDragStop(self) - Run when the mouse button is released after a drag started in the frame
- OnEditFocusGained(self) - Run when the edit box becomes focused for keyboard input
- OnEditFocusLost(self) - Run when the edit box loses keyboard input focus
- OnEnable(self) - Run when the frame is enabled
- OnEnter(self, motion) - Run when the mouse cursor enters the frame's interactive area
- OnEnterPressed(self) - Run when the Enter (or Return) key is pressed while the edit box has keyboard focus
- OnEscapePressed(self) - Run when the Escape key is pressed while the edit box has keyboard focus
- OnEvent(self, "event", ...) - Run whenever an [[docs/events|event]] fires for which the frame is registered
- OnHide(self) - Run when the frame's visbility changes to hidden
- OnInputLanguageChanged(self, "language") - Run when the edit box's language input mode changes
- OnKeyDown(self, "key") - Run when a keyboard key is pressed if the frame is keyboard enabled
- OnKeyUp(self, "key") - Run when a keyboard key is released if the frame is keyboard enabled
- OnLeave(self, motion) - Run when the mouse cursor leaves the frame's interactive area
- OnLoad(self) - Run when the frame is created
- OnMouseDown(self, "button") - Run when a mouse button is pressed while the cursor is over the frame
- OnMouseUp(self, "button") - Run when the mouse button is released following a mouse down action in the frame
- OnMouseWheel(self, delta) - Run when the frame receives a mouse wheel scrolling action
- OnReceiveDrag(self) - Run when the mouse button is released after dragging into the frame
- OnShow(self) - Run when the frame becomes visible
- OnSizeChanged(self, width, height) - Run when a frame's size changes
- OnSpacePressed(self) - Run when the space bar is pressed while the edit box has keyboard focus
- OnTabPressed(self) - Run when the Tab key is pressed while the edit box has keyboard focus
- OnTextChanged(self, isUserInput) - Run when the edit box's text is changed
- OnTextSet(self) - Run when the edit box's text is set programmatically
- OnUpdate(self, elapsed) - Run each time the screen is drawn by the game engine