Please note: if you are upgrading from a previous version of XmlLayout, as with most Unity assets, it is best if you remove the previous version before importing the new one. Sometimes, files or folders may be removed or moved around within the XmlLayout installation between versions, which isn't covered by Unity's import/update process. While this is fairly rare, it is still safest to remove the existing installation prior to importing a new one.

This is especially important when updating to version v1.79, as several files have been moved and/or renamed.

If you wish to backup your configuration settings, make a backup of the UI/XmlLayout/Configuration/Resources/XmlLayout_Configuration file and then restore it once the import is complete (or, if you haven't deleted the existing files, just skip importing this file).

</InstallingXmlLayout>

</BasicConcepts>

</AddingANewXmlLayoutObject>

</TheXmlLayoutComponent>

<XmlLayout xmlns="XmlLayout"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="XmlLayout UI/XmlLayout/Configuration/XmlLayout.xsd">

</AutocompleteIntellisense>

</ForcingALayoutRebuildViaC>

Please note that in order to use event handling, the Force Rebuild On Awake property of the XmlLayout must be set to true.

<!-- XmlLayoutController.ButtonClicked() will be called when this button is clicked -->
<Button onClick="ButtonClicked();">Button Text</Button>

<!-- Whenever this slider's value changes, XmlLayoutController.SliderValueChanged(x) 
     will be called, where 'x' is the new value -->
<Slider onValueChanged="SliderValueChanged(selectedValue);" />

<!-- The XmlLayoutController.HighlightButton() and XmlLayoutControllerClearButtonHighlight() methods 
     will be called when the mouse enters and exits this element. 
     The button itself will be passed as an argument. -->
<Button onMouseEnter="HighlightButton(this);" onMouseExit="ClearButtonHighlight(this);">Button Text</Button>

<!-- XmlLayoutController.ButtonClickedTwo(aStringValue) will be called when this button is clicked -->
<Button onClick="ButtonClickedTwo(aStringValue);">Button Text</Button>

void ButtonClicked()
{
    Debug.Log("The button was clicked.");
}

void SliderValueChanged(float newValue)
{
    Debug.Log("The slider's value was changed to " + newValue + ".");
}

void HighlightButton(Button button)
{
    // Code to highlight the button
}

void ClearButtonHighlight(Button button)
{
    // Code to clear the button highlight
}

void ButtonClickedTwo(string stringValue)
{
    // Will output: 'ButtonClickedTwo - value received = 'aStringValue'
    Debug.Log("ButtonClickedTwo - value received = '" + stringValue + "'");    
}

</EventHandling>

<VerticalLayout padding="10" spacing="10" id="menuButtons">
    <!-- This is a template which will be used by the XmlLayoutController to create the menu buttons dynamically -->
    <Button id="menuButtonTemplate" active="false"></Button>          
</VerticalLayout>

public override void LayoutRebuilt(ParseXmlResult parseResult)
{
    if (parseResult != ParseXmlResult.Changed) return;

    // get the menu button container
    menuButtonGroup = xmlLayout.GetElementById("menuButtons");            

    // get the menu button template so that we can clone it
    var menuButtonTemplate = xmlLayout.GetElementById("menuButtonTemplate");

    // in this case, 'Examples' is populated in the editor
    foreach (var example in Examples)
    {
        var name = example.name;
                
        // Create a copy of the template
        var menuButton = GameObject.Instantiate(menuButtonTemplate);
        menuButton.name = name;                

        // Access the XmlElement component and initialise it for this new button
        var xmlElement = menuButton.GetComponent<XmlElement>();
        xmlElement.Initialise(xmlLayout, (RectTransform)menuButton.transform, menuButtonTemplate.tagHandler);

        // Add the xmlElement to the menuButtonGroup
        menuButtonGroup.AddChildElement(menuButton);
                
        // Set the necessary attributes, and Apply them
        xmlElement.SetAttribute("text", name);
        // the template is inactive (so as not to be visible), so we need to activate this button
        xmlElement.SetAttribute("active", "true");  
        // Call the SelectExample function (in this XmlEventReceiver) when this button is clicked
        xmlElement.SetAttribute("onClick", "SelectExample(" + name + ");"); 
        xmlElement.ApplyAttributes();                
    }
}

</CreatingElementsDynamically>

</WorkingWithFormData>

Tooltips can be set for any element using the tooltip attribute. This attribute does support rich text, although tags such as color, size, b, or i must first be HTML-encoded (this is not necessary if the tooltip is specified dynamically using code, only if defined within an Xml file).

Tooltips can be styled directly on the element (using the various attributes provided, or they may be styled for all elements using the special Tooltip tag within a defaults section.

Tooltips will always have their position clamped within their canvas, so that they never appear partially off-screen.

Example

<Defaults>
    <!-- Set the default tooltip border and text colors for all tooltips 
         (except in cases where the element (or element style) overrides the value) -->
    <Tooltip tooltipBorderColor="rgb(1,1,1)" tooltipTextColor="rgb(1,1,1)" />
</Defaults>

<!-- Simple tooltip positioned below the element -->
<Button tooltip="This is a simple tooltip" tooltipPosition="Below"></Button>

<!-- Tooltip with encoded rich text (<color=green>green</color>) -->
<Button tooltip="This tooltip has some &lt;color=green&gt;green&lt;/color&gt; text."></Button>

</Tooltips>

Most attribute value types are straightforward, however, there are a few which warrant an explanation.

• Color

  For color values, several formats are acceptable:

  • HTML (6 character hex) color codes e.g. #FFFFFF (white 100% opacity)
  • 8 character hex color codes e.g. #FFFFFFCC (white 80% opacity)
  • RGB color codes: e.g. rgb(1,1,1) (white 100% opacity)
  • RGBA color codes: e.g. rgba(1,1,1,0.8) (white 80% opacity)
• Color Block

  Color block values are used to specify the colors for elements such as buttons and input fields.

  Format: (normalColor|highlightedColor|pressedColor|disabledColor) where each color is formatted as above, e.g. #FFFFFF|#FFFFFF|#C8C8C8|rgba(0.78,0.78,0.78,0.5)

• Paths

  All paths are passed through Unity's Resources.Load(), and as such any referenced Sprites, AudioClips, Prefabs, etc. must be located within a Resources folder.

  As of v1.23, you can create custom resource collections, allowing you to reference assets outside of a Resources folder if you wish.

• Bool

  Boolean attributes can accept 1 (true), true, 0 (false), or false.

• RectOffset

  RectOffsets, e.g. padding, accept the following formats:

  • float(left) float(right) float(top) float(bottom) e.g. 5 5 10 10 (padding value of 5 on the left and right sides, and 10 on the top and bottom)
  • float (all sides) e.g. 10 (padding value of 10 on all sides)

</AttributeTypes>

These attributes can be applied to most Xml Elements.

</CommonAttributes>

The XmlLayout tag is the root tag of any XmlLayout Xml document - it must be present, and only elements contained within the XmlLayout tag will be parsed.

Please note that for the XmlLayout tag, these values must all be set in order to use Intellisense in Visual Studio

</XmlLayout>

The defaults Tag allows you to set default values for UI elements. Primarily this will be used to set styles and the like, but there is no restriction on what default values you can set.

Defaults can be applied to all instances of a particular tag type, or only those of a particular class (as set by the class attribute). Please note that elements may use more than one class (separated by spaces).

As with its HTML counterpart (CSS), XmlLayout Defaults are applied in a cascading fashion. This means that an element will always use the most recent value for an attribute - for example, if an element implements a class, it will use the attribute values defined by that class except when the element itself also defines those attributes (attributes defined on the element will always take precedence).

Defaults tags can be placed anywhere in the Xml document, but will only apply to elements after it.

Example

<Defaults>
    <!-- Set the default color and font size for all Text elements -->
    <Text color="#DDDDDD" fontSize="16" />
    
    <!-- Set the default color for all Text elements using the 'darker' class -->
    <Text class="darker" color="#AAAAAA" />

    <!-- Set the default background image for all Button images -->
    <Button image="Sprites/Layout/Button" />
</Defaults>

<!-- This text's color will be "#DDDDDD" and its font size will be "16" -->
<Text>Text</Text>

<!-- This text's color will be "#AAAAAA" and its font size will be "16" -->
<Text class="darker">Text</Text>

<!-- This button will use the background image "Sprites/Layout/Button" -->
<Button>Button Text</Button>

<!-- Set the default border and text color for all tooltips -->
<Tooltip tooltipBorderColor="rgb(1,1,1)" tooltipTextColor="rgb(1,1,1)" />

Nested Defaults

New in v1.44

In a similar fashion to CSS, you can now define nested defaults/styles for elements which will allow you to create more advanced default value definitions.

These definitions specify default values which should only be applied to elements which match the specified conditions, such as being contained by another element, so, for example, you can now apply styles to all buttons in a specific list without having to set a class for each one.

Descendant Operators

Descendant operators specify how the nested defaults rules are applied:

• : - If this operator is used, then so long as the element is a descendant of the specified parent, then the defaults values will be applied to it, even if the element is not a direct child of the specified parent.
• > - If this operator is used, then the defaults values will only be applied to the element if it is a direct child of the specified parent.

Class/Type operators

• @ - If this operator is used, then XmlLayout will match by tag type, rather than by class name.
• If no operator is used, then XmlLayout will match using class names.

Example

<Defaults>
    <!-- All Buttons have a fontSize of 30 -->
    <Button fontSize="30" />
    
    <!-- All Buttons using the class 'myButton' will be red -->
    <Button class="myButton" colors="red" />

    <!-- All Buttons that are within a VerticalLayout, at any level, 
         will have yellow text with a black outline -->
    <Button class="@VerticalLayout:@Button" textOutline="black" textColor="yellow" />

    <!-- Buttons using the class'myButton' that are nested within a Panel, 
         which is a direct child of a VerticalLayout, will be green -->
    <Button class="@VerticalLayout>@Panel:myButton" colors="green" />
        
    <!-- Buttons using the class 'myButton', that are nested directly 
         within an element using the 'myPanel' class, which is nested directly
         in a VerticalLayout, will have white text -->
    <Button class="@VerticalLayout>myPanel>myButton" textColor="white" />    
    
  </Defaults>



  <Panel height="50%" rectAlignment="UpperCenter">
    <!-- This button will be red, and have black text -->
    <Button class="myButton" text="Red / Black Text" />
  </Panel>

  
  <Panel height="50%" rectAlignment="LowerCenter">
    <VerticalLayout>
      
      <Panel class="myPanel">
        <!-- This button will be green, and will have white text -->
        <Button class="myButton" text="Green / White Text" />
      </Panel>
      
      <!-- This button will be red, and have yellow text -->
      <Button class="myButton" text="Red / Yellow Text" />
     
      <!-- This button will be white, and have yellow text -->
      <Button text="White / Yellow Text" />
    
    </VerticalLayout>
  </Panel>

Named Colors

As of v1.53, you can now define your own custom named colors to use in your XmlLayout code.

Named colors can only be defined within a defaults section

Example

<Defaults>
    <Color name="primary" color="rgb(0.5,0.5,0.5)" />
    <Color name="highlight" color="rgb(0.5,0.5,0.75)" />
    <Color name="text" color="rgb(1,1,1)" />
    
    <Panel color="primary" />
    <Panel class="highlighted" color="highlight" />

    <Button textColor="text" />
    <Text color="text" />
</Defaults>

Custom Animations

As of v1.85, you can now define your own custom named animations to use for showing and/or hiding elements.

Custom animations can only be defined within a defaults section.

Example

<Defaults>
    <Animation name="FadeInLinear" 
               duration="0.5" 
               attribute="CanvasGroup.alpha" 
               from="0" 
               to="1" 
               valueType="float" 
               curve="Linear" />
</Defaults>


<!-- Use the newly defined 'FadeInLinear' animation to show this button -->
<Button showAnimation="FadeInLinear" ... />

Animation Chains

Animations can also be chained, i.e. you can define an animation which consists of a set of other animations that are played one after the other.

The chain can consist of any number of animations, but it can only use other custom animations (it cannot reference built-in animations like Grow, Shrink, etc.)

Chained Animation Example

<Defaults>
    <Animation name="GrowExpo"
               duration="1" 
               attribute="RectTransform.localScale"
               from="0 0 0" 
               to="1 1 1" 
               valueType="Vector3"
               curve="ExpoEaseIn" />

    <Animation name="ChangeColor"
               duration="1" 
               attribute="Image.color" 
               from="rgb(1,1,1)" 
               to="rgb(1,0.2,0.2)" 
               valueType="Color" />

    <!-- Grow, then change color -->
    <Animation name="GrowThenChangeColor" type="Chained" animations="GrowExpo ChangeColor" />
</Defaults>

<Button showAnimation="GrowThenChangeColor" ... />

Simultaneous Animations

Animations can also be played simultaneously, i.e. you can define an animation which consists of a set of other animations that are played at the same time on the same element.

Any number of animations can be played simultaneously, but as with animation chains, it can only reference other custom animations. Additionally, it can only reference single animations - it will not function correctly with references to chains or other simultaneous animations.

Simultaneous Animation Example

<Defaults>
    <Animation name="GrowExpo"
               duration="1" 
               attribute="RectTransform.localScale"
               from="0 0 0" 
               to="1 1 1" 
               valueType="Vector3"
               curve="ExpoEaseIn" />

    <Animation name="ChangeColor"
               duration="1" 
               attribute="Image.color" 
               from="rgb(1,1,1)" 
               to="rgb(1,0.2,0.2)" 
               valueType="Color" />

    <!-- Grow AND change color at the same time -->
    <Animation name="GrowAndChangeColor" type="Simultaneous" animations="GrowExpo ChangeColor" />
</Defaults>

<Button showAnimation="GrowAndChangeColor" ... />

Curves

Animation curves specify how the values of your property should change over time. The default 'Linear' curve changes the value of the property evenly over time, whereas other curves change the value differently over time to create interesting effects. You may wish to experiment with different curves in your animations to see what gives the best end-result.

For an idea of how these curves look, see this link.

XmlLayout currently has the following curves available (more may be added in the future if there is demand for them):

• Linear (Default - Unity Standard AnimationCurve.Linear)
• EaseInOut (Unity standard AnimationCurve.EaseInOut)
• ExpoEaseIn
• ExpoEaseOut
• CubicEaseIn
• CubicEaseOut
• ElasticEaseIn
• ElasticEaseOut
• BounceEaseIn
• BounceEaseOut
• BounceEaseInOut
• BounceEaseOutIn
• BackEaseIn
• BackEaseOut

Hover / Press / Select Classes

The 'hoverClass' attribute allows you to define a defaults class to be applied to an element (or class) when it is hovered over with the pointer or highlighted.

Similarly, the 'pressClass' allows you to define a defaults class to be applied to an element (or class) when it is pressed (clicked on), and 'selectClass' defines attributes to apply when the element is selected (e.g. Tab Selection).

In both cases, attributes applied via the hover or press class will be removed when the element leaves the highlighted / pressed state.

Please note that in order for hover/press classes to work, the element must block raycasts.

Example

<Defaults>
    <!-- Firstly, suppress the default button 'ColorTint' behaviour by setting 'transition' to None -->
    
    <!-- Specify the default color for buttons in their usual state (in this case, 'white'), 
         and the default text color (in this case, 'black') -->
    
    <!-- Then, specify that buttons use the 'hover', 'press', 
         and 'select' classes for their respective states -->
    <Button hoverClass="hover" 
            pressClass="press" 
            selectClass="select" 
            color="white" 
            textColor="black" 
            transition="None" />
    
    <!-- When hovered over, make the button grey, and make the text color blue -->
    <Button class="hover" color="grey" textColor="blue" />

    <!-- When pressed, make the button cyan -->
    <Button class="press" color="cyan" />

    <!-- When selected, make the button red -->
    <Button class="select" color="red" />
  </Defaults>

Please note that the above example shows how you can change some attributes. This can be used on any element, not just buttons, but when using it with a Selectable element such as buttons which provide state transition attributes, please note that it is probably best to use one or the other (e.g. mixing and matching 'colors' and hover/press/select class) as it might be confusing to try and use both approaches simultaneously.

You may also notice that in the example, default values have been specified for both color and textColor, even though the values provided are the regular default values for button elements - the reason for this is that providing default values aids XmlLayout in returning attributes to their default value when changing state, e.g. returning to default state from hover. If no default attribute values are provided, XmlLayout will try and use default values for the attribute type, but this may not necessarily be the desired effect.

</Defaults>

The Include tag allows you to load the contents of another XmlFile and include them within the current Xml document. This is commonly used to load Defaults files, but can be used to include any other Xml document.

Example

<Include path="Xml/Styles.xml" />

</Include>

This tag allows you to create a child XmlLayout using the specified view and (optional) controller.

NOTE: if the parent view is rebuilt for any reason, the child will be recreated from scratch as with any other nested Xml element.

Example

<ChildXmlLayout viewPath="Path/To/View" controller="NameOfControllerClass" />

</ChildxmlLayout>

Text

The text tag is a Unity UI Text object.

This tag supports Rich Text as shown in the following example:

Example

<!-- Standard Text element -->
<Text>Some Text</Text>

<!-- Rich Text -->
<Text>
    This text is <b>Bold</b>, <i>Italic</i>, 
    and <textcolor color="#00FF00">Green</textcolor>.
    <br>
    This text is <textsize size="18">Larger</textsize>.
</Text>

Image

The image tag is a Unity UI Image object.

Example

<Image image="Path/To/Image" />

RawImage

The RawImage tag is a Unity UI RawImage object.

Example

<RawImage texture="Path/To/Image" />

</BasicElements>

Panel

The panel tag is a simple layout element.

Example

<Panel>
    <Text>Text contained within Panel</Text>
</Panel>

HorizontalLayout

The HorizontalLayout tag is a Unity UI HorizontalLayoutGroup object.

Example

<HorizontalLayout>
    <Button>Button One</Button>
    <Button>Button Two</Button>
    <Button>Button Three</Button>
</HorizontalLayout>

VerticalLayout

The VerticalLayout tag is a Unity UI VerticalLayoutGroup object.

Example

<VerticalLayout>
    <Button>Button One</Button>
    <Button>Button Two</Button>
    <Button>Button Three</Button>
</VerticalLayout>

GridLayout

The GridLayout tag is a Unity UI GridLayoutGroup object.

Example

<GridLayout>
    <Button>Button One</Button>
    <Button>Button Two</Button>
    <Button>Button Three</Button>
</GridLayout>

TableLayout

The TableLayout tag is a layout element based on HTML tables, allowing you to specify the position of elements in specific rows/columns.

Example

<TableLayout>
    <!-- Row 1 -->
    <Row>
        <Cell><Button>Button One</Button></Cell>
        <Cell><Button>Button Two</Button></Cell>
    </Row>
    <!-- Row 2 -->
    <Row>
        <Cell><Button>Button One</Button></Cell>
        <Cell><Button>Button Three</Button></Cell>
    </Row>
</TableLayout>

Row

A row within a TableLayout.

Cell

A cell within a TableLayout.

</LayoutElements>

InputField

A UnityUI text InputField which can be used to create both single and multi-line input fields.

Example

<InputField>Default Text</InputField>

Button

A UnityUI Button object with optional text and/or icon.

Example

<!-- Standard Button -->
<Button>Button Text</Button>
<!-- Button with Icon -->
<Button icon="Sprites/Icons/Arrow_Up" />
<!-- Button with Icon and Text -->
<Button icon="Sprites/Icons/Arrow_Left">Button With Icon</Button>

Toggle

A UnityUI Toggle object with optional text.

Example

<Toggle>Toggle Text</Toggle>
<!-- Toggle which is selected by default -->
<Toggle isOn="true">Toggle Text</Toggle>

ToggleButton

A UnityUI Toggle object styled as a button with optional text and/or icon.

Example

<ToggleButton>Toggle Button Text</ToggleButton>

ToggleGroup

A UnityUI ToggleGroup object which can consist of a group of Toggle elements (whether the are Toggles or ToggleButtons).

A LayoutGroup (VerticalLayout/HorizontalLayout/TableLayout/GridLayout) can be used to position the Toggle elements.

ToggleExample

<ToggleGroup>
    <VerticalLayout>
        <Toggle>Toggle A</Toggle>
        <Toggle>Toggle B</Toggle>
        <Toggle>Toggle C</Toggle>
    </VerticalLayout>
</ToggleGroup>

ToggleButtonExample

<ToggleGroup>
    <HorizontalLayout>
        <ToggleButton>ToggleButton A</ToggleButton>
        <ToggleButton>ToggleButton B</ToggleButton>
        <ToggleButton>ToggleButton C</ToggleButton>
    </HorizontalLayout>
</ToggleGroup>

Slider

A UnityUI Slider object.

Example

<Slider minValue="0" maxValue="1" value="0.5" />

Dropdown

A UnityUI Dropdown object.

Example

<Dropdown>
    <Option selected="true">Option 1</Option>
    <Option>Option 2</Option>
    <Option>Option 3</Option>
    <Option>Option 4</Option>
</Dropdown>

Working with Dropdown elements in code

Setting the options for a dropdown element is fairly easy - you can use the 'SetOptions()' extension method provided by XmlLayout. Similarly, setting the selected value using the 'SetSelectedValue()' method.

Code Example

// Get a reference to the dropdown element
var dropdown = xmlLayout.GetElementById<UnityEngine.UI.Dropdown>("myDropdown");

// Set its options
dropdown.SetOptions(new List<string>(){
                    "Option One",
                    "Option Two",
                    "Option Three"});

// set the selected value
dropdown.SetSelectedValue("Option One"); // Note: you can also use an index, e.g. 0

// get the selected value
int selectedIndex = dropdown.value;

// get the selected text (new in XmlLayout v1.89)
string selectedText = dropdown.GetSelectedValue();

</InputFields>

HorizontalScrollView

A UnityUI ScrollRect object set up to scroll horizontally.

A layout element such as a Panel, HorizontalLayout, GridLayout, or TableLayout can be used to position child elements within the Scroll View.

Example

<HorizontalScrollView>
    <HorizontalLayout>
        <Panel>
            <Text>1</Text>
        </Panel>
        <Panel>
            <Text>2</Text>
        </Panel>
        <Panel>
            <Text>3</Text>
        </Panel>
        <Panel>
            <Text>4</Text>
        </Panel>
    </HorizontalLayout>
</HorizontalScrollView>

VerticalScrollView

A UnityUI ScrollRect object set up to scroll vertically.

A layout element such as a Panel, VerticalLayout, GridLayout, or TableLayout can be used to position child elements within the Scroll View.

Example

<VerticalScrollView>
    <VerticalLayout>
        <Panel>
            <Text>1</Text>
        </Panel>
        <Panel>
            <Text>2</Text>
        </Panel>
        <Panel>
            <Text>3</Text>
        </Panel>
        <Panel>
            <Text>4</Text>
        </Panel>
    </VerticalLayout>
</VerticalScrollView>

</ScrollViews>

Mask

A UnityUI Mask object which can be used to mask nested elements.

Example

<Mask image="Sprites/MaskImage">
    <Panel>
        <Text>Masked Content</Text>
    </Panel>
</Mask>

</Masks>

Canvas

The Canvas element can be used to separate UI content into smaller logical sections, which may improve performance by allowing Unity to make layout updates to the content of one Canvas without needing to recalculate the others.

Byu default, a Canvas has no visual component and is merely a logical grouping (although it does have follow the same size/layout/etc. rules as other elements).

Example

<Canvas>
     <Panel>
          <Text>Content of First Canvas</Text>
     </Panel>
</Canvas>

<Canvas>
    <Panel>
          <Text>Content of Second Canvas</Text>
     </Panel>
</Canvas>

</Canvas>

ProgressBar

A simple Progress Bar which can have its percentage value changed at runtime.

Can be used with MVVM or MVC.

Example

<ProgressBar percentage="50" />

</ProgressBar>

Importing PagedRect

• Start off by importing PagedRect into your project as with any other package.
• Save your project, and that's it - XmlLayout will detect PagedRect and incorporate it into the XSD file (for autocomplete). You can now use PagedRect in your XmlLayout elements!
  It may be necessary to reload Visual Studio / Monodevelop.

PagedRect

PagedRect's various templates have each been turned into an XmlLayout tag, for a total of seven tags (one of which, PagedRect, is a duplicate of PagedRect_Horizontal_ScrollRect):

• PagedRect: This is a horizontal PagedRect, with an integrated ScrollRect (the most common configuration).
• PagedRect_Horizontal: This is a horizontal PagedRect (without a ScrollRect).
• PagedRect_Horizontal_ScrollRect: This is the same as the default PagedRect tag.
• PagedRect_PagePreviews_Horizontal: A horizontal PagedRect set up to use Page Previews.
• PagedRect_Vertical: This is a vertical PagedRect (without a ScrollRect).
• PagedRect_Vertical_ScrollRect: This is a vertical PagedRed, with an integrated ScrollRect.
• PagedRect_PagePreviews_Vertical: A vertical PagedRect set up to use Page Previews.
• PagedRect_Slider: This is a horizontal PagedRect in the slider configuration, commonly used for image galleries.
• PagedRect_Slider_ScrollRect: This is a horizontal PagedRect in the slider configuration, with an integrated ScrollRect.

Example

<!-- This will produce a horizontal PagedRect with an integrated ScrollRect -->
<PagedRect>
    <!-- This section controls the position and appearance of this PagedRects Pagination section -->
    <!-- The Pagination object is a layout group 
         (either vertical or horizontal depending on the PagedRect template used) -->
    <Pagination height="150" spacing="20">
        <!-- These control the appearance and size of this PagedRects buttons -->
        <PaginationButtonTemplate type="CurrentPage" colors="#FFFFFF|#FFFFFF|#FFFFFF" />
        <PaginationButtonTemplate type="OtherPages" colors="#DDDDDD|#FFFFFF|#DDDDDD" />
        
        <PaginationButtonTemplate type="Previous" text="Prev" />
        <PaginationButtonTemplate type="Next" text="Next" />        
    </Pagination>
    <Page>
        <!-- Page 1 Content -->
    </Page>
    <Page>
        <!-- Page 2 Content -->
    </Page>
    <Page>
        <!-- Page 3 Content -->
    </Page>
</PagedRect>

Page

Pagination

Introduced in v1.06

The Pagination tag controls the position and appearance of the pagination section of the PagedRect.

You can control its position using standard width/height/rectAlignment attributes. XmlLayout will automatically attempt to resize and reposition the viewport to match.

The Pagination element is also a LayoutGroup, either a VerticalLayoutGroup or HorizontalLayoutGroup depending on the PagedRect template used. As such, you can also control properties such as spacing, childForceExpandHeight, childForceExpandWidth, and Padding.

PaginationButtonTemplate

Introduced in v1.06

The PaginationButtonTemplate tag controls the appearance of the buttons in a PagedRect.

You can set the button type using the type attribute - which is required. A PaginationButtonTemplate without this attribute specified will be ignored by XmlLayout.

As with most XmlLayout elements, you can control the image, size, etc. using the relevant basic attributes.

</Pagedrect>

Importing UIObject3D

• Start off by importing UIObject3D into your project as with any other package.
• Save your project, and that's it - XmlLayout will detect UIObject3D and incorporate it into the XSD file (for autocomplete). You can now use UIObject3D in your XmlLayout elements!
  It may be necessary to reload Visual Studio / Monodevelop.

UIObject3D

Once UIObject3D has been imported, the UIObject3D element will become available for use within XmlLayout.

Examples

<UIObject3D objectPrefab="Path/To/Model" />

<UIObject3D objectPrefab="Path/To/Model" targetRotation="0 180 0" />

<UIObject3D objectPrefab="Path/To/Model" enableCameraLight="1" lightColor="rgb(1,0,1)" />

In addition to standard image attributes (e.g. color), UIObject3D also provides the following attributes:

RotateUIObject3D

This component will automatically rotate the UIObject3D over time in the specified direction(s) and rate(s).

Example

<UIObject3D objectPrefab="Path/To/Model">
     <RotateUIObject3D rotateX="1" rotateXSpeed="90" />
</UIObject3D>

DragRotateUIObject3D

This component will allow you to drag the UIObject3D and have it rotate accordingly.

Example

<UIObject3D objectPrefab="Path/To/Model">
     <DragRotateUIObject3D rotateX="1" rotateY="1" sensitivity="0.4" />
</UIObject3D>

</Uiobject3d>

Importing DatePicker

• Start off by importing DatePicker into your project as with any other package.
• Save your project, and that's it - XmlLayout will detect DatePicker and incorporate it into the XSD file (for autocomplete). You can now use DatePicker in your XmlLayout elements!
  It may be necessary to reload Visual Studio / Monodevelop.

DatePicker

DatePicker's various templates have each been turned into an XmlLayout tag:

• DatePicker: This is a popup DatePicker attached to an InputField.
• DatePickerInline: This is an inline DatePicker.
• DatePickerDateRange: This is a DatePicker DateRange selector (two popup DatePickers set up to select a date range).

Simple Examples

<!-- This is a standard popup DatePicker attached to an InputField -->
<DatePicker selectedDate="2016-08-08" />

<!-- This is an inline DatePicker -->
<DatePickerInline selectedDate="2016-08-08" />

<!-- This is a DatePicker DateRange selector (two popup DatePickers set up to select a date range) -->
<DatePickerDateRange fromDate="2016-08-04" toDate="2016-08-08" />

DatePicker configuration is handled in a similar fashion to that of PagedRects Pagination - most of its attributes are grouped in child tags, e.g. the DP_Animation tag has all of the animation-related attributes for the DatePicker. All of these child tags are optional.

Configuration Example

<DatePicker selectedDate="2016-08-08">

    <!-- This section controls miscellaneous options -->
    <DP_MiscConfig showDatesInOtherMonths="true" />

    <!-- This section controls the sizing of the DatePicker -->
    <DP_Sizing overrideTransformHeight="true" preferredHeight="384" />

    <!-- This section controls whether or not the popup DatePicker is modal,
         and the appearance/functionality of the screen overlay -->
    <DP_Modal isModal="true" screenOverlayColor="rgba(0,0,0,0.5)" />

    <!-- This section allows you to restrict the dates which can be selected in the DatePicker -->
    <DP_DateRange restrictFromDate="true" fromDate="2016-08-03" restrictToDate="true" toDate="2016-08-12" />

    <!-- This section allows you to change the date format used by the DatePicker -->
    <DP_Format dateFormat="yyyy-MM-dd" />

    <!-- This section allows you to control the appearance of the border around the DatePicker -->
    <DP_Border size="2" color="rgba(1,1,1,0.25)" />

    <!-- This section allows you to control the appearance and functionality
         of the DatePickers header -->
    <DP_Header textColor="rgb(0,1,1)" font="Arial">
        <!-- You can use DP_HeaderButton tags to control the appearance 
             of the next/previous year/month buttons. You can specify attributes for all of them
             at once, or for individual buttons using the 'type' attribute to specify which -->
        <DP_HeaderButton colors="rgba(1,1,1,0.5),rgb(1,1,1),rgba(1,1,1,0.5),rgba(1,1,1,0.25)" />
    </DP_Header>

    <!-- This section allows you to control the appearance of the Week Day headings -->
    <DP_WeekDays textColor="rgb(0,1,1)" />

    <!-- This section allows you to control the appearance of the days in the DatePicker -->
    <DP_Days>
        <!-- You can use the DP_Day tags to control the appearance of the days.
             You can specify the attributes for all types at once, or for individual types
             using the 'type' attribute to specify which -->
        <DP_Day type="selectedDay" textColor="rgb(1,0,0)" />
    </DP_Days>

    <!-- This section allows you to specify which animations (if any) should be used
         when the DatePicker is shown, hidden, and when the visible month is changed -->
    <DP_Animation showAnimation="fade" hideAnimation="fade" />

    <!-- This section allows you to specify events to trigger when dates are selected/etc. -->
    <DP_Events onDaySelected="DateSelected(selectedDate);" />
</DatePicker>

</Datepicker>

Importing TextMesh Pro

Just download TextMesh Pro from the Unity Asset Store and import it into your project. XmlLayout will automatically detect it and the <TextMeshPro> tag will become available for use.

The TextMeshPro Tag

The TextMeshPro tag will create an instance of TextMesh Pro and apply the specified attributes to it, allowing you to create text elements with advanced styling.

TextMeshPro Tag Example

<Panel width="640" height="256" color="rgb(0.5,0.5,0.5)" image="Sprites/Layout/Base" padding="32">

    <TextMeshPro font="Fonts &amp; Materials/Bangers SDF" 
                 fontMaterial="Fonts &amp; Materials/Bangers SDF - Drop Shadow"
                 fontStyle="Bold"
                 fontSizeMin="25" fontSizeMax="100" enableAutoSizing="1"
                 alignment="Midline"
                 color="white"
                 outlineColor="black"
                 outlineWidth="0.2"
                 wordSpacing="2" characterSpacing="2" lineSpacing="25" paragraphSpacing="10"
                 colorGradient="rgb(0.2,0.7,0)|rgb(0.2,0.7,0)|rgb(0.2,0.9,0)|rgb(0.2,0.9,0)"
                 enableWordWrapping="false"
                 spriteAsset="Sprite Assets/Default Sprite Asset">
      <![CDATA[
      TextMesh Pro
      <size=50%><font="LiberationSans SDF"  material="LiberationSans SDF - Outline"><color=#DDDD00>
        (in XmlLayout <sprite=0>)
      </color></font></size>
      ]]>
    </TextMeshPro>

  </Panel>

As you can see, if you wish to use rich text (as with the standard <Text> tag, you'll need to use a CDATA block, as the rich text tags are not valid Xml.

Custom fonts, materials, sprite assets, etc. will need to be accessible to XmlLayout's Resource Database system (either in a Resources folder, or in a Resource Database) in order for them to be useable by the TextMeshPro tag.

Using TextMeshPro with Button and Toggle Elements

In order to use TextMesh Pro with Button or Toggle Elements, you'll need to add a <TextMeshPro> as a child of the Button/Toggle. From there, you can customise it as you would any other TextMeshPro tag.

When using this approach, any attributes specified on the TextMeshPro child element will override those specified by the parent (e.g. color).

Buttons

<Button>
     <TextMeshPro text="Button Text" fontStyle="Bold" />
</Button>

Toggles

<Toggle>
     <TextMeshPro text="Toggle Text" fontStyle="Bold" />
</Toggle>

The TextMeshProInputField Element

TextMesh Pro cannot be used with default InputField elements, so an alternative element, <TextMeshProInputField> has been provided. This element is functionally identical to a standard InputField.

Example

<TextMeshProInputField>
      <TMP_Text text="Input Field Text" />
      <TMP_Placeholder text="Placeholder Text" />
</TextMeshProInputField>

The TextMeshProDropdown Element

As with InputFields, TextMesh Pro cannot be used with standard Dropdown elements, so the <TextMeshProDropdown> element has been provided, which is functionally identical to a standard Dropdown element.

Example

<TextMeshProDropdown>
     <TMP_DropdownLabel fontSize="20" />
     <TMP_OptionTextTemplate fontSize="20" color="rgba(0,0,0,0.75)" />
          
     <TMP_Option selected="true">One</TMP_Option>
     <TMP_Option>Two</TMP_Option>
     <TMP_Option>Three</TMP_Option>
     <TMP_Option>Four</TMP_Option>
</TextMeshProDropdown>

TextMesh Pro Materials

As of XmlLayout v1.67, you can now create custom TextMesh Pro Materials via Xml. TextMesh Pro Materials allow you to customize the appearance of TextMesh Pro elements via underlays, outlines, bevelling, bump maps, and more.

Please note that these effects cannot be customized on a per-element basis, as doing so would create a lot of unnecessary material instances, negatively affecting performance (both in memory usage and rendering time). Instead, the <TextMeshProMaterial> element allows you to explicitly define material instances for use with TextMesh Pro elements in XmlLayout.

For more details on this subject, see the TextMesh Pro documentation.

Additional note: TextMesh Pro materials can only be used with the font they are explicitly defined for. Attempting to use materials with a different font will result in visual artifacts.

Example

<Defaults>  
    <!-- Define a new material named 'TestMaterial_1' -->
    <TextMeshProMaterial name="TestMaterial_1" 
                         font="Fonts &amp; Materials/LiberationSans SDF"
                         shader="TextMeshPro/Distance Field"
                         faceColor="rgb(0.25,1,0.25)"
                         bevelAmount="0.8"
                         bevelWidth="0.65"
                         bevelRoundness="1"
                         bevelType="OuterBevel"
                         bevelOffset="-0.25"
                         bevelClamp="0.25"
                         underlayOffsetX="0.35"
                         underlayOffsetY="-0.35"
                         underlaySoftness="0.1"
                         lightAngle="2"
                         lightSpecularColor="rgb(0,1,0)"
                         lightSpecularPower="2"
                         lightReflectivity="20"
                         glowColor="rgba(0,1,0,0.25)"
                         glowOuterAmount="0.5"
                         glowInnerAmount="0.12"
                         glowPower="0.25" />
    
    <!-- Define a new material named 'TestMaterial_2' which is based on 'TestMaterial_1' -->
    <TextMeshProMaterial name="TestMaterial_2" 
                         baseMaterial="TestMaterial_1"
                         faceColor="rgb(1,1,1)" />

    <!-- Use 'TestMaterial_1' for all TextMesh Pro elements -->
    <!-- (You can also specify this directly on the element) -->
    <TextMeshPro fontMaterial="TestMaterial_1" hoverClass="hover" />

    <!-- Use 'TestMaterial_2' for TextMesh Pro elements when the mouse hovers over them -->
    <TextMeshPro class="hover" fontMaterial="TestMaterial_2" />
  </Defaults>

  <!-- This element will use 'TestMaterial_1' by default, 
       and will switch to 'TestMaterial_2' when the mouse hovers over it -->
  <TextMeshPro fontSize="256">Test Text</TextMeshPro>

</TextmeshPro>

</ResourcesFolders>

Adding a new database file

To add a new Custom Resource Database, right click in the Project Window and then select Create -> XmlLayout -> Resources -> Custom Resource Database.

What you name your database file and where you choose to store it is up to you - XmlLayout will automatically pick it up and use it wherever it is.

Please note: if you're building for platforms such as WebGL, it may be necessary to restart Unity in order for the resource database to work correctly (in the build).

Locating assets for the database

There are three methods of locating assets for your new custom database:

• Monitoring the current folder: (Recommended)

  If you select the 'Monitor Current Folder' checkbox, then this database will monitor the folder it is currently located in (as well as any subfolders). Be sure to also check the 'AutomaticallyRemoveEntries' checkbox in order for this database to be entirely self sufficient.

  If this method is chosen, then you will not be able to edit the folders collection (as it will be controlled by this property), but apart from that, it works exactly as if you had specified the current folder this database is located in.




• Specifying folders:

  Your new database has a 'Folders' property which is a collection of string values. Each of these values specifies a folder that this database should monitor for assets.

  The paths should be specified from your Assets folder, e.g. if your folder is stored in "Assets/Some Folder/My Assets", then you should provide a value of "Some Folder/My Assets".

  If new assets are added into a folder monitored by a custom resource database, they will automatically be added to the database.

  If you'd like the database to also automatically remove entries for resources that have been removed/etc, then ensure that the 'AutomaticallyRemoveEntries' checkbox is selected.

  The paths generated by this method are similar to those generated by Unity's Resources Folder system - the paths of each asset will always be relative to the folder they were found in (as specified by the 'Folders property). If you'd like to see the path used by any particular asset, you can find it in the 'Entries' collection below.

  Note: As with Unity's Resources folders, Custom Resource Databases support assets located in subfolders.




• Speciying individual assets:

  You can also manually add entries to the database by adding values to the 'Entries' collection, specifying both a path and the asset itself.

  Using this method, you can specify and use any path value you wish. However, if you do use this method, then ensure that 'AutomaticallyRemoveEntries' is not selected, or your custom entries will automatically be removed.

Any changes made to a custom resource database will be picked up by XmlLayout and will be available for immediate use.

</CreatingCustomXmlLayoutResourceDatabases>

XmlLayoutResourceDatabase.instance.AddResource("MyNewSpritePath", myNewSprite);

</AddingCustomResourcesAtRuntime>

Adding a new localization file

You can add a new localization file by opening the 'Create' menu from the top menu bar, or by right-clicking in the project window, then selecting Create -> XmlLayout -> Localization -> New Localization File.

You should then name the file as appropriate - if, for example, the file will be used to contain values for the English language, then you should call it 'English', or perhaps 'EN-US', 'EN-EU', or something along those lines. However, what you choose to call it is ultimately entirely up to you.

If you wish to change languages at runtime, then it is usually best to ensure that the localization file is stored within a Resource Database or Resources folder (alternatively, you can store references to the file in your XmlLayoutController and use those, in which case it does not matter where the file is located).

Please note: You can use the same localization file for as many XmlLayouts as you like - or you can create a different localization file for each XmlLayout, the choice is up to you.

Setting keys and values

To edit a localization file, first select it in the project window.

From here, you can modify keys and values, remove entries, add new entries, etc.

When you're done, click the 'Save Changes' button to make sure your changes are stored (otherwise they may be lost).

Copying Keys from one localization file to another

When creating multiple localization files, you may find it repetitive adding the same sets of keys for each file. To this end, the localization file editor provides the Copy Keys to Clipboard and Paste Keys from Clipboard buttons. Use these to copy keys from one file to another, meaning that all you have to do is set the values.

</LocalizationFiles>

In order to use a localization file with an XmlLayout, you must first populate the XmlLayouts LocalizationFile property.

There are two ways in which you can do this:

• In the XmlLayout inspector, you can set the LocalizationFile property directly; or
• You can set the property in code using XmlLayout.SetLocalizationFile(XmlLayoutLocalization newLocalizationFile). This can be done at runtime - doing so will force the XmlLayout to rebuild using the new localization file.

Here is a snippet from the Localization Example, which shows how to reference keys/values from the localization file:

Example

<TableLayout>
    <Row class="headerRow">
      <Cell>
        <Text class="title">
          {LOCALIZATION_EXAMPLE_HEADER}
        </Text>
      </Cell>
    </Row>
    <Row class="viewport">
      <Cell>
        <TableLayout cellPadding="8" cellBackgroundColor="rgba(1,1,1,0.1)">
          <Row>
            <Cell>
              <Text class="h3">{LOCALIZATION_EXAMPLE_USERNAME_LABEL}</Text>
            </Cell>
            <Cell>
              <InputField id="username" 
                          placeholderText="{LOCALIZATION_EXAMPLE_USERNAME_PLACEHOLDER_TEXT}" />
            </Cell>
          </Row>

          <Row>
            <Cell>
              <Text class="h3">{LOCALIZATION_EXAMPLE_PASSWORD_LABEL}</Text>
            </Cell>
            <Cell>
              <InputField id="password" 
                          inputType="Password" 
                          placeholderText="{LOCALIZATION_EXAMPLE_PASSWORD_PLACEHOLDER_TEXT}" />
            </Cell>
          </Row>

          <Row>
            <Cell>
              <Button>{LOCALIZATION_EXAMPLE_LOGIN_BUTTON}</Button>
            </Cell>
            <Cell>
              <Button>{LOCALIZATION_EXAMPLE_REGISTER_BUTTON}</Button>
            </Cell>
          </Row>
        </TableLayout>
      </Cell>
    </Row>
  </TableLayout>

As you can see, you can use localization keys anywhere in the Xml file where text is supported.

For more details, including showing how to change localization files at runtime, see the Localization Example.

</UsingALocalizationFile>

<Element myAttributeName="myAttributeValue" />

</CustomAttributes>

<MyTagName />

</CustomTags>

</UsingCustomPrefabsWithExistingTags>

[ElementTagHandler("TestXmlTag")]
public class TestXmlTag : UI.Xml.Tags.BaseXmlTagHandler
{
    // Specify the Xml directly
    /*public override string Xml
    {
        get
        {
            return @"<Panel color=""red""></Panel>";
        }
    }*/

    // Specify a resource path to load an Xml file
    public override string XmlPath
    {
        get
        {
            return "Xml/DemoOverlay";
        }
    }
}

<TestXmlTag />

</CustomXmlTags>

To access the XmlLayout Configuration window, open the Assets menu, select 'XmlLayout', and then 'Configuration'.

This will allow you to see and change advanced XmlLayout configuration options.

• Automatically Update XSD File:

  If this option is enabled (default = enabled), XmlLayout will automatically update the XSD (autocomplete) file to match any custom elements/attributes/etc. If you aren't currently making any changes to custom elements/attributes/etc. or importing/removing any plugins, you can disable this for a slightly faster compile time. Under normal circumstances, it is recommended that you leave this enabled.

• Suppress XSD Update message:

  If this option is enabled (default = enabled), XmlLayout will not log a message when updating the XSD file. If the option is disabled, XmlLayout will log a message whenever the XSD file is updated for any reason (which, if the above option is enabled, will be every time scripts are compiled).

• Allow any attribute:

  If this option is enabled (default = disabled), the xsd file will be set up such that you can use any attribute you wish in your Xml without receiving a validation error.

• Comprehensive Custom Element and Attribute Check:

  If this option is enabled (default = enabled), XmlLayout will search through all assemblies it can find for plugins, custom elements, and attributes. Disabling this option will improve compilation time, but may prevent XmlLayout from properly detecting plugins. If you are not using any plugins, then it is safe to disable this option.

• Custom Assembly List:

  If the above option is disabled, you can specify a list of assemblies to search for plugins/etc. Note: this list requires the assemblies full name.

• Assembly Exclude List:

  If the comprehensive check is enabled, you can exclude specific assemblies from the check by adding their names to this list. This list supports partial matches, so you don't need the assemblies full name. A few select assemblies (usually dynamically generated ones) can cause issues with XmlLayout - adding them to this list will usually fix any problems.

• Use XmlLayout Selectable Navigation:

  If this option is enabled (default = enabled), then XmlLayout will automatically handle Selectable navigation in your project. If you'd like to use a different system, disable this option.

• Manage Assembly Definitions Automatically:

  If this option is enabled (U2018+ only), then XmlLayout will automatically generate assembly files for itself and any installed Digital Legacy plugins. Under normal circumstances, it is probably best to leave this option disabled and only use the options below to manually generate these files when necessary.

• Generate Assembly Definition Files:

  Clicking this button will generate assembly files for itself and any installed Digital Legacy plugins. This will split XmlLayout and any plugins into their own assemblies, which can improve compilation time by having Unity only recompile assemblies that have actually changed, rather than everything.

• Delete Assembly Definition Files:

  Clicking this button will have XmlLayout delete any assembly files that it has generated, reverting the project to its previous state.

• Regenerate XSD File Now:

  Clicking this button will force XmlLayout to regenerate its xsd (autocomplete) file.

• Disable/Enable MVVM Functionality:

  Clicking this button will enable or disable MVVM functionality. When MVVM is disabled, it will be excluded from compilation which may slightly improve compile time, and also may be useful if for example you wish to use .NET 2.0 (as of recent versions of Unity 2018, .NET 2.0 no longer contains the Remoting namespace, so MVVM is no longer compatible with .NET 2.0. With MVVM disabled, XmlLayout can still be compiled for .NET 2.0).

</TheXmlLayoutConfigurationWindow>

Installing plugins

By default, XmlLayout will automatically pick up plugins that are installed (such as PagedRect or TextMeshPro).

Removing plugins

When you remove a plugin, compilation errors may be shown as XmlLayout will still reference them. You can rectify this by using the 'Assets/XmlLayout/Fix Symbol Definitions' menu item.

As such, the recommended practice for removing a plugin is to delete the plugin files, and then click the menu item. If you're using assembly files, you may need to also tell XmlLayout to generate them so as to remove any references to the plugin.

</Plugins>

Modifying internal XmlLayout code

It is best not to modify internal XmlLayout code as any changes made will be lost when updating to the latest version, and may also lead to unexpected behaviour.

Resources folders

As of v1.23, with the addition of CustomXmlLayoutResourceDatabases, XmlLayout no longer requires you to use Resources folders. Unity recommmends that you don't use Resources folders, so, unless you need the assets used by XmlLayout to be in Resources folders for some other reason, it is recommended that you move your assets over to a custom resource database. To do so, simply rename the existing Resources folder to the name of your choice, then add a custom database asset to the folder and set it to 'Monitor the Current Folder'.

Updating XmlLayout

In general, it is best to delete the existing XmlLayout installation when updating XmlLayout to a later version. While updating without deleting the original installation will often work, it may lead to unexpected issues.

If you wish to preserve your configuration settings, back up the UI/XmlLayout/Configuration/Resources/XmlLayout_Configuration object before updating, and then restore it once the update has been imported.

</>