WoW:XML/Frame: Difference between revisions
Jump to navigation
Jump to search
m
Move page script moved page XML/Frame to WoW:XML/Frame without leaving a redirect
mNo edit summary |
m (Move page script moved page XML/Frame to WoW:XML/Frame without leaving a redirect) |
||
| (11 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{uixmlelem}} | |||
[[XML/Frame|Frame]] is a base type used as a fundamental UI building block for defining 'active' visible screen elements. The Frame type can be used for '''Layout''' due to [[XML/LayoutFrame|LayoutFrame]], and a full set of '''Appearance''' and '''Behaviour''' facilities. Provides a base type for [[XML/Button|Button]], [[XML/EditBox|EditBox]], [[XML/ScrollingMessageFrame|ScrollingMessageFrame]], and many others. | |||
== Inheritance == | |||
: Inherited by: [[XML/Button|Button]] ..., Inherits: [[XML/LayoutFrame|LayoutFrame]], Runtime object: [[UIOBJECT_Frame|Frame]] | |||
: Defined in: [[XML/Frames|Frames]], [[XML/Ui|Ui]] | |||
== Elements == | |||
* <[[XML/LayoutFrame|TitleRegion]]> | |||
==Elements== | * <[[XML/ResizeBounds|ResizeBounds]]> | ||
* <[[XML/ | |||
* <ResizeBounds> | |||
** <[[XML/Dimension|minResize]]> | ** <[[XML/Dimension|minResize]]> | ||
** <[[XML/Dimension|maxResize]]> | ** <[[XML/Dimension|maxResize]]> | ||
* <[[XML/Backdrop|Backdrop]]> | |||
* <[[XML/ | * <[[XML/Inset|BackgroundInsets]]> | ||
* <[[XML | * <[[XML/Inset|HitRectInsets]]> | ||
* <[[XML | * <[[XML/Layers|Layers]]> | ||
* <Layers> | |||
** <[[XML/Layer|Layer]]>... | ** <[[XML/Layer|Layer]]>... | ||
* </ | * <[[XML/Frames|Frames]]> | ||
** <[[XML/Frame|Frame]]>... | ** <[[XML/Frame|Frame]]>... | ||
* </ | * <[[XML/Scripts|Scripts]]> | ||
* < | ** <[[XML/Script|Script]]>... - See [[Widget handlers]]. | ||
** ( | * <[[XML/Attributes|Attributes]]> | ||
* </Scripts> | ** <[[XML/Attribute|Attribute]]>... | ||
===Inherited Elements: from [[XML/LayoutFrame|LayoutFrame]]=== | |||
* <[[XML/Dimension|Size]]> | |||
* <[[XML/Anchors|Anchors]]> | |||
** <[[XML/Anchor|Anchor]]> | |||
* <[[XML/KeyValues|KeyValues]]> | |||
** <[[XML/KeyValue|KeyValue]]> | |||
* <[[XML/Animations|Animations]]> | |||
** <[[XML/AnimationGroup|AnimationGroup]]>... | |||
*** <[[XML/Animation|Animation]]>... | |||
== Attributes == | |||
* alpha {{attrtype|float|1.0}} - opacity of the frame, where 1.0 is opaque and 0.0 is fully transparent | |||
* parent {{attrtype|string}} - name frame to use as parent. Overrides natural XML defined parent. Normally blank. | |||
* toplevel {{attrtype|boolean}} - if should be displayed on top of all the other frames in its strata. See frameStrata. | |||
* movable {{attrtype|boolean}} - if the frame can be moved by the user | |||
* resizable {{attrtype|boolean}} - if the frame can be resized by the user | |||
* frameStrata ([[XML/FRAMESTRATA|FRAMESTRATA]]) - which layer your frame should be on. Normally blank. Default is 'PARENT'. | |||
* frameLevel {{attrtype|int}} - position in the strata, overrides parent and XML order. Normally blank. See [[#frameLevel and frameStrata]]. | |||
* id {{attrtype|int|0}} - arbitrary frame id, like '1','2','3'. Accessible in Lua at runtime. Usually blank. | |||
* enableMouse {{attrtype|boolean}} - if mouse events are sent to the frame | |||
* enableKeyboard {{attrtype|boolean}} - if keystroke events are sent to the frame | |||
* clampedToScreen {{attrtype|boolean}} - if the frame is kept inside the screen boundaries | |||
* protected {{attrtype|boolean}} - if the frame is allowed to run protected code (only allowed in Blizzard code). | |||
* jumpNavigateEnabled {{attrtype|boolean}} | |||
* jumpNavigateStart {{attrtype|boolean}} | |||
* intrinsic {{attrtype|boolean}} - marks frame as an intrinsic frame type | |||
=== Inherited from [[XML/LayoutFrame|LayoutFrame]]: === | |||
* name {{attrtype|string}} - the name of the element. Creates Lua global variable holding a reference to this element at runtime. Prefixing with '$parent' replaces with next named parents name. | |||
* parentKey {{attrtype|string}} - name for a Lua key in the parent element, which will reference this element at runtime | |||
* parentArray {{attrtype|string}} - name for a Lua array in the parent, to hold a reference to this element at runtime | |||
* inherits {{attrtype|string}} - name of the virtual element as to use a template, to inherit properties and attributes from. | |||
* virtual {{attrtype|boolean}} - marks frame as inheritable type, causing runtime to not create frame. Default is false. | |||
* setAllPoints {{attrtype|boolean}} - automatically anchors the TOPLEFT and BOTTOMRIGHT points to the parent | |||
* hidden {{attrtype|boolean}} - makes the element hidden by default | |||
== Summary == | |||
[[XML/Frame|Frame]] based elements facilitate 'Layout', 'Appearance' and 'Behaviour' mechanisms for the WoW UI at runtime. When used with <[[XML/Scripts|Scripts]]> along with the <[[XML/Anchors|Anchors]]> and the <'''Size'''> element from [[XML/LayoutFrame|LayoutFrame]], allows WoW to 'Layout' all of its visible and make them interactive and responsive, including the 3D views of the world. Frame works by providing a flexible set of layout and scripting constructs. Frames also provide a sophisicated 'Z order' based layering system, both in <[[XML/Layers|Layers]]> element and between the frames themselves. | |||
== | === Example === | ||
<[[XML/Frame|Frame]] name="MyFrameTemplate" hidden="true" virtual="true"/> | |||
<[[XML/Frame|Frame]] name="MyFrame" inherits="MyFrameTemplate"> | |||
<[[XML/Dimension|Size]] x="400" y="400"/> | |||
<[[XML/Frames|Frames]]> | |||
<[[XML/Frame|Frame]] name="$parentChild" parentKey="child"> | |||
<[[XML/Dimension|Size]] x="200" y="100"/> | |||
<[[XML/Anchors|Anchors]]> | |||
<[[XML/Anchor|Anchor]] point="TOP"> | |||
<[[XML/Dimension|Offset]]> | |||
<[[XML/AbsDimension|AbsDimension]] x="0" y="-22" /> | |||
</Offset> | |||
</Anchor> | |||
</Anchors> | |||
</Frame> | |||
</Frames> | |||
</Frame> | </Frame> | ||
This example will align the top of the 'child' frame to the top of 'MyFrame', and then offset that alignment by -22 vertically. Also demonstrates use of Dimension with '''Size''' and [[XML/Anchor|Anchor]], and using '''Abs''' and '''inline''' values, as well as use of '$parent' to specify the name of the child where the child 'name' will be 'MyFrameChild' at runtime. Finally this example shows use of 'inherits' and 'virtual' where 'MyFrameTemplate' is inherited by 'MyFrame' causing 'MyFrame' to inherit 'hidden' from 'MyFrameTemplate' making 'MyFrame' hidden by default. At runtime, you can refer to the child frame as either <tt>MyFrameChild</tt> or <tt>MyFrame.child</tt>. | |||
==Description== | == Details == | ||
=== Description === | |||
Frames are the building blocks of the visual components of the user interface. All of the various visual elements of the UI are types of Frame, and inherit most if not all of the basic frame properties, in addition to adding some more. Frames are defined in the various <tt>.xml</tt> files in the <tt>Interface</tt> directory (except for the <tt>Bindings.xml</tt> files, which provide key bindings). | Frames are the building blocks of the visual components of the user interface. All of the various visual elements of the UI are types of Frame, and inherit most if not all of the basic frame properties, in addition to adding some more. Frames are defined in the various <tt>.xml</tt> files in the <tt>Interface</tt> directory (except for the <tt>Bindings.xml</tt> files, which provide key bindings). | ||
== Events == | === Events === | ||
In addition to Frames being the things that you can see, Frames are also the things which UI and game events are delivered to. If you're writing code that needs to know about something, it will need a Frame (though not necessarily a visible one) to receive the event. There are many types of events, though often in AddOn development it refers to | In addition to Frames being the things that you can see, Frames are also the things which UI and game events are delivered to. If you're writing code that needs to know about something, it will need a Frame (though not necessarily a visible one) to receive the event. There are many types of events, though often in AddOn development it refers to an [[API event]] game event. rather than other UI events. | ||
A frame indicates its interest in events in a number of ways: | A frame indicates its interest in events in a number of ways: | ||
=== UI Interaction === | ==== UI Interaction ==== | ||
The <Scripts> XML element of a frame definition defines a bunch of different handler types, for most of these (<OnEvent> being the exception) the Frame will automatically be informed of the appropriate events when they occur, via the defined handler script. | The <Scripts> XML element of a frame definition defines a bunch of different handler types, for most of these (<OnEvent> being the exception) the Frame will automatically be informed of the appropriate events when they occur, via the defined handler script. | ||
=== Game Interaction === | ==== Game Interaction ==== | ||
Most of the useful information comes from game events, which are all passed to the frame via the generic <OnEvent> script handler. There are literally hundreds of types of Game Events, so rather than spend a lot of time passing every event to every handler, an AddOn must register its interest in a frame receiving a certain event. This is accomplished through the [[API RegisterEvent|Frame:RegisterEvent("event")]] function, and is typically performed within the <OnLoad> or <OnShow> handlers. | Most of the useful information comes from game events, which are all passed to the frame via the generic <OnEvent> script handler. There are literally hundreds of types of Game Events, so rather than spend a lot of time passing every event to every handler, an AddOn must register its interest in a frame receiving a certain event. This is accomplished through the [[API Frame RegisterEvent|Frame:RegisterEvent("event")]] function, and is typically performed within the <OnLoad> or <OnShow> handlers. | ||
Once an event has been registered, the Frame's <OnEvent> handler will be called whenever that event occurs. | Once an event has been registered, the Frame's <OnEvent> handler will be called whenever that event occurs. | ||
== Virtual Frames == | === Virtual Frames === | ||
Frames can be defined as virtual, in which case instead of defining an actual UI element that shows up, the definition provides a template which can then be used multiple times by other Frames. A good example of a virtual Frame is the chat window, there are actually several virtual frames which are assembled into a chat window, but then each potential chat window simply implements the virtual one, which reduces the amount of duplicated code required. | Frames, like all [[XML/LayoutFrame|LayoutFrame]] types, can be defined as virtual, in which case instead of defining an actual UI element that shows up, the definition provides a template which can then be used multiple times by other Frames. A good example of a virtual Frame is the chat window, there are actually several virtual frames which are assembled into a chat window, but then each potential chat window simply implements the virtual one, which reduces the amount of duplicated code required. | ||
=== Parents === | |||
Frames have a parent frame. By default, the parent of any child frame is the frame the child is defined in. | |||
<pre> | |||
<Frame name="Fame1"> | |||
<Frames> | |||
<Frame name="Fame2"><!-- Frame2's 'parent' is automatically Frame1 --> | |||
</Frame> | |||
</Frames> | |||
</Frame> | |||
</pre> | |||
; Visibility | |||
Each Frame can be shown and hidden. If a Frame is Hidden, then it and all of its children cease to be visible. It's far simpler to show and hide the parent frame of a complex set, than to try and manage the visibility of many elements independently. | |||
; Scaling | |||
The UI engine is built to perform automatic scaling of UI elements, the entire UI (actually, the UIParent frame, which most frames are children of), or any component of it can be enlarged or shrunk to fit on a screen appropriately. Frames are scaled and located relative to their parent rather than the whole screen, which means that you only need to worry about how your subcomponents relate to each other, and then your component can be placed and sized any way necessary. | |||
; Notes | |||
Complex visual elements are usually formed using many frames. It's considered good design to have a single related parent frame amongst them. By default, all child frames already use the frame they are defined in as their parent. If some of the frames are defined separately, they can still explicitly set their parent to a common frame, using the 'parent' attribute, and have the rest use that (or its children) as their parent. | |||
Well behaved UI AddOns will normally want their top-level parent frame, the highest-level frame that is not defined in another frame, to be set expressly to 'UIParent'. Failure to do so means, amongst other things, that the AddOn's frame won't vanish when the Hide UI key is pressed. | |||
== Frame Levels == | === Frame Levels === | ||
Frame levels are that which determines what frame will be on top of other frame. Each frame has a frame level value. If frame A is placed in the same area as frame B, then the frame with the highest frame level will be on top of the other frame. | Frame levels are that which determines what frame will be on top of other frame. Each frame has a frame level value. If frame A is placed in the same area as frame B, then the frame with the highest frame level will be on top of the other frame. | ||
Instead of going around and specifying that frame A should have frame level 12, and frame B frame level 15, Blizzard uses a set of predefined "groups" of frame levels called frameStrata. The valid values for frameStrata are "PARENT", "BACKGROUND", "LOW", "MEDIUM", "HIGH", "DIALOG", "FULLSCREEN_DIALOG" and "TOOLTIP" (there may be more). For the values "BACKGROUND" through "TOOLTIP" the values are listed in their assumed ascendancy (i.e. it is assumed that "BACKGROUND" will be below "LOW"). The default value is "PARENT" if no frameStrata is specified. | Instead of going around and specifying that frame A should have frame level 12, and frame B frame level 15, Blizzard uses a set of predefined "groups" of frame levels called frameStrata. The valid values for frameStrata are "PARENT", "BACKGROUND", "LOW", "MEDIUM", "HIGH", "DIALOG", "FULLSCREEN_DIALOG" and "TOOLTIP" (there may be more). For the values "BACKGROUND" through "TOOLTIP" the values are listed in their assumed ascendancy (i.e. it is assumed that "BACKGROUND" will be below "LOW"). The default value is "PARENT" if no frameStrata is specified. | ||
There is also a special attribute called toplevel - this means (hopefully) that the frame should be on top of any other frame (or, possibly, on top of any other frame in the same [[frameStrata]]). | There is also a special attribute called toplevel - this means (hopefully) that the frame should be on top of any other frame (or, possibly, on top of any other frame in the same [[XML/Frame|frameStrata]]). | ||
==What is the difference between frameLevel and frameStrata? | === frameLevel and frameStrata === | ||
:''What is the difference between frameLevel and frameStrata?'' | |||
Well first off, though you can set frameLevel in your <Frame> tag, frameLevel is dictated by XML nesting. Check this example out: | Well first off, though you can set frameLevel in your <Frame> tag, frameLevel is dictated by XML nesting. Check this example out: | ||