Using Widget Templates

From Multiverse

User Interface Development

Overview  •  Managing Widgets  •  Event Handling  •  Using Widget Templates  •  Customizing Key Bindings  •  Localizing UI Text  •  Character Creation Framework  •  Minimap Component  •  Scripting Avatar Appearance

Reference

Widgets  •  Property Elements  •  Imageset Files

Tutorials

Hello World  •  Creating a Button  •  Creating a Menu  •  Creating a Help Dialog  •  Using Radio Buttons

Contents 1 Overview 2 Creating and using templates 3 Overriding inherited values 4 Templates inheriting from templates

Overview

Widget templates enable you to create a "virtual widget layout" that is inherited by other widgets, referred to as child widgets of the virtual widget. Child widgets automatically take on the properties, children, and attributes of the parent template. Thus, using templates reduces the amount of code required to create each frame.

NOTE: Some of the examples in this document do not work in the Multiverse Client, though they do illustrate the principles of templates and inheritance. We will correct this soon.

Creating and using templates

Define a template widget as you would a normal widget, but add the virtual attribute. For example, the following code defines a button template widget:

<Button name="MyButtonTemplate" virtual="true">
    <NormalText name="$parentText"/>
</Button>

Once you define a template widget, specify the name of the template in a widget's inherit attribute to make it inherit all the properties, children, and attributes of the template. The following code defines a button widget that inherits from the above template:

<Button name="MySpecialButton" inherits="MyButtonTemplate">
    <Size><AbsDimension x="40" y="22"/></Size>
</Button>

When creating a template, you must:

• Create it at the top level of the file (immediately within the <Ui> element). A template cannot be a child of another element.
• Set virtual attribute to true
• Give it a literal name; you cannot use the $parent keyword in the name.
• Use $parent in the names of child widgets, if they are named.

Use the $parent keyword for the names of property or child widget elements in the template. When a widget inherits from a template, it will substitute its name for $parent. Thus, in the example above, the button created would be the equivalent of the following:

<Button name="MySpecialButton" parent="UIParent">
    <Size><AbsDimension x="40" y="22"/></Size>
    <NormalText name="MySpecialButtonText"/>
</Button>

Notice how the <NormalText> element appended "MySpecialButton" and "Text" to get its name value, because the template specified name="$parentText".

Overriding inherited values

You can override inherited attributes, properties, or children. For example:

<Button name="MyButtonTemplate" virtual="true" text="Push Me!">
    <NormalText name="$parentText"/>
</Button>
<Button name="MySpecialButton" inherits="MyButtonTemplate" text="DO NOT Push Me!">
    <Size><AbsDimension x="40" y="22"/></Size>
</Button>

Is the same as:

<Button name="MySpecialButton" text="DO NOT Push Me!">
    <Size><AbsDimension x="40" y="22"/></Size>
    <NormalText name="MySpecialButtonText"/>
</Button>

Templates inheriting from templates

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. For example:

<Button name="MyButtonTemplate1" virtual="true">
    <NormalText name="$parentText"/>
</Button>
<Button name="MyButtonTemplate2" inherits="MyButtonTemplate1" virtual="true">
    <NormalFont inherits="GameFontNormal"/>
    <HighlightFont inherits="GameFontHighlight"/>
</Button>
<Button name="MySpecialButton" inherits="MyButtonTemplate2">
    <Size><AbsDimension x="40" y="22"/></Size>
</Button>

Is the same as:

<Button name="MySpecialButton" parent="UIParent">
    <Size><AbsDimension x="40" y="22"/></Size>
    <NormalText name="MySpecialButtonText"/>
    <NormalFont inherits="GameFontNormal"/>
    <HighlightFont inherits="GameFontHighlight"/>
</Button>