Wowpedia
Advertisement
Wowpedia
240,442
pages

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)

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:GetDisabledFontObject() - Return the font object for the Button when disabled - New in 1.10.
Button:GetDisabledTexture() - Get the texture for this button when disabled - New in 1.11.
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:GetHighlightTexture() - Get the texture for this button when highlighted.
Button:GetMotionScriptsWhileDisabled() - Get whether the button is allowed to run its OnEnter and OnLeave scripts even while disabled - New in 3.3.
Button:GetNormalFontObject() - Get the Font Object of the button.
Button:GetNormalTexture() - Get the normal texture for this button - New in 1.11.
Button:GetPushedTextOffset() - Get the text offset when this button is pushed (x, y) - New in 1.11.
Button:GetPushedTexture() - Get the texture for this button when pushed - 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:IsEnabled() - Determine whether the Button is enabled.
Button:LockHighlight() - Set the Button to always be drawn highlighted.
Button:RegisterForClicks(clickType1 [, clickType2, ...]) - 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:SetDisabledAtlas(atlasName)
Button:SetDisabledFontObject([font]) - Set the font object for settings when disabled - New in 1.10.
Button:SetDisabledTexture(texture or texturePath) - Set the disabled texture for the Button - Updated in 1.10.
Button:SetEnabled(boolean) - Same as Enable() or Disable()
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:SetHighlightAtlas(atlasName[, blendmode)
Button:SetHighlightFontObject([font]) - Set the font object for settings when highlighted - New in 1.10.
Button:SetHighlightTexture(texture or texturePath[,alphaMode]) - Set the highlight texture for the Button.
Button:SetMotionScriptsWhileDisabled([bool]) - Set whether button should fire its OnEnter and OnLeave scripts even while disabled - New in 3.3.
Button:SetNormalAtlas(atlasName)
Button:SetNormalFontObject(FontObject) - Set the Font Object of the button.
Button:SetNormalTexture(texture or texturePath) - Set the normal texture for the Button - Updated in 1.10.
Button:SetPushedAtlas(atlasName)
Button:SetPushedTextOffset(x, y) - Set the text offset for this button when pushed - New in 1.11.
Button:SetPushedTexture(texture or texturePath) - Set the pushed texture for the Button - Updated in 1.10.
Button:SetText(text) - Set the text label for the Button.
Button:UnlockHighlight() - Set the Button to not always be drawn highlighted.

Frame

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

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.
Position & Visibility
Frame:DesaturateHierarchy(desaturation)
Frame:DisableDrawLayer(layer) - Disables the specified draw layer.
Frame:EnableDrawLayer(layer) - Enables the specified draw layer.
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:GetEffectivelyFlattensRenderLayers()
Frame:GetFlattensRenderLayers()
Frame:GetFrameLevel() - Returns the level of this frame.
Frame:GetFrameStrata() - Returns the strata of this frame.
Frame:GetHitRectInsets(l, r, t, b) - Gets the frame's hit rectangle inset distances
Frame:GetMaxResize(w, h) - Returns the frame's maximum allowed resize bounds
Frame:GetMinResize(w, h) - Returns the frame's minimum allowed resize bounds
Frame:HasFixedFrameLevel() : boolean
Frame:HasFixedFrameStrata() : boolean
Frame:IgnoreDepth(ignoreFlag)
Frame:IsClampedToScreen() - Returns if the frame is prohibited from being dragged off screen.
Frame:IsIgnoringDepth()
Frame:IsToplevel() - Returns if the frame is set as top level.
Frame:Lower() - Lowers this frame behind other frames.
Frame:Raise() - Raises this frame above other frames.
Frame:RotateTextures(angleRadians [, pivotX, pivotY])
Frame:SetClampedToScreen(clamped) - Sets whether the frame is prohibited from being dragged off screen.
Frame:SetClampRectInsets(left, right, top, bottom) - Modify how much the frame may be dragged offscreen.
Frame:SetDepth(depth)
Frame:SetDontSavePosition()
Frame:SetDrawLayerEnabled(layer, mouseOver)
Frame:SetFixedFrameLevel(bool)
Frame:SetFixedFrameStrata(bool)
Frame:SetFlattensRenderLayers()
Frame:SetFrameBuffer(enabled) - Controls whether or not the frame is rendered to its own framebuffer.
Frame:SetFrameLevel(level) - Positions the frame within a subdivision of its z-axis interval
Frame:SetFrameStrata(strata) - Positions 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) - Sets the maximum dimensions this frame can be resized to.
Frame:SetMinResize(minWidth, minHeight) - Sets the minimum dimensions this frame can be resized to.
Frame:SetToplevel(isTopLevel) - Sets whether the frame should raise itself when clicked
Children
Frame:GetChildren() - Returns child Frames as multiple return values.
Frame:GetNumChildren() - Returns the number of child Frames.
Frame:DoesClipChildren()
Frame:SetClipsChildren(clipped) - Sets the frame clipping its children.
Regions
Frame:GetNumRegions() - Returns the number of regions.
Frame:GetRegions() - Returns the regions.
Frame:CreateFontString() - Creates a FontString
Frame:CreateLine{) - Creates a Line
Frame:CreateMaskTexture() - Creates a MaskTexture
Frame:CreateTexture() - Creates a Texture
User Input
Frame:EnableKeyboard(enableFlag) - Whether to receive keyboard input.
Frame:EnableMouse(enableFlag) - Whether to receives mouse input.
Frame:EnableMouseWheel(enableFlag) - Whether to receive mouse wheel notifications.
Frame:GetHyperlinksEnabled()
Frame:GetPropagateKeyboardInput() - Returns if keyboard inputs propagate.
Frame:IsKeyboardEnabled() - Returns if receiving keyboard input.
Frame:IsMouseClickEnabled() - Returns if receiving mouse click inputs.
Frame:IsMouseEnabled() - Returns if receiving mouse input.
Frame:IsMouseMotionEnabled() - Returns if receiving mouse enter/hover notifications.
Frame:IsMouseWheelEnabled() - Returns if receiving mouse wheel notifications.
Frame:IsMovable() - Returns if the frame can be moved.
Frame:IsResizable() - Returns if the frame can be resized.
Frame:IsUserPlaced() - Returns 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) - Whether the frame should be moved.
Frame:SetPropagateKeyboardInput(propagate) - Whether to propagate keyboard input to other frames.
Frame:SetResizable(isResizable) - Whether the frame should be resized.
Frame:SetUserPlaced(isUserPlaced) - Whether the frame is user-defined in the layout cache.
Frame:StartMoving() - Starts moving this frame.
Frame:StartSizing(point) - Starts sizing this frame using the specified anchor point.
Frame:StopMovingOrSizing() - Stops moving and/or sizing this frame.
Frame:EnableGamePadButton(enabled)
Frame:EnableGamePadStick(enabled)
Frame:IsGamePadButtonEnabled()
Frame:IsGamePadStickEnabled()
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()
Frame:GetID() - Returns the frame ID.
Frame:SetID(id) - Sets an ID on this frame.
Backdrop

The Backdrop API was moved to BackdropTemplate in Patch 9.0.1

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 ParentedObject) 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: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
Region:CanChangeProtectedState()
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:GetPointByName(name)
Region:ClearPointByName(name)
Region:AdjustPointsOffset([adjustX, adjustY])
Region:IsAnchoringRestricted()
Region:GetLeft() - Returns the distance of the region's left edge from the left side of the screen (scale dependent).
Region:GetRight() - Returns the distance of the region's right edge from the left side of the screen (scale dependent).
Region:GetTop() - Returns the distance of the region's top edge from the bottom of the screen (scale dependent).
Region:GetBottom() - Returns the distance of the region's bottom edge from the bottom of the screen (scale dependent).
Region:GetCenter() - Returns the distance of the region's middle from the bottom left 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 that all user interface elements derive from.

UIObject:GetName() - Returns the widget object's name.
UIObject:GetObjectType() - Returns the object's widget type.
UIObject:IsObjectType(type) - Returns whether the object belongs to a given widget type.

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)

OnClick(self, button, down) - Run when clicking a button.
OnDoubleClick(self, button) - Run when double-clicking a button.
PostClick(self, button, down) - Run immediately after `OnClick`.
PreClick(self, button, down) - Run immediately before `OnClick`.

Frame

Frame (inherits from Region and ScriptObject, created with CreateFrame) 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.
OnGamePadButtonDown
OnGamePadButtonUp
OnGamePadStick
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

  • WoW Icon update.png Patch 1.11.0 / API (2006-06-19): Added functions to retrieve the textures in use on the tick box[1]

External links

References

Advertisement