GUI Scripting: Names & Case Sensitivity

This page is part of a series. See GUI Scripting Language for overview.

Quick Take

• Names of things follow the usual C-language rules.
• Keywords - of the GUI scripting language and of preprocessor directives - are case-sensitive. Get it wrong... parsing will fail.
• Other names are case-insensitive.
• There are important naming and casing conventions.
• Case-sensitivity of the string values of directives and properties depends on where they are used.

Details

What follows is organized in terms of where a name is first encountered in a GUI file, but also may include information about how the name might be later referenced, i.e., in the body of an event handler.

Preprocessor Directives - Keywords & Values

A directive keyword (e.g., starts with "#", like "#defined") MUST be lower case. #defined names are case-sensitive and uppercase (with underscores) by convention. A quoted string value is stored as is, with the expectation the value will be appropriate where later used. Example:

#define INV_GUI_FONT "fonts/stone"

guiDefs - Type Keywords & Names

Types of guiDef are case sensitive. Keywords like "windowDef" need to be entered exactly to avoid crashes.

A windowDef is always at the top-level (i.e., starts the GUI), and by convention should be named "Desktop" (unless perhaps this is a non-overlay applied to a world object surface).

The names you give to guiDefs (unique within the GUI at hand) are up to you. The most common convention is camel-case, no underscores, and starting with a capital letter:

 windowDef SettingsCategories

Another common style is the same, but starting with lower case:

 windowDef rightPageCurl

Other styles are rare:

 windowDef statistics_select
 windowDef backgroundsingle

As just seen, no double-quotes are around the name when it is so declared. It will always be within a quoted string when referenced elsewhere.

A reference to the name of a guiDef is not case sensitive. For example given a windowDef named InventoryItemIcon:

 resetTime "inventoryitemicon" 0; // OK in onTime handler
 set "Debug::text" "$inventoryitemicon::myval"; // OK in event handler, where Debug is another windowDef and myval is a user variable in InventoryItemIcon. "$" tells "set" to use value, not literal string.

Nevertheless, it is recommended that you be consistent, as if it were case sensitive.

Property Names

The designers of properties followed a strong convention to use all lower case names, without underscores. Surprisingly, a property name is not case sensitive. During initialization:

Background "gui::Inventory_ItemIcon" // Both "Background" and the recommended "background" are fine

During referencing in an event handler:

set "Debug::text" "$InventoryItemIcon::Background"; // Both "Background" and "background" are fine.

Nevertheless, it is recommended that you adhere to the lower case convention.

User Variable Names

The names you give to user variables are up to you. There appears to be no consensus on a naming style (other than avoiding all-caps more appropriate for #defines), so do what you wish. Just avoid predefined keywords regardless of case.

A reference to the name of a user variable is not case sensitive. For example given a user variable "float myval 0":

 set "MyVal" 3; // OK in event handler
 if("MyVal" == 3) ... // OK in event handler

Nevertheless, it is recommended that you be consistent, as if it were case sensitive.

Properties with String Values

The string value of a property is stored as given. Whether case-sensitivity is an issue might depend on how/where it is used.

For string values representing paths, the convention (or is it required?) is all lower case plus punctuation, e.g.:

font		"fonts/carleton"
background "textures/water_source/blue_plain_flat_midmurk"

If the string value of property "text" contains an "_", it will be shown on screen as a " ". (This is probably a feature, not a bug.)

Main menu controls can be grouped together by a group name, referenced in a sliderDef, editDef, or choiceDef by using (as appropriate) the property "cvarGroup" or "updateGroup". That group name is case sensitive, when invoked by engine code, e.g., using an event like "cvar read <group name>". The convention for a group name is to use all lower case.

Event Handlers - Type Keywords & Names

Event handler types are case sensitive. Keywords like "onTime" need to be entered exactly to avoid confusing the parser.

With "onNamedEvent", a case-insensitive comparison is made, between the name used in the GUI and the event name raised in the .script or cpp code