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

The name of the icon.

size

• default: n/a
• value: pos

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

sprite

• default: "null"
• value: name

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

cell_id

• default: "0"
• value: 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.

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

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

always_shown

• default: "false"
• value: 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: 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: 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: 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: 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: 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: 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: name

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

sprite_button_top

• default: "null"
• value: name

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

sprite_button_top_over

• default: sprite_button_top
• value: 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: 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: 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: name

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

sprite_button_bottom_over

• default: sprite_button_bottom
• value: 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: 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: 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: 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: 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: enum "(top|center|bottom)"

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

buffer_zone

• default: "0"
• value: float

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

delay

• default: 500
• value: 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: name

Name of bitmap font to use for the appearing tooltip.

hide_object

• default: "false"
• value: 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: 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: 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: name

Sprite to use as the background of the appearing tooltip.

textcolor

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

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

use_object

• default: "null"
• value: 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: name

Name to identify the customized color with.