Editing WoW:UI XML tutorial (section)

== Managing Frames ==

''Note:'' A lot of this section applies to all user interface [[widget]]s, not just [[frame]]s. Properties for layout, sizing and so on are common to all widgets.

=== Layout ===

Frames have a combination of a size and one or more [[anchors]].  For a frame to be laid out, the combination of these needs to define a rectangle on the screen in which the frame is to be laid out.

A size is specified using a <tt>Size</tt> element with either an <tt>AbsDimension</tt> or <tt>RelDimension</tt> child element.

[[Anchors]] allow for relative positioning, and also to allow frames to dynamically reposition their content based on resizing.  A group of anchors is expressed via an <tt>Anchors</tt> element with one or more <tt>Anchor</tt> children, each of which may have an <tt>Offset</tt>.

Some examples: ''TODO: Get screenshots of all of these''

 <Frame>
  <Size><AbsDimension x="100" y="100"/></Size>
  <Anchors>
   <Anchor point="TOPLEFT"/>
  </Anchors>
 </Frame>

This specifies a 100x100 frame anchored so that its top left is at the top left of its parent frame.

 <Frame>
  <Size><RelDimension x="0.5" y="0.5"/> </Size>
  <Anchors>
   <Anchor point="LEFT"/>
  </Anchors>
 </Frame>

This specifies a frame that covers a quarter of your [[UI]] (regardless to the selected resolution).

 <Frame>
  <Size><AbsDimension x="100" y="100"/></Size>
  <Anchors>
   <Anchor point="TOPLEFT" relativePoint="TOPRIGHT"/>
  </Anchors>
 </Frame>

This specifies a 100x100 frame [[anchor]]ed so that its top left is at the top right of its [[parent]] frame.

 <Frame>
  <Size><AbsDimension x="100" y="100"/></Size>
  <Anchors>
   <Anchor point="TOPLEFT" relativeTo="SomeOtherFrame">
    <Offset><AbsDimension x="10" y="-10"/></Offset>
   </Anchor>
  </Anchors>
 </Frame>

This specifies a 100x100 frame anchored at the top left of the frame <tt>SomeOtherFrame</tt>, and offset by 10 pixels to the right and 10 pixels down.  (Note that the Y axis increases from the bottom up, so negative Y coordinates indicate downwards movement).

 <Frame>
  <Anchors>
   <Anchor point="TOPLEFT" relativeTo="SomeOtherFrame">
    <Offset><AbsDimension x="5" y="-5"/></Offset>
   </Anchor>
   <Anchor point="BOTTOMRIGHT" relativeTo="SomeOtherFrame">
    <Offset><AbsDimension x="-5" y="5"/></Offset>
   </Anchor>
  </Anchors>
 </Frame>

Note that no <tt>Size</tt> is specified here; the size and location of this frame is defined entirely by its relationship to <tt>SomeOtherFrame</tt>.  In particular, it will be inset by 5 pixels from the top left and bottom right of <tt>SomeOtherFrame</tt>.  As <tt>SomeOtherFrame</tt> changes size, our frame will change size as well.

=== Showing/Hiding ===

Frames may be shown or hidden by [[API LayoutFrame Hide|''FrameName'':Hide()]] and [[API LayoutFrame Show|''FrameName'':Show()]].  Also available are [[API ShowUIPanel|ShowUIPanel(''FrameName'')]] and [[API HideUIPanel|HideUIPanel(''FrameName'')]].

=== Layers and Textures ===
There are five [[XML/DRAWLAYER|levels]] of [[layer]]s, although in practice you will often only assign objects to three of the five.   Of these three, BACKGROUND is in the back, ARTWORK is in the middle and OVERLAY is in front.  The only way to be certain of where and how much of your object is visible is to assign it to a specific layer.

BACKGROUND - Level 0. Place the background of your frame here.<BR />
BORDER - Level 1. Place the border art of your frame here .<BR />
ARTWORK - Level 2. Place the artwork of your frame here.<BR />
OVERLAY - Level 3. Place your text, objects, and buttons in this level<BR />
HIGHLIGHT - Level 4. Place your text, objects, and buttons in this level<BR />
*Elements in the '''HIGHLIGHT''' Layer are '''automatically shown or hidden''' when the mouse enters or leaves!
*For Highlighting to work you need '''enableMouse="true"''' in your ''<Frame>'' attributes.


''Note: The above are capitalized for a reason. See example:''<BR />
<pre>
<Layers>
  <Layer level="BACKGROUND">
    ...
  </Layer>
  <Layer level="ARTWORK">
    ...
  </Layer>
  <Layer level="OVERLAY">
    ...
  </Layer>
</Layers>
</pre>
=== Using Templates ===
Templates are used when you want to create a common layout for several frames. In this way you can save on the amount of code needed to recreate each frame, as the frames will automatically take on the properties, children, and attributes from whatever template it inherits. There are several rules that must be following when initially creating the template:
<ul><li>Templates are created at the root of the file. Meaning that you cannot have a template that is a child of another element</li><li>Templates must have their virtual attributes set to true</li><li>Templates must have a name, and it cannot use the $parent keyword</li><li>Children of a template do not need to be named, but when doing so, you should use the $parent keyword</li></ul><br/>
As discussed above, there is a special keyword that can be used when naming something inside the template. When you inherit a frame, any object inside the template that is inherited, which has the keyword $parent, will automatically replace the keyword with the name of the parent which inherited the template. Example:

 <Button name="MyAddonButtonTemplate" parent="UIParent" virtual="true">
      <ButtonText name="$parentText"/>
 </Button>
 <Button name="MyAddonSpecialButton" inherits="MyAddonButtonTemplate">
      <Size><AbsDimension x="40" y="22"/></Size>
 </Button>

Is the same as doing:

 <Button name="MyAddonSpecialButton" parent="UIParent">
      <Size><AbsDimension x="40" y="22"/></Size>
      <ButtonText name="MyAddonSpecialButtonText"/>
 </Button>

Be aware that any inherited attributes, properties, or children can also be overridden. Example:

 <Button name="MyAddonButtonTemplate" parent="UIParent" movable="true" virtual="true">
      <ButtonText name="$parentText"/>
 </Button>
 <Button name="MyAddonSpecialButton" inherits="MyAddonButtonTemplate" movable="false">
      <Size><AbsDimension x="40" y="22"/></Size>
 </Button>

Is the same as doing:

 <Button name="MyAddonSpecialButton" parent="UIParent" movable="false">
      <Size><AbsDimension x="40" y="22"/></Size>
      <ButtonText name="MyAddonSpecialButtonText"/>
 </Button>

Templates can inherit other templates as well. When done in this way, any $parent keywords used in the template being inherited carry over to the template that inherits it. Example:

 <Button name="MyAddonButtonTemplate1" parent="UIParent" movable="true" virtual="true">
      <ButtonText name="$parentText"/>
 </Button>
 <Button name="MyAddonButtonTemplate2" clampedToScreen="true" inherits="MyAddonButtonTemplate1" virtual="true">
      <NormalFont inherits="GameFontNormal"/>
 </Button>
 <Button name="MyAddonSpecialButton" inherits="MyAddonButtonTemplate2">
      <Size><AbsDimension x="40" y="22"/></Size>
 </Button>

Is the same as doing:

 <Button name="MyAddonSpecialButton" parent="UIParent" clampedToScreen="true" movable="true">
      <Size><AbsDimension x="40" y="22"/></Size>
      <ButtonText name="MyAddonSpecialButtonText"/>
      <NormalFont inherits="GameFontNormal"/>
      <HighlightFont inherits="GameFontHighlight"/>
 </Button>