Some objects need to be predefined before they can be used, such as a new type of scrollbar which can be attached to other controls, or a particular icon that can be nested into caption text.

An indefinite number of such objects can be placed in the ''<setup.xml>'' list.

'''Key''': ''Italicised'' title means property is mandatory.

== icon ==
This lets you specify the size and texture of an icon that can be used within any caption that uses text (or perhaps only text-boxes). The only information you need to specify here is sprite name and size.

{{{
  <setup>
    <icon name="smiley"
          texture="smiley_happy02"
          size="10 10" 
    />
  </setup>
}}}

=== ''name'' ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the icon.

=== ''size'' ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#pos pos]

Specifies the width and height of the icon (ie ''size="<width> <height>"'').

=== ''sprite'' ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

Specifies the name of the sprite to use as the source of the icon. 

=== cell_id ===
 * default: "0"
 * value: [wiki:GUI_-_Data_Types#int int]

If the icon is part of a multi-cell sheet, use this to indicate which element (0..n) in the sheet to use. (eg: ''cell_id="2"'' where each cell is 10x10 will use the area of the texture at 30x10.)

== scrollbar ==

Sets up a bar that can be attached to a control, and used to scroll when the control's contents exceed its size (eg a window of scrollable text).

Horizontal scrollbars are not yet available, and will never be available for ''text'' boxes.

[[Image(http://www.wildfiregames.com/~code/resources/wiki/gui/scrollbar_example.gif)]]

{{{
  <setup>
    <scrollbar name="scrollbar1" 
               always_shown="true"
               minimum_bar_size="10"
               width="20" 
               scroll_wheel="false"
               scroll_speed="30"
               sprite_bar_vertical="scroll_dragbar"
               sprite_bar_vertical_over="scroll_dragbar_over"
               sprite_bar_vertical_pressed="scroll_dragbar_pressed"
               sprite_back_vertical="scrollbar_bkg"
               sprite_button_top="scroll_topbutton"
               sprite_button_top_disabled="scroll_topbutton_disabled"
               sprite_button_top_over="scroll_topbutton_over"
               sprite_button_top_pressed="scroll_topbutton_pressed"
               sprite_button_bottom="scroll_topbutton"
               sprite_button_bottom_disabled="scroll_topbutton_disabled"
               sprite_button_bottom_over="scroll_topbutton_over"
               sprite_button_bottom_pressed="scroll_topbutton_pressed"
    />
  </setup>
}}}

=== ''name'' ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#name name]

Name of this scrollbar. Reference this name for a control using the object setting ''scrollbar_style''.

=== always_shown ===
 * default: "false"
 * value: [wiki:GUI_-_Data_Types#bool bool] "(true|false)"

If this is "true", the scrollbar will be drawn even when no scrolling is needed, although the vertical scroll button (sprite_bar_vertical) won't be drawn and the scroll buttons will use their "*_disabled" variant.

{{Template:TODO|Gee|Not used.}}

=== minimum_bar_size ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#float float]

The ''sprite_bar_vertical'' vertical scroll button will vary in height depending on the amount of content in the object's window. This sets the minimum height (in pixels) that the ''sprite_bar_vertical'' must be no matter how much or little content is in the parent object. It won't shrink any smaller than this size.

Could be considered the "height" equivalent to the scrollbar's ''width''.

=== scroll_wheel ===
 * default: "false"
 * value: [wiki:GUI_-_Data_Types#bool bool]"(true|false)"

When ''true'', the user can use his mouse wheel to scroll the scrollbar. When ''false'', he cannot.

'''Not yet implemented.''' Do we need this?

=== scroll_speed ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#float float]

Specifies the number of pixels that the window will scroll each time the player clicks a scroll button or moves one step with the mouse wheel. Lower numbers are smoother; higher numbers are quicker.
'''Not yet implemented.''' This is hard-coded as of now.

=== sprite_bar_vertical ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the vertical sprite button (the long button that can be dragged up and down the scroll bar). 

Notice there is no ''*_disabled'' version of this property, this is because a disabled scrollbar displays no bar at all.

=== sprite_bar_vertical_over ===
 * default: ''sprite_bar_vertical''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the ''sprite_bar_vertical'' when the user is hovering the mouse over it.

=== sprite_bar_vertical_pressed ===
 * default: ''sprite_bar_vertical''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the ''sprite_bar_vertical'' when the user is clicking it.

=== sprite_back_vertical ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the background of the scrollbar.

=== sprite_button_top ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the top arrow button.

=== sprite_button_top_over ===
 * default: ''sprite_button_top''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the top arrow button when the user is hovering the mouse over it.

=== sprite_button_top_pressed ===
 * default: ''sprite_button_top''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the top arrow button when the user is clicking it.

=== sprite_button_top_disabled ===
 * default: ''sprite_button_top''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the top arrow button when it is disabled (eg when always_shown is true).

=== sprite_button_bottom ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the bottom arrow button.

=== sprite_button_bottom_over ===
 * default: ''sprite_button_bottom''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the bottom arrow button when the user is hovering the mouse over it.

=== sprite_button_bottom_pressed ===
 * default: ''sprite_button_bottom''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the bottom arrow button when the user is clicking it.

=== sprite_button_bottom_disabled ===
 * default: ''sprite_button_bottom''
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the sprite to use for the bottom arrow button when it is disabled (eg when always_shown is true).

=== width ===
 * default: n/a
 * value: [wiki:GUI_-_Data_Types#float float]

The horizontal width, in pixels, of the scrollbar. Use a higher number for a "fatter" scrollbar. 

The object that owns the scrollbar will be reduced in width by this amount.

== tooltip ==

This object sets up the look and feel of a tooltip (a window that displays formatted text when the user hovers over a control).

There are two types of tooltips: ''appearing'' and ''existing''. They're mutually exclusive, so any incompatible settings will simply be ignored.

 * An appearing tooltip is one setup from here and which appears next to the cursor when active. (So use an appearing tooltip when you want a tooltip that follows the cursor.)
  * Uses: name, anchor, 
 * An existing tooltip "hijacks" another control and writes the object's tooltip text to its caption when active. (So use an existing tooltip when you want it to stay fixed at a certain position.)
  * Uses: name, hide_object, use_object 

{{{
  <setup>
    <!-- Appearing text-box -->
    <tooltip name="tooltip1"
             anchor="top"
             buffer_zone="2"
             delay="500"
             font="font"
             maxwidth="300"
             offset="10 10"
             sprite="backsprite"
             textcolor="0 0 0" 
    />
  
    <!-- Existing text-box -->
    <tooltip name="tooltip2"
             delay="0" 
             hide-object="true"
             useobject="text-box-object-name"
    />
  </setup>
}}}

=== ''name'' ===
 * default: "null"
 * value: [wiki:GUI_-_Data_Types#name name]

The name of the tooltip. Plug this name into the control's ''tooltip_style'' to tell it to use this tooltip.

=== anchor ===
 * default: "bottom"
 * value: [wiki:GUI_-_Data_Types#enum enum] "(top|center|bottom)"

This determines what part (vertically) of the tooltip box will be aligned with the cursor (if [wiki:#offset offset] is set to "0 0"). If "bottom", the tooltip box's bottom border will align with the cursor position (again, if [wiki:#offset offset] is set to "0 0").

=== buffer_zone ===
 * default: "0"
 * value: [wiki:GUI_-_Data_Types#float float]

Size of the "border" between the text area and the edge of the appearing tooltip window.

=== delay ===
 * default: 500
 * value: [wiki:GUI_-_Properties#int int]

The number of milliseconds to wait before displaying the tooltip when the player is hovering a control. Can be used by either kind of tooltip.

=== font ===
 * default: n/a
 * value: [wiki:GUI_-_Properties#name name]

Name of bitmap font to use for the appearing tooltip.

=== hide_object ===
 * default: "false"
 * value: [wiki:GUI_-_Properties#bool bool] "(true|false)"

Use for an existing tooltip. If set to "true", the tooltip object will only be visible while a tooltip is active. If "false", it will remain on the screen at all times.

=== maxwidth ===
 * default: "0"
 * value: [wiki:GUI_-_Properties#int int]

Maximum width of the appearing tooltip box. When the tooltip string is longer than this amount of pixels, the tooltip window will wordwrap. Obviously, this shouldn't be wider than the minimum width of the screen!

=== offset ===
 * default: "0 0"
 * value: [wiki:GUI_-_Properties#pos pos]

X and Y position of the appearing tooltip relative to the cursor. In other words, the tooltip will appear this number of pixels to the right (x) and below (y) the cursor.

=== sprite ===
 * default: "null"
 * value: [wiki:GUI_-_Properties#name name]

Sprite to use as the background of the appearing tooltip.

=== textcolor ===
 * default: "0 0 0"
 * value: [wiki:GUI_-_Properties#color color]

RGB colour of the text that appears in the appearing tooltip.

=== use_object ===
 * default: "null"
 * value: [wiki:GUI_-_Properties#name name]

Instead of having a box appearing on top of the cursor, you can use an already existing object with a ''caption''. Enter the name of this object here.

== Color ==
It is possible to create pre-defined colors, so that one can define a color property simply as "Super-intelligent shade of blue", instead of maybe "23 11 244". This is useful if the color is used more than once. The syntax is simple:

{{{
  <color name="Super-intelligent shade of blue"
  >23 11 244
  </color>
}}}

=== ''name'' ===
 * default: n/a
 * value: [wiki:GUI_-_Properties#name name]

Name to identify the customized color with.