Updated September 2024; see History
A "property sheet" is a control made up of two columns and a variable number of rows; the first column contains labels (attributes); the second column contains the data corresponding to the labels (attribute values).
In earlier versions of A-Shell (before 1202 of January 2011), there was nothing stopping you from implementing such a structure with a two-column XTREE. But it was difficult, if not impossible, to support a variety of different data formats (checkboxes, radio buttons, different widths of editable text, lists, etc.), since in the property sheet configuration, they would all be in the same column and the XTREE configuration scheme tends to limit each column to a single data format.
The XTF2_PROPSHEET option addresses this by effectively rotating the tree 90 degrees so that the columns (according to the coldef) are displayed as rows. The column titles become the row headers or labels.
Property sheet mode also supports multi-level. To configure this, specify the cformat code @ for each "column" (i.e. each item) that should appear at level 1. Columns (i.e. items) without this code will appear at level 0. To designate an item at level 2 or below, add additional @ codes (one per level). For example:
coldef = "1~1~Shipping Info~S~~" ! Level 0 (no "@")
coldef = coldef + "2~30~Address~SE@~" ! Level 1 (one "@")
coldef = coldef + "32~30~City~SE@~" ! Level 1 (one "@")
...
Here are some points and limitations to keep in mind:
| • | You are limited to a single row of data (which appears as a column). In fact, rather than specify an array of one item, you can just specify a singular structure (whose fields line up with the column definitions.) Since the usual object is to edit this structure, you can specify a copy of the same structure for the answer parameter (remember to set the XTF2_ANSEQDATA flag), or specify the same variable for both parameters. |
| • | You cannot define any hidden columns. (This includes the columns that would be needed to support any row-oriented features like row color, row font. |
| • | None of the following are supported: XTF_MSEL, XTF_DRAGDROP, XTF_REORD, XTF_SORT, XTF_MLVL, XTF_SPLIT. |
| • | Column colors (RBGbg, RGBfg) are not (yet) supported. But you can assign background colors to individual cells using cformat B. |
Comments
| • | If you are using anything but left justification, and if there is any possibility of cells extending logically beyond the control width, you should XTR.'CLOSEDENDED mode and XTF2_AUTOEXPCOL. Otherwise, you may end up column data that doesn't appear unless you use the horizontal scroll bar to scroll to the right. |
| • | If Dspwid=# is specified for an editable cell, it determines the width of the edit box when a cell is being actively edited. This provides an alternate method (besides cformat _) to adjust the width of the edit box to be more appropriate for the maximum number of characters allowed in that cell. If Dspwid is not specified, then the cformat _ logic is used, and if that isn't specified, the edit box width will be the same as the column width. Note that in the property sheet case, the units of Dspwid are taken to be characters, rather than grid units (as in the non-property sheet case.) |
See the sample program XTRA15.BP in EXLIB:[908,21] for an example of property sheet mode.
History
2024 September, A-Shell 7.0.1762: Resolve conflict between the normal list hierarchy '@@' (enabling the use of left/right arrows for expand/contract) and '@@' meaning level 2. See List Hierarchy.
2011 January, A-Shell 5.1.1202: Added to A-Shell
