Changes between Initial Version and Version 1 of GUI_-_Properties

Timestamp:

Feb 23, 2008, 4:19:00 AM (16 years ago)

Author:

trac

Comment:

--

GUI_-_Properties

@@ +1 @@
+First of all, it's important that I explain what is concidered 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: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name 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 [wiki:Styles] for more information.
+
+== type ==
+ * default: "empty"
+ * value: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name name]
+
+Used to return the name of the parent of this child object.
+
+== size ==
+ * default: "0 0 100% 100%"
+ * value: [wiki:GUI_-_Data_Types#client_area client area]
+
+The position and size of the object. To learn more about sizing, see [wiki:GUI_-_Data_Types#client_area 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: [wiki:GUI_-_Data_Types#float 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: [wiki:GUI_-_Data_Types#float 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: [wiki:GUI_-_Data_Types#float 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: [wiki:GUI_-_Data_Types#string 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 [wiki:GUI_-_Text_Renderer Text Renderer] sections for more information.
+
+== checked ==
+ * default: "false"
+ * value: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#string 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 [wiki:cell_size] image property for more information about multi-cell sprites.
+
+== dropdown_buffer ==
+ * default: *
+ * value: [wiki:GUI_-_Data_Types#float float]
+{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}
+
+To make a [wiki:GUI_-_Drop-down Drop-down] look good, you will probably need sprites that are a bit larger than they should be, just like for [wiki:GUI_-_Input Input] controls. This will force the [wiki:GUI_-_Drop-down Drop-down] part to be placed with a little buffer below the main part.
+
+Check out the [wiki:GUI_-_Drop-down Drop-down] for an image of this.
+
+== dropdown_size ==
+ * default: *
+ * value: [wiki:GUI_-_Data_Types#float 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 [wiki:GUI_-_Drop-down Drop-down] for an image of this.
+
+== font ==
+ * default: "verdana12"
+ * value: [wiki:GUI_-_Data_Types#name 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 [wiki:Font_Builder 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.}}
+
+== input_init_value_destroyed_at_focus ==
+'''Not yet implemented.'''  
+ * default: "false"
+ * value: [wiki:GUI_-_Data_Types#bool bool] "(true|false)"
+
+Used by the input box. If set to true, the initial caption of the input box (eg "Insert Text Here") is removed the first time the control is clicked.
+
+== list ==
+ * Default: ''empty of items''
+ * Value: [wiki:GUI_-_Data_Types#list list]
+
+The list of strings in, for instance, the [wiki:GUI_-_List 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 [wiki:GUI_-_Data_Types#list its documentation].
+
+== max_length ==
+ * Default: *
+ * Value: [wiki:GUI_-_Data_Types#int int]
+{{Template:TODO|Gee|* Just add a default value to the default style and update this.}}
+
+Used by the [wiki:GUI_-_Input Input] control to specify the maximum number of characters the user is allowed to enter.
+
+== multiline ==
+ * default: "false"
+ * value: [wiki:GUI_-_Data_Types#bool bool] "(true|false)"
+
+Should the [wiki:GUI_-_Input Input] control word-wrap or scroll horizontally when reaching the right edge? True and it'll continue on the next row.
+
+== scrollbar ==
+ * default: "false"
+ * value: [wiki:GUI_-_Data_Types#bool 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: [wiki:GUI_-_Data_Types#name name]
+
+Specifies the type of scrollbar attached to this object. See the [wiki:GUI_-_Custom_Objects#scrollbar scrollbar] object for more information.
+
+An object uses the ''default'' scrollbar when ''scrollbar_style'' isn't specified.
+
+== selected ==
+ * default: "-1"
+ * value: [wiki:GUI_-_Data_Types#int 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).
+
+== sprite ==
+ * default: "null"
+ * value: [wiki:GUI_-_Data_Types#name name]
+
+The object displays this texture container (or collage of textures) within its sprite boundaries. See [wiki:GUI_-_Sprites 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 [wiki:GUI_-_Sprites#Skip_a_step Skip a step] for more information.
+
+== sprite_background ==
+ * default: "null"
+ * value: [wiki:GUI_-_Data_Types#name name]
+
+Specifies the sprite to use as the background of the ''progressbar'' control.
+
+Also see the [wiki:GUI_-_Progress-bar Progress-bar].
+
+== sprite_bar ==
+ * default: "null"
+ * value: [wiki:GUI_-_Data_Types#name name]
+
+Specifies the sprite to use as the advancing bar of the ''progressbar'' control.
+
+Also see the [wiki:GUI_-_Progress-bar Progress-bar].
+
+== sprite_disabled ==
+ * default: ''sprite''
+ * value: [wiki:GUI_-_Data_Types#name name]
+
+This sprite is used when the primary sprite is disabled. (See the [wiki:GUI_-_Properties#enabled enabled] property for more information about this state).
+
+If no value is specified, it uses the value of the object's "sprite" property.
+
+== sprite_list ==
+ * default: "null"
+ * value: [wiki:GUI_-_Data_Types#name name]
+
+Background of the list in the [wiki:GUI_-_Drop-down Drop-down], go to its documentation for an image of this.
+
+== sprite_over ==
+ * default: ''sprite''
+ * value: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name name]
+
+The sprite to cover a selected area in several controls. For example text in an [wiki:GUI_-_Input input] control, or perhaps an element in a [wiki:GUI_-_List list] control (take a look at the image in the [wiki:GUI_-_List list's documentation]).
+
+== sprite2 ==
+ * default: "null"
+ * value: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name name]
+
+This sprite is used when the secondary sprite is disabled. (See the [wiki:GUI_-_Properties#enabled 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: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#name 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: [wiki:GUI_-_Data_Types#float float]
+
+[wiki:GUI_-_Check-box Check-boxes] and [wiki:GUI_-_Radio-button 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 [wiki:GUI_-_Check-box 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: [wiki:GUI_-_Data_Types#enum 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: [wiki:GUI_-_Data_Types#enum 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: [wiki:GUI_-_Data_Types#color color]
+
+Specifies the colour of caption's text (eg "255 255 255" for white text). See [wiki:GUI_-_Data_Types#color color] for more information about colour settings.
+
+== textcolor_disabled ==
+ * default: ''textcolor''
+ * value: [wiki:GUI_-_Data_Types#color color]
+
+Specifies the colour of caption's text when the object is disabled. (See the [wiki:GUI_-_Properties#enabled 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: [wiki:GUI_-_Data_Types#color 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: [wiki:GUI_-_Data_Types#color 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: [wiki:GUI_-_Data_Types#color 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: [wiki:GUI_-_Data_Types#string 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 [wiki:GUI_-_Custom_Objects#tooltip tooltip] object for more information.
+
+== tooltip_style ==
+ * default: "default"
+ * value: [wiki:GUI_-_Data_Types#string 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 [wiki:GUI_-_Custom_Objects#tooltip tooltip] object for more information.