GUI Window Tutorial

From HEWIKI
Jump to: navigation, search

Contents

He intermediate.png

Overview

This is a step by step tutorial on how to create a custom GUI Control - a popup window which says, "Hello World". There is a tutorial for creating a custom GUI Control using the GUI Editor and another tutorial to create the same GUI Control using GUIXML. Both tutorials will result in a GUI Control that looks and behaves the same.

The finished My Test Window


Prerequisites

Before going any further, you should already have worked through at least the following tutorials:

You should have HeroBlade open, and the script editor. Either create a new client-side script, or use one of your existing client-side work scripts where you can add the necessary function. Whichever script name you use, should be inserted in the place of <script-name> below.

This tutorial has been written in a "cookbook" fashion so that it is not necessary to understand each GUIControl attribute. If you want though, there is a detailed line by line explanation of the modifications, farther down on this page.

To learn more about the details of other GUIControl attributes which were not modified in this tutorial, please see the comprehensive list of Base Fields on the GUIControls page. The documentation there also includes a wealth of other information about the different Controls, including the default and potential values for each of their fields.


GUI Editor Tutorial

This tutorial will show how to create a custom GUI Control using the GUI Editor.


Create the Prototype

Create the Prototype

MyTestWindow GUI Control


Add a Titlebar

MyTestWindow with a title bar


Add a Scrollable Panel

MyTestWindow with a scrollable panel


Save the GUI Control

GUIEditorToolbar.png


GUI XML Tutorial

This tutorial will show how to create a custom GUI Control by writing GUIXML in the HeroScript Editor.


Create the Prototype 

<createControlType type="MyTestWindow" description="GUI Window Tutorial" inheritFrom="_movePanel" owner="0">
  <size x="300" y="100"/>
</createControlType>


Add a Title Bar 

<createControlType type="MyTestWindow" description="GUI Window Tutorial" inheritFrom="_movePanel" owner="0">
  <size x="300" y="100"/>
  <_titlebar name="titlebar">
    <set name='MyTestWindow.titlebar.title' attribute='text' value="My Test Window"/>
  </_titlebar>
</createControlType>


Add a Scrollable Panel 

<createControlType type="MyTestWindow" description="GUI Window Tutorial" inheritFrom="_movePanel" owner="0">
  <size x="300" y="100"/>
  <_titlebar name="titlebar">
    <set name='MyTestWindow.titlebar.title' attribute='text' value="My Test Window"/>
  </_titlebar>
  <_scrollableParent name="scrollable"/>
</createControlType>


Compile and Submit

Compile Toolbar


Invoking the GUI Control

Overview

The following function will create a node from the new GUIControl Prototype called "MyTestWindow".

The code in this function modifies the attributes of the subcontrols directly. It also creates an additional new GUIControl, called "myTestDataLabel", based on the "_label" prototype. The new label will have text added to it, and then be connected to the client area of MyTestWindow for display.

When the function is run, the window and associated text will appear in the center of the viewport.


Create the function

A detailed line-by-line analysis of this code is available further down on this page. For now though, it can suffice to simply type in the following, or copy/paste this function into your client-side work script: 

function MakeMyTestWindow()
  // This creates a window GUIControl from a prototype
 
  myTestWindow as NodeRef of Class GUIControl = createNodeFromPrototype("MyTestWindow")
 
  // Always make the new window renderable in the viewport first
  myTestWindow.build = true
 
  // Configure the window's position in the viewport
  screen as Vector3 = getViewPortSize()
  myTestWindow.position.x = (screen.x - myTestWindow.size.x) / 2
  myTestWindow.position.y = (screen.y - myTestWindow.size.y) / 2
 
  // Create the Label where the main window text will appear
  myTestDataLabel as NodeRef of Class GUILabel = createNodeFromPrototype("_label")
 
  // Always make the new label renderable in the viewport first
  myTestDataLabel.build = true
 
  myTestDataLabel.name = "data_label"
  myTestDataLabel.text = "Hello World!"
  myTestDataLabel.autoSetHeight = true
 
  // Find the clientarea on the window control, and connect
  //   the new text label control to it.
  clientArea as NodeRef of Class GUIControl = findGUIControlByName(myTestWindow, "scrollable.clientarea")
  add back myTestDataLabel to clientArea.children
  myTestDataLabel.dockMode = TOP
.


Detailed Explanations of the Function's Code

Detailed explanation of these steps is below:


Create the GUIControl Window Node

There are many pre-made prototypes that exist for creating a window. For example: A basic window, a scrollable window, a resizeable window, etc. For this example, the "MyTestWindow" prototype was used.

Each GUI control prototype has its own GUIXML file. The available prototypes for GUI controls are listed in the GUI Editor panel which can be opened from HeroBlade's HerScript menu. 

myTestWindow as NodeRef of Class GUIControl = createNodeFromPrototype("MyTestWindow")


Make the GUIControl Renderable

When the build flag is set to TRUE, that tells the engine that this Control is okay to render on the screen. If the Control were still in a half-finished state, this flag would probably be kept at FALSE so that the Control wouldn't be rendered yet. 

myTestWindow.build = true


Position the Control on the screen

If a position is not specified, the Control will be positioned at 0,0, which means that its upper left corner will be at the far upper left of the viewport (the game screen). The position fields in this case are merely to determine the Control's starting location.

To center the Control, first determine the current size of the Viewport, with getViewPortSize(). This returns a value in vector3 format, where the x and y values are the current width and height of the Viewport. A simple calculation between the size of the Control and the size of the Viewport (divided by two) provides the perfect location at which to position the Control. 

screen as Vector3 = getViewPortSize()
myTestWindow.position.x = (screen.x - myTestWindow.size.x) / 2
myTestWindow.position.y = (screen.y - myTestWindow.size.y) / 2

However, the Control could also be positioned anywhere else in the Viewport as well. For example: 

myTestWindow.position.x = 300
myTestWindow.position.y = 300

Note that the position will change automatically if the user decides to drag the window around.


Create a label to hold your content

In this step, the function creates a new GUILabel Control, based on the _label prototype. 

myTestDataLabel as NodeRef of Class GUILabel = createNodeFromPrototype("_label")


Make the Label Renderable

Since "myTestDataLabel" was created by the script it's build flag needs to be toggled TRUE. 

myTestDataLabel.build = true


Put some data in the new label

This code will set the name of the GUILabel and set the text that is displayed by this GUILabel. 

myTestDataLabel.name = "data_label"
myTestDataLabel.text = "Hello World!"


Set the size of the label

It's possible to set the size to a specific value, or it can be automatically determined. In the case of this tutorial, the size is being set automatically: 

myTestDataLabel.autoSetHeight = true

This automatically make the size of the label large enough to accomodate however much text is in it.

Note: autoSetHeight does not modify the size of the font, only the size of the Control that contains the font. Though it's possible to make a larger font by scaling a Control to a larger size (which scales the font along with it), this does not look very clean. As of this writing, there is not any way to elegantly change font size or type.


Find the Client Area Control

This is a control that's already a child of myTestWindow. To manipulate it though, we need a node reference to it. So we need to "find" it on the parent, using the FindGUIControlByName function. 

clientArea as NodeRef of Class GUIControl = findGUIControlByName(myTestWindow, "scrollable.clientarea")

This control defines the panel that will hold the things that you want to display. It's what's left of the window after taking account of the resize bars, title bars, etc. The clientarea fills up all the spaces between all these things.


Add the Label to the List of Client Area

This adds the new Label to the end of the list of children of clientArea. If other labels are created, they can be added in behind this one. 

add back myTestDataLabel to clientArea.children


Additional information

Retrieved from "http://wiki.heroengine.com/wiki/GUI_Window_Tutorial"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox