Geep: Add category tag

2022-11-04T16:08:30Z

Add category tag

← Older revision		Revision as of 16:08, 4 November 2022
Line 74:		Line 74:

	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		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

			{{GUI}}

Geep: create this article

2022-10-04T19:36:34Z

create this article

New page

''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

GUI Scripting: Names & Case Sensitivity - Revision history

Geep: Add category tag

Geep: create this article