UFO-Scripts/menu *.ufo

From UFO:AI

Contents 1 General 1.1 Valid entities 2 Menu definition 2.1 Actions 2.2 Image 2.2.1 Example for texh and texl 2.3 String 2.4 Zone 2.5 Model 2.6 Text 2.7 Menu function 2.7.1 Init 2.7.2 Close 2.7.3 Confunc 2.7.4 Cvarfunc 2.7.5 event 2.7.6 Mouse events 2.8 Bar 2.9 Container 2.10 Select box (drop down box) 2.11 Checkbox 3 Links

General

All menus in UFO:AI are script based. It's a convention that all menus are placed in files with menu_MENUNAME.ufo (where MENUNAME is to be replaced).

Valid entities

• tooltip V_STRING

use a _ as first char to make it translatable - nevertheless this is not V_TRANSLATION_STRING but a V_STRING. (If you don't know what I'm talking about - then it doesn't matter)

Make sure, that the node you want to display the tooltips for has at least one hover function - this can be click, rclick, in, out or whatever you like - they even can be empty.

Also make sure, that if you want to use tooltips for e.g. string nodes that you define a size for this node, too (to create the box where the tooltip is to be shown)

Example:

tooltip "_This is your tooltip"

• key V_STRING

use a * as first char followed by binding and a scriptcommand to print the keybinding for a given scriptcommand as tooltip

Example:

key "*binding nextround"

Menu definition

Every menu needs a unique identifier.

menu bases
{
	[...]
}

The identifier of this menu is bases. You can push the menu onto the stack by using the command

mn_push bases

It is also possible to define a menu that inherits content from another menu. Use the "extends" keyword in the menu identifier:

menu hudinv extends inventory
{
	[...]
}

This defines a new menu hudinv which inherits the content of a previously defined menu inventory. This provides a basic means of re-using some menu content. The menu_inventory.ufo is a simple example which defines two soldier inventory menus (one for the HUD and another for the alt-HUD) that inherit most of their content from a generic inventory menu. A menu that extends another can also override inherited content, simply by redefining nodes (see menu_singleplayer.ufo for an example). Note: it is not yet possible for a menu to extend more than one other menu. However chains of menu extension are possible (e.g. menu C extends menu B which in-turn extends menu A). Finally the order of menus is important... if menu B extends menu A then menu A must be defined first (in general both menus should be in the same .ufo file with menu A defined at the top).

Actions

• clicks: click, rclick, mclick
• hover: in, out

pic aircraft_return
{
	[...]
	click		{ }
	out		{ }
	in		{ }
}

You can define various actions in these event handlers. You can execute commands with cmd "command" or change attribute of the current node.

Let us take the aircraft_return node as an example again:

pic aircraft_return
{
	image	menu/buttons_small
	[..]
	texl	"0 32"
	texh	"16 48"
	click	{ cmd "aircraft_return" }
	out	{ *aircraft_return texl "0 32" *aircraft_return texh "16 48" }
	in	{ *aircraft_return texl "16 32" *aircraft_return texh "32 48" }
}

We use the image menu/buttons_small in this image node (see image for more details. And define several event handlers, the click, in and out event handler. The click event handler will execute the command aircraft_return when you left click onto the rendered node. The out and in event handlers will change some attributes of the node.

This is done by:

*aircraft_return texl "0 32" *aircraft_return texh "16 48"

This line changes the attributes texl and texh for the node aircraft_return to the given values. Every other attribute can be changed in the same way. You can change the size, color or whatever you like (even of other nodes than aircraft_return).

Image

pic aircraft_return
{
	image	menu/buttons_small
	pos	"550 410"
	pos	"128 0"
	texl	"0 32"
	texh	"16 48"
	[..]
}

To include images into the menu you have to use a pic node. This node has several attributes:

• image: V_STRING the image path - relative to base/pics (see directory tree)
• pos: V_POS the position on the screen. These values are normalized to 1024x768
• size: V_POS the size of the image. These values are normalized to 1024x768. If you only want to scale into one direction, set the other to 0.
• texh: V_POS the coordinates from the image source file (x direction)
• texl: V_POS the coordinates from the image source file (y direction)
• blend: V_BOOL Set this to true (or 1) in order to use semi-transparent images. Default is false (0)

Example for texh and texl

Assume you are using a picture with the dimensions 128x32 that includes 2 buttons - each of a size 64x32. One of them is used for highlighting the other one (remember the menu actions). The first button (the left one) uses the texl coordinates texl "0 0" and the texh coordinates texh "64 32" because it starts at pixel 0 for x and y and go 64 pixels in x direction and 32 pixels in y direction. The hover part of the current button was placed right beside the current item at x 64, y 0 - this leads to a texl of texl "64 0" and texh of texh "128 32"

String

A string can be a normal string:

string team_members
{
	string	"_Team Members:"
	pos	"480 486"
}

or a cvar value of a given cvar:

string team_hired
{
	string	"*cvar mn_hired"
	pos	"480 508"
}

both cases needs a pos (V_POS) to be placed (this is normalized to a resolution of 1024x768). Also notice the _ for "Team Members:". This is the translation marker. Please have a look at translating or V_TRANSLATION_STRING and V_TRANSLATION2_STRING for information about this.

Zone

3 types of zone :

• zone render : menu is displayed in full screen.
• zone popup : menu is not displayed in full screen. Others menus previously displayed are visible.
• zone click : usefull to detect a mouse click inside the defined zone.

At least 3 attributes :

• pos: V_POS the position on the screen. These values are normalized to 1024x768
• size: V_POS
• invis : true or false. it doesn't make sense to use it, because a zone is not displayed.

Model

To include a 3D-model:

• model: V_STRING the path to the model - relative to base/models (see directory tree)

Text

• pos: V_POS
• size: V_POS
• bgcolor V_COLOR

draw the text field with a background color

• format: V_POS

format is used for tabstops and newlines - V_POS is y and x, for tabs go x in x direction for newline go y in y direction

Make sure every clickable text node has the format parameter set (at least the y value [the first]) (Otherwise a click to such a node will produce an assertation)

• num: V_INT
  • 0 = TEXT_STANDARD
  • 1 = TEXT_LIST
  • 2 = TEXT_UFOPEDIA
  • 3 = TEXT_BUILDINGS
  • 4 = TEXT_BUILDING_INFO
  • 5 = TEXT_RESEARCH
  • 6 = TEXT_RESEARCH_INFO
  • 7 = TEXT_POPUP
  • 8 = TEXT_POPUP_INFO
  • 9 = TEXT_AIRCRAFT_LIST
  • 10 = TEXT_AIRCRAFT
  • 11 = TEXT_AIRCRAFT_INFO
  • 12 = TEXT_MESSAGESYSTEM
  • 13 = TEXT_CAMPAIGN_LIST
  • 14 = TEXT_MULTISELECTION
  • There are way more ids in use - see the cl_menu.h for and up-to-date list

Display the content of the global variable menuText[num].

if no num value is given - it's TEXT_STANDARD (0) by default. This enumeration is located in the /src/client/client.h file.

text infoscreen
{
	pos		"425 702"
	size	"260 50"
	format	"20 0"
}

• scrollbar: V_BOOL

Use a scrollbar for this node - also set height.

• height: V_INT

The maximum amount of lines to print - see format parameter to set the pixel height of one line.

Menu function

Init

Called everytime the menu is pushed onto the stack (mn_push - see commands)

func init
{
	cmd "someCommandName"
}

Close

Called when removing the menu from the stack (mn_pop - see commands)

func close
{
	cmd "someCommandName"
}

Confunc

Confunc are script functions that are defined from within the scripts. They are available as commands like all other script commands.

confunc uniqueID
{
	[..]
	cmd "someCommand"
	[..]
}

Cvarfunc

???

cvarfunc uniqueID
{
}

event

Every menu can have an event func - this node also needs a timeout value (default is 2000). The timeout value is a ms value after which the cmd in this event func should be executed. This can be used to update menus without userinteraction

func event
{
	timeout 30000
	cmd "someCommand"
}

Mouse events

To call a specific function when a user click on a text control, you have two choices on how to integrate the scriptfunction.

• add an instruction in CL_InitLocal function, in /src/client/cl_main.c file.
• use a confunc (see above)

First example will look like this:

Cmd_AddCommand("TexTName_click", FunctionName);

Example :

Cmd_AddCommand("ships_click", CL_SelectAircraft_f);	 
Cmd_AddCommand("ships_rclick", CL_OpenAircraft_f);

Second one is only to define a confunc with the name TexTName_click Example:

confunc ships_click {
	*ships bgcolor "1 1 1 1"
}

This example will change the bgcolor attribute of the node named ships to a V_COLOR value of 1 1 1 1 (white)

Bar

• pos: V_POS the position on the screen. These values are normalized to 1024x768.
• size: V_POS
• color: V_COLOR
• current: V_STRING cvar used to read/save the value of bar.
• min: V_FLOAT value when bar is empty - default value is 0.
• max: V_FLOAT value when bar is full - default value is 1.
• align: V_ALIGN use ul (upper-left) value to allow users to fully up the bar.

Container

Used for the inventory, as in

container backpack	{ pos "872 54" }

Select box (drop down box)

Put them to the end of the menu definition - otherwise other strings and images will shine through on opening the box.

selectbox texres_box
{
	image	"menu/selectbox_green"
	pos	"774 232"
	size	"100 20"
	color	"0.6 0.6 0.6 0.3"
	cvar	"*cvar gl_maxtexres"
	option low_value {
		label	"_Low"
		value	"256"
		action	""
	}
	option medium_value {
		label	"_Medium"
		value	"512"
		action	""
	}
	option normal_value {
		label	"_Normal"
		value	"1024"
		action	""
	}
	option high_value {
		label	"_High"
		value	"2048"
		action	""
	}
	option excellent_value {
		label	"_Excellent"
		value	"4096"
		action	""
	}
	option extrem_value {
		label	"_Extreme"
		value	"8192"
		action	""
	}
}

• action: V_STRING

execute this script command when the option entry was selected

• image: V_STRING

you can also set another image - the default one is menu/selectbox.

• label: V_TRANSLATION2_STRING

the list entry description

• value: V_STRING

the cvar value for the cvar given via e.g. cvar "*cvar gl_maxtexres". Clicking the label in the selectbox will update the cvar value of gl_maxtexres to the value given via value.

Checkbox

Checkboxes are only for cvars that can only be 0 or 1

checkbox public_value
{
	value	"*cvar public"
	pos	"840 120"
	align	ur
}

• value: V_STRING

this is the cvar that a click on the checkbox should change

• image: V_STRING

you can also set another image - the default one is menu/checkbox - you have to be aware, that the menu system appends _checked and _unchecked to the image name.

Links

• Scripting
• Create menu