The majority of the ruleset most probably deals with windows and controls.
Windows are sheets, subsets of sheets such as tabbed subwindows, and elements in list views. The elements on
the desktop are formed out of desktop panels, each containing a window as well.
Windows act as containers for controls. Controls are the individual user interface units that implement
functionality, such as number fields, scroller controls and status icons.
Window classes
The appearance and functionality of each window is determined by a window class. A window class is a concept
that defines a certain type of window used for a specific purpose. You can think of window classes as blueprints by which
individual windows are built. Several existing windows can share the same window class.
Window classes are defined using the windowclass tag. Among the things defined are the default, minimum and
maximum sizes of the window. The window class definition also lists the controls the windows created based on the class
contain.
The following is an example window class definition:
<windowclass name="note">
<frame>storybox</frame>
<placement>
<size>
<width>250</width>
<height>306</height>
</size>
</placement>
<sizelimits>
<dynamic />
</sizelimits>
<minimize>minimized_note</minimize>
<playercontrol />
<sharable />
<tooltip>
<field>name</field>
</tooltip>
<sheetdata>
<windowreferencecontrol>
<bounds>15,11,20,20</bounds>
<icon>
<normal>button_openwindow</normal>
<pressed>button_emptytarget</pressed>
</icon>
<class>note</class>
<description>
<field>name</field>
</description>
</windowreferencecontrol>
<stringfield name="name">
<bounds>40,13,-15,20</bounds>
<empty>« New Note »</empty>
<font>sheettext</font>
<nodrag />
<nodragselect />
</stringfield>
<stringfield name="text">
<bounds>10,40,-15,-15</bounds>
<multilinespacing>18</multilinespacing>
<font>sheettext</font>
</stringfield>
</sheetdata>
</windowclass>
The window class definition can contain a script block.
Examples of window classes are character sheets, image windows and NPC sheets.
Window instances
The individual windows created using a window class as a blueprint are called window instances. All window
instances are identified by a unique combination of two parameters: the window class and the window data source.
The window data source is the data base node whose child nodes contain the values for the data fields in the particular
window. Thus, several windows of the same kind can exist, pointing to different data contents. Two windows with the same class
and the same data source can't exist.
It is possible to create windows without a data source. The fields in such a window do not reference the data base by default,
and the values in the fields are therefore not stored when the window is closed and opened again. An unbound window's data source
is treated as an empty value, acting as a valid unique identifier for the data source of a window instance. Therefore, two unbound
instances of a single window class can't exist at the same time.
Window instances are also contained in some controls. A subwindow contains a window instance, and a windowlist
typically contains several window instances. These windows are called embedded. They contain the same definitions as
top level windows, but do not typically contain size limits.
Window instances can be created using windowreferencecontrol controls, from desktop panel objects or via
scripting. Embedded windows are automatically created by the containing control.
Window instance objects are represented in scripts by windowinstance objects, extended using the script
block of the window class.
Examples of window instances are Langston's character sheet, the NPC sheet containing the statistics for a goblin, or the map of
the campaign world.
Controls
Controls are elements contained in windows, and provide the concrete level of interaction possibilities for the user. There are
several different types of controls available.
- Value controls contain a value of a specific type: a number, a string, a token, a set of dice, an image or a window shortcut.
There are dedicated control types for each value type.
- Utility controls provide means of organizing or navigating the interface. Examples of such controls are subwindows, window lists,
scrollers and buttons.
- New functionality and meaning can be defined for controls by extending their operation through scripting. The most basic
building block for such operation is the generic control type, containing no default functionality in itself.
The ruleset reference documentation contains information on each control type. Controls can be identified
by looking for elements whose context (specified at the top of the element pages) is "windowinstance".
Defining controls
Controls are defined in the <sheetdata> section of a window class definition.
The controls are laid out and drawn starting with the topmost entry in the sheet data definition. This means that when using anchoring
(see below), the controls acting as anchors should always be specified first. When control areas overlap, the ones defined later will be
drawn on top.
All controls should have a position. The next section specifies the available positioning alternatives.
Control positioning
There are two basic methods available for defining the position of a control in a window. First, the position of the control can be
given as basic pixel coordinates. Second, the control edges can be anchored to follow the edges of another control or the window itself.
Due to the verbose nature of anchor definitions, a shorthand notation defining some of the most common setups is provided as a
convenience feature.
Static bounds
The basic format of static position coordinates is four positive integer numbers, measured in pixels.
- The x coordinate (horizontal position of the left edge)
- The y coordinate (vertical position of the top edge)
- The width of the control
- The height of the control
The following example would create a control 150 pixels wide and 200 pixels high, set 15 pixels from the left edge of the window
and 30 pixels from the top.
<bounds>15,30,150,200</bounds>
A slightly more complex set up involves negative coordinates. Any or all of the four numbers may be negated, with the following
results, respectively:
- The x coordiate of the left edge of the control is calculated from the right edge of the window
- The y coordinate of the top edge of the control is calculated from the bottom edge of the window
- The width of the control is automatically adjusted to be such that the right edge of the control is the specified
number of pixels from the right edge of the window
- The height of the control is automatically adjusted to be such that the bottom edge of the control is the specified
number of pixels from the bottom edge of the window
The following example creates a control whose left edge is 15 pixels from the left edge of the window, and right edge 15 pixels from the
right edge of the window. The width would be equal to the window width minus 30 pixels. The top edge would be 40 pixels from the bottom of
the window. The height of the control would be 25 pixels, due to the fact that the bottom edge would be calculated to be 15 pixels from the
bottom of the window.
<bounds>15,-40,-15,20</bounds>
Anchoring
When using the anchored positioning scheme, edges of the control are tied to other controls in the window or to the window edges. The
width and height of the controls can be explicitly specified, or calculated from the edges.
It is also possible to omit the anchoring on opposite edges or the width/height definition, to dynamically size a control to its
contents, such as a string control growing to accommodate the text. In such cases, it is often recommended to omit only one edge
(typically right or bottom) for best results.
To define anchors, use the <anchored> tag. The edges are anchored by specifying a nested <left>,
<top>, <right> or <bottom> tag.
Each edge anchor can contain three children:
- The <parent> tag contains a string value identifying the name of the control to which the edge is
being anchored. If this tag is omitted, the anchoring will be done to the window edges.
- The <anchor> tag identifies the edge on the target from which the position is calculated. This
value must be specified.
- The <offset> tag contains a number value by which the edge is adjusted after the anchoring calculations.
A positive value indicates a shift to the right or down, a negative to the left or up.
An explicit size is defined by using a <size> tag as a child of the <anchored> tag.
This definition can contain two number values identified by the tags <width> and <height>.
The following definition places the control to the right of a control called "label", with the top of the control being 5 pixels from
the top of the window. The size of the control is 30 pixels by 22 pixels.
<anchored>
<left>
<parent>label</parent>
<anchor>right</anchor>
</left>
<top>
<anchor>top</anchor>
<offset>5</offset>
</top>
<size>
<width>30</width>
<height>22</height>
</size>
</anchored>
There is also a special construct available, for stacking any number of controls onto an anchoring control so that all the
anchored controls avoid overlap. To do this, a fourth tag called <relation> may be specified inside the
<anchored> tag.
- If the value of this parameter is "absolute" (the default), the controls are placed as described above.
- A value of "relative" will cause the control to be anchored at the location of the last "relative" control
that anchored to the parent control. The next successive "relative" control will receive an adjusted location
based on the current control.
- A value of "current" will cause the control to be anchored at the location of the last "relative" control,
similar to "relative". This value will not, however, adjust the position of the next "relative" or "current"
control, and is useful for creating stacked rows or columns.
Using the anchoring shorthand notation
Some typical anchoring schemes can also be set up using a slightly less verbose notation. This method is based on the assumption
that the anchoring controls share one or two corners. The positions are illustrated by the diagram below. In the diagram, the parent
control is considered to occupy the area formed by the four lines, and the anchored control is placed next to it at the position
indicated by the text labels.
The positions along the centers of the lines (left, above, right, below, insideleft, insidetop, insideright and insidebottom)
share two corners with the parent control. The "over" label indicates a special case, in which all four edges match the edges of the
parent. All other positions share one corner with the parent.
To use the shorthand notation, three tags are placed under the <anchored> tag.
- The <to> tag indicates the name of the control to anchor to
- The <position> tag defines the position relative to the parent control (see above)
- The <offset> tag contains two integer numbers, separated by a comma. These define the horizontal
and vertical offset, respectively, applied to the positioning. These numbers are treated such that they increase the distance
between the two controls, so the actual direction varies by position. For positions that share an entire edge, a positive offset
will make the anchored control larger than the anchor target.
The shorthand notation can be combined with the standard anchoring notification, with the standard notification anchors overriding
the shorthand form.
It is usually desirable to define the width and/or height explicitly, or specifying an additional anchor using the standard anchoring
scheme. The following example creates a control to the right of "initresult". The height of the control is the same as the anchor target's,
and the width is explicitly set to 34.
<anchored>
<to>initresult</to>
<position>right</position>
<offset>5,0</offset>
<size>
<width>34</width>
</size>
</anchored>
Panels
Elements on the desktop are created using panel definitions. The panels are positioned relative to the desktop or other
panels similar to controls, with the exception of not having access to shortcut placement notation.
Each panel contains a window instance. The window instance is created with no data source. The window class used for the panel should
not contain any positioning or size constraints. In other regards, the window functions similarly to conventional windows and can contain
all the same functionality.
Panels can contain a mode attribute defining whether they are created in "host", "client" or "local" modes. These can be combined
by indicating several in the value of the attribute. Omitting the mode attribute will cause the panel to be created in all modes.
Similarly named panels with differing mode specifications can contain different contents.
The following creates a panel attached to the bottom of the desktop, being offset from the bottom by 15 pixels and having a height of 20
pixels. It spans the width of the desktop from the left edge to the left edge another panel called "shortcuts". It is only active when
running as a session host.
<panel name="identitylist" modes="host">
<class>identitylist</class>
<bounds>
<anchored>
<bottom>
<anchor>bottom</anchor>
<offset>-35</offset>
</bottom>
<right>
<parent>shortcuts</parent>
<anchor>left</anchor>
</right>
<left>
<anchor>left</anchor>
</left>
<size>
<height>20</height>
</size>
</anchored>
</bounds>
</panel>
Widgets
Widgets are graphical elements that can be added to any control, to implement custom functionality or serve as indicators. They
are not directly definable through the XML definition, and require a scripting implementation. See the widget interface
for details on the scripting interface.
Custom control types can be created by using a combination of a generic control type, widgets and templating.
There are two widget types available, text widgets and bitmap widgets.
Positioning widgets
Widgets are positioned relative to one of the corners or the center point of a control. The position of the widget may be offset
in the vertical and horizontal directions.
Text widgets
Text widgets (textwidget interface) contain a text string in the font specified. For widgets that contain a string definable by the user, it is recommended
to set the maximum width allowed. Text content causing the maximum width to be exceeded is truncated and preceded by three dots ("...").
Bitmap widgets
Bitmap widgets (bitmapwidget interface) can contain a bitmap contained in an icon resource.
Background frames
Each widget can optionally have a frame resource associated with it. The frame is drawn as the widget background, under the
actual contents of the widget.
