Multi-Column List Gadgets

PML Customisation User Guide

Gadget Set : List Gadgets : Multi-Column List Gadgets

You can simulate a multi-column list using spaces and tabs if you are using a fixed-width font. But if you is using a proportionally spaced font, then you cannot do this and guarantee the columns will always line up.

The list gadget may have multiple columns as shown in the following example, which is also a single-choice, zero-selection list. The column widths can be interactively modified using the mouse cursor in the headings row.

Figure 21:3.

Multi-Column List Gadget

The number of columns is deduced from the List's data. If you specify a set of (1 or more) column headings before the list is populated, then this will determine the number of columns. If no headings are pre-specified then the number of columns is deduced from the display text of the List's first row. This provides upwards compatibility for existing Appware using single column lists.

A List gadget's headings can be replaced after the list has been populated. If the new headings specify the same number of columns then the headings are replaced but the List's data fields and selection remain unchanged. If the number of columns is different, then the list is replaced by an empty list with the new headings. Invoking the Clear() method will clear the list's data fields and rebuild the current headings.

The column headings, and hence the number of columns, for the list are assigned as an array of STRING:

!This.List.SetHeadings( !headings )

The Dtexts for each column of each row of the list can be provided as a PML array, where each element is an array of STRING. This can be row oriented or column oriented.

!This.List.SetRows( !rows )

!rows is an array of ‘row arrays’, and its size determines the number of rows in the list.

!This.List.SetColumns( !columns )	

!columns is an array of ‘column arrays’, and its size must match the number of columns of the list. The size of all the column arrays must be the same and determines the no of rows in the list.

The default width of each column is determined by the longest header or Dtext value supplied. Rtext values for each row are supplied as for single column lists.

Selection within the list applies to the entire row not individual cells, but rows of the list can be selected on the basis of a column’s Dtext:

Select( !column is REAL, !dtext is STRING )

This selects the first list row whose column has the given Dtext. If the list is a multi-choice list then repeated use of this method will add selected rows to the list.

Note:

For a multi-column list gadget each row’s Dtext string is held as a ‘horizontal tab’ character separated string of column data, matching the column headings (as opposed to a simple string for single column list). The standard list members val, Dtext, Dtext[n] and methods Select( ‘Dtext’, …), Selection( ‘Dtext’ ) work on multi-column lists with the following limitations:

•

Querying Dtexts will return the tab separated strings.

•

Supplying Dtext to populate the list or invoke selections will require tab separated strings as input.

See the Software Customisation Reference Manual for more information.

Popup-Menus on Multi-Column List Gadgets

List gadgets with a popup menu assigned to them will pop up the menu when the right-mouse button is released when the cursor is over the list title or any list selection field.

For multi-column lists right-mouse in a list field will first select that field, and unselect any other selected fields, before the popup appears. This selection behaviour does not occur for single column lists.

The use of popup menus on list gadgets can be confusing so use them with care.