Frame is in many ways the most fundamental widget object. Other types of widget derivatives such as FontStrings, Textures and Animations can only be created attached to a Frame or other derivative of a Frame. Frames provide the basis for interaction with the user, and registering and responding to game events.
When an addon needs to respond to game events or state changes and needs no visible components, this is typically accomplished using a Frame. Visibly, widgets that display game information such as threat or cooldowns and aren't directly interactive beyond being draggable are typically Frames. They are also commonly used as ways to group other related frames, either visibly (such as the way the Talents pane groups the buttons representing your character's talents) or invisibly (such as the way MultiBarRight groups twelve action buttons).
You create a plain frame by specifying "Frame" as the first argument to CreateFrame
, or with a <Frame>
element in an XML file:
-- Create a new frame in Lua
local self = CreateFrame("Frame", "FunWidget", UIParent)
<Frame name="FunWidget" parent="UIParent">
<!-- insert anchors, scripts, children and other components here in XML -->
</Frame>
Frames in the FrameXML include the action bars (the frames that group the action buttons together), the panels that display information like your character status and quest log, and the grand-daddy of the rest of the UI, UIParent.
Defined Methods
- Frame:GetPropagateKeyboardInput() - This function is not yet documented
- Frame:RegisterUnitEvent() - This function is not yet documented
- Frame:SetDontSavePosition() - This function is not yet documented
- Frame:SetPropagateKeyboardInput() - This function is not yet documented
- Frame:SetShown() - This function is not yet documented
- Frame:SetToplevel(enable) - Sets whether the frame should automatically come to the front when clicked
- Frame:SetUserPlaced(enable) - Flags the frame for automatic saving and restoration of position and dimensions
- Frame:StartMoving() - Begins repositioning the frame via mouse movement
- Frame:StartSizing() - Begins resizing the frame via mouse movement
- Frame:StopMovingOrSizing() - Ends movement or resizing of the frame initiated with [[docs/widgets/Frame/StartMoving|`:StartMoving()`]] or [[docs/widgets/Frame/StartSizing|`:StartSizing()`]]
- Frame:UnregisterAllEvents() - Unregisters the frame from any [[docs/events|events]] for which it is registered
- Frame:UnregisterEvent("event") - Unregisters the frame for an event
Inherited Methods
- Frame:IsForbidden() - This function is not yet documented
- isOver = Frame:IsMouseOver([topOffset [, leftOffset [, bottomOffset [, rightOffset]]]]) - Returns whether the mouse cursor is over the given region
- isType = Frame:IsObjectType("type") - Returns whether the object belongs to a given widget type
- isProtected, explicit = Frame:IsProtected() - Returns whether the region is protected
- shown = Frame:IsShown() - Returns whether the region is shown
- visible = Frame:IsVisible() - Returns whether the region is visible
- Frame:SetAllPoints([region]) or Frame:SetAllPoints(["name"]) - Sets all anchor points of the region to match those of another region
- Frame:SetAlpha(alpha) - Sets the opacity of the region relative to its parent
- Frame:SetHeight(height) - Sets the region's height
- Frame:SetParent(frame) or Frame:SetParent("name") - Makes another frame the parent of this region
- Frame:SetPoint("point" [, relativeTo [, "relativePoint" [, xOffset [, yOffset]]]]) - Sets an anchor point for the region
- Frame:SetScript("scriptType", handler) - Sets the widget's handler function for a script
- Frame:SetSize(width, height) - Sets the size of the region to the specified values
- Frame:SetWidth(width) - Sets the region's width
- Frame:Show() - Shows the region
- Frame:StopAnimating() - Stops any active animations involving the region or its children
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
- 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 [[docs/events|event]] fires for which the frame is registered
- OnHide(self) - Run when the frame's visbility changes to hidden
- 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
- OnUpdate(self, elapsed) - Run each time the screen is drawn by the game engine