Widgets

S2Engine GUI system is based on widgets. A widget is a screen element that can have a text, an image, dimensions and a position.
To Create a widget You must use the function CreateWidget. There are many different types of widget you can create in S2Engine GUI system.
Every widget can have its own script file, you can use script for programming widget behaviour, even if some basic widgets like buttons, progressBars, sliders, can already have their own predefined behaviour.
Widget are organized into hierachies, every widget can comunicate with its subwidgets or its parent widget by messages (see also SendMessageSubWidget, SendMessageParentWidget, SendMessageWidget, SendMessageWidgetHUD). All Widgets can be grayed by setting the flag w_grayed with SetFlags, ResetFlags, SetSubWidgetFlags, ResetSubWidgetFlags functions.
They can also be showed/hided (see ShowWidget) and actived-deactived (see ActiveWidget).
Like Objects, widgets have params that can you can set/get by SetParam, SetSubWidgetParam, GetParam and GetSubWidgetParam functions.

Widget

Thw widget is the base element of a GUI. All GUI elements are widgets.
Following are parameters common to al widgets.

Parameters

pos	the position of the widget respect its parent (if it has no parents the position is in screen coordinates).
width	width of the widget.
height	height of the widget.
name	name of the widget, it is used to recognize the widget from its parent.
Texture	the filename of picture of the widget, can also be empty.
Font	the filename of the font. All Fonts are inside Fonts folder and have .ft2 as extension.
Fontsize	the size of the font characters.
Fontcolor	the color of the font characters.
Fontspace	the space, in pixels, between characters
TextAlign	alignment of the text inside widget. This param has integer values: -1 means text at left, 0 means text at center, 1 means text at right.
Valign	vertical alignment of the widget respect to its parent (screen if no parents): This param has integer values: -1 means widget at bottom of its parent, 0 means widget at center of its parent, 1 means widget at top of its parent.
Halign	horizontal alignment of the widget respect to its parent (screen if no parents): This param has integer values: -1 means widget at left of its parent, 0 means widget at center of its parent, 1 means widget at right of its parent.
Litcolor	color that text has when cursor stays over the widget (used expecially for buttons). It must be specified as a triple of scalar values between 0 and 1. For example grey color is "0.5,0.5,0.5", white is "1,1,1", balck is "0,0,0".
text	string that contains the text that shall appear on the widget.
Extended	This is a boolean flag. If true the widget dimensions begin equal to the screen dimensions.
Script	the filename of the script to assign to the widget. Remember that the script files are inside scripts folder, when specify the script filename, you must write script\ before the filename.
LitTexture	The filename of the texture the widget has when cursor stays over it
GrayedTexture	The filename of the texture the widget has when it is grayed.
Wextended
Hextended
border
borderColor
dockTop
dockBottom
dockRight
dockLeft
data
icon
iconSize
Lextended
WLextended
HLextended
grayedColor
texColor
texAlpha
fadeSpeed

Attention

the pictures are texture assets. When you specify the filename of the picture you must specify the relative path from project directory.

For a detailed description of available widget classes see GUI Core Classes

Container

A Container is a widgets that can contain other widgets. We have already said that widgets are organized into hierarchy. In fact the container is the parent of the contained widgets, and these last are the childs of the container widget, if some of the child widgets are container they can have other childs, and so on.... When programming a widget that contains other widgets you must create the subwidgets inside the init() entry point function using the CreateWidget function, and implement the message() entry point function to process messages coming from the subwidgets.

Attention

Container is an abstract class so you cannot create a container directly, if you want to create a void container use Frame class.

GUI

The GUI Script is the script of the game GUI container widget, i.e. The widget that contains all other widget inside the game GUI. GUI main widget can contain the cursor. You can Show/Hide the cursor by calling ShowCursor action. To associate a script to the GUI widget you have to specify its filename into the S2Engine.ini file:

main=mainGame.sc2

where mainGame.s2 is the filename of the GUI widget script. If you want to test your main script you have to execute the S2Frontend.exe application after setting the S2Engine.ini file. Here is a example of a simple main script that you can use to load a scene level:

/* tell the engine that it has to scan this scene when publishing. See Publish page. */
#scene "scenes/FPSTemplate4.bin"

/* load flag */
var bool _load;

/* application init */
function void init()
{
  /* set extend param to true to set fullscreen */
  SetParam("extended","true");

  /* create a render frame in which the scene will be drawed */     
  CreateWidget("renderframe","","render, ,800,600,0,0,blu.tga,arial.ft2,0","0,0");
  
  /* do not show the border for render frame */
  SetSubWidgetParam("render","Border","false");
 
  /* the scene must be drawed in fullscreen */
  SetSubWidgetParam("render","extended","true");
  
  /* have to load the level */
  _load=true;
    
  /* do not show the cursor */
  ShowCursor(false);
}

/* Application Update */
function void Update()
{
  /* must load? */
  if(_load)
  {
    /* yes. So load the level */
    LoadLevel("scenes/FPSTemplate4.bin");
    
    /* level just loaded */
    _load=false;
  }
   
  /* check for esc key pression */
  if( IsKeyPressed("@esc",1) )
  {
    /* if so exit from the application */
    Exit();
  }
}

Attention

The GUI script is automatically loaded into a MainFrame used by the system as GUI main Frame.

HUD

the HUD script is the script of the main HUD container widget, i.e. The widget that contains all other widgets inside the HUD gui. HUD main widget can contain the cursor.

You can Show/Hide the cursor by calling ShowCursor action. The HUD main widget, instead, must be created inside the loaded game level using the CreateHUD function. It can be created in one of the object scripts of the level, you could also create an helper object containing exclusively the HUD script. It also could be useful to create HUD script inside the player character script.

Attention

The HUD script is automatically loaded into a MainFrame used by the system as HUD main Frame.

If you want to create a widget to attach to HUD outside the HUD script (for example inside player script) you have to use CreateWidgetHUD function.

Loading screen

There is another main widget, it is the Loading Screen container widget, that contains all the widgets appearing on the loading screen, during the loading level time, it also can be scripted. The loading screen main widget is always associated to the loading.sc2 script. So if you want to modify loading screen behaviour you have to modify that script file. Here is an example of Loading screen script:

function void init()
{
  SetParam("Extended","true");
  SetParam("texture","white.tga");
    
  CreateWidget("label","","sfondoPIC, ,300,300,0,0,intro_bg.dds,arial.ft2,0","0,-50");
  CreateWidget("progressbar","","progress, ,512,32,0,0,progress.dds,arial.ft2,0","0,100");  
  CreateWidget("label","","percent, ,120,64,0,0, ,arial.ft2,0","0,132");    
}

function void message()
{
  if(ReceivedMessage("progress"))
  {
    var float progress;
    progress=float(message#0)/10.0;
    
    SetSubWidgetParam("progress","scalar",string(progress));
    SetSubWidgetParam("percent","text",string(int(message#0))+"%");
  }
}

Attention

The LoadingScreen script is automatically loaded into a MainFrame used by the system as LoadingScreen main Frame.