Updated June 2016

cformat switch:  u

Similar to "U" in that it defines a variation on an editable text cell. While "U" causes the editing logic to skip over the cell in input mode, making it only updatable by the application, lower case "u" allows the cell to be given the edit focus but in read-only mode. Read only mode looks the same as regular edit mode except that the background of the cell is gray instead of white.

The idea behind this feature is to give the user a sense of being able to edit the cell, but without allowing them to directly edit it. Instead, when the cell has the focus, most keys other than navigation keys will cause the XTREE to exit (with exitcode = -48, as for normal cell editing validation), so that the application can then present a more customized cell editing capability.

For example, in an appointment scheduler, you might want the user to be able to "edit" a cell in order to make or change an appointment, but you don't want them to just be able to type anything in the cell. Instead, they cause the cell to have the focus (using navigation keys or by clicking with the mouse) and then they can indicate the desire to update the cell by hitting Enter, or any exit key, or for that matter, any normal character key. The application would then detect this event by the combination of the exitcode (-48 for Enter or printable characters, or the normal exitcode  for other exit keys) and determine the cell by the XTR.XROW and XTR.XCOL fields. Then it might pop up a dialog designed for editing an appointment. When that dialog is finished, the application can plug an updated value for the cell into the appropriate slot in the ANSARY parameter and re-enter the XTREE using XTR.OPCODE 4 (reselect).

Note that when re-entering, the initial focus will be determined by the XTR.XCOL and XTR.XROW fields (presumably still pointing the cell we were just in) and the XTR.XNAVCOD field, which contains the value of the key used to exit the field. Depending on that value, the initial focus may be advanced to another cell. For example, the standard action for the Enter key is to advance to the next cell. If you don't want that, then zero out XTR.XNAVCOD before re-entering the XTREE.

Also note: XTR.XNAVCOD can be used to determine which key the user entered to cause XTREE to exit. 13=Enter, while values from asc("1") to asc("z") indicate the corresponding character key.

Pre-Exit on read-only cell

The combination "uX" (editable read-only, with validation) causes an automatic exit with exitcode -48 whenever the cell is ENTERED (rather than EXITED).

This makes some sense, given that you should not be able to modify the cell if it is read-only, so there isn't any point in post validation. But there is a point in pre-validation if you wanted to perform some action whenever the user selects one of these cells, either by clicking on it or using keyboard navigation.)

Note that the XTR.XVALIDATE flag will be set to +2 to indicate that pre-validation of the cell identified by XTR.TARGETROW and XTR.TARGETCOL is needed.

Also note that as of A-Shell 6.3.1516 there is no straightforward option to pre-validate an editable cell. However, you can simulate the effect by setting the adjacent columns to unconditional validation. In your program's validation routine, you can then detect when you are about to enter the column you wish to pre-validate by checking if it matches XTR.TARGETCOL. This will trap most cases of navigating into the column, except the user directly clicking on the column or the app directly starting on it.

History

2006 October, A-Shell 4.9.968:

•   This function now supports individual cell colors.

•   Text in the cell is not selected when starting the edit operation

•   Double-click now exits with exitcode -59.