UI Tutorial Creating a Button

From Multiverse

Jump to: navigation, search
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

In this tutorial, you will learn how to place a button on the screen and how to attach an event handler to it, so it does something when the user clicks the button. It is designed to be followed after the UI Tutorial Hello World, but this is not absolutely necessary.

This tutorial was created by Chris Childs.

Contents

[edit]

Get started

If you have not already done so, create a temporary directory called UITutorial to hold the files you're going to work with in this tutorial.

Next, open the Asset Importer tool. Make sure you have already designated an asset repository. If you are working with Sampleworld, use the Sampleworld asset repository.

[edit]

Create button image

Here is a simple 64 x 64 pixel image file to use as a button:

Example button bitmap

Right-click on this image and save it to the UITutorial directory. Keep the default file name, UITutorial02.jpg. If there is a ".png" at the end of the file name, remove it.

NOTE: When creating imageset files, the image size has to be in powers of two (2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, and so on). The imageset does not have to be a sqaure (64x64), but it must follow the rules for each dimension (32x32, 32x64, 32x128, 1024x512, etc.). If you do not follow these rules, the image will not appear correctly when being displayed. No error or warning will be generated.

[edit]

Create XML Files

You are going to create two XML files:

  • An imageset file containing the imageset to display
  • A frame file containing the layout of the UI
[edit]

Create imageset file

Create a new text file and call it UITutorial02_Imageset.xml. Copy the following text to the file and save it to the UITutorial directory. 

<Imageset Name="UITutorial02_Imageset" Imagefile="UITutorial02.jpg" NativeHorzRes="64"
          NativeVertRes="64" AutoScaled="false">
  <Image Name="Button_Red"   XPos="0"  YPos="0"  Width="32" Height="32" />
  <Image Name="Button_Green" XPos="32" YPos="0"  Width="32" Height="32" />
  <Image Name="Button_Blue"  XPos="0"  YPos="32" Width="32" Height="32" />
  <Image Name="Button_Grey"  XPos="32" YPos="32" Width="32" Height="32" />
</Imageset>

Note: The name of an imageset file must match the imageset name (the Name attribute of the Imageset tag).

[edit]

Explanation of the imageset file

  • Imageset tag: An imageset file is contained within the Imageset tags.
    • Name attribute: The Imageset Name has to be the same name as the imageset XML filename!
    • Imagefile tag: The name of the graphic file for the buttons you created. Notice that a path is not needed, just the file name. Asset Importer will automatically place image files in the correct directory.
    • NativeHorzRes and NativeVertRes are the horizontal and vertial size in pixels of the image.
  • Image tag: The definition of an image to be used in the UI.
    • The Name attribute is how the image is referenced.
    • XPos and YPos are the offset values in the image file of where the start of the image is.
    • Width and Height are the size values of the image in the image file.
[edit]

Create frame XML file

Create a frame XML file and call it UITutorial02.xml. Copy the following text to the file and save it. 

<Ui>
<Frame name="Frame_UITutorial02">
  <Size>
    <AbsDimension x="32" y="32"/>
  </Size>
  <Anchors>
    <Anchor point="TOPRIGHT" relativePoint="TOPRIGHT"/>
  </Anchors>
  <Frames>
    <Button name="$parent_Button_HelloWorld" text="Hi!">
      <NormalText inherits="NormalFont" justifyH="CENTER" justifyV="MIDDLE">
        <Color r="0.0" g="0.0" b="0.0" a="1.0"/>
      </NormalText>
      <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> Frame_UITutorial01_HelloWorld.SetText("Hi!"); </OnClick>
      </Scripts>
    </Button>
  </Frames>
</Frame>
</Ui>
[edit]

Create frame XML asset definition

In Asset Importer:

  1. Choose File | New or click the New icon.
  2. Select Asset Type "Frame XML"
  3. Click the Browse button next to the "XML" field, and choose UI_Tutorial02.xml.
  4. Drag "UI_Tutorial02_Imageset.xml" from the Files list to the "Optional Imageset" field.
  5. Drag "UITutorial02.jpg" from the Files list to the "Optional Texture" field.
  6. Click the Save icon or choose File | Save Asset As... Accept the default name "UI_Tutorial02_FrameXML.asset".

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

[edit]

Explanation of Frame XML file

  • Size tag: The frame size can be as big or as small as you need. I have created this frame to be the same size as the button we are going to use.
  • Anchor tag: 
<Anchor point="TOPRIGHT" relativePoint="TOPRIGHT"/>.

This tag indicates that the button will be placed in the top right corner. By using the TOPRIGHT value for relativePoint, we ensure that the frame is on the screen with the frame's top right corner touching the parent's top right corner.

  • Button tag: 
<Button name="$parent_Button_HelloWorld" text="Hi!">

A button tag can have an additional text attribute that sets the text of the button.

  • NormalText: NormalText, PushedText, and DisabledText are the three property elements that control the text color and font. I have only set the normal text style.
  • Color: To make the button text black instead of the default yellow, put the color tag inside the NormalFont tag so that it would be associated with the normal text. Placing the tag in the button scope outside one of the text property elements will not have any effect on the text.
  • Size: For the Button size, define it in terms of the actual pixels of the image. In this case, the button will be 32x32.
  • NormalTexture: NormalTexture, PushedTexture, DisabledTexture, and HighlightTexture are the four texture property elements of a button. I have only been able to get the NormalTexture element to work.

NOTE: Only NormalTexture is working now. When functionality is added for the other attributes, nothing will need to be done to change the states. The UI will manage displaying the correct texture for the current state.

The file attribute is formated as follows:

Interface (which I think is just ignored for now)\filename (of the imageset xml file)\image name (of one of the images defined in the imageset

  • Scripts tag: 
<Scripts language="python">

You must set the script language, regardless of whether you are embedding scripts in the XML file or calling functions from an embedded script.

  • OnClick tag: OnClick is one of the many events that you can hook for a button. You will be calling a function on the frame in the previous tutorial to change the text. 
Frame_UITutorial01_HelloWorld.SetText("Hi!");

The SetText method of a frame is called with the new text that we want displayed. In UITutorial01.xml, we defined the FontString to be named "$parent_HelloWorld" and the name of the Frame that it is in is "Frame_UITutorial01".

[edit]

Modify the theme (toc) file

Next, modify the mars.toc file in your asset repository's \Interface\FrameXML directory to include the UITutorial02.xml file at the end of the list of files.

[edit]

Try it out

UI Tutorial button at upper right
Enlarge
UI Tutorial button at upper right

Run the client as before: 

MultiverseClient.exe --use_default_repository --standalone

You will see the button in the upper right corner of the client window, as illustrated at right.

Click on the button to change the Hello World message at the center of the screen from "Hello World" to "Hi!". Note: This will not work if you did not follow the previous "Hello World" tutorial.


[edit]

Put the event handler script in an external file

You can move the OnClick event handler script to an external file, which makes it easier to add more complex code, such as debugging information.

Edit UITutorial02.xml in the UITutorial directory and make the following changes:

  1. Add the following line right after the <Ui> tag 
    <Script file="UITutorial02.py"/>
  2. Change the OnClick event from 
    <OnClick> Frame_UITutorial01_HelloWorld.SetText("Hi!") </OnClick>

    to 

    <OnClick> OnHelloWorldButton("Hi!") </OnClick>
  3. Now create the Python script file called UITutorial02.py in the UITutorial directory. Copy the following text to the file and save it: 
    import ClientAPI

Text_Enter         = "Entering UITutorial.py"
Text_Exit          = "Exiting UITutorial.py"
Text_OnClick       = "OnClick"

ClientAPI.Log(Text_Enter)

def OnHelloWorldButton(str):
	ClientAPI.Log(Text_OnClick)
	Frame_UITutorial01_HelloWorld.SetText(str)

ClientAPI.Log(Text_Exit)
  4. In Asset Importer, recreate the frame XML file following the same steps as before. Give it the same name. This will overwrite the existing asset definition in your asset repository and copy the Python script file to the repository.
  5. Restart the servers and the client, and verify that the button works. Check the client trace file for the debugging text.

[edit]

Explanation of event handler script

The first line imports the ClientAPI module so you can use it your script file: 

import ClientAPI

The next lines define text string variables used later: 

Text_Enter = "Entering UITutorial.py"

This is how you add messages to the MultiverseClient.log file. 

ClientAPI.Log(Text_Enter)

Then you define a function with a text string parameter to pass data from the XML file: 

def OnHelloWorldButton(str):

This is an example of how to pass data back and forth between the XML file and the script file. 

Frame_UITutorial01_HelloWorld.SetText(str)

This is the same call made in the event handler in the XML file. It is being called from a script function now instead. This function includes some debug logging to help track whether the button was pressed if the text should not change on the FontString.

Retrieved from "http://update.multiverse.net/wiki/index.php/UI_Tutorial_Creating_a_Button"
Personal tools