XML Overview

I’m in the progress of migrating this documentation to the dtd specifications (bond-2.0.dsc file). I would love it if people sent me patches for the docs. Browse the code for more documentation. There is also documentation in the ~/uigtk directory before each function on what options can be in the xml file.

bond.dtd is an (almost) complete specification for the bond xml format, and clearly defines the bond’s markup structure.

The widgets are all based around the GTK widget toolkit. If you are not familiar with GTK then I recommend you read their tutorial and api reference guide as the naming, properties and layout of widgets is closely based around their standards. http://www.gtk.org

Most widgets and dbobjects can have names specified for them. This is by putting a name attribute into an element. Ie:

<window name="nameofthiswindow">

I have not mentioned the name attribute in the following listing, but it can be specified. If it isn’t specified, however, the parser will make up a name for the widget.

The name of a widget is important because it is used to reference that widget or database object for api calls, database sources etc. A longname attribute is inserted automatically by the parser. The longname attribute should not be manually specified. It contains the full path of the widget as well as the name.

<window>

Creates a window/form widget. This may only contain one child, though for example this can be a <box> which contains many widgets. A window element can only occur under a <bond> element. The attribute visible defaults to false, so if you want it visible you must specify “true” here.

Example

      <window name="givenname" title="Window Title" visible="true">
        <vbox> ... </vbox>
      </window>

<box>

Creates a tabled box which can contain many other widgets, under GTK its called GtkTable. Boxes can be contained within boxes.

The size of the box needs to be specified in attributes. The only child elements of a box are cells. This is the container widget for other widgets and can further describe the layout of widgets within it. Attributes of box

• columns, rows
  An integer value for the number of columns or rows in the table, respectively. Both default to 1.
• homogeneous
  A boolean value for whether all cells should be lined up or not. Defaults to “false”.
• visible
  A boolean value for whether widget is visible or not. Defaults to “true”.
• spacing, column_spacing, row_spacing
  Spacing (in pixels) between both columns and rows, only columns, or only rows respectively. Default is 4.

Example

      <box columns="2" rows="6">
        <cell xpos="0" ypos="0">
          <label>hello</label>
        </cell>
        <cell xpos="1" ypos="0">
          <entry>...</entry>
        </cell>
        ...
      </box>

A cell may be in a box, vbox or hbox. The attributes available to it are different in the vbox and hbox.

Attributes of cell under box

• xpos, ypos
  Column (row) position in , offsets from top left.
• xpad, ypad
  Column (row) padding between cell and widget.
• xspan, yspan
  How many columns (rows) this cell spans.
• expand, xexpand, yexpand
  If the height and width, only the height or only the width of the cell can be expanded in size.
• fill, xfill, yfill
  If the widget should fill the contents of the cell, just the height or the cell or just the width.
• shrink, xshrink, yshrink
  If the whole cell, only the height or only the width can shrink (ie after resizing).

Attributes of cell under vbox/hbox

• padding
  Column padding (in pixels) between cell and widget.
• expand
  Whether the cell can be expanded in size or not.
• fill
  Whether the widget should fill the contents of the cell or not. Default is “true”.
• shrink=bool
  If the cell can shrink (ie after resizing). Default is false.

Example

    <vbox>
      <cell fill="true" expand="true" shirk="false">
        <box columns="4" rows="3">
          <cell xpos="0" ypos="0">
          ...
          </cell>
          ...
        </box>
      </cell>
    </vbox>

<dbobject>

A database object. This can be included as a child to any widget, though it normally is used under <window>.

Example

    <dbobject name="sales">
      <sql>
        SELECT id, qty, amount 
        FROM sales 
        ORDER BY date
      </sql>
    </dbobject>

<field>

Specifies a link to a database field. If no <<bobjectsrc> is stated it will recursively look up its widget path for a <dbobjectsrc> or dbobject in one of its parents. So if a dbobject is specified in the window the field occurs it will use that if no dbobjectsrc is states.

Example

    <entry name="TextDataEntryBox1">
      <field>tablefieldname</field>
    </entry>

<dropdown>

If you’re using a <dbobjectsrc> where the contents is reasonably static you can cache it using the with a <lookup> element to speed up draw times.

Dropdown boxes with lookups can have dynamically changing contents. So you can have a dynamic dropdown list based on other widgets or fields present. An example of this would be a drill down approach with 2 dropdown boxes, where one dominates the contents of the other drop down box.

A primary field can be specified in a <lookup>. This is in case you don’t want to save the value your displaying in the list, but an alternative primary key value instead. You use the <primary> tag in the <lookup> to specify what field it will be. An example is if you would like to display the name value for a group of objects, but save an id value associated with the item.

Calling functions

You can call C functions in your programme and in other libraries if they are mentoned in your .conf file. You use the tag no a trigger. You then create a list of function arguments to define what is passed though. These arguments are passed though as a series of GList* items in the order that they are specified.