192.168.0.142 at 10:33, 16 October 2007

2007-10-16T10:33:53Z

New page

Templates can be used for reducing the size of GUIs and improving the readability of them.<includeonly>

{{main|GUIs: Templates}}</includeonly><noinclude>

== Templates ==
Templates are very useful and the use of them is essential in creating some of the more complex GUIs like the main menu, server browser and the limbo menu. It increases the readability of the scripts a lot since often used script code can be hidden away in the templates and it can guarantee that for example buttons in the main menu all behave and look the same way.

Basic example of a GUI template:
$template simpleTemplate
[put text here]
$endtemplate
All occurrences of ''simpleTemplate'' in any GUIs will be replaced with the ''[put text here]'' keywords when parsing the GUIs.

== Naming convention ==
Templates that are generic and could/is being used several places should have one underscore. Templates or "helper templates" that are only used in a GUI should have two underscores.

Both these templates are from ''guis/common/utility.include''. ''__right'' is only used as a helper template for ''_right'' and should have two underscores:
$template __right( windowName, padding )
( ( gui.windowName.rect.width - rect.width ) - padding )
$endtemplate

$template _right( windowName )
__right( windowName, PADDING )
$endtemplate
There are hundreds of places where ''_right'' is used since you just about always want to have padding between windows, while ''__right'' is not used outside the include file (except for one case).

== Simple Templates ==
The simplest templates have no parameters and replaces the parameter name throughout the GUIs with the contents of the template during parsing:

Found in ''guis/common/utility.include'' and used in the main menu:
$template _monitor_music_volume
events {
onCVarChanged "s_volumeMusic_dB" {
gui.fadeSoundClass( 1, gui.getCVarFloat( "s_volumeMusic_dB" ), 500 );
}
}
$endtemplate

Main Menu line ~85:
...
_menu_icons
_crosshair_materials
_monitor_music_volume

// init window classes
_btn_init
_dlg_init
...

== Templates With Parameters ==
Often templates have arguments, for example the _bottom and _center templates found in ''guis/common/utility.include'', useful for placing a windows in relation to other windows:
$template _bottom( windowName )
( ( gui.windowName.rect.height - rect.h ) - PADDING )
$endtemplate

$template _center( windowName, orientation )
( ( gui.windowName.rect.orientation * 0.5 ) - ( rect.orientation * 0.5 ) )
$endtemplate

A window at this position:
rect rect = ( ( gui.desktop.rect.orientation * 0.5 ) - ( rect.width * 0.5 ) ), ( ( gui.desktop.rect.height - rect.h ) - PADDING ), SCREEN_WIDTH/2, 32;
is equal to a window at this position using templates:
rect rect = _center( desktop, width ), _bottom( desktop ), SCREEN_WIDTH/2, 32;
The example will place the window at the center of the screen, just above the bottom edge of the GUI. The second version is much easier to read and you can be sure that no spelling mistakes have been made for it since the template is most likely being used in several other places.

A more commpliated template with the use of multiple parameters:
$template _horizontal_line( NameParm, XPos, YPos, WidthParm, HeightParm )
windowDef div##NameParm {
properties {
rect rect = XPos, YPos, WidthParm, HeightParm;
color backColor = COLOR_MED;
string material = "window_line_t";
}
$endtemplate
For many templates like buttons/edit boxes/lists/sliders/etc. there is a closing template which allows you to include the start template then add some additional scripting if needed before closing the window with a _end_<template name>:
$template _end_horizontal_line
}
$endtemplate

Notice the two ''##'' which means it will concatenate div and the name NameParm. If you create a horizontal line like this for example:
_horizontal_line( Horizontal1, 0, 0, SREEN_WIDTH, 4 )
_end_horizontal_line
After parsing it will expand to:
windowDef divHorizontal1 {
properties {
rect rect = 0, 0, SREEN_WIDTH, 4;
color backColor = COLOR_MED;
string material = "window_line_t";
}
}

Names can be made literal with a single # as a prefix. If a template parameter is ''MaterialName'' and the value of ''MaterialName'' is window_line_t then using ''#MaterialName'' will expand to ''"window_line_t"'' after parsing.

== Game Settings Template ==
The Game Settings dialog in the main menu is actually a template itself so only a single line needs to be included in ''guis/mainmenu/mainmenu.gui'' to include the dialog. It heavily uses templates itself which makes it a lot more readable.

Here's the advanced vehicles section of the game settings, found in ''guis/mainmenu/dialogs/gamesettings.include'':
_label_localized( GameSettings_AdvVehicles, localize( "guis/mainmenu/vehicles" ), PADDING, PADDING, 100, BUTTON_HEIGHT, COLOR_WHITE )
properties {
vec2 textAlignment = TA_LEFT, TA_VCENTER;
}
_end_label
_check( GameSettings_AdvFlight, localize( "guis/mainmenu/advflight" ), $evalfloat( 2 * PADDING ), 0, 120 )
_cvar_bool( ui_advancedFlightControls )
_end_check

To really understand this you just have to look up the template and see what the parameters do.

''guis/mainmenu/components/label.include'':
$template _label_localized( NameParm, TextParm, XPos, YPos, Width, Height, ColorParm )
NameParm is the name of the window. Draw a localized label at XPos/YPos with the Width/Height where TextParm is the text handle with a color of ColorParm.

''guis/mainmenu/components/lines.include'':
$template _check( NameParm, TextParm, xPos, yPos, WidthParm )
NameParm is the name of the window. Draw a check box with the localized text handle TextParm at xPos/yPos with the specified width.

''guis/mainmenu/cvars.include'':
$template _cvar_bool( CVarParm )
This template ties the value of the checkbox with the CVar specified.

Now it is really easy to add another checkbox here if we would want to, here's an example that adds an advanced driving controls checkbox:
_check( GameSettings_AdvDriving, localize( "guis/mainmenu/advdriving" ), $evalfloat( 2 * PADDING ), 0, 120 )
_cvar_bool( ui_advancedDrivingControls )
_end_check

[[Category:GUIs]]

</noinclude>

GUIs: Templates - Revision history

192.168.0.142 at 10:33, 16 October 2007