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.
A DataWindow uses three buffers to store data:
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 |
As the user moves around the DataWindow control, the DataWindow places an edit control over the current cell (row and column):
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.
When the user changes the contents of the edit control and presses Enter or leaves the cell (by tabbing, using the mouse, or pressing up arrow or down arrow), 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.
When data is changed in the edit control, several events occur. The names of the events are different in each environment, as shown in the table. This chapter refers to events using PowerBuilder names.
Event |
Description |
|
|---|---|---|
For PowerBuilder, Web DataWindow client control |
For Web ActiveX |
|
EditChanged (not available on client control) |
onEditChange |
Occurs for each keystroke the user types in the edit control |
ItemChanged |
beforeItemChange |
Occurs when a cell has been modified and loses focus |
ItemError |
onItemError |
Occurs when new data fails the validation rules for the column |
ItemFocusChanged |
onItemFocusChange |
Occurs when the current item in the control changes |
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 type, 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 2-2: How text is processed in edit controls
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 with a code of 1 in the ItemChanged event.
To specify action/return codes:
For information about codes for individual events, see the DataWindow Reference.
