Pivot: A Practical Example, Part 1 - UI Markup Using WTKX

The user interface of a Pivot application is often defined using XML markup rather than Java code. This is because XML can be considerably easier to read and work with than straight Java. The hierarchical structure of an XML document more closely parallels the structure of the component hierarchy, which makes it easier to visualize the resulting output.

Pivot allows developers to split the definition of the user interface into multiple WTKX files. This allows each piece to vary independently and makes the overall structure easier to manage. The layout of the Stock Tracker application is divided into two WTKX documents: one that sets up the main structure of the application and another that defines the layout for the quote detail:

• stocktracker.wtkx
  • stocktracker.detail.wtkx

We'll take a look at the top-level markup in stocktracker.wtkx first, concentrating on the two main page elements, TablePane and TableView. Then we'll investigate the markup for the stock quote detail, which uses the Form container and lays the ground work for the data binding support we'll discuss in a later section.

TablePane

The root node of stocktracker.wtkx is a TablePane element. A TablePane is a type of layout container that arranges its children in a manner similar to an HTML table.

Like HTML tables, TablePane contents are organized into rows and columns. Unlike HTML, however, which may attempt to infer a table structure from its contents, a TablePane's structure must be defined in advance, as shown below:

<TablePane styles="{padding:8, spacing:6}">
    <rows>
        <Row height="-1"/>
        <Row height="1*"/>
        <Row height="-1"/>
        <Row height="-1"/>
    </rows>
    <columns>
        <Column width="244"/>
        <Column width="1*"/>
    </columns>
    ...
</TablePane>

TablePane row heights and column widths can be specified as either automatic, absolute, or relative:

• A value of -1 specifies an automatic size; the table pane will determine the height of the row as the maximum preferred height of all components in that row; the same applies to automatic column widths.

• An explicit, non-negative value defines an absolute width or height, specified in pixels.

• A number followed by an asterisk specifies a relative size; the width or height is determined by applying a weighted percentage of the space left over after subtracting the width or height of all automatic and absolute columns and rows (which may be 0).

In the example above, the second row is given a relative height that will assign it all of the available space once the other rows are accounted for; all other rows are given an automatic height. The first column is given an explicit width of 244 pixels, and the second column is given 100% of the remaining width.

The following graphic shows the resulting layout (the blue lines represent the table cell boundaries):

Stock Tracker table pane cells

Styles

Note the styles attribute of the TabPane element. Styles are used to customize the appearance of a component, and are specified in WTKX as a JSON-formatted collection of name/value pairs. All WTKX elements support the styles attribute, but each element may support a different set of styles depending on the currently installed skin.

In this example, the TablePane is assigned a padding value of 8 and a spacing value of 6. Padding represents the amount of space that the table pane will leave around its components, and spacing is the size of the gap the table pane will leave between components.

Table Pane Cells

The actual content of a table pane is specified in the <cells> element. Each immediate child element of the <cells> element is considered a child component of the table pane. The row and column in which the child will be placed is specified by the row and column attributes attached to the sub-element, as shown below:

<Label row="0" column="0" text="%stockTracker"
    styles="{font:'Verdana bold 14', verticalAlignment:'center'}"/>

Note the use of the percent symbol in the text attribute value. This tells the WTKX component loader that value of the text attribute should be provided by a resource string with the name specified in the attribute, minus the percent sign. This will be discussed in more detail in the Localization section.