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.
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.
Table 114 describes universal key function events.
Table 115 describes navigation key function events.
|
|
|
|
BACK-TAB
|
Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box
|
|
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
|
|
|
PREV-FRAME
|
|
|
TAB
|
Browse, browse cell, button, combo box, control container, editor, fill‑in, radio set, selection list, slider, toggle box
|
|
Table 116 describes field editing key function events.
Table 118 lists the mouse events that apply to all mice, no matter how the buttons are configured.
Three‑button mouse events
Table 119 lists the mouse events associated with physical mouse buttons.
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.
|
|
|
|
|
CHOOSE
|
|
|
|
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.
|
|
|
DROP-FILE-NOTIFY 1,2
|
|
Browse, Button, Combo-box, Dialog-box, Editor, Fill-in, Frame, Radio-set, Selection-list, Slider, Toggle, Window
|
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.
|
|
|
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.
|
|
|
ENTRY
|
|
Browse, browse cell, button, combo box, control container, dialog box, editor, fill‑in, frame, radio set, selection list, slider, toggle box, window
|
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.
|
|
|
ITERATION-CHANGED
|
|
|
|
LEAVE
|
|
Browse, browse cell, button, combo box, control container, dialog box, editor, fill‑in, frame, radio set, selection list, slider, toggle box, window
|
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
|
|
|
|
OFF-END 4
|
|
|
|
OFF-HOME
|
|
|
|
PARENT‑WINDOW‑CLOSE
|
An event that each descendant window receives when the common ancestor window in that family receives a WINDOW-CLOSE event.
|
|
|
ROW-DISPLAY
|
|
|
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
|
|
|
|
ROW-LEAVE
|
A keyboard or mouse action that takes focus from the browse row where an updateable cell has focus.
|
|
|
SCROLL-NOTIFY
|
|
|
Note: This event allows the developer to track physical movement of the focused row in the browse viewport.
|
START-SEARCH1
|
|
|
|
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
|
|
WINDOW-CLOSE
|
A keyboard or mouse action that causes the native window manager to close the affected window or dialog box.
|
|
|
WINDOW-MAXIMIZED1
|
A keyboard or mouse action that causes the native window system to resize the window to its maximum size.
|
|
Trigger executes after event takes place. However since the native system has control, a NO-APPLY does not stop the event from occurring.
|
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.
|
|
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.
|
|
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.
|
|
Trigger executes after event takes place. However since the native system has control, a NO-APPLY does not stop the event from occurring.
|
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.
Table 121 lists the direct manipulation events that apply to field‑level widgets and frames.
|
|
|
|
|
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.
|
|
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.
|
|
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.
|
Table 122 lists the direct manipulation events that apply only to frames.
|
|
|
|
|
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.
|
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.
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.
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.
|
|
|
|
AFTER-FILL
|
|
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
|
|
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.
|
|
|
|
AFTER-ROW-FILL
|
|
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
|
|
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-CREATE
|
|
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
|
|
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
|
|
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).
|
|
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.
|
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.
