WoW:XML/LayoutFrame

From AddOn Studio
< XML
Revision as of 21:18, 31 January 2015 by Bear (talk | contribs) (→‎Keys)
Jump to navigation Jump to search

← XML UI ← XML types < LayoutFrame

LayoutFrame is a base type used as a fundamental UI building block for defining UI screen layout. The LayoutFrame type can be used for Size, Position and Animation, and provides a base type for Texture, FontString, Frame, and others. Used as the TitleRegion property.

Inheritance

Inherited by: Frame,Texture,FontString, Inherits: none, Defined in: none

Elements

Attributes

  • name (string) - the name of the element. creates a Lua global variable holding a reference to this element at runtime. Prefixing with '$parent' replaces with next named parents name.
  • parentKey (string) - name for a Lua key in the parent element, which will reference this element at runtime.
  • parentArray (string) - name for a Lua array in the parent, to hold a reference to this element at runtime.
  • inherits (string) - name of the virtual element as to use a template, to inherit properties and attributes from.
  • virtual (boolean) - marks frame as inheritable type, causing runtime to not create frame. Default is false.
  • setAllPoints (boolean) - Automatically anchors the TOPLEFT and BOTTOMRIGHT points to the parent.
  • hidden (boolean) - Makes the element hidden by default.

Summary

LayoutFrame based elements facilitate the 'Layout' mechanism in the WoW UI. When used with <Size> along with the <Anchors> element, allow WoW to position all of its visible and interactive elements on the screen, including the 3D views of the world. LayoutFrame works by providing a flexible set of size or positional constructs.

Example

<Frame name="MyFrameTemplate" hidden="true" virtual="true"/>
<Frame name="MyFrame" inherts="MyFrameTemplate">
  <Size x="400" y="400"/>
    <Layers>
      <Layer>
        <FontString parentKey="Name" inherits="MyFont" text="Bob"/>
      </Layer>
    </Layers>
  <Frames>
    <Framename="$parentChild">
      <Size x="200" y="100"/>
      <Anchors>
        <Anchor relativeKey="$parent.Name" point="TOP" relativePoint="BOTTOM">
          <Offset>
            <AbsDimension x="0" y="-22" />
          </Offset>
        </Anchor>
      </Anchors>         
    </frame>
  </Frames>
</Frame>

This example will align the top of the 'child' frame to the bottom of the FontString in 'MyFrame' by using 'parentKey' 'relativeKey' references, and then offset that alignment by -22 vertically. Also demonstrates use of Dimension with Size and 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.

Details

Names

Gets registered in the LUA global variables. Using the $parent tag on a name refers to the parent's name - or the parent's parent's name, if the parent is unnamed, or even further up. For readability and errors avoiding it's strongly recommended to avoid same names with different letters.

You can use "$parent" inside name, this one will be replaced with parent attribute of element to form final name: 

<Button name="$parentButton" parent="MyFrame">

gives out "MyFrameButton" name for element. When used without parent attribute it replaces with name of first named parent element. This needs for templates - if you use elements in template they will take name from real parent, not template one: 

<Frame name="FrameTemplate" virtual="true">
  ...
  <Button name="$parentButton"/>
  ... 
</Frame">
<Frame name="RealFrame" inherits="FrameTemplate">

will result in creation of element "RealFrame" with "RealFrameButton" inside it. If parent attribute undefined name of container of element used. 

<Frame Name="NamedFrame">
  ...
  <Frame>
    ...
    <Button name="$parentButton">
      ...
    </Button>
  </Frame>
</Frame>

Will create button named NamedFrameButton.

Keys

Setting 'parentKey' or 'parentArray' will add a named Lua variable referencing this object to its parent object at runtime. Both can be used at the same time. Setting 'parentArray' will add this object to a named array in its parent, and setting 'parentKey' will create a simple Lua member to this object in the parent with that name. For 'parentKey' conflicts, the last element loaded using the same key name on the same parent will be the one referenced. For 'parentArray', multiple elements with the same key name on the same parent will simply be added to the array.

Inherited 'parentKey' or 'parentArray' values are not overridden as usual, but are additive. If a 'parentKey' is set on both the inherited and inheriting element with different names, then both keys will be added to the parent and set to the same child. If multiple children in the same parent inherit the same template with a 'parentKey' set in the template, then that key will be set to the last child to load. Likewise, a template with 'parentArray' set would create or add to an array in the parent, in addition to whatever 'parentArray' key may be set in the inheriting element, and elements can get added more than once if any up the inheritance chain are set to the same key. These behaviors can be both incredibly confusing, like code targeting wrong element, and incredibly convenient, like adding all children to an array using one attribute in one template.

For Anchors within XML, 'parentKey' can be used with 'relativeKey', just like 'name' and 'relativeTo' are, to make an anchor point relative to another layout frame. Similarly must be prefixed to make it mean 'look in the parent', like '$parent.keyName' including the '.', to reference another child on the same parent. However, 'relativeKey' by default references a key set on itself, rather than a global name like 'relativeTo' does.

With 'name' based anchors: 

name="$parentChild1" (on child 1)
relativeTo="$parentChild1" (on child 2)

With 'key' based anchors: 

parentKey="Child1" (on child 1)
relativeKey="$parent.Child1" (on child 2)
Retrieved from "https://addonstudio.org/mw/index.php?title=WoW:XML/LayoutFrame&oldid=16207"