There are two C++ base classes for GUI support:

There is also one management class:

You probably will create GUIs using Python and XML most of the time. There is no BigWorld GUI editor, thus all GUI is currently created using the Python console in game.

The code below shows an example:

import GUI
 
#create a simple GUI component
s=GUI.Simple( "maps/guis/stats_bar.dds" )

#width/height initially in pixels. can use widthRelative/heightRelative
#to designate the component uses clip coordinates ( -1 .. +1 ) instead.
s.width = 64
s.height = 16

#colour attribute is ( r,g,b,a )
s.colour = ( 255, 128, 0, 255 )

#the materialFX is simply the blend mode. can be "BLEND","SOLID","ADD"... 
s.materialFX = "BLEND"

#the position is always in clip coordinates ( -1 .. +1 )
s.position = ( 0, 0.85, 0.5 )

#the anchors determine what the position means with respect to the width 
#and height. in this example, the position of (0,0.85,0.5) and anchors
#"TOP,CENTER" means that the top centre of the component will rest at 
#the given position.
#The component will hang down from y=0.85, and will be centred on x=0.0
s.verticalAnchor = "TOP"
s.horizontalAnchor = "CENTER"
 
#create a clipper for the health amount. clip shaders are used to
#implement stats bars. the constructor parameter "RIGHT" means the 
#shader will clip the component from the right hand side.
c=GUI.ClipShader( "RIGHT" )

#all shaders animate their values. the speed indicates how long the
#internal parameter will change from the old value to the new. This speed
#indicates the health bar will always take 1/2 a second to change.
c.speed = 0.5

#the value is what the game normally changes if player's health changes.
c.value = 1.0

#this line adds the shader. Note that you can call your shader any name
#you like. Internally, the simple GUI component sees you are trying to 
#add a GuiShader to it, under the name of clipper.
#Internally it will call SimpleGUIComponent::addShader()
s.clipper = c
 
#create a colourer for the health amount
c=GUI.ColourShader()

#the start,middle and end simply represent colours to blend to when the
# value parameter is 1.0, 0.5 and 0.0 respectively.
c.start=(255,0,0,192)
c.middle=(255,255,0,192)
c.end=(0,255,0,192)
c.speed=0.5
c.value=1.0
s.colourer=c
 
#and make the health bar be drawn
GUI.addRoot( s )

Example of GUI creation

You can then customise the new health bar simply by setting the appropriate values in the shaders:

# player's health went down to 80%
s.clipper.value = s.colourer.value = 0.8

Finally, you can associate a script with the GUI component, in order to handle input and I/O events, and to build high-level functionality onto it. Associate a script object with the component using the script attribute:

s.script = PyGUI.Button( s )

For more details about GUI scripts, see XML and Python, and Input events. For more details on attributes, see the Client Python API's entry Main Page → Client → GUI → Classes → SimpleGUIComponent.

If you are creating a GUI purely in Python, then you must ensure that you correctly drop all references to it when it is to be deleted, or there will be a memory leak. This is because the Python garbage collection is turned off in the BigWorld engine, it uses reference counting instead for speed. You might get a warning message like the following:

---------------------------------------------------------
Some SimpleGUIComponent instances haven't been destroyed.
To debug, in <engine_config>.xml, set:
   <simpleGui>
     <breakOnAllocId> AllocId </breakOnAllocId>
     <breakOnLeak>    true </breakOnLeak>
   </simpleGui>
---------------------------------------------------------

To delete, you must set all references to the GUI component to None, and this includes removing the component from its parent.

if s.parent:
    s.parent.delChild( s )
else:
    GUI.delRoot( s )
s = None

GUI can also be represented as XML files. They can be saved in the folder <res>/guis once constructed, for example, using the method described above.

The advantage of the Python interface is that once you have created the GUI, simply call:

s.save( "guis/health_bar.gui" )

An XML file will be created encapsulating the GUI component, its shaders, and all of its children. Once you have done this, write:

GUI.delRoot( s )
s = None
s = GUI.load( "guis/health_bar.gui" )
GUI.addRoot( s )

After that, you will have exactly the same component, with all its shaders and children set up.

Advanced users will find creating XML by hand the quickest way to create your GUI. Alternatively, a GUI editor can be entirely created in Python.

When you have a GUI component with a script saved in XML, your Python script must implement the following methods (at the very least to stub them out):

SimpleGUI offers support for keyboard, joystick, and mouse input. To capture events, a component needs to have its property focus set to true, and an associated Python script attached.

When loading a component from a GUI file, the attribute of a SimpleGUIComponent is automatically set if the XML declares a script field. The value of the field is used to instantiate the script object (it must be a callable receiving one parameter — the SimpleGUIComponent being created — , and returning a Python object). The Python object returned will be the one assigned as the script object for the newly created component.

The script attribute can also be set manually for an existing component, like in the example below:

# instantiate a new PyGUI Button class, and make it the component's 
# script attribute. note most scripts are passed the GUI component 
# in their constructor so they can perform operations on them.
s.script = PyGUI.Button( s )

There are separate focus properties for each category of input events, as described below:

To make a component start receiving input events, you must set the appropriate property to True, and to have it no longer receiving events set it to False, as illustrated below:

# start receiving key/axis events
c.focus = True

# stop receiving mouse enter/leave events
c.crossFocus = False

When a component has a script and it has focus enabled, the script will start capturing input events.

The script must define the appropriate methods to handle the events. The example below illustrated a script defining the methods to handle keyboard and joystick (axis) events:

class Button:
   def handleKeyEvent( self, event ):
      # do whatever, and return 1 if 
      # this key event was consumed

   def handleAxisEvent( self, event ):
      # do whatever, and return 1 
      # if this axis event was consumed

The following sub-sections describe the events supported by SimpleGUI. For more details, see the Client Python API's entry Main Page → Client → GUI → Classes → SimpleGUIComponent.

def handleKeyEvent( self, event )

def handleAxisEvent( self, axis, value, dTime )

def handleMouseButtonEvent( self, comp, event )

def handleMouseClickEvent( self, comp, pos )

def handleMouseEnterEvent( self, comp, pos )

def handleMouseLeaveEvent( self, comp, pos )

def handleMouseEvent( self, comp, event )

def handleDragStartEvent( self, comp, pos )

def handleDragStopEvent( self, comp, pos )

def handleDragEnterEvent( self, comp, pos, dropped )

def handleDragLeaveEvent( self, comp, pos )

def handleDropEvent( self, comp, pos, dropped )

It is possible to control the behaviour and appearance of the mouse cursor from the game scripts. Mouse cursor-related functions and properties can be accessed though the MouseCursor object.

The MouseCursor object is a singleton, and can be obtained using the method GUI.mcursor.

The properties published by it are described below:

The MouseCursor is an instance of the abstract concept InputCursor. There can only be one active InputCursor at any given time.

To activate the MouseCursor, use the method BigWorld.setCursor. To deactivate it, activate another input cursor, or pass None to BigWorld.setCursor.

Mouse and drag-and-drop events are only propagated to GUI components while the MouseCursor is active.

The code below illustrates how to use the MouseCursor:

# access and modify the mouse cursor
import GUI
import BigWorld

mc = GUI.mcursor()
mc.shape = "arrow"
mc.visible = True
if not mc.active:
   lastPosition = mc.position
   mc.position = ( 0.0, 0.0 )
   BigWorld.setCursor( mc )
   # mc.active is now True

Example of how to use MouseCursor object