Response Definition
Respond to selection of an object.
[interrupt] response to {OBJECT_NAME|CLASS_NAME|OBJECT_TYPE}
[[ON_CLAUSE] [ACTION_STATEMENT] ...] ...
interrupt
Allow ESL to leave and return to any block currently executing, except a guarded block, when the response is stimulated. If a response within a block is being executed, ESL will first finish any current action statements left in the response, then execute the actions in the interrupt response, and finally return to the block and await a stimulus from within the original block.
OBJECT_NAME
The identifier for the object. If this name is not a compile-time value, an error message will be produced.
CLASS_NAME
The identifier for a class of objects. If this name is not a compile-time value, an error message will be produced.
OBJECT_TYPE
One of the following:
•check box
•key
•combination box
•list box
•dialog box
•multiline entry field
•dialog region
•push button
•dropdown list
•radio button
•dropdown combination box
•sense region
•entry field
•slider
•graphical region
•spin button
•image region
•table
•textual region
ON_CLAUSE
One of the following:
on activate
Take the response if the user activates the object.
on button1 down
Take the response if the user clicks on the client area of the window/table with the primary mouse selection button.
on button1 double click
Take the response if the user double-clicks on the client area of the window/table with the primary mouse selection button.
on close
Take the response if the user selects the Close choice from the system menu, or double-clicks on the system menu. A region without a system menu will never receive this event.
on column resize (table objects only)
Take the response when the user directly resizes a column. This is not invoked if the program changes the size of a column.
on drag
Take the response when the user tries to initiate a drag operation.
on dragover
Take the response when the user drags over an object. Avoid performing time consuming calculations inside this response clause.
on drop
Take the response when the user drops on an object.
on drophelp
Take the response when the user presses the F1 key when dragging over an object.
on edit (table objects only)
Take the response when the user requests to edit or enter data in a cell. Use this response to decide whether to allow the cell to be edited or to perform some action before allowing edits.
on edit cancel (table objects only)
Take the response when the user cancels the editing of text in a cell. This is caused either when the user presses the Esc key to finish editing a cell or when they accept a value that is not legal.
on hscroll
Take the response if the user clicks on the horizontal scroll bar.
on maximize
Take the response if the user clicks on a region's maximize button.
on minimize
Take the response if the user clicks on a region's minimize button.
on move
Take the response if the user moves a region.
on restore
Take the response if the user restores a region.
on resize
Take the response if the user resizes the region.
on spin (spin buttons only)
Take the response if the user clicks on the up or down arrow of a spin button.
on validation (for entry fields, spin buttons and tables only)
Take the response if the user moves the focus out of the entry field or spin button into any other control in the same dialog box or dialog region, except the Cancel push button.
For entry fields only, if you include a validation is clause with on validation, ESL performs the validation is clause before the on validation clause. If you specify only the on validation clause, the clause acts as an exit routine.
See "Writing Table Responses" for a complete description of the effect of this clause on tables.
on validation failure
Take the response if the entry field fails the validity check specified in the validation is clause in the entry field definition.
on vscroll
Take the response if the user clicks on the vertical scroll bar.
See "Object/on Clause Combinations " later in this definition for meaningful combinations.
ACTION_STATEMENT
An action statement you want executed.
Description
Use this statement to define the response to the user's selection of an object, a type of object, or any object in a class. The response will be invoked only if the specified object/type is enabled at the time that it is selected.
If you use response to CLASS_NAME, the selection of any object in the class will stimulate the response.
The same response statement precedence rules apply to response to as to other ESL response definitions. That is, the first matching response in a block--whether responding to a specific object, a class of objects, or a generic object type--is the one taken. Once the response is taken, ESL does not search for additional matching responses in the block. Therefore, you should place generic OBJECT_TYPE responses after any specific or class responses.
A response may contain one or more of the on clauses, in any order. However, a given response may contain no more than one of each type. For example, only one on close clause is allowed in any one response.
An on button1 double click event is always preceded by an on button1 down event. The corresponding actions for on button1 down (or the generic response to...) will be invoked before the invocation of the actions for on button1 double click.
It is possible to trigger both an on resize and an on move response when a region is resized. This will occur when a region is resized in such a way that the region's origin is moved. When this happens, ESL will take the on resize response before on move.
ESL will not delete an object that is closed from the system menu if there is an on close response that it can invoke. This allows your program to gain control when the user attempts to close a window, and to query the user about it. For example, you may want to display a "Verify changes" dialog box.
When you do not include an ON_CLAUSE, a response is taken when the user selects an object (that is, the normal response behavior of the object), except in the case of dialog objects.
When taking a response to a dialog box or dialog region, the response to statement must always include an on clause for any action you want taken. This applies to responses to individual dialog boxes/dialog regions, generic responses (response to dialog box and response to dialog region), and classes where an object resolves to a dialog box or dialog region.
Writing on activate Responses
The on activate response statement is invoked when a region becomes active as a result of a user selecting it, or one of its children, with the mouse or the keyboard. The active region is displayed with its title bar highlighted, or border highlighted, if it is a dialog region.
If a region is activated due to the execution of an ESL statement (such as activate or make...visible), the on activate response for that region is not invoked.
Do not call the ReplyToMessage( ) function, or any function that displays a message box, from an on activate response.
When a previously inactive region becomes activated, all of its ancestors are activated as well, beginning with the child and working back, with the farthest-removed ancestor activated last.
For dynamically created regions, an on activate response is not invoked when the region is first created.
Writing Drag and Drop Responses
A source object is an object from which a drag can be initiated. A target object is an object that can potentially be dropped on.
A source object needs to have an on drag response. In this response, the source object must use the drag action to actually initiate a drag. Otherwise, a drag operation will not occur.
A target object needs to have both an on dragover and an on drop response. The on dragover response gives the target a chance to decide whether to allow a drop. The on drop response tells the target that the user actually dropped on it. The on drophelp response tells the target that the user would like information on what happens if they drop at that point.
The dragover response is triggered every time the mouse moves over an object. To avoid slowing down the drag operation, the actions executed in this response should be very short and fast. For instance, we recommend that you do not access a database during a dragover response. Ideally, you should simply test the dragtype value to determine whether to call allow drop.
Your application can use the built-in functions dragtype, xcoord, and ycoord in the on dragover, on drop, and on drophelp responses. In a dragover response, they are used to determine whether a drop should be allowed. In a drop response, they are used to execute the appropriate application logic. In a drophelp response, they are used to determine which help panel to display. dragdata is set to the value of the DATA_STR specified in the drag action statement that initiated the drag operation, and is only available in an on drop response. The built-in functions xcoord and ycoord are set to the mouse pointer's position in the target object.
Writing Table Responses
For all table responses (except on hscroll and on vscroll), the xcoord and ycoord built-in functions will be set to indicate the part of the table that is involved.
For a cell, both of them will be non-zero.
For a column or column heading, xcoord will be non-zero and ycoord will be zero.
For a row or row heading, ycoord will be non-zero and xcoord will be zero.
For an empty part of the table, both will be zero.
For scrolling, xdelta and ydelta will be set.
An on button1 down response is taken when the selection status of a row or column is changed (including when keyboard shortcuts are used). This will occur when the user moves the cursor to a new cell (e.g., clicks on it or uses the arrow keys). It also occurs when the user clicks on a row or column heading (whether selection is allowed or not). If a click on a row or column heading causes both the cell position and the row or column selection to change, then there will be two responses, one for each event.
An on button1 double click response is taken when button 1 is double-clicked in a cell, a row heading, or a column heading, or when a user double-clicks in white space in a table. In the latter case, xcoord and ycoord will both be 0.
An on column resize response is taken when the user directly resizes a column. This is not invoked if your application program changes the size of a column.
To resize a table with its parent, use an on resize clause on the parent of the table and adjust the table and other controls appropriately.
An on edit response is taken when the user starts to edit or enter data in a cell. Your application may use this response to decide whether to allow the cell to be edited or to perform some action before allowing editing.
The user can initiate this by pressing the edit key or typing a printing character to enter in a cell. This response is not taken when an application program directly changes a cell, nor when it issues a make edit statement.
If your program issues a make TABLE cancel action statement in an on edit response, then the user will not be able to edit the cell.
For example, a database program could lock a row before allowing it to be edited. Alternately, a data entry program could display a row edit dialog box, instead of allowing the user to edit the cell directly.
An on edit cancel response is taken when the user cancels the editing/entry of text in a cell. This is caused either when the user presses the Esc key to finish editing a cell, or when the user accepts a value that is not legal. In the latter case, the table beeps, the old value is restored, and this on clause is generated.
An on validation response is taken when the user finishes editing a cell and the change is accepted, not when the user aborts the cell edit. Note that ESL does not perform validation on tables in the same way that it does for entry fields. For tables, ESL only verifies that the user has entered the correct type of data (string, boolean, etc.). You cannot define validation masks or ranges in table entry.
Writing Window Event Responses
Window events occur when window attributes are selected to modify a window. Window events are triggered by the following window commands:
Event |
on Clause |
|
close |
on close |
|
horizontal scroll |
on hscroll |
|
maximize |
on maximize |
|
minimize |
on minimize |
|
move |
on move |
|
restore |
on restore |
|
resize |
on resize |
|
vertical scroll |
on vscroll |
|
These on clauses provide you with a way to respond to window events. You can use them for any of the following ESL object types that are defined to contain the appropriate window frame attribute or a system menu to trigger the event:
graphical region
image region
textual region
dialog region
dialog box (system menu)
list box
multiple-line entry field
table object
The dialog controls, including the table object, can only have horizontal and vertical scroll bars. For example, if a graphical region has a size border or a system menu, the user may resize the region, and an on resize response will be taken. If the region does not have either a size border or a system menu, no on resize response can be taken for that region.
The window event on clauses are taken only in response to window events triggered by window attributes and system menus, including keyboard selection of system menu items. They are not taken in response to ESL action statements.
For example, the on close response is taken if the user closes a window by selecting Close from the system menu, or by double-clicking on the system menu. The response is not taken if the user programatically deletes the window.
Similarly, the on move response is taken only if the user moves the ESL object by selecting the object's title bar with the mouse, or by selecting Move from the object's system menu. The ESL statement move Object1 to 100 100 would not cause the response to be taken.
When the response to an on clause is taken, the window event will have already occurred, and the object will have been modified. Therefore, when an on clause is taken, any object query using ESL's object inquiry built-in functions (xsize of/ysize of, xposition of/yposition of, top of/bottom of, etc.) will return the post-window event value. For example, if the response code for on resize uses the built-in functions xsize of and ysize of to query the size of the object, the value returned will be the object's new size.
In addition, you can use the built-in functions xdelta and ydelta to determine the net change in the size, position, or window position as a result of size, move, or scroll window commands, respectively.
Note that you should not use the is minimized built-in function to test an on minimize response because ESL will not return a correct response. Similarly, do not use is maximized to test on maximize, nor is restored to test on restore.
Scrolling Responses
There are four ways to scroll a window using window attributes, and six ways to scroll with the keyboard. To scroll using window attributes, users can:
Click on one of the scroll arrows once.
Click on the scroll bar above, below, to the left of, or to the right of the scroll box.
Drag the scroll box to a position on the scroll bar.
Hold down the scroll arrow, and release when scrolled sufficiently.
These assume that the object, window, or control is large enough to activate the scroll bars defined for it.
Each time the window is scrolled, only one on scroll response is generated for any of the first three scrolling methods. For example, if the user drags the scroll box to a new location, only one on scroll response is taken -- even though the result of the scroll may be multiple scroll units. However, when the user holds down the scroll arrow, then releases it after the desired scroll position is reached, a scroll response is taken each time the window scrolls during that process. In addition, the values returned by the xdelta and ydelta built-in functions during the scrolling process are affected.
Writing Validation Responses for Entry Fields
Validation is defined by the entry field's validation is clause. You can also specify your own validation criteria by using an on validation clause. When specified without a validation is clause, on validation acts as an exit routine for the entry field, which is useful for writing your own validation criteria for an entry field. The on validation clause allows you to define a more complex validation criteria than what is available through the validation is clause. If you specify an on validation failure clause, the entry field must have a validation is clause for it to be invoked.
When the validation is clause results in validation failure, the system posts an error message describing the nature of the error, and returns the input focus to the entry field. To customize the validation failure response, define the on validation failure clause. If you specify this clause, you should include code that posts an error message and returns the input focus to the entry field.
The response to ENTRY_FIELD on validation definition will cause ESL to generate one response after the user performs some action that would cause the focus to move to another dialog control within the same dialog box or dialog region (such as tabbing, or clicking on another object). If the user selects another object for which a response is defined, the on validation response is processed first.
The following table provides a summary of the validation clauses and their functions. Note that a validity check is triggered when all the listed conditions occur for that clause.
on validation failure
Clause/Action |
Trigger Conditions |
Validity Check Response |
on validation |
The user moves the input focus out of the entry field and into any other control in the same dialog box or dialog region, except the Cancel push button. If a validation is was specified, then it was successful. |
Customized success responses. |
Validation is |
The user moves the input focus out of the entry field and into any other control in the same dialog box or dialog region, except the Cancel push button, or when a push button with a verify attribute specified is pressed. |
In case of an error, the system posts a default error message specified to the validation defined for the entry field, then returns the input focus to the entry field. |
|
The user moves the input focus out of the entry field and into any other control in the same dialog box or dialog region, except the Cancel push button. The entry field has a validation is clause, and the user's input does not meet the specifications defined by the validation is clause in the entry field. |
Customized error handling for validation is clause. If specified, should include code that posts an error message and returns the input focus to the entry field. |
Object/on Clause Combinations
The ESL compiler will accept any on clause syntax for any response to an object or class name. However, note that some object/on-clause combinations are not useful, and will never be executed. The following table lists the combinations that are meaningful.
Object |
on Clause |
Notes |
Graphical region Image region Textual region |
on activate on button1 down on button1 double click on close on drag on dragover on drop on drophelp on hscroll on vscroll on maximize on minimize on move on restore on resize |
A system menu attribute is required to invoke an on close response. |
Sense region Key |
on button1 down on button1 double click on drag on dragover on drop on drophelp |
|
Combination box |
on drag on dragover on drop on drophelp on vscroll on button1 down on button1 double click |
If it is a single-selection list and you click on the same item twice, you will not invoke a response.
Pressing the Enter key is the same as double-clicking an item. This is only possible in a simple combination box. |
Drop-down list |
on drag on dragover on drop on drophelp on hscroll on vscroll on button1 down |
There must be at least one item in the list box part of the combination box for an on button1 down response to be triggered. If you click on the list box area but it is empty, or you click on the area below the last item, a response will not be triggered. |
Dialog box |
on activate on drag on dragover on drop on drophelp |
Pressing the Esc key, double-clicking on the system menu, or selecting Close from the system menu invokes a response to the Cancel push button, if there is one. |
Dialog region |
on activate on close on drag on dragover on drop on drophelp on hscroll on maximize on minimize on move on restore on resize on vscroll |
Pressing the Esc key, double-clicking on the system menu, or selecting Close from the system menu invokes a response to the Cancel push button, if there is one. If no response to the Cancel push button is found, ESL looks for and invokes an on close response for that region. If there is no Cancel push button and no on close response to invoke, ESL destroys the dialog region. |
List box |
on button1 down on vscroll on drag on dragover on drop on drophelp on button1 double click |
Taken when the user selects an entry. If it is a single-selection list and you click on the same item twice, you will not invoke a response. Pressing the Enter key is the same as double-clicking on an item. Note that this will also trigger a default push button. |
Push button Radio button Check box |
on drag on dragover on drop on drophelp on button1 down |
|
Table Object |
on activate on drag on dragover on drop on drophelp on button1 down on button1 double click on vscroll on hscroll on column resize on edit on edit cancel on validation |
Taken as described in "Writing Table Responses."
Validation in tables only checks whether the user has entered the correct type of data. |
Entry Field |
on drag on dragover on drop on drophelp on validation on validation failure on vscroll |
Taken as described in "Writing Validation Responses." Only for multiple-line entry fields. |
Spin Button |
on drag on dragover on drop on drophelp on spin on validation |
|
Example
response to Command_Key
enable Cover
make Prompt visible
interrupt response to Warning
action WarnUser
response to MainWindow
on close
if (ReplyToMessage ("Close","Are you sure?",
MessageYesNo, 2, MessageNoIcon) = "yes") then
action CloseUp
end if
on button1 down
make MainWindow red
response to StartTime_EF
# Use default validation, but custom response
# to validation failure.
on validation failure
# If the entry field fails validation,
# post a custom error message and return
# the focus to the entry field.
copy ReplyToMessage ("Validation Error",
"The starting time must be between "
OpenTime " and 4:30 PM.", MessageOK,
1, MessageNoIcon) to Temp
activate StartTimeEF
# Response to sizing a window.
response to PrimaryWindow on resize
# Resize Primary window's child windows.
change ClientWindow size to
(window size of PrimaryWindow - ICON_BAR_WIDTH_INT)
(window size of PrimaryWindow - STATUS_LINE_HEIGHT_INT)
change StatusLineWindow position to
ICON_BAR_WIDTH_INT (yposition of ClientWindow) #x/yposition
# Response to moving a window.
response to SQLTableClass
on move
action RedrawTheConnections
# Response to scrolling.
# This keeps a specified child region at a specific location.
response to PrimaryTextRegion on vscroll
change SecondaryTextRegion window position to window xposition of PrimaryTextRegion window yposition of PrimaryTextRegion
# Response to resizing an MLE to fill a dialog region when
# the DR is resized.
primary dialog region my_DR
size 300 200 at 10 10 in desktop
title bar "Editor"
size border
system menu
multiline entry field my_MLE
size (window xsize of my_DR) (window ysize of my _DR)
at 0 0 in my_DR
response to my_DR on resize
begin resumable
response to timeout -1
leave block
end
change my_DR window position to 0 0
change my_MLE size to (xsize of my_DR) (ysize of my_DR)
# drag and drop responses
response to Employee_KEY
on drag
drag EmployeeId_IV type "Employee"
using icon "employee.ico"
response to Department_GR
on dragover
if (dragtype = "Employee") then
allow drop # an Employee can be dropped on
# Primary_GR
end if
on drop
if (dragtype = "Employee") then
copy dragdata to EmployeeId_IV
copy parameter to DeptId_IV # parameter of
# Department_GR holds
# the dept id
call MoveEmployee( EmployeeId_IV, DeptId_IV )
end if
on drophelp
if (dragtype = "Employee") then
copy "Help for Drop Employee (Move)" to HelpId_SV
call HelpDisplayHelpPanel( HelpId_SV )
end if
See Also
allow drop Action Statement
drag Action Statement
dragdata Response Inquiry Built-in Function
dragtype Response Inquiry Built-in Function
entry field Definition
is minimized Object Inquiry Built-in Function
is maximized Object Inquiry Built-in Function
is restored Object Inquiry Built-in Function
make OBJECT maximize Action Statement
make OBJECT minimize Action Statement
make OBJECT restore Action Statement
table Object Definition
xcoord and ycoord Response Inquiry Built-in Functions
xdelta and ydelta Response Inquiry Built-in Functions
