Updated April 2022

cformat switch:  T (standard) or T+ (extended) or T3+ (three-state extended) or T++ (extra extended)

An editable checkbox is represented in the data and answer arrays by a one-character column coded according to the following table:

Note: values in the above table are strings ("0", "1", etc.), not binary values.

Extended 2-state checkboxes (T+) and 3-state checkboxes (T3+) support the following additional mouse & keyboard commands:

•   When the focus is on a checkbox cell, Ctrl+A sets (ticks) all the enabled checkboxes in the column.

•   When the focus is on a checkbox cell, Ctrl+B resets (clears) all the enabled checkboxes in the column.

•   When the focus is on a checkbox cell, Ctrl+Z reverses the action of the immediately preceding Ctrl+A, Ctrl+B, or Shift+Click.

•   To toggle (tick or clear) a range of checkboxes in the same column, click to set the first checkbox in the normal way, then Shift+Click on the last checkbox in the range. Note that individual cell validation (cformats x,X,v,V) is not supported during a multi-cell toggle operation.

Extra-extended (T++) 2-state or 3-state checkbox columns will have a 3-state checkbox added to the header of the column which is automatically set to the checked state if all the boxes in the column are checked; the unchecked state if all the boxes are unchecked, or the indeterminate state if there is a mixture (or if all of the boxes are indeterminate), as in this example:

Clicking the checkbox in the header cycles through the check-all, uncheck-all, set-all-to-indeterminate (if 3-state), and back to the original mixed state (if applicable).

The following special context menu commands (see PopupMenu) relate specifically to extended checkboxes:

•   $CBSET acts like Ctrl+A (sets all checkboxes in the column over which the mouse was right-clicked to bring up the context menu).  If the menu is activated by right-clicking on any column other than an extended checkbox column, this option will not appear on the menu.

•   $CBRST is like $CBSET, but acts like Ctrl+B (reset or clear all checkboxes)

•   $CBUNDO acts like Ctrl+Z.  Like $CBSET and $CBRST, it will only appear in the menu if the menu is activated for an extended checkbox column.  In addition, if undo is not possible, the option will be grey.

•   $CBSETDEP is like $CBSET, but applies only to the dependents of the current item.  If the item clicked has no dependents, the option will be grey.  If the tree is not multi-level (XTF_MLVL not set – see XTREE Flags), the option will not appear at all.

•   $CBRSTDEP is like $CBSETDEP, but resets rather than sets the dependent checkboxes.

Because the above context menu commands adjust to the runtime circumstances, they can be added to the common PopupMenu for a tree, without regard to whether the tree even contains extended checkboxes, rather than having to add them only to column-specific context menus.  The only reason why these items weren’t just automatically defined for extended checkbox columns is to allow you to define the wording.  For example, for a tree in which the items represented styles of products, grouped into categories, you might define the context menu items as follows:

Coldef = "0~0~x~H~PopupMenu=Order all styles,$CBSET;Cancel all,$CBRST;"; &

+ "Order all styles in category,$CBSETDEP;Cancel all in category;$CBRSTDEP;" &

+ "Undo;$CBUNDO~~"

The context menu might then appear as:

Comments

•   You must also specify the flag XTF_EDITABLE when using checkboxes.

•   If the checkbox column supports cell colors (cformat code B) then the column data (in both the data and answer arrays) should be two characters wide (instead of one), with the first character reserved for the color code.

•   Use Cformat code t for non-editable checkbox, and code 3 for three-state checkboxes.

•   As long as the checkbox value column position is blank, the entire field contents will be displayed as text, even if the column width is more than one. This might be useful in some exotic situations where a single column contains check-boxes in some rows, but text in others. The text would not be editable, regardless of the editable state of the column. See History.

History

2020 June, A-Shell 6.5.1684:  Checkbox columns may now contain text as long as the first data position—i.e. the checkbox value character—is blank.

2016 October, A-Shell 6.3.1530.6:  Column ordering for all the columns (up to the max of 100) can now be saved when using the TreeID mechanism with the XTUCFG_COLORD bit set in the XTR.USRCFG field. Previously the limit was 31 columns, which remains the limit when using the XTR.COLORDER() array method without the TreeID option.

2016 October, A-Shell 6.3.1530.5:  Extended checkbox columns may now be extended to a second degree by adding a second "+" (e.g. T++ or T3++). This adds a 3-state checkbox to the header of the column which is automatically set to the checked state if all the boxes in the column are checked; the unchecked state if all the boxes are unchecked, or the indeterminate state if there is a mixture (or if all of the boxes are indeterminate). Clicking the checkbox in the header cycles through the check-all, uncheck-all, set-all-to-indeterminate (if 3-state), and back to the origional mixed state (if applicable).

2013 October, A-Shell 6.1.1363:  The PopupMenu options $CBSET, $CBRST, and $CBUNDO now return EXITCODE=-48 and XTR.XVALIDATE=3 when validation (conditional or unconditional) is active for the column. $CBSETDEP and $CBRSTDEP return XTR.XVALIDATE=4.