XTREE Answer Examples
Consider a tree with three editable checkbox columns. You would map the answer array as follows:
MAP1 ANSWER
MAP2 ANSARY(x),S,3 ! (x=# rows, 3=number of editable checkbox columns)
Or, perhaps more clearly:
MAP1 ANSWER
MAP2 ANSARY(x) ! (x) must be at least as large as addcnt
MAP3 ANS'CB1,S,1 ! first editable checkbox column
MAP3 ANS'CB2,S,1 ! second editable checkbox column
MAP3 ANS'CB3,S,1 ! third editable checkbox column
The encoding of these arrays is similar to that for multiple-selection mode, i.e. "0" = unchecked, "1" = checked, and " " (blank) causes the cell to be left blank (with no checkbox at all). For three-state checkboxes, "2" specifies the indeterminate state.
If multi-selection is allowed, then the first column of the answer array is reserved for the selection flags. For the example above, the multi-selection version should be mapped as:
MAP1 ANSWER
MAP2 ANSARY(x) ! (x) must be at least as large as addcnt
MAP3 SELECTION,S,1 ! selection flags (must be first)
MAP3 ANS'CB1,S,1 ! first editable checkbox column
MAP3 ANS'CB2,S,1 ! second editable checkbox column
MAP3 ANS'CB3,S,1 ! third editable checkbox column
When editable text or combobox columns (see cformat E and l ) are present, the same rule as for checkboxes applies, except that the width of the elements in the answer array must include the total width of all the editable columns. To continue the example above, if, in addition to the three checkbox columns there were also two editable text columns, one a standard edit 12 bytes wide and the other a combobox 25 bytes wide, and both the first checkbox and the first editable cell supported individual cell colors (cformat B), the correct mapping of the answer array would be:
MAP1 ANSWER
MAP2 ANSARY(x) ! (x) must be at least as large as addcnt
MAP3 ANS'CLR1,S,1 ! color byte for first editable checkbox column
MAP3 ANS'CB1,S,1 ! first editable checkbox column
MAP3 ANS'CB2,S,1 ! second editable checkbox column
MAP3 ANS'CB3,S,1 ! third editable checkbox column
MAP3 ANS'CLR2,S,1 ! color byte for first editable text column
MAP3 ANS'TEXT1,S,12 ! first editable text column
MAP3 ANS'TEXT2,S,25 ! second editable text (combobox) column
Regardless of the relative position of the checkboxes (and radiobuttons) vs. the editable text columns in the source array, the checkboxes and radiobuttons must precede the text columns in the answer array, as shown above.
Notes
| • | Although using a multi-level mapping as shown above is the easiest way to visualize the format of the answer array, you may also map or dynamically allocate a single-dimension array (e.g. DIMX ANSARY(X),S,Y) and pass that array to XTREE by specifying the first element (e.g. xcall XTREE, srow, scol, ANSARY(1), ARRAY(1), addcnt,...), provided that you use substring modifiers or some other method to construct each row of the array according to the rules described above. Better yet, use a DIMX. |
| • | Note that the order of the columns is relative to the order in which they are defined (in Coldef) and is not affected by the user rearranging their order in the display. |
| • | The answer array can be initialized to nulls or blanks. Whenever the tree is loaded or re-entered, if the answer array is all blank, the editable cells will be loaded purely from the data array. However, if the answer array contains any non-blank / non-null characters, then the answer array data will override the corresponding cells in the data array. Whenever XTREE exits, it will update the answer array cells to reflect the current status (with the exception of the color bytes - see next bullet). The concept is to use the data in the main array to represent the original data; and the data in the answer array to represent the current data. Beware that if, as a result of editing, you manage to clear all of the editable cells such that the entire answer array is blank, then on the next re-entry, the entire tree will be set back to the initial status per the data array. (To prevent this, you will either need to copy the blank answer array over the data array, or perhaps define a color column and plug in an explicit code for white, just to have a non-blank byte in the answer array, so that it is considered valid rather than uninitialized.) |
| • | On creation of the control, blank individual cell color bytes in the answer array are initialized from the data array, like other answer array fields). On return, they will be set to the current status (in this case, the current RGB Color Index) of the field, or blank for no (i.e. default) color. Note that to set a cell which currently has an individual cell color back to the default color, set the corresponding byte in the answer array to blank prior to re-entry. (This works as of edit 1210, even with the XTF_NOREDRAW flag set; prior to that, blank was treated as "no change" rather than "no color", and XTF_NOREDRAW stifled color updates.) Note, however, that the default color for the cell in this case may not be the same as the default color for the entire tree; the cell default color may be affected by a column color. To override the column color and force the cell to use the tree's default (typically white) color, use the special RGB color index code "=". |
| • | Individual cells within an editable text column can be marked to ignore by setting the associated field in the answer array to "|" (vertical bar), followed by whatever text you want to display in the cell (if any). See the advanced coldef option RGBignore for an additional note on this, and the sample program XTRA5 for an example. (The description in the 3rd row is marked non-editable by this means.) |
| • | To disable an editable checkbox (T) or radio button (R) cell, add 4 to the numeric code in the answer array byte. For example, while 0 is unchecked/enabled and 1 is checked/enabled, 4 would be unchecked/disabled and 5 would be checked/disabled. See the sample program XTRA6 for an example of this (select the validation option, then as you click on Yes and No radio buttons, the corresponding N/A button will be enabled/disabled.) |
| • | Editable text and editable checkboxes are only supported in array mode (not file mode). |
