UI Tutorial Creating a Menu

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

1 Overview
2 Create frame file
- 2.1 Explanation of the XML
3 Create event handler script
4 Create asset using Asset Importer
5 Modify theme (toc) file
6 Try it out

[edit]

Overview

In this tutorial, you will learn how to create a widget that covers the entire screen.

This tutorial was created by Chris Childs.

[edit]

Create frame file

Create an XML file called UITutorial03.xml. Copy the following text to the file and save it.

<Ui>
  <Script file="UITutorial03.py"/>
  <Frame name="Frame_UITutorial03" alpha="1.0" hidden="FALSE">
    <Anchors>
      <Anchor point="TOPLEFT"/>
      <Anchor point="BOTTOMRIGHT"/>
    </Anchors>
    <Layers>
      <Layer level="BACKGROUND">
        <Texture name="$parentBackground">
          <Anchors>
            <Anchor point="TOPLEFT" relativeTo="$parent" />
            <Anchor point="BOTTOMRIGHT" relativeTo="$parent" />
          </Anchors>
        </Texture>
        <Color r="0" g="0" b="0" a="0.5"/>
      </Layer>
      <Layer level="ARTWORK">
        <Texture name="$parentTexture" file="Interface\UITutorial02_Imageset\Button_Grey">
          <Anchors>
            <Anchor point="TOPLEFT" relativeTo="$parent" />
            <Anchor point="BOTTOMRIGHT" relativeTo="$parent" />
          </Anchors>
        </Texture>
      </Layer>
    </Layers>    
    <Frames>
      <Button name="$parent_Button_Close_Menu">
        <Size>
          <AbsDimension x="32" y="32"/>
        </Size>
        <Anchors>
          <Anchor point="TOPRIGHT" relativePoint="TOPRIGHT"/>
        </Anchors>
        <NormalTexture file="Interface\UITutorial02_Imageset\Button_Red" />
        <Scripts language="python">
          <OnClick> OnButton_CloseMenu(); </OnClick>
        </Scripts>
      </Button>
    </Frames>
  </Frame>
</Ui>

[edit]

Explanation of the XML

Frame tag Although we have covered frames, there are two attributes worth noting here. The <Frame> tag looks like this:

<Frame name="Frame_UITutorial03" alpha="1.0" hidden="FALSE">

In addition to the name, there are two attributes:

alpha is a value between 0.0 and 1.0 where 0.0 is transparent and 1.0 is solid

The hidden attribute specifies the default state of the frame when it is loaded. If set to TRUE, it will not be shown until the frame's Show() method is called. If set to FALSE, then it will be visible upon load.

Anchors tag Use the <Anchors> tag to make the frame take up the entire window. Instead of using size elements, use <Anchor> tags to anchor the upper left corner and the bottom right and that will cover the entire screen, regardless of the screen resulotuion.

<Anchors>
  <Anchor point="TOPLEFT"/>
  <Anchor point="BOTTOMRIGHT"/>
</Anchors>

NOTE: that if a widget covers the entire screen, input will be sent to the widget instead of the client, meaning you will not be able to use your mouse to move your character. It is for this reason that if you have a full screen widget visible that you want to have at least a button to hide the window so control can be returned to the client.

Layers tag

TBD.

Button tag The button tag looks like this:

<Button name="$parent_Button_Close_Menu">

See the UI Tutorial Creating a Button for information on creating a button.

[edit]

Create event handler script

Now create the Python script file called UITutorial03.py in the UITutorial directory. Copy the following text to the file and save it:

import ClientAPI

Text_Enter              = "UITutorial03: Entering UITutorial03.py"
Text_Exit               = "UITutorial03: Exiting UITutorial03.py"
Text_OnButton_OpenMenu  = "UITutorial03: OnButton_OpenMenu"
Text_OnButton_CloseMenu = "UITutorial03: OnButton_CloseMenu"

ClientAPI.LogWarn(Text_Enter);

def OnButton_OpenMenu():
  ClientAPI.LogWarn(Text_OnButton_OpenMenu)
  Frame_UITutorial03.Show()

def OnButton_CloseMenu():
  ClientAPI.LogWarn(Text_OnButton_CloseMenu)
  Frame_UITutorial03.Hide()

ClientAPI.LogWarn(Text_Exit);

The only new things in the script file are the Show() and Hide() methods for the frame. You can reference the frame by the name you assigned it.

[edit]

Create asset using Asset Importer

In Asset Importer:

Choose File | New or click the New icon.
Select Asset Type "Frame XML"
Click the Browse button next to the "XML" field, and choose UI_Tutorial03.xml.
Drag "UITutorial03.py" file from the Files list to the "Optional Python Scripts" field.
Drag "UI_Tutorial02_Imageset.xml" from the Files list to the "Optional Imageset" field.
Click the Save icon or choose File | Save Asset As... Accept the default name "UI_Tutorial03_FrameXML.asset".

Saving the asset definition will automatically copy the XML and Python files to your asset repository.

[edit]