Editable Tree Controls

Updated and reviewed November 2010

XTREE supports editable text columns, combo boxes, checkboxes, and radio buttons. To activate this feature, set the XTF_EDITABLE option in the Flags parameter, and define one or more columns using the E (editable text) or T (editable checkbox) or R (editable radio button) or l (list selection) options in the coldef parameter. (You must use the Advanced Coldef syntax.) You must also map the Answer in such a way to allow the updated text and/or checkboxes to be returned there.) You will probably also want to change the selection style in the XTR'SELECTAREA field of the Xtrctl parameter so that the selection indicator does not highlight the entire row (which makes it distracting to see the editable fields.)

XTREE is a "tree" rather than a "grid" control, so its primary function is to display data and allow the user to select items. It doesn't support individual cell formats or functions, like a spreadsheet would. But its editing capabilities should suffice for a wide variety of scenarios which combine the need to display a lot of data in rows and columns, with lightweight editing capabilities.

As a simple example, consider an application where you have a list of invitees to an event, and you want to check off those that show up. You might have several display columns for each person, with a single column of checkboxes to indicate if they have arrived. In this case, there would be no need for validating the data after each check either, although you might want to allow the operator to double-click on the person's name to print a badge. Another example would be a simple inventory sheet that lists all of the parts and has an editable text column allowing you to enter the amount on the shelf. A more sophisticated example might be a student grade book containing one row per student, and one column per assignment, where the teacher could enter data into any cell.

When the XTF_EDITABLE flag is set, as long as the first column is not editable, you will be able to move the selection indicator up and down with the arrow keys, and select an item by hitting Enter.The left and right arrow keys, however, will move the "focus" to the first editable cell in the appropriate direction, after which the arrows and Tab / Shift+Tab keys will move from editable cell to editable cell.

If the first column is not editable, you can exit from editing mode (back to row selection mode) by clicking on the first column. Unless the XTF_ENTESC flag is set, you can also do this by hitting Escape. (Otherwise Escape exits the tree.) To exit from editing mode and out of the tree entirely (back to the calling program), you can double click on an item (not in an editable column), or use a function key (assuming the XTF_FKEY flag is set in the flags parameter) or click on an external button or control (even another XTREE) programmed to generate an exitcode (see MBF_KBD and XTR'KBDSTR), or any other event that triggers an exitcode. If the XTF_ENTESC flag is set you can also hit Escape (from any cell) or hit Enter from the last editable cell in the tree.

If you need to perform validation of the data on a cell by cell basis (without waiting for the user to exit from XTREE), you can add the "x" or "X" flag to any editable column. The lower case "x" forces XTREE to exit immediately (with exitcode -48) as each editable text cell loses the focus. The application can examine the XTR'XROW, XTR'XCOL, XTR'TARGETROW, XTR'TARGETCOL, and XTR'XNAVIGATE fields (see XTR'TARGET... and XTR'XVALIDATE) for information on which cell(s) need to be validated. The upper case version, "X", is the same except that it only exits if the data in the cell changed. Checkboxes and radio buttons treat both "x" and "X" equivalently, in both cases exiting immediately when the item is clicked (i.e. which changes its value). Read-only editable cells ("u") also treat "x" and "X" the same, as they exit immediately before getting the focus, rather than after losing the focus.

See the Answer parameter for details on how it must be structured in order for editable cells to function properly.

Note that you can cause individual rows (cells) within an editable text column to be ignored (skipped over) by setting the first data character of the corresponding entry in the Answer array to "|". Also see First Position Reserved (cformat "P") which may simplify use of the "|" flag.

The editable option is only supported with array mode (not file mode).