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:

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:

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:

Last modified: Mon Nov 6 16:04:46 2006 by Fred Barnes.