How a DataWindow control manages data

As users add or change data, the data is first handled as text in an edit control. If the data is accepted, it is then stored as an item in a buffer.

About the DataWindow buffers

A DataWindow uses three buffers to store data:

**Table 9-1: DataWindow buffers**
Buffer	Contents
Primary	Data that has not been deleted or filtered out (that is, the rows that are viewable)
Filter	Data that was filtered out
Delete	Data that was deleted by the user or through code

About the edit control

As the user moves around the DataWindow control, the DataWindow places an edit control over the current cell (row and column):

Figure 9-2: Editing text in a DataWindow control

A sample window titled Maintain Customers contains master and detail Data Windows. The master Data Window displays columns for Customer I D, First Name, Last Name, and Company Name. A customer I D is highlighted and surrounded by a dotted rectangle, signifying that an edit control has been placed on it. For the highlighted customer I D, the detail Data Window displays not only first, last, and company name, but also the phone number, address, city, state, and zip code associated with that customer I D.

The contents of the edit control are called text. Text is data that has not yet been accepted by the DataWindow control. Data entered in the edit control is not in a DataWindow buffer yet; it is simply text in the edit control.

About items

When the user changes the contents of the edit control and presses Enter or leaves the cell (by tabbing, using the stylus, or pressing Up arrow or Down arrow from the soft input panel or other keyboard), the DataWindow processes the data and either accepts or rejects it, depending on whether it meets the requirements specified for the column.

If the data is accepted, the text is moved to the current row and column in the DataWindow Primary buffer. The data in the Primary buffer for a particular column is referred to as an item.

Events for changing text and items

When data is changed in the edit control, several events occur.

**Table 9-2: Events triggered by changing text and items**
Event	Description
EditChanged	Occurs for each keystroke the user types in the edit control
ItemChanged	Occurs when a cell has been modified and loses focus
ItemError	Occurs when new data fails the validation rules for the column
ItemFocusChanged	Occurs when the current item in the control changes

How text is processed in the edit control

When the data in a column in a DataWindow has been changed and the column loses focus (for example, because the user tabs to the next column), the following sequence of events occurs:

The DataWindow control converts the text into the correct datatype for the column. For example, if the user is in a numeric column, the DataWindow control converts the string that was entered into a number. If the data cannot be converted, the ItemError event is triggered.
If the data converts successfully to the correct datatype, the DataWindow control applies any validation rule used by the column. If the data fails validation, the ItemError event is triggered.
If the data passes validation, then the ItemChanged event is triggered. If you set an action/return code of 1 in the ItemChanged event, the DataWindow control rejects the data and does not allow the focus to change. In this case, the ItemError event is triggered.
If the ItemChanged event accepts the data, the ItemFocusChanged event is triggered next and the data is stored as an item in a buffer.

Figure 9-3: How text is processed in edit controls

A flow chart illustrates the steps for processing text in edit controls. The flow starts with the user successfully entering data. The data is then converted. If conversion succeeds, the data is validated. If validation succeeds, the Item Changed event is triggered. If the item is successfully changed, the Item Focus Changed event is trigerred. If either data conversion or validation fails, the Item Error event is triggered. If the Item Changed event action or return code is set to one, the Item Error event is triggered and the focus does not change.

Action/return codes for events

You can affect the outcome of events by specifying numeric values in the event’s program code. For example, step 3 above describes how you can force data to be rejected by using a RETURN statement with a code of 1 in the ItemChanged event.

For information about codes for individual events, see the DataWindow Reference in the online Help.