5 GUI Properties
Vantha edited this page 2024-05-24 16:57:59 +02:00

First of all, it's important that I explain what is considered a property (or a setting) and what is not. Properties are all values that can be defined in the XML files when creating GUIs. These properties can later on be manipulated from Javascript by typing the property after the name, such as:

  myobject.color = newcolor;

Now the important part is this, the above can be done with not just properties, there is for instance a way to fetch the parent by typing "myobject.parent" also. This is, however, not a setting and won't be listed below. It is taken care of solely when talking about the GUI's Javascript interface. {{Template:TODO|Gee|Add link to javascript interface.}}

The default values are used to save space. Know the defaults, and know your styles' defaults, and you'll have a lot cleaner XML files.

Foundation Settings

The Foundation Settings are the premise of any object, they differ from Base Settings as they cannot be changed.

name

  • default: "null"
  • value: name

Something to uniquely identify the object; no object should share the same name with another object.

The name is case-sensitive and only regular characters should be used.

Technically, the object name is optional; if a name is not specified, the object is given an internal name when declared. For example, an empty parent can be used to group children without specifying a name for the parent. If you want to do anything with an object, though (like toggle visibility of that group), it needs a name. Of course you can always manipulate the object by changing the settings of a super-object (ie the parent or its parent etc).

style

  • default: "default"
  • value: name

Specifies the name a "style" sheet that will be used to populate the control with any additional properties not specified at definition.

If not specified, an object uses the values of the "default" style. (Current known values of the "default" style are specified in the "default:" properties in this control guide.)

See Styles for more information.

type

  • default: "empty"
  • value: name

Specifies the type of object (for example, "button", "text", or "progressbar"). Different types unlock different types of extended settings (see below), and have different behaviours.

The different type options are:

Base Settings

Settings shared between all types of object.

absolute

  • default: "false"
  • value: bool "(true|false)"

If set to false, the child's position, size and "height" (z) is relative to its parent's coordinates; they are calculated as delta values added to its parent's values ("0 0 100% 100%" would set it to the dimensions of its parent, and it could not exceed that border).

This is handy when you want to link the position of an object(s) to another object. For example, a group of buttons could then be shifted in position by a few pixels without having to separately update each control's size value.

If true (or left as default), the child's size is absolute (its size is relative to the screen resolution).

When an object uses a scrollbar, all children are required to have absolute set to false, or they will not scroll within the parent window area.

enabled

  • default: "true"
  • value: bool "(true|false)"

If set to "false", the object is disabled. It cannot be pressed by the user, and it uses the "_disabled" versions of its sprites. (Use for a control that is visible but temporarily unavailable. For example, a greyed-out checkbox, or a "train swordsman" icon when the player doesn't have enough resources to train the unit.)

ghost

  • default: "false"
  • value: bool "(true|false)"

An object with ghost set to "true" does not acknowledge user input; it becomes purely cosmetic. Attempting to click it would only affect any object underneath it. (Useful for a non-interactive number drawn over an interactive button, for example).

hidden

  • default: "false"
  • value: bool "(true|false)"

If false, the object is visible. If hidden, the object is invisible and cannot be pressed.

If a parent is hidden, all of its children are also hidden. (Thus child controls can be grouped under a parent and toggled on or off by changing the "hidden" property of the parent.)

hotkey

  • default: "null"
  • value: name

Hotkey variables are declared in an appropriate .cfg file (such as binaries/config/system.cfg) by prefixing the variable with "hotkey."

Object properties do not require the prefix, so if the .cfg variable is declared as hotkey.toggle.fps, reference it using the object property hotkey="toggle.fps".

When the player presses the key mapped to this hotkey, the "Press" event for an object with that hotkey property is triggered, as if the player had, say, clicked that button control.

parent

  • default: "null"
  • value: name

Used to return the name of the parent of this child object.

size

The position and size of the object. To learn more about sizing, see client area.

Unless an object with a greater-than-zero size has the "ghost" property, or the control is of the "empty" type, it will block interaction with the game world underneath this control.

z

  • default: .parent.z+10 (or "0" if the control has no parent)
  • value: float

An object's "Z value" specifies its drawing order. An object with a higher Z will be layered on top of an object with a lower Z.

By default, all root (parentless) objects have a Z value of "0". Children will - if not manually set - have the value of its parent's Z plus 10.

Since Z values are set automatically, this should only need to be specified in rare circumstances (such as when two siblings overlap each other). Generally just defining the objects in sequence should layer them in the right order.

Extended Settings

Settings that are only used by certain types of object.

buffer_zone

  • default: "5"
  • value: float

Specifies the distance in pixels between the text's bounding box and the edge of the control. The larger this value, the greater the size of the "border" between the text area and the edges of the sprite.

button_width

  • default: *
  • value: float

{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}

Certain controls, such as the dropdown, have a small button that appears on the far right to open the dropdown list and select a new option.

This value specifies the width of this button, so that the button does not have to be square (such as in a large dropdown with large texture images, where a slender button is preferred).

Notice that even with the button, you can still press the whole control to open the dropdown area, not just this button.

caption

  • default: "null"
  • value: string

When a control needs to contain text, such as the label over a button or the field in an input box, it is stored in the object's caption property.

The caption cannot actually be set as a caption="" property in the object's XML settings. Instead, it is stored as the value of the control object:

  <object name="whatever" type="text">This is the caption</object>

It is however called the caption when stored as a property of the object, and can be accessed as such through JS script:

  whatever = getGUIObjectByName("whatever")
  whatever.caption = "Some other text"

Captions are special strings that can accept a number of formatting tags. See the Text Renderer sections for more information.

checked

  • default: "false"
  • value: bool "(true|false)"

If set to "false", the control uses its "sprite*" properties to determine which artwork is displayed. (An empty box, for example.) If set to "true", the control uses its "sprite2*" properties to determine which artwork is displayed. (A checked box, for example.)

cell_id

  • default: "null"
  • value: string

Used in conjunction with a sprite of cells to specify which element (in the range 0..n) of a multi-cell sprite= to display at this time.

See the cell_size image property for more information about multi-cell sprites.

dropdown_buffer

  • default: *
  • value: float

{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}

To make a Drop-down look good, you will probably need sprites that are a bit larger than they should be, just like for Input controls. This will force the Drop-down part to be placed with a little buffer below the main part.

Check out the Drop-down for an image of this.

dropdown_size

  • default: *
  • value: float

{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}

In Windows, the size of a dropdown is specified as the perimeter of the whole control when opened, and then the height when closed is set to one row. This manually specifies this value, so the size of the dropdown is the size when closed.

Check out the Drop-down for an image of this.

font

  • default: "verdana12"
  • value: name

Specifies the name of the font used to display the control's text.

Fonts are bitmap fonts generated from TrueType fonts with certain size and formatting options using the Font Builder tool.

fov_wedge_color

{{Template:TODO|Gee|I know this is for the Minimap control, but I can't see it ever being used in the code.}}

list

  • Default: empty of items
  • Value: list

The list of strings in, for instance, the list control.

The Data Type list is a bit different as it can't be defined using a string. To understand more about it, see its documentation.

max_length

  • Default: *
  • Value: int

{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}

Used by the Input control to specify the maximum number of characters the user is allowed to enter.

multiline

  • default: "false"
  • value: bool "(true|false)"

Should the Input control word-wrap or scroll horizontally when reaching the right edge? True and it'll continue on the next row.

placeholder_color

  • default: "0 0 0"
  • value: color

Specifies the color of the initial label in the input field (e.g. "255 255 255" for white text). For more information about color settings, see color.

placeholder_text

  • default: "null"
  • value: string

Used by the input field. If set, an initial label is displayed in the input field (e.g. "Insert text here"), which is removed when the first text is entered.

scrollbar

  • default: "false"
  • value: bool "(true|false)"

If set to "true", the control displays its attached scrollbar at all times, not just when the length of its caption exceeds the size of the object. Not yet implemented. As of now, there's no automatic detection that will make a scrollbar appear only when needed.

scrollbar_style

  • default: "sb2"
  • value: name

Specifies the type of scrollbar attached to this object. See the scrollbar object for more information.

An object uses the default scrollbar when scrollbar_style isn't specified.

selected

  • default: "-1"
  • value: int

This value begins counting at 0, and -1 means nothing is selected.

Stores the value of which element in the control is currently selected. (For example, the current selection from a dropdown list, or the current row in a list box).

selected_column

  • default: "null"
  • value: name

By what columnn an OList is sorted.

selected_column_order

  • default: "null"
  • value: name

In which order a column of an OList is sorted. The value -1 means descending, the value 0 means not sorted, the value 1 means ascending.

sortable

  • default: "null"
  • value: bool

Whether or not an OList can be sorted.

sprite

  • default: "null"
  • value: name

The object displays this texture container (or collage of textures) within its sprite boundaries. See Sprites for more information about declaring sprites.

If you only wish to display a texture that stretches to fit the control's size, you can do this without defining the texture as a sprite in sprite1.xml using the syntax sprite="stretched:subfolder/texture.dds" (where subfolder/ is any subfolder under art/textures/ui/, and texture is the name of the texture. See Skip a step for more information.

sprite_background

  • default: "null"
  • value: name

Specifies the sprite to use as the background of the progressbar control.

Also see the Progress-bar.

sprite_bar

  • default: "null"
  • value: name

Specifies the sprite to use as the advancing bar of the progressbar control.

Also see the Progress-bar.

sprite_asc

  • default: "null"
  • value: name

This small sprite is displayed next to the heading of an OList if it is sorted by that column in ascending order.

sprite_desc

  • default: "null"
  • value: name

This small sprite is displayed next to the heading of an OList if it is sorted by that column in descending order.

sprite_disabled

  • default: sprite
  • value: name

This sprite is used when the primary sprite is disabled. (See the enabled property for more information about this state).

If no value is specified, it uses the value of the object's "sprite" property.

sprite_heading

  • default: "null"
  • value: name

Background of an OList's headings.

sprite_list

  • default: "null"
  • value: name

Background of the list in the Drop-down, go to its documentation for an image of this.

sprite_not_sorted

  • default: "null"
  • value: name

This small sprite is displayed next to the heading of an OList if it is sorted a different column.

sprite_over

  • default: sprite
  • value: name

This sprite is used when the user hovers the cursor over the primary sprite.

If no value is specified, it uses the value of the object's "sprite" property.

sprite_pressed

  • default: sprite
  • value: name

This sprite is used when the user clicks a button, it is only displayed while the mouse button is still down, and the cursor is hovering the object. If you're looking for a conventional button, this sprite should be an indented copy of sprite.

If no value is specified, it uses the value of the object's "sprite" property.

sprite_selectarea

  • default: "null"
  • value: name

The sprite to cover a selected area in several controls. For example text in an input control, or perhaps an element in a list control (take a look at the image in the list's documentation).

sprite2

  • default: "null"
  • value: name

Used by controls that can be switched to another state or consist of more than one sprite. This specifies the "secondary sprite" used when the object is in its secondary mode.

sprite2_disabled

  • default: sprite2
  • value: name

This sprite is used when the secondary sprite is disabled. (See the enabled property for more information about this state).

If no value is specified, it uses the value of the object's "sprite2" property.

sprite2_over

  • default: sprite2
  • value: name

This sprite is used when the user hovers the cursor over the secondary sprite.

If no value is specified, it uses the value of the object's "sprite2" property.

sprite2_pressed

  • default: sprite2
  • value: name

This sprite is used when the user clicks the secondary sprite (ie the "Press" event is being fired).

If no value is specified, it uses the value of the object's "sprite2" property.

square_side

  • default: "0"
  • value: float

Check-boxes and Radio-buttons both have got square sized sprite to the side of the text showing a checked/unchecked state. This is not the sprite, but the side of the square. See Check-box for an image of this. If one would want a rectangle instead of a square, making a sprite that looks rectangular when fit into a square does the trick.

text_align

  • default: "left" ("center" for type "button")
  • value: enum "(left|center|right)"

Not yet implemented. The button does not have a special default on this value.

Specifies horizontal alignment of caption text. (Left-aligned, right-aligned, or centered).

text_valign

  • default: "top" ("center" for types "button", "checkbox" and "radiobutton")
  • value: enum "(top|center|bottom)"

Not yet implemented. The button, checkbox and radiobutton does not have a special default on this value.

Specifies vertical alignment of caption text. (top-aligned, bottom-aligned, or centered).

textcolor

  • default: "0 0 0"
  • value: color

Specifies the colour of caption's text (eg "255 255 255" for white text). See color for more information about colour settings.

textcolor_disabled

  • default: textcolor
  • value: color

Specifies the colour of caption's text when the object is disabled. (See the enabled property for more information about this state).

If no value is specified, it uses the value of the object's "textcolor" property.

textcolor_over

  • default: textcolor
  • value: color

Specifies the colour of caption's text when the user hovers the cursor over the object.

If no value is specified, it uses the value of the object's "textcolor" property.

textcolor_pressed

  • default: textcolor
  • value: color

Specifies the colour of caption's text when the user clicks the object (ie the "Press" event is being fired).

If no value is specified, it uses the value of the object's "textcolor" property.

textcolor_selected

  • default: textcolor
  • value: color

Specifies the colour of caption's text when the input box is selected (the current focus; user's able to type text into it).

If no value is specified, it uses the value of the object's "textcolor" property.

tooltip

  • default: "null"
  • value: string

Specifies the string of text to display in the tooltip object when this object is being "hovered" by the user. If empty, the string does not display a tooltip.

See the tooltip object for more information.

tooltip_style

  • default: "default"
  • value: string

Specifies the name of the style of tooltip to display when this object is "hovered".

If not specified, the object uses the tooltip called default.

See the tooltip object for more information.

mask

  • default: "false"
  • value: bool "(true|false)"

Specifies whether to mask text (like in a password field).

mask_char

Specifies what character to mask text with if mask is true.