Index of pages
Introduction
Resources
Windows and Controls
The Data Base
Scripting
Templates
Extensions



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>&#171; New Note &#187;</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.


'Fantasy Grounds' is a trademark of SmiteWorks Ltd. All other trademarks are the property of their respective owners.
2004-2010 SmiteWorks Ltd. ALL RIGHTS RESERVED.
Privacy policy