Update

Update Update Update Update Update Update Update Update Update
2025-05-04 20:46:46 +02:00
parent 169a514973
commit ba1f7e14bf
38 changed files with 2952 additions and 90 deletions
--- a/ui/Frame.lua
+++ b/ui/Frame.lua
@@ -1,76 +1,467 @@
 ---@meta

---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.
---@class Frame : UIObject
+---@class Frame : Region
 Frame = {
-	---Sets whether the frame should automatically come to the front when clicked. When a frame with Toplevel behavior enabled is clicked, it automatically changes its frame level such that it is greater than (and therefore drawn "in front of") all other frames in its strata.
-	---@param self Frame
-	---@param enable boolean True to cause the frame to automatically come to the front when clicked; false otherwise
-	SetTopLevel = function(self, enable) end,
+	--- Aborts the current drag operation.
+	--- @example
+	--- myFrame:AbortDrag()
+	AbortDrag = function(self) end,

-	---Flags the frame for automatic saving and restoration of position and dimensions. The position and size of frames so flagged is automatically saved when the UI is shut down (as when quitting, logging out, or reloading) and restored when the UI next starts up (as when logging in or reloading). If the frame does not have a name (set at creation time) specified, its position will not be saved. As implied by its name, enabling this property is useful for frames which can be moved or resized by the user.
-	---
-	---This function is automatically called with the value true when frame:StartMoving() is called.
-	---
-	---In order for the saved position to be applied to the frame in later sessions, the frame must have been made movable with frame:SetMovable(true).
-	---@param self Frame
-	---@param enable boolean True to enable automatic saving and restoration of the frame's position and dimensions; false to disable
-	SetUserPlaced = function(self, enable) end,
+	--- Returns true if secure frame attributes can be changed.
+	--- @return boolean canChange True if attributes can be changed.
+	--- @example
+	--- local canChange = myFrame:CanChangeAttribute()
+	CanChangeAttribute = function(self) end,

-	---Begins repositioning the frame via mouse movement.
-	---@param self Frame
+	--- Creates and returns a FontString as a child of this Frame.
+	--- @param self Frame
+	--- @param name string? Optional. The name of the FontString.
+	--- @param layer string? Optional. The layer of the FontString.
+	--- @param inheritsFrom string? Optional. The name of the FontString to inherit from.
+	--- @return FontString fontString The created FontString.
+	--- @example
+	--- local myFontString = myFrame:CreateFontString("MyFontString", "OVERLAY")
+	CreateFontString = function(self, name, layer, inheritsFrom) end,
+
+	--- Creates a Texture as a child of this Frame.
+	--- @param self Frame
+	--- @param name string? Optional. The name of the Texture.
+	--- @param layer string? Optional. The layer of the Texture.
+	--- @param inheritsFrom string? Optional. The name of the Texture to inherit from.
+	--- @return Texture texture The created Texture.
+	--- @example
+	--- local myTexture = myFrame:CreateTexture("MyTexture", "BACKGROUND")
+	CreateTexture = function(self, name, layer, inheritsFrom) end,
+
+	--- Creates a title region for the frame if it does not have one.
+	--- @param self Frame
+	--- @return Region titleRegion The created title region.
+	--- @example
+	--- myFrame:CreateTitleRegion()
+	CreateTitleRegion = function(self) end,
+
+	--- Disables rendering of "regions" (fontstrings, textures) in the specified draw layer.
+	--- @param self Frame
+	--- @param layer string The layer to disable.
+	--- @example
+	--- myFrame:DisableDrawLayer("BORDER")
+	DisableDrawLayer = function(self, layer) end,
+
+	--- Enables rendering of "regions" (fontstrings, textures) in the specified draw layer.
+	--- @param self Frame
+	--- @param layer string The layer to enable.
+	--- @example
+	--- myFrame:EnableDrawLayer("BORDER")
+	EnableDrawLayer = function(self, layer) end,
+
+	--- Sets the opacity of the frame.
+	--- @param self Frame
+	--- @param alpha number The opacity value (0 to 1).
+	--- @example
+	--- myFrame:SetAlpha(0.5) -- Set to 50% opacity
+	SetAlpha = function(self, alpha) end,
+
+	--- Returns the frame's numeric identifier.
+	--- @param self Frame
+	--- @return number id The frame's ID.
+	--- @example
+	--- local id = myFrame:GetID()
+	GetID = function(self) end,
+
+	--- Shows this object (it will appear if its parent is visible).
+	--- @example
+	--- myFrame:Show()
+	Show = function(self) end,
+
+	--- Hides this object (it and all of its children will disappear).
+	--- @example
+	--- myFrame:Hide()
+	Hide = function(self) end,
+
+	--- Starts moving the frame via mouse movement.
+	--- @example
+	--- myFrame:StartMoving()
 	StartMoving = function(self) end,

-	---Begins resizing the frame via mouse movement.
-	---@param self Frame
-	StartSizing = function(self) end,
-
-	---Ends movement or resizing of the frame initiated with :StartMoving() or :StartSizing().
-	---@param self Frame
+	--- Stops moving the frame.
+	--- @example
+	--- myFrame:StopMovingOrSizing()
 	StopMovingOrSizing = function(self) end,

-	---Unregisters the frame from any events for which it is registered.
-	---@param self Frame
+	--- Sets whether the frame can be moved.
+	--- @param self Frame
+	--- @param movable boolean True to allow moving.
+	--- @example
+	--- myFrame:SetMovable(true)
+	SetMovable = function(self, movable) end,
+
+	--- Sets the frame's level.
+	--- @param self Frame
+	--- @param level number The level to set.
+	--- @example
+	--- myFrame:SetFrameLevel(5)
+	SetFrameLevel = function(self, level) end,
+
+	--- Sets the frame's strata.
+	--- @param self Frame
+	--- @param strata string The strata to set (e.g., "BACKGROUND", "MEDIUM", "HIGH").
+	--- @example
+	--- myFrame:SetFrameStrata("HIGH")
+	SetFrameStrata = function(self, strata) end,
+
+	--- Registers the frame for a specific event.
+	--- @param self Frame
+	--- @param eventName string The name of the event to register.
+	--- @example
+	--- myFrame:RegisterEvent("PLAYER_LOGIN")
+	RegisterEvent = function(self, eventName) end,
+
+	--- Unregisters an event from the frame.
+	--- @param self Frame
+	--- @param eventName string The name of the event to unregister.
+	--- @example
+	--- myFrame:UnregisterEvent("PLAYER_LOGIN")
+	UnregisterEvent = function(self, eventName) end,
+
+	--- Sets the backdrop of the frame according to the specification provided.
+	--- @param self Frame
+	--- @param backdropTable table? Optional. A table defining the backdrop.
+	--- @example
+	--- myFrame:SetBackdrop({bgFile = "Interface\\DialogFrame\\UI-DialogBox-Background"})
+	SetBackdrop = function(self, backdropTable) end,
+
+	--- Sets the frame's backdrop color.
+	--- @param self Frame
+	--- @param r number The red component of the color.
+	--- @param g number The green component of the color.
+	--- @param b number The blue component of the color.
+	--- @param a number? Optional. The alpha component of the color.
+	--- @example
+	--- myFrame:SetBackdropColor(0, 0, 0, 0.5) -- Set to semi-transparent black
+	SetBackdropColor = function(self, r, g, b, a) end,
+
+	--- Sets the frame's backdrop border color.
+	--- @param self Frame
+	--- @param r number The red component of the border color.
+	--- @param g number The green component of the border color.
+	--- @param b number The blue component of the border color.
+	--- @param a number? Optional. The alpha component of the border color.
+	--- @example
+	--- myFrame:SetBackdropBorderColor(1, 1, 1) -- Set to white
+	SetBackdropBorderColor = function(self, r, g, b, a) end,
+
+	--- Sets whether this frame will get keyboard input.
+	--- @param self Frame
+	--- @param enableFlag boolean True to enable keyboard input.
+	--- @example
+	--- myFrame:EnableKeyboard(true)
+	EnableKeyboard = function(self, enableFlag) end,
+
+	--- Sets whether this frame will get mouse input.
+	--- @param self Frame
+	--- @param enableFlag boolean True to enable mouse input.
+	--- @example
+	--- myFrame:EnableMouse(true)
+	EnableMouse = function(self, enableFlag) end,
+
+	--- Sets whether this frame will get mouse wheel notifications.
+	--- @param self Frame
+	--- @param enableFlag boolean True to enable mouse wheel notifications.
+	--- @example
+	--- myFrame:EnableMouseWheel(true)
+	EnableMouseWheel = function(self, enableFlag) end,
+
+	--- Sets the height of the object.
+	--- @param self Frame
+	--- @param height number The height to set.
+	--- @example
+	--- myFrame:SetHeight(200)
+	SetHeight = function(self, height) end,
+
+	--- Sets the width of the object.
+	--- @param self Frame
+	--- @param width number The width to set.
+	--- @example
+	--- myFrame:SetWidth(300)
+	SetWidth = function(self, width) end,
+
+	--- Sets the size of the frame.
+	--- @param self Frame
+	--- @param width number The width to set.
+	--- @param height number The height to set.
+	--- @example
+	--- myFrame:SetSize(300, 200)
+	SetSize = function(self, width, height) end,
+
+	--- Sets the parent for this frame.
+	--- @param self Frame|string The parent frame or name of the parent frame.
+	--- @example
+	--- myFrame:SetParent(otherFrame)
+	SetParent = function(self, parent) end,
+
+	--- Returns the first existing attribute of (prefix..name..suffix), ("*"..name..suffix), (prefix..name.."*"), ("*"..name.."*"), (name).
+	--- @param self Frame
+	--- @param prefix string The prefix to use.
+	--- @param name string The name of the attribute.
+	--- @param suffix string The suffix to use.
+	--- @return any attribute The found attribute.
+	--- @example
+	--- local attr = myFrame:GetAttribute("prefix", "name", "suffix")
+	GetAttribute = function(self, prefix, name, suffix) end,
+
+	--- Creates and returns a backdrop table suitable for use in SetBackdrop.
+	--- @param self Frame
+	--- @return table backdropTable The backdrop table.
+	--- @example
+	--- local backdrop = myFrame:GetBackdrop()
+	GetBackdrop = function(self) end,
+
+	--- Gets the frame's backdrop border color (r, g, b, a).
+	--- @param self Frame
+	--- @return number r The red component.
+	--- @return number g The green component.
+	--- @return number b The blue component.
+	--- @return number a The alpha component.
+	--- @example
+	--- local r, g, b, a = myFrame:GetBackdropBorderColor()
+	GetBackdropBorderColor = function(self) end,
+
+	--- Gets the frame's backdrop color (r, g, b, a).
+	--- @param self Frame
+	--- @return number r The red component.
+	--- @return number g The green component.
+	--- @return number b The blue component.
+	--- @return number a The alpha component.
+	--- @example
+	--- local r, g, b, a = myFrame:GetBackdropColor()
+	GetBackdropColor = function(self) end,
+
+	--- Gets the list of "children" (frames and things derived from frames) of this frame.
+	--- @param self Frame
+	--- @return table children The list of child frames.
+	--- @example
+	--- local children = myFrame:GetChildren()
+	GetChildren = function(self) end,
+
+	--- Gets the modifiers to the frame's rectangle used for clamping the frame to screen.
+	--- @param self Frame
+	--- @return number left The left modifier.
+	--- @return number right The right modifier.
+	--- @return number top The top modifier.
+	--- @return number bottom The bottom modifier.
+	--- @example
+	--- local left, right, top, bottom = myFrame:GetClampRectInsets()
+	GetClampRectInsets = function(self) end,
+
+	--- Gets the effective alpha of a frame.
+	--- @param self Frame
+	--- @return number alpha The effective alpha.
+	--- @example
+	--- local alpha = myFrame:GetEffectiveAlpha()
+	GetEffectiveAlpha = function(self) end,
+
+	--- Gets the scale factor of this object relative to the root window.
+	--- @param self Frame
+	--- @return number scale The effective scale.
+	--- @example
+	--- local scale = myFrame:GetEffectiveScale()
+	GetEffectiveScale = function(self) end,
+
+	--- Gets the level of this frame.
+	--- @param self Frame
+	--- @return number level The frame level.
+	--- @example
+	--- local level = myFrame:GetFrameLevel()
+	GetFrameLevel = function(self) end,
+
+	--- Gets the strata of this frame.
+	--- @param self Frame
+	--- @return string strata The frame strata.
+	--- @example
+	--- local strata = myFrame:GetFrameStrata()
+	GetFrameStrata = function(self) end,
+
+	--- Gets the type of this frame.
+	--- @param self Frame
+	--- @return string frameType The frame type.
+	--- @example
+	--- local frameType = myFrame:GetFrameType()
+	GetFrameType = function(self) end,
+
+	--- Gets the frame's hit rectangle inset distances (l, r, t, b).
+	--- @param self Frame
+	--- @return number left The left inset.
+	--- @return number right The right inset.
+	--- @return number top The top inset.
+	--- @return number bottom The bottom inset.
+	--- @example
+	--- local left, right, top, bottom = myFrame:GetHitRectInsets()
+	GetHitRectInsets = function(self) end,
+
+	--- Gets the frame's maximum allowed resize bounds (w, h).
+	--- @param self Frame
+	--- @return number maxWidth The maximum width.
+	--- @return number maxHeight The maximum height.
+	--- @example
+	--- local maxWidth, maxHeight = myFrame:GetMaxResize()
+	GetMaxResize = function(self) end,
+
+	--- Gets the frame's minimum allowed resize bounds (w, h).
+	--- @param self Frame
+	--- @return number minWidth The minimum width.
+	--- @return number minHeight The minimum height.
+	--- @example
+	--- local minWidth, minHeight = myFrame:GetMinResize()
+	GetMinResize = function(self) end,
+
+	--- Gets the number of "children" (frames and things derived from frames) this frame has.
+	--- @param self Frame
+	--- @return number numChildren The number of children.
+	--- @example
+	--- local numChildren = myFrame:GetNumChildren()
+	GetNumChildren = function(self) end,
+
+	--- Returns the number of "regions" (fontstrings, textures) belonging to this frame.
+	--- @param self Frame
+	--- @return number numRegions The number of regions.
+	--- @example
+	--- local numRegions = myFrame:GetNumRegions()
+	GetNumRegions = function(self) end,
+
+	--- Returns the "regions" (fontstrings, textures) of the frame (multiple return values) belonging to this frame.
+	--- @param self Frame
+	--- @return ... any regions The regions belonging to this frame.
+	--- @example
+	--- local regions = {myFrame:GetRegions()}
+	GetRegions = function(self) end,
+
+	--- Gets the scale factor of this object relative to its parent.
+	--- @param self Frame
+	--- @return number scale The scale factor.
+	--- @example
+	--- local scale = myFrame:GetScale()
+	GetScale = function(self) end,
+
+	--- Gets the function for one of this frame's handlers.
+	--- @param self Frame
+	--- @param handler string The handler name.
+	--- @return function handlerFunction The handler function.
+	--- @example
+	--- local handlerFunction = myFrame:GetScript("OnClick")
+	GetScript = function(self, handler) end,
+
+	--- Returns true if the frame can be given a handler of the specified type.
+	--- @param self Frame
+	--- @param handler string The handler name.
+	--- @return boolean canHaveHandler True if it can have the handler.
+	--- @example
+	--- local canHaveHandler = myFrame:HasScript("OnClick")
+	HasScript = function(self, handler) end,
+
+	--- Hooks a secure frame script.
+	--- @param self Frame
+	--- @param handler string The handler name.
+	--- @param func function The function to hook.
+	--- @example
+	--- myFrame:HookScript("OnClick", function() print("Clicked!") end)
+	HookScript = function(self, handler, func) end,
+
+	--- Sets whether the frame is prohibited from being dragged off screen.
+	--- @param self Frame
+	--- @param clamped boolean True to enable clamping.
+	--- @example
+	--- myFrame:SetClampedToScreen(true)
+	SetClampedToScreen = function(self, clamped) end,
+
+	--- Modifies the frame's rectangle used to prevent dragging offscreen.
+	--- @param self Frame
+	--- @param left number The left inset.
+	--- @param right number The right inset.
+	--- @param top number The top inset.
+	--- @param bottom number The bottom inset.
+	--- @example
+	--- myFrame:SetClampRectInsets(5, 5, 5, 5)
+	SetClampRectInsets = function(self, left, right, top, bottom) end,
+
+	--- Sets the inset distances for the frame's hit rectangle.
+	--- @param self Frame
+	--- @param left number The left inset.
+	--- @param right number The right inset.
+	--- @param top number The top inset.
+	--- @param bottom number The bottom inset.
+	--- @example
+	--- myFrame:SetHitRectInsets(5, 5, 5, 5)
+	SetHitRectInsets = function(self, left, right, top, bottom) end,
+
+	--- Sets the ID of this frame.
+	--- @param self Frame
+	--- @param id number The ID to set.
+	--- @example
+	--- myFrame:SetID(1)
+	SetID = function(self, id) end,
+
+	--- Sets the maximum dimensions this frame can be resized to.
+	--- @param self Frame
+	--- @param maxWidth number The maximum width.
+	--- @param maxHeight number The maximum height.
+	--- @example
+	--- myFrame:SetMaxResize(800, 600)
+	SetMaxResize = function(self, maxWidth, maxHeight) end,
+
+	--- Sets the minimum dimensions this frame can be resized to.
+	--- @param self Frame
+	--- @param minWidth number The minimum width.
+	--- @param minHeight number The minimum height.
+	--- @example
+	--- myFrame:SetMinResize(200, 150)
+	SetMinResize = function(self, minWidth, minHeight) end,
+
+	--- Sets whether the frame can be resized.
+	--- @param self Frame
+	--- @param isResizable boolean True to make the frame resizable.
+	--- @example
+	--- myFrame:SetResizable(true)
+	SetResizable = function(self, isResizable) end,
+
+	--- Sets the scale factor of this frame relative to its parent.
+	--- @param self Frame
+	--- @param scale number The scale factor to set.
+	--- @example
+	--- myFrame:SetScale(1.5)
+	SetScale = function(self, scale) end,
+
+	--- Sets the function to use for a handler on this frame.
+	--- @param self Frame
+	--- @param handler string The handler name.
+	--- @param func function The function to set.
+	--- @example
+	--- myFrame:SetScript("OnClick", function() print("Clicked!") end)
+	SetScript = function(self, handler, func) end,
+
+	--- Sets whether the frame should raise itself when clicked.
+	--- @param self Frame
+	--- @param isTopLevel boolean True to set as top-level.
+	--- @example
+	--- myFrame:SetToplevel(true)
+	SetToplevel = function(self, isTopLevel) end,
+
+	--- Sets whether the frame has been relocated by the user.
+	--- @param self Frame
+	--- @param isUserPlaced boolean True to mark as user-placed.
+	--- @example
+	--- myFrame:SetUserPlaced(true)
+	SetUserPlaced = function(self, isUserPlaced) end,
+
+	--- Starts sizing this frame using the specified anchor point.
+	--- @param self Frame
+	--- @param point string The anchor point to use.
+	--- @example
+	--- myFrame:StartSizing("TOPLEFT")
+	StartSizing = function(self, point) end,
+
+	--- Indicates that this frame should no longer be notified when any events occur.
+	--- @param self Frame
+	--- @example
+	--- myFrame:UnregisterAllEvents()
 	UnregisterAllEvents = function(self) end,
-
-	---Unregisters the frame for an event. Once unregistered, the frame's OnEvent script handler will not be called for that event.
-	---
-	---Unregistering from notifications for an event can be useful for improving addon performance at times when it's not necessary to process the event. For example, a frame which monitors target health does not need to receive the UNIT_HEALTH event while the player has no target. An addon that sorts the contents of the player's bags can register for the BAG_UPDATE event to keep track of when items are picked up, but unregister from the event while it performs its sorting.
-	---@param self Frame
-	---@param event string Name of an event
-	UnregisterEvent = function(self, event) end,
-
-	---Returns whether the mouse cursor is over the given region. This function replaces the previous MouseIsOver FrameXML function.
-	---
-	---If provided, the arguments are treated as offsets by which to adjust the hit rectangle when comparing it to the mouse. They are in screen coordinates; positive offsets move an edge right or up, negative values move it left or down. No frame edges are actually moved. For example:
-	---
-	--- if button:IsMouseOver(2, -2, -2, 2) then
-	---
-	---will return true if the mouse is within 2 pixels of the given frame.
-	---@overload fun(self: Frame): boolean
-	---@overload fun(self: Frame, topOffset: number): boolean
-	---@overload fun(self: Frame, topOffset: number, leftOffset: number): boolean
-	---@overload fun(self: Frame, topOffset: number, leftOffset: number, bottomOffset: number): boolean
-	---@overload fun(self: Frame, topOffset: number, leftOffset: number, bottomOffset: number, rightOffset: number): boolean
-	---@param self Frame
-	---@param topOffset number The amount by which to displace the top edge of the test rectangle
-	---@param leftOffset number The amount by which to displace the left edge of the test rectangle
-	---@param bottomOffset number The amount by which to displace the bottom edge of the test rectangle
-	---@param rightOffset number The amount by which to displace the right edge of the test rectangle
-	---@return boolean isOver true if the mouse is over the region; otherwise false
-	IsMouseOver = function(self, topOffset, leftOffset, bottomOffset, rightOffset) end,
 }