UI Tutorial Hello World

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

This tutorial was created by Chris Childs.

Contents 1 Overview 2 Create the UI File 3 See the result 4 Examine the UI File 4.1 Frame Tag 4.2 Size Tag 4.3 Anchors Tag 4.4 Anchor Tag 4.5 Frames Tag 4.6 FontString Tag

Overview

In this tutorial, you will make the Multiverse Client display the text "Hello World" in the Multiverse Sampleworld.

Before you start:

• Make sure you have designated the Sampleworld asset repository as the default asset repository for the Multiverse tools; you'll be using this asset repository in this tutorial.
• Create a temporary directory called UITutorial to hold the files you're going to work with in this tutorial.

Create the UI File

Follow these steps:

1. Create a new text file named UITutorial01.xml in your temporary UITutorial directory. NOTE: if you create the file with a text editor such as Notepad, verify that the file was saved as type XML (file name extension .xml) and not a text file.
2. Copy the following text to the file and save it. This is the XML code that defines the interface elements you are adding. In this case, it is just text that displays "Hello World!"

<Ui>
  <Frame name="Frame_UITutorial01">
    <Size>
      <AbsDimension x="100" y="100"/>
    </Size>
    <Anchors>
      <Anchor point="TOP"/>
    </Anchors>
    <Frames>
      <FontString name="$parent_HelloWorld" inherits="NormalFont" text="Hello World!"/>
    </Frames>
  </Frame>
</Ui>

See the next section for an explanation of this code.

3. Use Asset Importer to import the Frame file into your asset repository, with these steps:
   • Click on the Create New Asset icon or choose File | New Asset.
   • Choose Asset Type Frame XML from the dropdown list.
   • Click the Browse button next to the XML field, and browse to the UITutorial01.xml file you just created.
   • Click the Save icon or choose File | Save Asset. Keep the default name "UITutorial01_FrameXML.asset."
4. Edit the file SampleAssets\Interface\FrameXML\mars.toc.
5. Add the text "UITutorial01.xml" on a line by itself at the end of the theme file.

The .toc file is called a theme file, and specifies the UI files the client uses. See Overview of Developing Client UI for more information. By convention, the server specifies the UI theme in the configuration file mv-home/config/common/global_props.py, with the following statement:

World.addTheme("mars.toc");

NOTE: You don't need to edit global_props.py, because the file in Sampleworld already has the above line.

See the result

To see the results of your work, run the client as follows:

MultiverseClient.exe --standalone --use_default_repository

Make sure you have specified the asset repository with the tools already. You will see "Hello World!" at the top center of the display, as shown at right.

NOTE: When you use the --standalone option, you will be running the Client in "standalone" mode without a server. See Running the Client in standalone mode.

The following section explains how the XML file you added achieves this result.

Examine the UI File

Now that you've seen the UI file in action, take a closer look. This section will explain the simple UI file above in detail. For a complete reference of all the available widgets, see Widget Reference.

You can have as many UI files as you want. The UI file contains XML tags or elements. Each file must have at least the <Ui> tag, which must be the top most level (the very first and very last tag).

Frame Tag

The Frame tag looks like this:

<Frame name="Frame_UITutorial01">
  ...
</Frame>

A Frame defines a window in the display. Within that window, you can place and control widgets. A single UI file can define many frames, or you can separate them into their own files. A frame can reference any named frame that is loaded.

The Frame tag has one attribute, name. which must be unique among all the frames that are loaded in the theme. Other UI theme files and scripts refer to the frame by this name.

Size Tag

The Size tag looks like this:

<Size>
  <AbsDimension x="100" y="100"/>
</Size>

The <Size> tag defines the size of the window frame that contains it with an <AbsDimension/> tag that specifies the dimensions in pixels.

You can also define the size of the frame with just the anchors, in which case the <Size> tag is not needed.

Anchors Tag

The Anchors tag looks like this:

<Anchors>
   ...
</Anchors>

The anchors tag contains a list of anchors for the frame. The anchors define where the frame is anchored to or where it is located on the display. If you use absolute values for the size of the frame, then you only need a single anchor to position the frame .

Two anchors can be used to define the top left corner of the frame and the bottom right corner of the frame, which defines the entire size of the frame so the size element would not be needed.

Anchor Tag

The Anchor tag looks like this:

<Anchor point="TOP"/>

The anchor tag is the actual anchor point. You can use two type of points with anchors: point and relativePoint. Both types are often needed to help fine-tune how the new frame should appear on the parent window.

You specify the point values with the point and relativePoint attributes. The point attribute is the point on the parent frame to which the frame is attached. The relativePoint attribute is the point on the new frame that is going to attach to the parent frame. Not using the relativePoint could cause the frame to be outside the parent window (and consequently, not displayed).

Frames Tag

The Frames tag looks like this:

<Frames>
  ...      
</Frames>

The Frames tag contains all the widgets in the frame, including other frames, controls, and text strings.

FontString Tag

The FontString tag looks like this:

<FontString name="$parent_HelloWorld" inherits="NormalFont" text="Hello World!"/>

The FontString tag is a text field that is displayed. The text attribute determines the default text it displays. Other attributes can specify the font to use, font size, color, and many other details associated with fonts.

The attributes of FontString in this example are:

• name: Although a name is not required for all elements, giving an element a name will allow scripts to reference this element and assign new values to properties, such as the text string.

IMPORTANT: All elements must have a unique name. If one is not assigned, the platform will assign some abritrary value. You can use the special $parent value to help in this process. This value is replaced at runtime with the name of the parent. Using the $parent keyword in front of your local name will help ensure the whole name is unique.

• inherits: There are many pre-defined elements, in this case font styles. Any properties of the inherited object can be overwriten, but in this example, we are using all the default settings for the inherited object.

• text: This property is what actually gets displayed. This value can be set from within the script when this object name is referenced.