oboe/src/doxy/mainpage.md

Blades of Exile Documentation			{#mainpage}
=============================

This is the documentation for parts of the Blades of Exile source code.
Currently it covers only the dialog engine.

Defining a Dialog
=================

Creating a new dialog consists of two basic steps: first, you have to
create the XML dialog definition, and then you need to write the code to
set it up and implement all the required callbacks.

The format of the XML dialog files is defined by the schema in
_rsrc/schemas/dialog.xsd_, but this document will cover what you need to
know in a more readable manner. A dialog definition consists of a
`<dialog>` tag containing any number of tags representing various dialog
controls. Each tag will be documented in some detail below.

Common Attributes
-----------------

The following attributes are allowed on all or most elements:

* `top`, `left`, `width`, `height` - Specifies the location and bounding
rect of the control within the dialog. All non-container controls
support these attributes, and in fact the `top` and `left` attributes
are required. Some controls may ignore the `width` and `height`
attributes. All of these must be non-negative integers.
* `relative` - Specifies how the location is computed; defaults to `"abs"`.
Must be one or two (space-separated) of the following;
if two are specified, they represent the mode used for calculating x and y respectively:
  * `abs` - Computed in global dialog space, relative to the top left corner.
  * `pos` - Computed relative to the reference widget's bottom right corner.
  * `pos-in` - Computed relative to the reference widget's top left corner.
  * `neg` - Computed relative to the reference widget's top left corner,
with the axes inverted (as if top and left were negative).
As a special case, if this is used with no reference widget,
the widget's size does not contribute to computation of the dialog's size,
and the widget is positioned relative to the dialog's bottom right corner.
  * `neg-in` - Computed relative to the reference widget's bottom right corner,
with the axes inverted.
* `anchor` - Specifies the `name` of the reference widget for this widget's location.
* `rel-anchor` - Set to `prev` or `next` to use the previous or next element in the XML ordering
as the reference widget for this widget's location.
This currently does not work for widgets in containers.
Mutually exclusive with `anchor`.
* `def-key` - Specifies the default keyboard shortcut for the
control. See **Keyboard Shortcuts** below for more information on the
format of this attribute.
* `font`, `size`, `color`, `colour` - Specifies text attributes of the
control. See **Text Formatting** below for details on accepted values.
* `name` - Give the control a unique identifier which you can use to
refer to it from the code. If omitted, the code will generate a random
identifier. All controls support this attribute.
* `fromlist` - Currently unused, but the intended use is to look up the
control's text value in a string list (in _rsrc/strings_)
* `framed` - Specifies whether the control should be drawn with a frame
around it, and what type of frame. Can be either `true` or `false`
* `outline` - Sets the type of frame to use for this control. Must be one
of `solid`, `inset`, `outset`, `double`. It defaults to `inset` and is
meaningless if `framed` is `false`.

The `<dialog>` tag
------------------

The `<dialog>` tag accepts the following attributes:

* `skin` - Specify the dialog's background pattern. Currently only
accepts `dark` or `light`. If omitted, a default is used which depends
on whether the dialog is used in the game or the scenario editor. As
such, this attribute should be omitted for most dialogs.
* `debug` - This attribute is completely ignored by the game, but if set
to `true`, the XSL stylesheet will draw the bounding rects of LEDs and
other debug information.
* `fore` - The default text colour. Generally this shouldn't be needed.
* `defbtn` - The ID (`name` attribute) of the default button. This is an
IDREF, so it must exist in the dialog.

The `<text>` tag
----------------

The `<text>` tag can be used either for a non-editable text message or
for a frame to group elements. Within a `<text>` tag, you can use a
`<br>` tag to insert a line break. See **Whitespace** for an explanation
of the intended whitespace collapsing behaviour.

The `<text>` tag accepts the following attributes:

* `framed` - See **Common Attributes** above. Defaults to `false`.
* `outline` - See **Common Attributes** above.
* `fromlist`, `font`, `size`, `color`, `colour`, `def-key` -
See **Common Attributes** above.

The `<button>` tag
------------------

The `<button>` tag decribes a non-LED button. It can contain label text
as well as an optional empty `<key>` element. It does not support the
`<br>` tag. The `<key>` element was intended as a way of inserting a
readable form of the button's keyboard shortcut, but at present this is
unimplemented.

The `<button>` tag accepts the following attributes:

* `name` - This attribute is required on the `<button>` tag. See
**Common Attributes** above.
* `type` - Specifies the type of button. This attribute is required.
* `wrap` - Specifies whether to wrap the text on the button. Can be
either `true` or `false`; defaults to `false`.
* `fromlist`, `def-key` - See **Common Attributes** above.

The possible values for the `type` attribute are:

* `small` - A small 23x23 button.
* `regular` - A normal-sized 63x23 button.
* `large` - A large 102x23 button.
* `help` - A small 16x13 help button - a white bubble with a ? mark.
* `left` - A normal-sized 63x23 button with a left-pointing arrow.
* `right` - A normal-sized 63x23 button with a right-pointing arrow.
* `up` - A normal-sized 63x23 button with an up-pointing arrow.
* `down` - A normal-sized 63x23 button with a down-pointing arrow.
* `tiny` - A tiny 14x10 button, same size as an LED and with the same
label behaviour.
* `done` - A normal-sized 63x23 button with "Done" on it.
* `tall` - A tall 63x40 button.
* `trait` - A tall 63x40 button with "Race Good/Bad Traits" on it.
* `push` - A round red 30x30 push button. The label is centred below it.

(Naturally, they correspond perfectly with the values of the @ref eBtnType
enumeration.)

The `<led>` tag
---------------

The `<led>` tag describes an LED button. It can contain label text,
which is drawn to the right of the button graphic. This differs from
normal practice in the original Blades of Exile dialog engine, where LED
labels were typically left-aligned to the _left_ of their associated
LED. I've chosen to make this change because I feel it is easier to see
which LED a label is associated to, and because the behaviour is more
similar to the checkboxes and radio buttons found in normal GUIs.

The `<led>` tag accepts the following attributes:

* `name` - This attribute is required on the `<led>` tag. See **Common
Attributes** above.
* `state` - Specifies the starting state of the LED. Can be one of
`red`, `green`, or `off`; defaults to `off`.
* `font`, `size`, `color`, `colour` - See **Common Attributes** above. Note that, for an LED, omitting the size attribute gives a different result than any of the possible values.

The `<group>` tag
-----------------

The `<group>` tag defines an LED group, a collection of LEDs that behave
like radio buttons rather than checkboxes. The tag can contain any
number of `<led>` elements.

The `<group>` tag accepts the following attributes:

* `fromlist` - See **Common Attributes** above. I don't remember exactly
how this would have applied to an LED group though; perhaps it would use
the string list to assign labels to its component LEDs in order of
declaration?

The `<pict>` tag
----------------

The `<pict>` tag defines a dialog picture. This covers a wide range of
things, from large pictures to small icons.

The `<pict>` tag accepts the following attributes:

* `type` - Specifies the type of graphic. This attribute is required.
* `num` - Specifies the graphic number. This attribute is required.
* `custom` - Specifies whether the picture is custom or preset. Can be
either `true` or `false`; defaults to `false`.
* `framed` - See **Common Attributes** above. Defaults to `true`.
* `outline` - See **Common Attributes** above.
* `size` - For certain types of graphics, this provides an additional
hint. Can be one of `small`, `wide`, `tall`, or `large`. See the list of
types below to determine if this attribute is relevant.
* `scaled` - For certain larger types of graphics, this determines
whether it should be scaled to fit within the provided bounds. It only
has an effect for types `full`, `dlog`, and `scen`, and the latter two
only if `size` is `large`. Can be either `true` or `false`, defaults to
`false`.
* `def-key` - See **Common Attributes** above.

The possible values for the `type` attribute are:

* `blank` - Draw no graphic, just fill the bounding rect with black.
* `ter` - A terrain graphic.
* `teranim` - An animated terrain graphic.
* `monst` - A monster graphic. The `size` attribute can be set to any of
its four accepted values to indicate the size of the monster.
* `dlog` - A dialog graphic. The `size` attribute can be `small` (the
default) or `large`.
* `talk` - A conversation graphic.
* `scen` - A scenario icon. The `size` attribute can be `small` (the
default) or `large`.
* `item` - An item graphic. The `size` attribute can be `large` (the
default) or `small`.
* `pc` - A PC graphic.
* `field` - A field graphic.
* `boom` - A boom graphic.
* `missile` - A missile graphic.
* `map` - A map graphic.
* `status` - A status icon.
* `full` - A full sheet. With this value and with `custom` left at
`false`, the `num` parameter must be one of the following:
	* 1100 - The inventory help frame.
	* 1200 - The stats area help frame.
	* 1300 - The action points help fram.
	* 1400 - The outdoor toolbar help frame.
	* 1401 - The combat toolbar help frame.
	* 1402 - The town toolbar help frame.

The `<field>` tag
-----------------

The `<field>` tag defines an editable text field. It can contain default
text as its contents, but does not support the `<br>` tag.

The `<field>` tag accepts the following attributes:

* `type` - Specifies the input type of the field. Can be one of `text`,
`int`, `uint`, or `real`; defaults to `text`.
* `tab-order` - Specifies the tab order of the field. This must be an
integer that is unique in the dialog.

The `<slider>` tag
------------------

The `<slider>` tag defines a slider control (presented with a scrollbar).

The `<slider>` tag accepts the following attributes:

* `style` - Specifies the slider style. Can be either `white` or `led`;
defaults to `led`.
* `vertical` - Specifies whether the slider should be shown horizontally
or vertically. Usually defaults to true, but if `width` is provided and
`height` is not, then it will default to false.
* `initial` - Specifies the initial value of the slider. Must be a value
from 0 to `max` inclusive. Defaults to 0.
* `max` - Specifies the maximum value of the slider. This attribute is required.
* `page-size` - Specifies how much the slider should scroll when clicking
between the thumb and the arrow button. Defaults to 10.
* `link` - If present, the control with this ID will have its text set
to the slider's value whenever it changes. It works best if the referenced
control appears before the slider control in the definition.

The `<stack>` tag
-----------------

The `<stack>` tag groups elements that represent a single entry in an array.
It can contain any elements except for nested `<stack>` or `<pane>` elements.

The `<stack>` tag accepts the following attributes:

* `pages` - The initial number of pages in the stack. This can also be
set programmatically.

The `<pane>` tag
----------------

The `<pane>` tag groups elements into a scrollable subpane.
It can contain any elements except for nested `<stack>` or `<pane>` elements.

The `<pane>` tag accepts the following attributes:

* `framed` - See **Common Attributes** above. Defaults to `false`.
* `outline` - See **Common Attributes** above.
* `style` - Same as for `<slider>`, see above. Applies to the pane's scrollbar.

Keyboard Shortcuts
------------------

Keyboard shortcuts are specified with the `def-key` attribute.

The `def-key` attribute is a space separated list of values. The final value in this list
specifies the main key that triggers the control. It can be any of the following values:

* A single digit
* A lowercase letter
* One of the following special characters:

		` - = [ ] \ ; ' , . /
* `left` - The left arrow key
* `right` - The right arrow key
* `up` - The up arrow key
* `down` - The down arrow key
* `esc` - The escape key
* `enter` - The enter key.
* `return` - The enter key. (Note: Theoretically, `enter` should be
numpad enter while this is normal enter; I don't think this distinction
is implemented though.)
* `tab` - The tab key.
* `help` - The help key (on keyboards that have one) or the F1 key.
* `space` - The space key.

Preceding values in the `def-key` attribute specify the modifiers to be used with the key.
Any of the following values is allowed:

* `ctrl` - The primary accelerator key (either control or command).
* `shift` - The shift key
* `alt` - The alt or option key

The following special value is also allowed for the `def-key` attribute:

* `none` - No key shortcut (the default).

Text Formatting
---------------

Text formatting options in dialogs are actually quite limited. There are
only three possible attributes, with a very limited number of possible
values.

* `font` - This attribute can take one of the following values: `plain`,
`bold`, `dungeon`, `maidenword`. It defaults to `bold`. The latter two
options are fantasy-style scripts such as that used for the conversation
screen.
* `size` - Although the dialog engine supports any font size, the XML
specification simplifies it to three keywords: `small`, `large`, and
`title`, representing 10pt, 12pt, and 18pt font, respectively.
* `color` or `colour` - This is the only truly unrestricted attribute,
accepting any HTML colour code. It understands three-digit hex codes (eg
`#333`, which is equivalent to `#333333`), six-digit hex codes, and the
sixteen standard HTML colour names. Both the British and American
spelling are supported for the attribute name.

Whitespace
----------

Whitespace collapse rules within Dialog XML elements are a little weird.
All tabs are stripped out, and then runs of newlines are replaced with a
single space, but runs of spaces are left as-is. Thus, you can use spaces
to do things like forcing indentation, while tabs can serve to indent
the XML itself.

Implementing a Dialog
=====================

Once the dialog is defined, it needs to be implemented! This consists of
a few steps - construct the dialog, attach handlers, possibly populate
the dialog's fields and other dynamic elements according to whatever the
dialog is supposed to display, and then run the dialog.

Use of `std::bind` for attaching the handlers is encouraged, and can be
used in conjunction with `std::ref` to provide state for the dialog.
Lambda expressions may also be useful for some of the simpler handlers.
Use of `dynamic_cast` will be required when dealing with LEDs or icons.