Fred's Home Page

About me
csh is bad
Help out
KRoC/Linux (old)
occam upgrades
occam tutorial
Projects (PhD)
Quick gdb
UNIX crashcourse
WG / WGBuilder

XHPD: XML Hierarchical Program Description

[ introduction | structure | gadgets | properties | actions | updates | newgadgets | commands | pseudo gadgets ]


XHPD files describe/encode micro-WG interfaces. These are processed by `ubuildinit' (part of UWG) and RAPP. `ubuildinit' generates C code that will create, and to some extent manage, interfaces. RAPP, on the other hand, dynamically creates interfaces.

This document covers the `syntax' of XHPD files, and will be updated as the tools evolve. For documentation by example, see the various XHPD files that are shipped with UWG and RAPP.

Structure Overview

XHPD files follow a fairly ordinary XML style, with a single top-level `xhpd' element. For example:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <xhpd version="1.0">
        ...  property-sets
        ...  application settings
        ...  tool-specific sections
        ...  top-level window gadgets

Property Sets

The `property-sets' allow a file to define groups of properties with specific values, largely for ease of use. A typical example might be a property-set that defines standard colours for gadgets:

    <propset id="cpref">
        <property name="background" value="@background" />
        <property name="foreground" value="@foreground" />
        <property name="highlight" value="@highlight" />
        <property name="shadow" value="@shadow" />
        <property name="iecolor" value="@extra" />
        <property name="tentry" value="@tentry" />

The `special' colour values indicate to use the value from the preferences file. A more useful example is:

    <propset id="helvfont">
        <property name="font" value="-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*" />

The properties of a property-set can be selected by specifying the set name, e.g.:

    <property set="helvfont" />

Application Settings

There are various application-level properties that may be set here. Some processing tools may ignore these settings (e.g. `ubuildinit', because it only generates code for interfaces). A typical set of application settings might be:

        <property name="hint-delay" value="0, 800000" />
        <property name="hint-font" value="-adobe-helvetica-medium-r-*-*-10-*-*-*-*-*-*-*" />
        <property name="hint-foreground" value="#000000" />
        <property name="hint-background" value="#d0f8d8" />

Tool Specific Sections

A fairly generic `section' tag is used to include tool-specific options/code in the XML. Each section may contain an arbitrary number of `sub-sections', that contain character data blocks. For example:

    <section name="buildinit">
                #include <stdio.h>
                #include <stdlib.h>
                #include <unistd.h>
        ...  more sub-sections

Where a single XHPD file drops code in multiple files, certain sections are restrictable to single files, e.g: <cpreface restrict="mainwin">

Declaring Gadgets

Gadgets are declared using `gadget' elements, with available sub-elements:

  • properties for the gadget
  • action handling for the gadget (optional)
  • nested child gadgets (optional)

The following, for example, describes a fairly basic top-level window (without any contents):

    <gadget name="win1" type="UWGWindow">
    	<property name="caption" value="Test application" />
    	<property name="icon-name" value="UWG testapp" />
    	<property name="width" value="256" />
    	<property name="height" value="384" />
    	<property name="position" value="user" />
    	<property name="style" value="border" />
    	<property name="visible" value="true" />
    	<property set="cpref" />

Of course, that's not particularly interesting; as we'd probably want some gadgets in the window, and maybe the odd action:

    <gadget name="win1" type="UWGWindow">
        ...  properties

        <gadget type="UWGPanel">
    	    <property name="geometry" value="0,0,256,384" />
    	    <property name="indent" value="2" />
    	    <property set="cpref" />

            <gadget type="UWGLabel">
    	        <property name="geometry" value="8,8,240,24" />
    	        <property name="caption" value="This is a label!" />
    	        <property set="cpref" />
    	        <property set="helvfont" />

        <action name="on_delete">
            <command name="@termloop">
                <arg value="0" />

This displays a window with a panel (covering the whole window) and label. The `on_delete' action is triggered when the user (or other) attempts to close the window (i.e. the window-manager sending a `WM_DELETE_WINDOW' message). The commands inside the action instructs UWG to shut-down the mainloop (that may or may not mean the whole application). The argument supplied is the value to be returned from UWG's `mainloop' (that might not be relevant for some tools).

Describing Properties

Properties are used for two main purposes: specifying the initial properties of a gadget (as shown above); and for specifying source properties in an update. Initial properties have the form:

    <property name="prop-name" value="prop-value" />
    <property set="prop-set-id" />

A list of supported properties is given on the UWG home-page. The strings used in XHPD files to name properties are lowercase versions of the C constants, minus the leading "PROP_" and with other underscores turned to hyphens. E.g. "PROP_GEOMETRY" becomes "geometry", and "PROP_INACTIVE_BACKGROUND" becomes "inactive-background". For properties that are naturally strings, the value given is used verbatim. For others, the XHPD parser will attempt to convert (e.g. "PROP_GEOMETRY" in UWG actually uses 4 integer parameters to set the geometry, not a comma-separated string containing them).

When specifying a property as a source for a gadget update (or for some tools, a reporting mechanism in gadget actions), the following value-free form is used:

    <property name="prop-name" />
    <property name="prop-name" source="gadget-name" />

If the "source" of a property is not specified, it is taken from any enclosing block that identifies a gadget. For example:

    <gadget type="UWGEdit">
        <property name="geometry" value="0,0,96,24" />
        <property set="cpref" />

        <action name="on_accept">
            <property name="text" />

This will cause tools such as RAPP to report the text of the edit-box when it is "accepted" (enter pressed in the edit-box). ubuildinit will not actually do anything with it.

Action Handling

Actions describe some processing to be performed when gadgets deliver application-level events (e.g. on-create, on-click). Four different ways of specifying actions are possible:

Blocks of code to be in-lined by tools that generate code are given in XML `CDATA' sections. For example:

    <gadget type="UWGButton">
        <property name="geometry" value="0,0,96,24" />
        <property set="cpref" />
        <property name="caption" value="click me!" />

        <action name="on_click">
                fprintf (stderr, "i got clicked! (I was a %s)\n", gadget->visual->id);

Inside a CDATA section, the gadget that triggered the action can be referred to as "gadget", as shown above. Other gadgets can be referred to by name (if assigned).

Updating Gadgets

Update blocks are used to change properties of existing gadgets, typically inside action blocks, but can also be used stand-alone. For example:

    <action name="on_click">
        <update name="othergadget">
            <property name="caption">
                <property name="text" source="thisgadget" />

In this example, when the action is triggered, the "caption" property of "othergadget" will be set to the "text" property of "thisgadget". Properties may also be given outright, for example:

        <update name="othergadget">
            <property name="enabled" value="false" />

Creating New Gadgets

Alongside updates, new gadgets may also be created. This applies more to the RAPP style of XHPD interaction, where a back-end server may wish to create or destroy gadgets on an interface dynamically. The new gadget (or tree of gadgets) to be created are specified in the same way as before (see declaring gadgets), for example:

    <newgadget parent="my_panel">
        <gadget name="tmpbutton" type="UWGButton">
    	    <property name="geometry" value="160,136,128,32" />
    	    <property set="cpref" />
    	    <property name="caption" value="remove me!" />

            <action name="on_click">
                <command name="@delgadget">
                    <arg value="tmpbutton" />

This will create a new button, whose on-click action is to remove the button (although it could do more useful and interesting things).

Executing Commands

In addition to properties, gadgets have `commands'. Unlike properties, these are handled on a per-gadget basis. For example:

    <action name="on_create">
        <command name="add_item">
            <arg value="wibble" />

Currently, only constant arguments (specified with "<arg>" tags) are supported in commands. Anything more elaborate requires code.

Other Commands

There are also some special commands which serve various useful purposes:

  • @delgadget: deletes/removes a gadget.

        <command name="@delgadget">
            <arg value="button1" />
  • @newgadget: instantiates a top-level window.

        <command name="@newgadget">
            <arg value="otherwindow" />

    This is used to render a top-level window which is already known about -- unlike the "newgadget" command, which also takes the XHPD data for the new gadget.

  • @dialogbox: shows a modalised dialog-box.

        <command name="@dialogbox">
            <arg value="my application" />
            <arg value="Save changes before exiting ?" />
            <arg value="@default" />
            <arg value="yes,no,abort,border,question" />

    The button which is clicked is returned as an action, incorporating the name of the button pressed, e.g. "@dialogbox:yes". The supported buttons are "yes", "no", "abort", "retry", "fail", "ok" and "cancel". The popup-window style can be specified as either "border" or "noborder". The icon displayed is specified with one of "info", "warning", "question" or "error".

  • @filedlg: shows the UWG default file-selector window (modalised).

        <command name="@filedlg">
            <arg value="open" />
            <arg value="" />

    The first argument specifies the type of the file-selector dialog, either 'open', 'save' or 'saveas'/'save-as'. The second provides a default path. The action is reported in an on-click event, e.g. "@filedlg:ok" (others being '@filedlg:cancel' and '@filedlg:error'). For 'ok' events, the selected path/file is returned as a "text" property of something called "path".

  • @termloop: used to exit the UWG main-loop, usually shutting-down the application.

        <command name="@termloop">
            <arg value="0" />

Pseudo Gadgets

There are additionally a handful of pseudo-gadgets. These provide for fairly common/useful client-side functionality. Tools such as ubuildinit will generate code where appropriate, whereas the RAPP client implements that functionality directly.

Pseudo-gadgets may be named like other gadgets (sometimes needed for referring to them), and also contain properties, child gadgets and have commands called on them. Currently supported are:

  • @TabManager: manages a collection of (mostly container) gadgets such that only one is visible. The various containers are given as children to this gadget. Typical example:

        ... to be completed ...
Last modified: 2006-11-06 16:04:46.000000000 +0000 by Fred Barnes [ls] [plain]
Page generated: Sun Apr 28 11:39:34 2013
Valid XHTML 1.0! Valid CSS!