As part of the Unified Community Platform project, your wiki will be migrated to the new platform in the next few weeks. Read more here.

UIOBJECT CheckButton

From Wowpedia
Jump to: navigation, search

CheckButton (inherits from Button) comprises a tickable box beside a text label. Interacting with either the box or label toggles the button state between checked and not checked appearances.

Construction

Lua

With "CheckButton" as the first argument in CreateFrame()

local cb = CreateFrame("CheckButton", "MyCheckButton", UIParent)

XML

With a <CheckButton> element in an XML file.

<CheckButton name="MyCheckButton" parent="UIParent">
	<!-- insert anchors, scripts, children and other components here in XML -->
</CheckButton>

Methods

CheckButton

CheckButton:GetChecked() - Get the status of the checkbox.
CheckButton:GetCheckedTexture() - Get the texture used for a checked box
CheckButton:GetDisabledCheckedTexture() - Get the texture used for a disabled checked box
CheckButton:SetChecked(boolean) - Set the status of the checkbox.
CheckButton:SetCheckedTexture(texture) - Set the texture to use for a checked box.
CheckButton:SetDisabledCheckedTexture(texture) - Set the texture to use for a disabled but checked box.

Button

Button (inherits from Frame) responds to mouse clicks.

Interaction
Button:Click() - Execute the click action of the button.
Button:Disable() - Disable the Button so that it cannot be clicked.
Button:Enable() - Enable to the Button so that it may be clicked.
Button:GetButtonState() - Return the current state ("PUSHED","NORMAL") of the Button.
Button:GetMotionScriptsWhileDisabled() - Get whether the button is allowed to run its OnEnter and OnLeave scripts even while disabled - New in 3.3.
Button:GetNormalTexture() - Get the normal texture for this button - New in 1.11.
Button:GetPushedTexture() - Get the texture for this button when pushed - New in 1.11.
Button:IsEnabled() - Determine whether the Button is enabled.
Button:RegisterForClicks(clickType[,clickType...]) - Specify which mouse button up/down actions cause this button to receive an OnClick notification.
Button:RegisterForMouse()
Button:SetButtonState(state[, lock]) - Set the state of the Button ("PUSHED", "NORMAL") and whether it is locked.
Button:SetEnabled(boolean) - Same as Enable() or Disable()
Button:SetMotionScriptsWhileDisabled([bool]) - Set whether button should fire its OnEnter and OnLeave scripts even while disabled - New in 3.3.
Appearance
Button:GetDisabledTexture() - Get the texture for this button when disabled - New in 1.11.
Button:GetHighlightTexture() - Get the texture for this button when highlighted.
Button:LockHighlight() - Set the Button to always be drawn highlighted.
Button:SetDisabledAtlas(atlasName)
Button:SetDisabledTexture(texture or texturePath) - Set the disabled texture for the Button - Updated in 1.10.
Button:SetHighlightAtlas(atlasName[, blendmode)
Button:SetHighlightTexture(texture or texturePath[,alphaMode]) - Set the highlight texture for the Button.
Button:SetNormalAtlas(atlasName)
Button:SetNormalTexture(texture or texturePath) - Set the normal texture for the Button - Updated in 1.10.
Button:UnlockHighlight() - Set the Button to not always be drawn highlighted.
Button:SetPushedAtlas(atlasName)
Button:SetPushedTexture(texture or texturePath) - Set the pushed texture for the Button - Updated in 1.10.
Label
Button:GetDisabledFontObject() - Return the font object for the Button when disabled - New in 1.10.
Button:GetFontString() - Get this button's label FontString - New in 1.11.
Button:GetHighlightFontObject() - Return the font object for the Button when highlighted - New in 1.10.
Button:GetNormalFontObject() - Get the Font Object of the button.
Button:GetPushedTextOffset() - Get the text offset when this button is pushed (x, y) - New in 1.11.
Button:GetText() - Get the text label for the Button.
Button:GetTextHeight() - Get the height of the Button's text.
Button:GetTextWidth() - Get the width of the Button's text.
Button:SetDisabledFontObject([font]) - Set the font object for settings when disabled - New in 1.10.
Button:SetFontString(fontString) - Set the button's label FontString - New in 1.11.
Button:SetFormattedText(formatstring[, ...]) - Set the formatted text label for the Button. - New in 2.3.
Button:SetHighlightFontObject([font]) - Set the font object for settings when highlighted - New in 1.10.
Button:SetNormalFontObject(FontObject) - Set the Font Object of the button.
Button:SetPushedTextOffset(x, y) - Set the text offset for this button when pushed - New in 1.11.
Button:SetText(text) - Set the text label for the Button.

Frame

Frame (inherits from Region and ScriptObject) provides the basis for interaction with the user, and registering and responding to game events.

Frame:GetID() - Returns the frame ID.
Frame:SetID(id) - Sets an ID on this frame.
Attributes
Frame:GetAttribute(prefix, name, suffix) - Returns the current value of an attribute matching a given pattern.
Frame:SetAttribute(name, value) - Sets an attribute on the frame.
Frame:ExecuteAttribute(name [, ...])
Frame:CanChangeAttribute()
Events
Frame:RegisterEvent(event) - Register for notifications when an event occurs.
Frame:RegisterUnitEvent(event, unit1 [, unit2]) - Register for notifications when events apply to certain units.
Frame:RegisterAllEvents() - Register this frame to receive all events (For debugging only!)
Frame:UnregisterEvent(event) - Indicate that this frame should no longer be notified when event occurs.
Frame:UnregisterAllEvents() - Indicate that this frame should no longer be notified when any events occur.
Frame:IsEventRegistered(event) - Returns true if the given event is registered to the frame.
User input
Frame:EnableJoystick()
Frame:EnableKeyboard(enableFlag) - Define whether to receive keyboard input.
Frame:EnableMouse(enableFlag) - Define whether to frame receives mouse input.
Frame:EnableMouseWheel(enableFlag) - Define whether to receive mouse wheel notifications.
Frame:GetHyperlinksEnabled()
Frame:GetPropagateKeyboardInput() - Returns whether keyboard inputs propagate.
Frame:IsJoystickEnabled()
Frame:IsKeyboardEnabled() - Returns whether receiving keyboard input.
Frame:IsMouseClickEnabled() - Returns whether receiving mouse click inputs.
Frame:IsMouseEnabled() - Returns whether receiving mouse input.
Frame:IsMouseMotionEnabled() - Returns whether receiving mouse enter/hover notifications.
Frame:IsMouseWheelEnabled() - Returns whether receiving mouse wheel notifications.
Frame:IsMovable() - Determine if the frame can be moved.
Frame:IsResizable() - Determine if the frame can be resized.
Frame:IsUserPlaced() - Determine if this frame has been relocated by the user.
Frame:RegisterForDrag(buttonType[,buttonType...]) - Direct the frame to monitor for mouse-dragging.
Frame:SetHyperlinksEnabled()
Frame:SetMouseClickEnabled()
Frame:SetMouseMotionEnabled()
Frame:SetMovable(isMovable) - Set whether the frame can be moved.
Frame:SetPropagateKeyboardInput(propagate) - Sets whether to propagate keyboard input to other frames.
Frame:SetResizable(isResizable) - Set whether the frame can be resized.
Frame:SetUserPlaced(isUserPlaced) - Set whether the frame has a user-defined position in the layout cache.
Frame:StartMoving() - Start moving this frame.
Frame:StartSizing(point) - Start sizing this frame using the specified anchor point.
Frame:StopMovingOrSizing() - Stop moving and/or sizing this frame.
Position & Visibility
Frame:GetBoundsRect()
Frame:GetClampRectInsets() - Gets the modifiers used for limiting the frame from leaving the screen..
Frame:GetDepth()
Frame:GetDontSavePosition()
Frame:GetEffectiveAlpha() - Returns the effective alpha of a frame.
Frame:GetEffectiveDepth() -
Frame:GetFrameLevel() - Get the level of this frame.
Frame:GetFrameStrata() - Get the strata of this frame.
Frame:GetHitRectInsets(l, r, t, b) - Gets the frame's hit rectangle inset distances
Frame:GetMaxResize(w, h) - Gets the frame's maximum allowed resize bounds
Frame:GetMinResize(w, h) - Gets the frame's minimum allowed resize bounds
Frame:IgnoreDepth(ignoreFlag)
Frame:IsClampedToScreen() - Gets whether the frame is prohibited from being dragged off screen.
Frame:IsIgnoringDepth()
Frame:IsToplevel() - Get whether the frame is set as toplevel
Frame:Lower() - Lower this frame behind other frames.
Frame:Raise() - Raise this frame above other frames.
Frame:SetClampRectInsets(left, right, top, bottom) - Modify how much the frame may be dragged offscreen.
Frame:SetClampedToScreen(clamped) - Set whether the frame is prohibited from being dragged off screen.
Frame:SetClipsChildren(clipped) - Set the frame clipping its children.
Frame:SetDepth(depth)
Frame:SetDontSavePosition()
Frame:SetFrameLevel(level) - Position the frame within a subdivision of its z-axis interval
Frame:SetFrameStrata(strata) - Position the frame within a z-axis interval.
Frame:SetHitRectInsets(left, right, top, bottom) - Set the inset distances for the frame's hit rectangle.
Frame:SetMaxResize(maxWidth, maxHeight) - Set the maximum dimensions this frame can be resized to.
Frame:SetMinResize(minWidth, minHeight) - Set the minimum dimensions this frame can be resized to.
Frame:SetToplevel(isTopLevel) - Set whether the frame should raise itself when clicked
Children (LayeredRegions)
Frame:CreateFontString() - Create and return a new FontString.
Frame:CreateLine{) - Create and return a new Line.
Frame:CreateMaskTexture() - Create and return a new MaskTexture .
Frame:CreateTexture() - Create and return a new Texture.
Frame:GetChildren() - Return child Frames as multiple return values.
Frame:GetRegions() - Return child LayeredRegions as multiple return values.
Frame:GetNumChildren() - Return the number of child Frames.
Frame:GetNumRegions() - Return the number of child LayeredRegions.
Frame:DisableDrawLayer(layer) - Disable LayeredRegions in the specified draw layer.
Frame:EnableDrawLayer(layer) - Enable LayeredRegions in the specified draw layer.
Frame:DesaturateHierarchy(desaturation)
Frame:GetEffectivelyFlattensRenderLayers()
Frame:GetFlattensRenderLayers()
Frame:SetFlattensRenderLayers()
Frame:DoesClipChildren()
Backdrops
WoW Icon update.png Classic only from Patch 9.0.1; see BackdropTemplate
Frame:GetBackdrop() - Creates and returns a backdrop table suitable for use in SetBackdrop
Frame:GetBackdropBorderColor(r, g, b, a) - Gets the frame's backdrop border color
Frame:GetBackdropColor(r, g, b, a) - Gets the frame's backdrop color
Frame:SetBackdrop([backdropTable]) - Set the backdrop of the frame according to the specification provided.
Frame:SetBackdropBorderColor(r, g, b [, a]) - Set the frame's backdrop's border's color.
Frame:SetBackdropColor(r, g, b [, a]) - Set the frame's backdrop color.

Region

Region (inherits from UIObject) is an abstract widget type for anything that can occupy an area of the screen.

Region:SetParent(parent) - Parents this to another object. Parented objects will inherit their scale & visibility.
Region:CanChangeProtectedState()
Region:IsDragging() - True if this Region or its Parent is being dragged. - New in 3.1.0
Region:IsMouseOver([top, bottom, left, right]) - Checks whether the mouse is over the frame (or within specified offsets).
Region:IsObjectLoaded()
Region:IsProtected() - Indicates if this object can be manipulated in certain ways by tainted code in combat or not
Position & Scale
Region:GetPoint(index) - Returns the details of the indexth anchor point defined for this frame (point, relativeTo, relativePoint, xofs, yofs).
Region:SetPoint(point, relativeTo, relativePoint, ofsx, ofsy) - Defines an attachment point of this region.
Region:SetAllPoints(frame or frameName) - Defines attachment points for this region to match edges of the specified frame.
Region:ClearAllPoints() - Removes all previously-defined attachment points for this region.
Region:GetNumPoints() - Returns the number of anchor points defined for this frame.
Region:GetLeft() - Returns the distance from the left edge of the screen (scale dependent).
Region:GetRight() - Returns the distance from the bottom of the screen (scale dependent).
Region:GetTop() - Returns the distance of the top edge from the bottom of the screen (scale dependent).
Region:GetBottom() - Returns the distance from the bottom edge of the screen (scale dependent).
Region:GetCenter() - Returns the distance of the region's middle from the bottom-left corner of the screen (scale dependent).
Region:GetRect() - Returns the location and size (scale dependent), as shorthand for GetBottom(), GetLeft(), GetWidth() and GetHeight()
Region:GetScaledRect() - Returns the location and size in a standard coordinate space (as if effectiveScale = 1).
Region:IsRectValid() - Indicates the region has been sufficiently defined for placement on the screen.
Region:GetWidth() - Returns the width of this object (scale dependent).
Region:SetWidth(width) - Defines the width of the object (scale dependent).
Region:GetHeight() - Returns the height of this object (scale dependent).
Region:SetHeight(height) - Defines the height of the object (scale dependent).
Region:GetSize() - Returns the width and height (scale dependent).
Region:SetSize(width, height) - Defines the width and the height, as shorthand for SetWidth() and SetHeight()
Region:GetScale() - Returns the set scale (normally relative to its parent).
Region:SetScale(scale) - Defines the scale relative to an immediate parent or standard coordinate space, depending on IsIgnoringParentScale()
Region:GetEffectiveScale() - Returns the net scale, inclusive of all parents.
Region:SetIgnoreParentScale(boolean) - Directs the region to scale itself manually without inheritence.
Region:IsIgnoringParentScale() - Indicates the region scales itself manually without inheritence.
Visibility
Region:Show() - Directs the region to appear and permits its children to appear also, but not while the region's parent (if any) is hidden
Region:Hide() - Directs the region and its children to disappear
Region:SetShown(boolean) - Directs the region to appear or disappar, as an alternative to Hide() and Show()
Region:IsShown() - Indicates the region will appear, but only while its parent appears or if it has no parent
Region:IsVisible() - Indicates the region and its parent (if any) are currently appearing
Region:GetAlpha() - Returns the object's set opacity between 0 and 1 (normally relative to its parent)
Region:GetEffectiveAlpha() - Return's the net opacity, inclusive of all parents
Region:SetAlpha(alpha) - Defines the object's opacity between 0 and 1 (normally relative to its parent)
Region:SetIgnoreParentAlpha(boolean) - Directs the region to adopt a manually defined opacity uninherited from its parent
Region:IsIgnoringParentAlpha() - Indicates the region has a manually defined opacity uninherited from its parent
Animations
Region:CreateAnimationGroup() - Constructs a new AnimationGroup as a child of this Region. - New in 3.1.0
Region:GetAnimationGroups() - Returns all AnimationGroups that are children of this Region. - New in 3.1.0
Region:StopAnimating() - Halts any active Animations on the Region and its children - New in 3.1.0

UIObject

UIObject is an abstract widget type. All of the user interface elements are derived from UIObject.

UIObject:GetName() - Returns the widget's name.
UIObject:GetDebugName() - Returns the widget's debug name.
UIObject:GetParent() - Returns the widget's parent object.
UIObject:GetObjectType() - Returns the widget's type.
UIObject:IsObjectType(type) - Returns whether the widget belongs to a given widget type.
UIObject:IsForbidden() - Returns whether insecure interaction with a widget is forbidden.
UIObject:SetForbidden(boolean) - Sets the widget to be forbidden from insecure code.

ScriptObject

ScriptObject is an abstract widget type that provides support for widget scripts.

ScriptObject:GetScript(scriptType [, bindingType]) - Returns the widget's script handler.
ScriptObject:SetScript(scriptType, handler) - Sets the widget's script handler.
ScriptObject:HookScript(scriptType, handler [, bindingType]) - Securely hooks a script handler.
ScriptObject:HasScript(scriptType) - Returns whether the widget supports a script type.

Handlers

CheckButton does not introduce any new handlers, but inherits from Button. Notably, its GetChecked() method reflects the new state during Button's OnClick handler.

Button

Button (inherits from Frame) responds to mouse clicks.

OnClick(self, button, down) - Run when the button is clicked.
OnDoubleClick(self, button) - Run when the button is double-clicked.
PostClick(self, button, down) - Run immediately following the button's `OnClick` handler with the same arguments.
PreClick(self, button, down) - Run immediately before the button's `OnClick` handler with the same arguments.

Frame

Frame (inherits from Region and ScriptObject) provides the basis for interaction with the user, and registering and responding to game events.

OnAttributeChanged(self, key, value) - Run when a frame attribute is changed.
OnChar(self, text) - Run for each text character typed in the frame.
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,
OnEnable(self) - Run when the frame is enabled.
OnEnter(self, motion) - Run when the mouse cursor enters the frame's interactive area.
OnEvent(self, event, ...) - Run whenever an event fires for which the frame is registered.
OnHide(self) - Run when the frame's visbility changes to hidden.
OnHyperlinkClick(self, link, text, button) - Run when the mouse clicks a hyperlink on the FontInstance object.
OnHyperlinkEnter(self, link, text) - Run when the mouse moves over a hyperlink on the FontInstance object.
OnHyperlinkLeave(self, link, text) - Run when the mouse moves away from a hyperlink on the FontInstance object.
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.
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.

ScriptObject

ScriptObject is an abstract widget type that provides support for widget scripts.

OnLoad(self) - Run when the frame is created.
OnUpdate(self, elapsed) - Run each time the screen is drawn by the game engine.


Examples

The following example provides a basic CheckButton inheriting a common template to configure its default appearance.

local myCheckButton = CreateFrame("CheckButton", nil, UIParent, "ChatConfigCheckButtonTemplate")
myCheckButton:SetPoint("TOPLEFT", 200, -65)
myCheckButton:SetText("CheckBox Name")
myCheckButton.tooltip = "This is where you place MouseOver Text."
myCheckButton:HookScript("OnClick", function()
	--do stuff
end)

The following example creates a "checkbox-factory function" to automate several steps (but could be substituted using a FramePoolMixin):

local numCheckButtons = 0;
function createCheckButton(parent, xOff, yOff, displayname)
	numCheckButtons =  numCheckButtons + 1;
	local checkButton = CreateFrame("CheckButton", "my_addon_checkbutton_" ..  numCheckButtons, parent, "ChatConfigCheckButtonTemplate");
	checkButton:SetPoint("TOPLEFT", xOff or 0, yOff or 0);
	checkButton:SetText(displayname or "");
	return checkbutton;
end

myCheckButton = my_addon.createCheckButton(UIParent, 400, -600, "A Checkbox");
myCheckButton.tooltip = "If this is checked, nothing will happen, because this is a demo checkbox.";
myCheckButton:HookScript("OnClick", function()
	-- do stuff
end);

Patch changes

External links

References