Cell Editing
|
|
|
|
|
|
Cell Editing |
Starting with release 5.0 of SftTree/OCX, a new cell editing mechanism is available. This new mechanism allows many more controls to be used for cell editing. Up until this release, only a built-in edit control and combo box were available for cell editing. While the old mechanism is still available (and required when using SftTree/OCX with Internet Explorer), it is recommended to only use the new cell editing method, as it offers much more flexibility and control over the editing process.
SftTree/OCX supports many Windows controls and ActiveX controls can be used for cell editing. Each language or development environment offers its own edit controls, combo boxes, etc. which can normally be used with SftTree/OCX. Even ActiveX controls, such as SftMask/OCX Masked Edit Control and SftBox/OCX Combo Box can be used, significantly improving upon the standard Windows controls.
SftTree/OCX offers a simple approach to cell editing. The application retains control and ownership of all controls used for cell editing. All their properties can usually be defined at design-time, even using their property pages if available.
In order to use a control for cell editing, it is simply added to the form that also contains the tree control. Because only one cell can be edited at a time, only one control is needed for the entire tree control. Of course, it is also possible to use several different kinds of controls, an edit control for some cells and a combo box control for others. One of each control type is added to the form.
When cell editing is started using the Cell.Edit method, a number of events occur that are used to position the control used for cell editing, initialize its contents and prepare it for editing.
First, the EditInitializing event occurs. It is used to make a control for cell editing available, by returning a control window handle. The control's display attributes and contents are initialized by this event and the desired size calculated. Its dimensions and position should be returned in the event's Left, Top, Width, Height arguments. This allows the control's position to be determined by the application. The control used for cell editing does not necessarily have to have the same dimensions as the cell being edited. It can also be larger or smaller.
Then the EditInitialized event occurs. Cell editing is about to begin. The control's position and dimension can be set, based on the Left, Top, Width, Height arguments. The application also must make the control visible, enabled and set the input focus to the control and additional final customizations can be performed. For example, when a combo box is used, this event can drop down the dropdown portion of the edit control.
Once cell editing is in progress, the user can end cell editing by hitting the ESCAPE key or by clicking outside the cell being edited.
Whenever cell editing ends, data entered must be validated (unless the user is abandoning the input data, for example by hitting the ESCAPE key). The EditValidate event occurs when the new contents of the cell being edited are to be validated. An application can test the new input data, display an error message if necessary and cell editing can resume.
The EditEnding event occurs after input validation has occurred (EditValidate event) and the input data is valid. This event is used to save input data in the tree control and to hide and disable the control used for cell editing.
Once cell editing has completely ended, the EditEnded event occurs. If the user is editing a cell and uses cell navigation to edit another cell or clicks on another cell for editing purposes, the EditEnded event does not occur after the EditEnding event. Instead, the entire cell editing process is restarted with the initial EditInitializing event.
Even though many different Windows and ActiveX controls can be used for cell editing, SftTree/OCX offers complete navigation features while cell editing is in progress. Keystrokes, such as the TAB key, RETURN key, arrow keys, etc., can be intercepted and interpreted to move to other cells within the tree control, for editing purposes. This is accomplished using the CellEditIntercept method, which defines keystrokes to be intercepted during cell editing using the EditNavigating event.
The CellEditIntercept method is normally used in the EditInitializing event to define cell navigation keys for the cell about to be edited.
Cell editing using the methods and properties shown below should no longer be used as these are provided for compatibility with earlier versions of the product only. With the exception that compatibility mode must be used for cell editing with Internet Explorer, as it does not support the new cell editing mechanisms introduced with SftTree/OCX 7.0.
SftTree/OCX supports editing of cells using the built-in edit control or combo box control. SftTree/OCX will notify your application of certain events (such as double-clicking on a tree item). Your application can then start cell editing using an edit control (StartEdit method) or a combo box control (StartCombo, StartComboEdit methods). SftTree/OCX will notify your application when editing is about to end, with or without data validation, by generating the AfterEdit and PostEdit events.
Only the built-in edit control or combo box can be used for cell editing.
There are two methods to handle cell editing events based on the CellEventHandling property:
If the user clicks a mouse button outside of the cell being edited or presses the TAB or ENTER key, the AfterEdit event is generated. This allows the application to perform input validation and other cleanup processing. If Cancel = False, the text selected replaces the cell's text. If Cancel = True, cell editing is not ended.
If the user presses the ESCAPE key, cell editing is ended and the original cell text is restored. An AfterEdit event is not generated. Any data the user entered or selected is lost.
Once cell editing has ended (or was aborted by the user), the PostEdit event is generated.
If the user clicks a mouse button outside of the cell being edited, the AfterEdit event is generated. This allows the application to perform input validation and other cleanup processing. If Cancel = False, the text selected replaces the cell's text. If Cancel = True, cell editing is not ended.
The ENTER or TAB keys do not end cell editing and must be handled by the CEKeyDown or CEKeyPress event. Using these events, an application can implement cell motion, moving from one cell to the next in response to keystrokes.
If the user presses the ESCAPE key, cell editing is ended and the original cell text is restored. An AfterEdit event is not generated. Any data the user entered or selected is lost.
Once cell editing has ended (or was aborted by the user), the PostEdit event is generated.