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:
|
Buffer |
Contents |
|---|---|
|
Primary |
Data that has not been deleted or filtered |
|
Filter |
Data that was filtered out |
|
Delete |
Data that was deleted by the user or |
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):
About text
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 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.
Events for changing text and items
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 |
For Web ActiveX |
|
|
EditChanged (not available on client control) |
onEditChange |
Occurs for each keystroke the user types |
|
ItemChanged |
beforeItemChange |
Occurs when a cell has been modified |
|
ItemError |
onItemError |
Occurs when new data fails the validation |
|
ItemFocusChanged |
onItemFocusChange |
Occurs when the current item in the control |
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
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
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 with a code
of 1 in the ItemChanged event.
To specify action/return codes:
-
PowerBuilder and Web DataWindow
Use a RETURN statement
-
Web ActiveX
Call the SetActionCode or setActionCode method
For information about codes for individual
events, see the DataWindow Reference.