| • | If cell (3,5) is being edited, and the user clicks on cell (6,7), and the (3,5) cell requires validation (see coldef codes x and X), then XTREE will exit with XTR.XROW=3, XTR.XCOL=5, XTR.TARGETROW=6 and XTR.TARGETCOL=7. XTR.XVALIDATE will be set to 1 to indicate that the cell identified by XTR.XROW / XTR.XCOL should be validated. The exitcode will be -48 (cell validation). If the application calls XTREE again to continue editing, the operation will start at the cell identified by XTR.TARGETROW / XTR.TARGETCOL. If it doesn't like the contents of the cell that was just edited (3,5), it can force re-entry at that location by setting XTR.TARGETROW and XTR.TARGETCOL to XTR.XROW and XTR.XCOL (or it can just zero out XTR.TARGETROW and XTR.TARGETCOL to accomplish the same thing). |
| • | In the example just described, if, while editing cell (3,5) the user hits a navigation key (such as Tab or Down-Arrow) to move the focus to another cell, then the outputs will be the same as just described, except that XTR.TARGETROW / XTR.TARGETCOL will be set to indicate the next cell to get the focus (based on the navigation key used and the layout of the tree.) XTR.NAVCOD will indicate the navigation key used. |
| • | Another variation of the example just given would be if, while editing cell (3,5) the user right-clicked on a cell that was not editable but which had a context-menu defined. In that case, the context menu would first be displayed, and XTREE would wait for a menu option to be selected. If the user canceled the menu, the editing of cell (3,5) would resume. Otherwise, XTREE would exit with the exitcode corresponding to the chosen menu option, but the XTR.XROW, XTR.XCOL, XTR.TARGETROW, XTR.TARGETCOL and XTR.XVALIDATE fields would be set just as in the first example. If the application tried to re-enter with changing the XTR.TARGETROW and XTR.TARGETCOL, if would enter in selection mode with the focus on that row, rather than in cell editing mode (since the cell was not editable). |
| • | A similar case occurs when the user terminated a cell editing operation by clicking on some control outside of XTREE. In this case, the XTR.XROW / XTR.XCOL will still point to the cell that was being edited, and XTR.XVALIDATE will be set to 1 to indicate whether it needs validation. But XTR.TARGETROW / XTR.TARGETCOL will be 0, since the target location is outside of the context of XTREE. If the application re-enters, since XTR.TARGETROW / XTR.TARGETCOL are 0, XTREE will use the incoming XTR.XROW / XTR.XCOL to set the starting focus. |
| • | A variation of the cased just describe is where the user is editing a cell and clicks on a cell in another XTREE. In this case, XTR.XROW, XTR.XCOL and XTR.XVALIDATE will be set according to the cell that was being edited, just as in the previous case. But XTR.TARGETROW and XTR.TARGETCOL will point to the cell that was clicked on in the other XTREE. The application will be able to identify this case by the fact that the exitcode value will correspond to the other XTREE. It would presumably then want to transfer the XTR.TARGETROW / XTR.TARGETCOL values to another copy of the xtrctl structure (corresponding to the other XTREE) and then re-enter that XTREE. |
| • | When the editable cells in question are not text cells but checkboxes, it works slightly differently. Since checkboxes change value immediately when clicked, if they have the X or x code for validation, they will exit immediately at that time (rather than when the focus is moved to another cell). So if we go back to the first example above but imagine that the two cells in question, (3,5) and (6,7) are checkboxes, then if the user clicked on the (6,7) checkbox while the (3,5) checkbox had the focus, the return codes would all be the same as in that example, except that XTR.XVALIDATE would be set to 2 to indicate that it is the XTR.TARGETROW / XTR.TARGETCOL cell that needs validating. |
| • | If the focus is on an editable checkbox, and the user then clicks it, or uses the space bar to toggle the checkbox, if the column is coded for validation, XTREE will exit with both XTR.XROW / XTR.XCOL and XTR.TARGETROW / XTR.TARGETCOL pointing to that same cell. In this case it doesn't really matter whether XTR.XVALIDATE is returned as 1 or 2, since in either case, it is the same cell that needs validation. |
Note that XTR.XVALIDATE=1 means that the XTR.XROW/XTR.XCOL cell (i.e. the one we just left) needs to be validated; while 2 means that the XTR.TARGETROW/XTR.TARGETCOL cell needs to be validated (the one we just clicked or are navigating to). In the case of checkboxes, they exit for validation only when the checkbox value changes, which occurs immediately when you click, rather than when you move the cell focus (as would be the case with a normal editable cell). So if you are focused on a checkbox at 5,7 and you click another checkbox at 3,9 then XTR.XROW/XTR.XCOL will be returned as 5,7, while XTR.TARGETROW/XTR.TARGETCOL will be returned as 3,9. But the checkbox that has changed is the one at 3,9 (the one clicked), so it is the one that should be validated.
