Event tables

The tables in this section describe user interface events, the user actions that generate the events, and widgets that have default behavior for the events. The term field‑level widgets refers to any widgets that can be part of a field group in a frame: fill‑ins, sliders, selection lists, toggle boxes, radio sets, editors, rectangles, images, text, buttons, combo boxes, and browse widgets. Frames, dialog boxes, windows, menus (including menu bars and pop‑up menus), sub‑menus, and menu items can also receive events. Note that there is frequently a distinction made between a browse widget and a single cell in an updateable browse. For the most part, a browse cell behaves as a fill‑in widget.

The event tables in this section describe the following kinds of events:

Keyboard events

Mouse events

High-level widget events

Direct manipulation events

Developer events

Socket events

ProDataSet events

Keyboard events

ABL makes all keyboard actions available as events that you can specify by either key label or key function. You can write triggers for these keyboard events, and associate these triggers with any field‑level widget that receives input focus. For a complete list of key label and key function names, and information on how to use them, see the chapter on handling user input in OpenEdge Development: Programming Interfaces.

Keyboard events have default effects depending on the widget that receives the event. For example, the “A” key label event displays an uppercase “A” in a fill‑in or editor widget, but has no default effect when applied to a button. ABL organizes some key function events into several classes that have default effects on selected groups of widgets. ABL also provides special keyboard events to write default triggers on classes of keys. You can use these default events to write a trigger for all keys in a particular class for which you have not defined a key label or key function event trigger.

Main classes of key function events

ABL supports three main classes of key function events:

Universal key function events — Apply to all user‑interface widgets except menus, submenus, and menu items

Navigation key function events — Apply to those field‑level widgets that can receive focus

Field editing key function events — Apply to fill‑ins and browse cells

Table 114 describes universal key function events.

 

Table 114:

Universal key function events

Event	Affected widgets	AVM action
BELL	All except control container, menu, menu item, and submenu	Trigger dependent (typically used to execute the BELL statement).
END-ERROR	All except menu, menu item, and submenu	For the first input operation of the program, raise the ENDKEY condition. For subsequent input operations, raise the ERROR condition.
ENDKEY	All except menu, menu item, and submenu	Raise the ENDKEY condition.
ERROR	All except control container, menu, menu item, and submenu	Raise the ERROR condition.
GO	All except menu, menu item, and submenu	Submit the input values for this frame.
HELP	All except menu, menu item, and submenu	Invoke application help.

Table 115 describes navigation key function events.

 

Table 115:

Navigation key function events

Event	Affected widgets	AVM action
BACK-TAB	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	Move focus to the previous widget in the tab order within the current frame family.
CURSOR-DOWN DOWN	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	In a Windows GUI, move focus vertically to the next cell in a browse column, or to the next row of a browse widget when no cell is enabled. In the bottom-most browse cell or row, do not change focus. All other widgets provide no default AVM action. In character mode, move focus vertically down in the widget. If the cursor is in the bottom-most position of a widget, move focus to the first character position of the next widget below the current widget in the frame family. In the bottom-most position of the bottom-most widget in the frame family, do not change focus.
CURSOR-LEFT LEFT	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	In a Windows GUI, move focus to the previous character position in the current cell of a browse widget. In the first character position of the cell, do not change focus. All other widgets provide no default AVM action. In character mode, move focus to the previous character position to the left in the current widget. In the left-most character position of the widget, move focus to the first character position of the next widget to the left within the frame, or if the current widget is the left-most widget in the frame, do not change focus.
CURSOR-RIGHT RIGHT	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	In a Windows GUI, move focus to the next character position in the current cell of a browse widget. In the last character position of the cell, do not change focus. All other widgets provide no default AVM action. In character mode, move focus to the next character position to the right in the current widget. In the right-most character position of the widget, move focus to the first character position of the next widget to the right within the frame, or if the current widget is the right-most widget in the frame, do not change focus.
CURSOR-UP UP	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	In a Windows GUI, move focus vertically to the previous cell in a browse column, or to the previous row of a browse widget when no cell is enabled. In the top-most browse cell or row, do not change focus. All other widgets provide no default AVM action. In character mode, move focus vertically up in the widget. If the cursor is in the top-most position of a widget, move focus to the first character position of the next widget above the current widget in the frame family. In the top-most position of the top-most widget in the frame family, do not change focus.
NEXT-FRAME	Browse, browse cell, button, combo box, editor, fill‑in, radio set, selection list, slider, toggle box	Move focus to the next frame parented by the active window.
PREV-FRAME	Browse, browse cell, button, combo box, editor, fill‑in, radio set, selection list, slider, toggle box	Move focus to previous frame parented by the active window.
TAB	Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box	Move focus to the next widget in the tab order within the current frame family.

Table 116 describes field editing key function events.

 

Table 116:

Field editing key function events

Event	Affected widgets	AVM action
BACKSPACE	Fill‑in, browse cell	Delete one character to the left.
CLEAR	Fill‑in, browse cell	Clear the current field value (character interfaces only).
DELETE-CHARACTER	Fill‑in, browse cell	Delete one character to the right.
RECALL	Fill‑in, browse cell	Restore the field to its value when it was last enabled.
RETURN	Fill‑in, browse cell	Default behavior is different for character and graphical interfaces and dependent on the DATA-ENTRY-RETURN attribute of the SESSION handle.

Default keyboard events

ABL provides two keyboard events that you can use to write default triggers. Table 117 describes these events.

 

Table 117:

Default keyboard events

Event	Affected widgets	Meaning
ANY-KEY	Browse, browse cell, button, combo box, editor, fill‑in, radio set, selection list, slider, toggle box	Executes for any keyboard event for which the user has not defined a specific trigger.
ANY-PRINTABLE	Browse, browse cell, button, combo box, editor, fill‑in, radio set, selection list, slider, toggle box	Executes for any keyboard event that normally produces a printable character.

Mouse events

ABL supports two types of mouse events—portable and three‑button events. You can use portable mouse events to associate triggers with logical actions of any mouse. You can use the three‑button mouse events to associate triggers with specific physical actions of a three‑button mouse.

The following tables reference portable mouse buttons for portable mouse events and physical mouse buttons for three‑button mouse events. For more information on the mapping between portable and physical mouse buttons and how the AVM processes mouse events, see the chapter on handling user input in OpenEdge Development: Programming Interfaces.

Portable mouse events

Table 118 lists the mouse events that apply to all mice, no matter how the buttons are configured.

 

Table 118:

Portable mouse events

Event	User action	Affected widgets	AVM action
MOUSE-SELECT-DOWN	Press the mouse SELECT button.	All	Trigger dependent
MOUSE-SELECT-UP	Release the pressed mouse SELECT button.	All	Trigger dependent
MOUSE-SELECT-CLICK	Press and release the mouse SELECT button.	All	Trigger dependent
MOUSE-SELECT-DBLCLICK	Press and release the mouse SELECT button twice.	All	Trigger dependent
MOUSE-MENU-DOWN	Press the mouse MENU button.	All	Trigger dependent
MOUSE-MENU-UP	Release the pressed mouse MENU button.	All	Trigger dependent
MOUSE-MENU-CLICK	Press and release the mouse MENU button.	All	Trigger dependent
MOUSE-MENU-DBLCLICK	Press and release the mouse MENU button twice.	All	Trigger dependent
MOUSE-EXTEND-DOWN	Press the mouse EXTEND button.	All	Trigger dependent
MOUSE-EXTEND-UP	Release the pressed mouse EXTEND button.	All	Trigger dependent
MOUSE-EXTEND-CLICK	Press and release the mouse EXTEND button.	All	Trigger dependent
MOUSE-EXTEND-DBLCLICK	Press and release the mouse EXTEND button twice.	All	Trigger dependent
MOUSE-MOVE-DOWN	Press the mouse MOVE button. Note: In Windows, a MOUSE-SELECT-DOWN trigger defined for the same widget takes priority over MOUSE-MOVE-DOWN.	All	Trigger dependent
MOUSE-MOVE-UP	Release the pressed mouse MOVE button. In Windows, a MOUSE-SELECT-UP trigger defined for the same widget takes priority over MOUSE-MOVE-UP.	All	Trigger dependent
MOUSE-MOVE-CLICK	Press and release the mouse MOVE button. Note: In Windows, a MOUSE-SELECT-CLICK trigger defined for the same widget takes priority over MOUSE-MOVE-CLICK.	All	Trigger dependent
MOUSE-MOVE-DBLCLICK	Press and release the mouse MOVE button twice. Note: In Windows, a MOUSE-SELECT-DBLCLICK trigger defined for the same widget takes priority over MOUSE-MOVE-DBLCLICK.	All	Trigger dependent

Three‑button mouse events

Table 119 lists the mouse events associated with physical mouse buttons.

 

Table 119:

Three‑button mouse events

Event	User action	Affected widgets	AVM action
LEFT-MOUSE-DOWN	Press the left mouse button.	All	Trigger dependent
LEFT-MOUSE-UP	Release the pressed left mouse button.	All	Trigger dependent
LEFT-MOUSE-CLICK	Press and release the left mouse button.	All	Trigger dependent
LEFT-MOUSE-DBLCLICK	Press and release the left mouse button twice.	All	Trigger dependent
RIGHT-MOUSE-DOWN	Press the right mouse button.	All	Trigger dependent
RIGHT-MOUSE-UP	Release the pressed right mouse button.	All	Trigger dependent
RIGHT-MOUSE-CLICK	Press and release the right mouse button.	All	Trigger dependent
RIGHT-MOUSE-DBLCLICK	Press and release the right mouse button twice.	All	Trigger dependent
MIDDLE-MOUSE-DOWN	Press the middle mouse button.	All	Trigger dependent
MIDDLE-MOUSE-UP	Release the pressed middle mouse button.	All	Trigger dependent
MIDDLE-MOUSE-CLICK	Press and release the middle mouse button.	All	Trigger dependent
MIDDLE-MOUSE-DBLCLICK	Press and release the middle mouse button twice.	All	Trigger dependent

High-level widget events

Table 120 lists high‑level widget events. These are events generated by mouse or keyboard actions that perform high‑level operations on a widget, such as entering a fill‑in, choosing a button, or displaying a menu. Unless noted in the AVM Action column, triggers on these events execute before the AVM applies the event. If the trigger returns NO-APPLY, the AVM does not apply the event. If the trigger executes after the event takes place, NO-APPLY has no effect.

Note:

If a CHOOSE, DEFAULT-ACTION, or VALUE-CHANGED event executes a trigger as a result of a mouse click that changes input focus, NO-APPLY will return focus to the widget that had focus prior to the event.

 

Table 120:

High‑level widget events

Event	User action	Affected widgets	AVM action
CHOOSE	A keyboard or mouse action that chooses a widget.	Button, non-toggle-box menu item	Trigger executes after choose takes place
DEFAULT-ACTION	A native keyboard or mouse event that confirms the selection of a value in a selection list or browse. In Windows applications, double‑click a list item. In character applications, press RETURN or DELETE-LINE.	Selection list, Browse	Trigger dependent
DROP-FILE-NOTIFY ,	A mouse action that completes a drag-and-drop operation on a widget.	Browse, Button, Combo-box, Dialog-box, Editor, Fill-in, Frame, Radio-set, Selection-list, Slider, Toggle, Window	Trigger executes after drag-and-drop operation concludes Note: The trigger should call the END-FILE-DROP() method when it has finished processing all the files.
END	Occurs when the user repositions the browse to the end of the query’s result set by pressing the END key.	Browse	Trigger dependent
END-SEARCH1	Occurs when an updateable browse ends a user‑initiated search when a user either selects a row marker or clicks in a cell.	Browse	Trigger dependent
ENTRY	A keyboard or mouse action that gives focus to the widget.	Browse, browse cell, button, combo box, control container, dialog box, editor, fill‑in, frame, radio set, selection list, slider, toggle box, window	Trigger dependent Note: For a browse widget, ON ENTRY OF browse-name specifies a trigger for the browse widget and ON ENTRY OF column-name IN BROWSE browse-name specifies a trigger for a browse cell. The browse cell is the intersection of the named column and the currently focused row.
HOME	Occurs when the user repositions the browse to the beginning of the query’s result set by pressing the HOME key.	Browse	Trigger dependent
ITERATION-CHANGED	A keyboard or mouse action that changes the current iteration of a browse. This event is obsolete; see the VALUE-CHANGED Event reference entry.	Browse	Trigger dependent
LEAVE	A keyboard or mouse action that takes focus from the widget.	Browse, browse cell, button, combo box, control container, dialog box, editor, fill‑in, frame, radio set, selection list, slider, toggle box, window	Trigger dependent Note: For a browse widget, ON LEAVE OF browse-name specifies a trigger for the browse widget and ON LEAVE OF column-name IN BROWSE browse-name specifies a trigger for a browse cell. The browse cell is the intersection of the named column and the currently focused row.
MENU-DROP	A keyboard or mouse action that displays a menu.	Menu,3 submenu	Trigger dependent
OFF-END	A keyboard or mouse action that tries to move after the last row of a browse.	Browse	Trigger dependent
OFF-HOME	A keyboard or mouse action that tries to move before the first row of a browse.	Browse	Trigger dependent
PARENT‑WINDOW‑CLOSE	An event that each descendant window receives when the common ancestor window in that family receives a WINDOW-CLOSE event.	Window	Trigger dependent
ROW-DISPLAY	Any browse action that results in a row being displayed in the browse.	Browse	Trigger dependent Note: The use of triggers for this event is restricted to special cases. When a row is displayed, use a trigger to modify attributes of individual cells in the column. It should be restricted to the following uses: changing cell colors, changing the cell font, referencing the cell in an expression, and (in Windows) changing the cell format.
ROW-ENTRY	A keyboard or mouse action that gives an updateable cell focus in a browse row.	Browse	Trigger dependent
ROW-LEAVE	A keyboard or mouse action that takes focus from the browse row where an updateable cell has focus.	Browse	Trigger dependent
SCROLL-NOTIFY	A mouse action in the scrollbar area of a browse.	Browse	Trigger dependent Note: This event allows the developer to track physical movement of the focused row in the browse viewport.
START-SEARCH1	A keyboard or mouse action that places an updateable browse into search mode.	Browse	Trigger dependent
VALUE-CHANGED	A keyboard or mouse action that changes the value of a widget. For the browse, any action that selects a row.	Browse, combo-box, editor (Windows GUI only), fill-in, radio set, selection list, slider, toggle box, toggle box menu item	Trigger executes after value changes
WINDOW-CLOSE	A keyboard or mouse action that causes the native window manager to close the affected window or dialog box.	Dialog box, window	Trigger dependent
WINDOW-MAXIMIZED1	A keyboard or mouse action that causes the native window system to resize the window to its maximum size.	Window	Trigger executes after event takes place. However since the native system has control, a NO-APPLY does not stop the event from occurring. Note: This event occurs only in Windows.
WINDOW-MINIMIZED	A keyboard or mouse action that causes the native window system to minimize (iconify) a window and hide all of its descendant windows.	Window	Trigger executes after event takes place. However, since the native system has control, a NO-APPLY does not stop the event from occurring.
WINDOW-RESIZED	A keyboard or mouse action that causes the native window system to resize the window to any extent vertically or horizontally.	Window	Trigger executes after event takes place. However, since the native system has control, a NO-APPLY does not stop the event from occurring.
WINDOW-RESTORED	A keyboard or mouse action that causes the native window system to restore a window and any descendant windows to the state they were in before a prior maximize or minimize event.	Window	Trigger executes after event takes place. However since the native system has control, a NO-APPLY does not stop the event from occurring.

---

1

Windows only.

2

Graphical interfaces only.

3

Supported only if the Menu POPUP-ONLY attribute is set to TRUE and the menu is set as a popup for some other widget.

4

The OFF-END event can also occur when there are more rows to retrieve in the query on a ProDataSet temp-table buffer. For more information, see the “ProDataSet events” section.

Direct manipulation events

Direct manipulation events are ABL events that directly modify the size, shape, position, and appearance of a widget. These events are generated by mouse actions. Each user interface widget either has direct manipulation enabled or does not. Some types of widgets, such as menus, cannot have direct manipulation enabled. You can enable widgets for direct manipulation by setting the SELECTABLE, MOVABLE, or RESIZABLE attribute to TRUE.

If a widget has direct manipulation enabled, then direct manipulation events take priority over all other events. In other words, while data manipulation is enabled, the widget cannot perform data entry or application control functions. For example, if you set SELECTABLE to TRUE for a button, ABL interprets a MOUSE-SELECT-UP event as a SELECTION event. If you set SELECTABLE to FALSE, ABL interprets the same event as a CHOOSE event.

Direct manipulation events can be broken down into two types: general and frame-only. General direct manipulation events apply to both field-level and frame widgets. Frame-only direct manipulation events apply only to frames.

The following sections list the ABL events associated with direct widget manipulation. The user actions listed for these events assume that you set the appropriate attributes to make each event possible. For example, a widget must be SELECTABLE to receive the SELECTION event.

General direct manipulation events

Table 121 lists the direct manipulation events that apply to field‑level widgets and frames.

 

Table 121:

General direct manipulation events

Event	User action	Affected widgets	AVM action
DESELECTION	For all selected widgets in a frame, click the mouse SELECT button on an unselected widget or in empty space in the frame. For a single selected widget, click the mouse EXTEND button on a selected widget.	Frame and field‑level widgets with SELECTABLE attribute set to TRUE; browses.	Internal: Sets the widget’s SELECTED attribute to FALSE. This setting takes effect after any trigger for the event executes. Screen: Removes the highlight from the affected widget or widgets.
END-MOVE	Release the pressed mouse MOVE button after moving the drag box for the widget or widgets.	Frame and field‑level widgets with MOVABLE attribute set to TRUE; Also browse‑columns.	Internal: Generates an END-MOVE event for each moved widget. Screen: Moves each widget to the new x and y coordinates of its drag box.
END-RESIZE	Release the pressed mouse SELECT button after stretching the resize box to resize the widget.	Frame and field‑level widgets with RESIZABLE and SELECTABLE attributes set to TRUE; Also browse‑columns.	Internal: Generates an END-RESIZE event for the resized widget. Screen: Resizes the widget to the new x and y coordinates of its resize box.
END-ROW-RESIZE	Release the pressed mouse SELECT button after resizing a row.	Browses.	Internal: Generates an END-ROW-RESIZE event for the resized row. Screen: Resizes all rows to the new height.
SELECTION	For a single unselected widget, click the mouse SELECT or EXTEND button on the widget. For multiple unselected widgets, release the pressed EXTEND button after drawing a select box around the widgets.	Frame and field‑level widgets with SELECTABLE attribute set to TRUE.	Internal: Sets each widget’s SELECTED attribute to TRUE. This setting takes effect after any trigger for the event executes. Screen: Highlights the affected widget or widgets.
START-MOVE	For a single widget, with the mouse pointer on the widget, press and hold the mouse MOVE button, and begin moving the mouse pointer. For multiple selected widgets—With the mouse pointer on any one of the selected widgets, press and hold the mouse MOVE button, and begin moving the mouse pointer.	Frame and field‑level widgets with MOVABLE attribute set to TRUE; for multiple widgets, SELECTABLE attribute also set to TRUE; Also browse‑columns.	Internal: Sends a START-MOVE event to all selected widgets. If the trigger returns a NO-APPLY, the AVM does not generate the subsequent END-MOVE event. Screen: Draws a drag box around each of the one or more affected widgets, and moves each drag box in the direction of the moving mouse pointer.
START-RESIZE	With the mouse pointer on a resize handle of a selected widget, press and hold the mouse SELECT button and begin moving the mouse pointer.	Frame and field‑level widgets with RESIZABLE and SELECTABLE attributes set to TRUE; Browse columns.	Internal: Sends a START-RESIZE event to the selected widget. If the trigger returns NO-APPLY, the AVM does not generate the subsequent END-RESIZE event. Screen: Stretches a resize box around the widget in the direction of the moving mouse pointer.
START-ROW-RESIZE	With the mouse pointer on a row, press and hold the mouse SELECT button and begin moving the mouse pointer.	Browses.	Internal: Sends a START-ROW-RESIZE event to the browse. If the trigger returns NO-APPLY, the AVM does not generate the subsequent END-ROW-RESIZE event. Screen: Stretches a resize box around the row in the direction of the moving mouse pointer.

Frame-only direct manipulation events

Table 122 lists the direct manipulation events that apply only to frames.

 

Table 122:

Frame-only direct manipulation events

Event	User action	Affected widgets	AVM action
EMPTY-SELECTION	Click the mouse SELECT button on an empty space in the frame.	Frame and dialog box, whether its SELECTABLE attribute is set to TRUE or FALSE.	Internal: Sends a DESELECTION event to all selected widgets in the frame and sends the EMPTY-SELECTION event to the frame. Screen: Removes the highlight around any selected widgets in the frame.
END-BOX-SELECTION	Release the pressed mouse SELECT or EXTEND button after moving the mouse pointer to stretch the select box.	Frame and dialog box with BOX-SELECTABLE attribute set to TRUE.	Internal: If the user pressed the mouse SELECT button, the AVM sends a SELECTION event to all widgets surrounded by the select box. If the user pressed a mouse EXTEND button, the AVM sends a SELECTION event to all unselected widgets, and a DESELECTION event to all selected widgets surrounded by the select box. If a trigger on END-BOX-SELECTION returns NO-APPLY, the AVM does not send a subsequent SELECTION or DESELECTION event. Note that this behavior differs from the behavior of END-MOVE and END-RESIZE. Screen: Erases the select box, highlights selected widgets, and removes the highlight from deselected widgets.
START-BOX-SELECTION	Press and hold the mouse SELECT or EXTEND button in an empty area of the frame and begin moving the mouse pointer.	Frame and dialog box with BOX-SELECTABLE attribute set to TRUE.	Internal: Sends a START-BOX-SELECTION event to the frame. If a trigger returns NO-APPLY, the AVM does not generate the subsequent END-BOX-SELECTION event. Screen: Draws a select box, which initially appears as a dot.

Developer events

ABL provides eleven events, labeled U1 through U10 and CLOSE, that you can invoke on any widget using the APPLY statement. The only function of a developer event is the one provided by your own trigger definition.

Socket events

ABL looks for events to execute in the context of input-blocking or event-processing statements. During this processing if the AVM detects that data is available on a socket or that the remote end closed its socket or it detects that a client has connected to a port that the server has enabled connections to, a socket event is generated.

There are only two socket events, the READ-RESPONSE event, which applies only to socket objects, and the CONNECT event which applies only to server socket objects.

READ-RESPONSE event

AVM Detects — Data is available on a socket or the remote end of a connection has closed its socket; applies only to socket objects.

AVM Action — The AVM invokes the READ-RESPONSE event procedure.

The SET-READ-RESPONSE-PROCEDURE( ) method is used to name the READ-RESPONSE event procedure and to associate it with a socket object. The AVM invokes this procedure whenever it detects that data is available on the socket or that the remote end of the socket has closed its end of the socket. In this procedure, the SELF handle identifies the affected socket object.

To determine if the event procedure was invoked because data is available for reading or because of a disconnect, the application can use one of several methods:

The CONNECTED( ) method returns FALSE if the socket is not connected to a port, TRUE if it is connected.

The GET-BYTES-AVAILABLE( ) method returns zero if the socket is not connected to a port or the number of bytes available for reading if it is connected.

The READ( ) method returns FALSE if the socket is not connected to a port. It returns TRUE and the read data if it is connected.

CONNECT event

AVM Detects — A client has connected to a port that the server has enabled connections to; applies only to server socket objects.

AVM Action — The AVM invokes the CONNECT event procedure.

The SET-CONNECT-PROCEDURE( ) method is used to name the CONNECT event procedure and to associate it with a server socket object. The CONNECT event procedure must accept one input parameter of type HANDLE. This is the handle to the implicitly created socket object for this connection. It is via this socket object that the server communicates with the client.

If the SET-CONNECT-PROCEDURE( ) method is not invoked, or if it fails, no connection procedure will be executed when the CONNECT event occurs.

ProDataSet events

ABL provides events you can invoke to execute application-specific code that handles FILL operations on a ProDataSet object or Buffer object, as well as row-level change operations. You can use the SET-CALLBACK-PROCEDURE( ) method to associate an action with these events.

Event procedures must define a single parameter for the ProDataSet object (DATASET or DATASET-HANDLE) as an INPUT parameter BY-REFERENCE. This allows the event procedure to operate on the ProDataSet object using static ABL to reference its buffers and fields, without the ProDataSet object being physically copied. This also means that because the ProDataSet object is not copied, changes made to the ProDataSet object by the event procedure are made to the same copy used by all procedures.

The following sections describe the ProDataSet events:

FILL events

Row-level events

OFF-END event

FIND-FAILED event

SYNCHRONIZE event

FILL events

There are two levels of FILL events: the first level is for a ProDataSet object or one of its member buffer objects; the second level is for individual records created in each temp-table.

Table 123 lists the first-level FILL events.

 

Table 123:

First-level FILL events

Event	Affected objects	AVM action
AFTER-FILL	Buffer object of a DATASET temp-table, ProDataSet object	This event occurs at the very end of a FILL, and can be used to adjust the contents of the ProDataSet object or Buffer object, reject the FILL operation, or disconnect from a server or database. For a child table, the event occurs once for each parent record that is created.
BEFORE-FILL	Buffer object of a DATASET temp-table, ProDataSet object	This event occurs at the very beginning of a FILL, before anything is read or created. For a Buffer object, this event allows the developer to do preparatory work for an individual table. For the parent table in a set of related tables, where the FILL event is applied to this top-level table, it could be the same kind of connection code as for the ProDataSet object as a whole. For a child table, the event occurs once for each parent record that is created, and allows the developer to adjust the query for the child table, or cancel the FILL for that parent altogether. For a ProDataSet object, this event allows the developer to make a server or database connection, or do other preparatory work. Alternatively, it allows the developer to intercept and fully replace the default behavior.

Table 124 lists the second-level FILL events. These events occur once immediately before or after each record is created in a temp-table during a FILL.

 

Table 124:

Second-level FILL events

Event	Affected objects	AVM action
AFTER-ROW-FILL	Buffer object of a DATASET temp-table	This event occurs after a record is created in the temp-table. The procedure can, for example, modify field values in the record by supplying values for calculated fields, or perform filtering and reject a record by deleting it. The procedure cannot modify record currency using the ProDataSet object buffers in any other way. It can use separately defined buffers to modify the ProDataSet object in other ways. The procedure can RETURN ERROR to abort the entire FILL, or RETURN NO-APPLY to cancel the cascading of the FILL to child buffers, if any.
BEFORE-ROW-FILL	Buffer object of a DATASET temp-table	This event occurs before a record is created in the temp-table, but after the data source record(s) for it are read. For example, this procedure could examine the database buffers or other information and decide not to create the record, using a RETURN NO-APPLY statement.

Row-level events

Row-level events are defined for making local changes to the records in a ProDataSet member buffer object. Table 125 lists the row-level events.

 

Table 125:

Row-level events

Event	Affected objects	AVM action
ROW-CREATE	Buffer object of a DATASET temp-table	This event occurs immediately after the record is created in the temp-table. The current buffer for the temp-table is available and contains initial values as defined in the temp-table definition (or inherited from the schema). You can use this event to calculate initial values for fields, make changes to other records, or reject the creation by deleting the new temp-table record.
ROW-DELETE	Buffer object of a DATASET temp-table	This event occurs when you delete a temp-table record, immediately before the record is deleted. The event procedure can use this event to RETURN ERROR to cancel the delete, or to make adjustments to other records based on the delete. Since the record has not yet been deleted, the record is in the temp-table buffer and the code can look at its values. Because the code can assume that the DELETE will go through unless cancelled by the event procedure itself, it can take actions based on the record deletion while the record is still there to be looked at.
ROW-UPDATE	Buffer object of a DATASET temp-table	This event occurs immediately before the record is updated in the temp-table. It typically occurs when: The buffer scope ends The transaction scope ends The RELEASE statement or BUFFER-RELEASE( ) method is run on the buffer The buffer is needed for another record The AVM sets the SELF system handle to the handle of the buffer on which the event procedure is running before calling the event handler. If the event handler returns NO-APPLY or ERROR, the return is ignored. The handler has run, and it is too late to undo any changes to the record. You can use this event to determine if and how a record has changed by reading the buffer in the before-image table (using the SELF:BEFORE-ROWID attribute) and comparing it to the updated buffer. You can also use this event in the event handler to update fields in the record (for example, to supply a calculated field). You cannot read another record into the buffer on which the event procedure is running in the event handler. If you need to read another record, use a different buffer to avoid disturbing the record you are currently updating.

OFF-END event

The OFF-END event occurs when you position a query on a ProDataSet temp-table buffer past the last row. You can use this event to retrieve additional data source rows to add at the bottom of a ProDataSet temp-table (for example, in batches when there are too many data source rows to retrieve at one time).

The OFF-END event can also occur when the user performs a keyboard or mouse action in a browse that scrolls off the end (past the last row) of a browse on a ProDataSet temp-table buffer. For more information about using the OFF-END event with a browse, see the “High-level widget events” section.

Note:

The OFF-END event is similar to the QUERY-OFF-END attribute, which is set to TRUE whenever the associated query object is positioned past the last row. The difference is that you must test the QUERY-OFF-END attribute for this condition at a specific place in your application code, whereas the OFF-END event procedure executes like a trigger whenever the event occurs.

Consider the following restrictions when using the OFF-END event with a query on a ProDataSet temp-table buffer:

You can attach these events only to a query on a single ProDataSet temp-table buffer. You cannot attach these events to a query on a database buffer, or a query that involves a join.

The query must be a scrolling query.

If you never RETURN NO-APPLY, from the OFF-END event handler, the query will infinitely loop.

Call the SET-CALLBACK-PROCEDURE( ) method before the query is opened.

If you use the GET LAST statement or GET-LAST( ) method to get the last record associated with the query, the event handler is called repeatedly until it does not RETURN NO-APPLY (indicating that all records have been retrieved). For this reason, use caution when offering users the GET LAST action.

The INDEXED-REPOSITION option is ignored for the query.

FIND-FAILED event

The FIND-FAILED event occurs when a FIND on a ProDataSet temp-table buffer fails. This can be the result of the FIND statement (but not the FIND NEXT, FIND PREV, or FIND LAST statements, and not the CAN-FIND function), or the FIND-FIRST( ) or FIND-UNIQUE( ) methods (but not on the FIND-LAST( ) method).

You can use this event to adjust the contents of the ProDataSet object. The event handler must be able to determine the action to take based on the context of the ProDataSet object, and must RETURN NO-APPLY to indicate the action was successful. For example, when the event occurs, the event handler could retrieve a missing row or a set of related rows from the server automatically.

SYNCHRONIZE event

The SYNCHRONIZE event occurs when a ProDataSet temp-table buffer is synchronized. That is, when the SYNCHRONIZE( ) method is run on the buffer or a parent buffer, or the buffer is selected in a browse. The event handler is invoked recursively at every level of the ProDataSet object hierarchy just before the recursion to the child levels.

By default, if the query is associated with a browse, the synchronize action of reopening the query automatically refreshes the browse. If the query is not associated with a browse, the synchronize action automatically gets the first row in the query by invoking a GET FIRST operation. If there is a REPOSITION data relation and no browse, the synchronize action gets the next record in the query by invoking a GET NEXT operation. Once these actions attempt to populate the buffer at a particular level, the SYNCHRONIZE event runs before moving recursively to the next lower level.

This event allows you to fetch rows, display buffer values in a frame, or take some other action. The handler procedure can also RETURN NO-APPLY to cancel the cascading of the synchronization to child buffers.