The following events are associated with controls:
CMD-CLICKED (value 4) This event occurs for push button, check box, and radio button controls, even if NOTIFY is not specified. Specifying NOTIFY makes this a terminating event for check boxes and radio buttons. CMD-CLICKED is always a terminating event for push buttons. The EVENT-DATA-1 and EVENT-DATA-2 values are not used.
CMD-DBLCLICK (value 5) Indicates that the user has double-clicked on an item in a list-box or combo-box (returning this event), and that the box does not have a TERMINATION-VALUE or EXCEPTION-VALUE associated with it. This will only occur if the application requests it via the NOTIFY-DBLCLICK list-box and combo-box styles. EVENT-DATA-1 is the index of the selected item in the list (starting at "1"). EVENT-DATA-2 is not used.
CMD-GOTO (value 3) Indicates that the user wants to activate the control that generated the event. This happens when the user clicks on an inactive control with the mouse or types the control's key letter. The application should perform a normal ACCEPT of that control in response. (Failing to ACCEPT a control in response to a CMD-GOTO event for that control is generally not good programming practice, because it prevents the control from behaving normally.) The EVENT-DATA-1 and EVENT-DATA-2 values are not used. Note that the event is not generated if you are ACCEPTing a Screen Section item and the user selects different controls in that screen. The Screen Section handler automatically performs the necessary activation.
The CMD-GOTO event is handled specially in the Screen Section with regard to embedded procedures. This event causes a control's AFTER procedure to execute, instead of its EXCEPTION procedure. We assume that moving between fields with the mouse is a normal event and that field validation and clean-up (normally located in AFTER procedures) should be executed.
CMD-HELP (value 8) This event occurs when help is requested for the control described in EVENT-CONTROL-HANDLE. The control's help ID is in EVENT-DATA-2 (this value is zero if the control does not have a help ID). Because this event is handled by the runtime, it is not a terminating event in your program. However, you can detect this event in the control's event procedure. You can also handle this event in the event procedure itself and prevent the runtime's automatic handling by setting the EVENT-ACTION-CONTINUE element of the EVENT-STATUS data item. For a detailed description of EVENT-ACTION-CONTINUE and other elements of the EVENT-STATUS data item, see section 4.1.3, Book 3, "Reference Manual."
CMD-TABCHANGED (value 7) This event occurs when the user selects a new tab from a TAB control. The value of the selected tab is in EVENT-DATA-1. Unlike most events, this one performs any validation specified in the ACCEPT, and the current field's AFTER procedure is executed rather than its EXCEPTION procedure. This event ensures that the user cannot use the TAB control to leave a form when it contains invalid data. EVENT-DATA-2 is not used.
MSG-AX-EVENT (value 16436) This event occurs when an ActiveX control has "fired" an event. EVENT-DATA-2 contains the ActiveX control's event type. Two pairs of library routines, C$GETEVENTDATA/C$SETEVENTDATA and C$GETEVENTPARAM/C$SETEVENTPARAM are used to get and set he event parameters for the current event. These library routines are described in Appendix I, Book 4, "Appendices."
MSG-BEGIN-DRAG (value 16406) This is generated when the user begins dragging the mouse in a grid control while holding down the left-button. This is generated only for non-header cells. This is generated immediately before the first corresponding MSG-GOTO-CELL-DRAG event. EVENT-DATA-1 contains the column number of the cell where the user began dragging the mouse, and EVENT-DATA-2 contains the row number of that cell. The properties X and Y are set to match these values for the duration of this event. The properties START-X and START-Y are also set to match these values (note that unlike "X" and "Y," these settings are retained after this event finishes).
MSG-BEGIN-ENTRY (value 16392) This event occurs when the user starts modifying a cell in a grid control. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event (i.e., they are set to the cursor's location at entry to the event procedure and restored to their prior values at exit). This allows you to get a "before" image of the cell easily by simply doing an INQUIRE on CELL-DATA.
You can prevent the entry from occurring by setting EVENT-ACTION to EVENT-ACTION-FAIL.
MSG-BITMAP-CLICKED (value 16400) This event occurs when the user left-clicks on a bitmap contained in a grid control. EVENT-DATA-1 contains the column number of the cell clicked, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.
If you set EVENT-ACTION to EVENT-ACTION-FAIL, the normal action of left-clicking in a cell is prevented (i.e., the cursor is not moved to that cell).
MSG-BITMAP-DBLCLICK (value 16401) This event occurs when the user double clicks on a bitmap contained in a grid control. EVENT-DATA-1 contains the column number of the cell double-clicked, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.
If you set EVENT-ACTION to EVENT-ACTION-FAIL, the normal action of double-clicking in a cell is prevented (i.e., the grid does not shift to entry mode for the cell).
MSG-BEGIN-HEADING-DRAG (value 16408) This is generated when the user begins dragging the mouse in a grid control while holding down the left-button. This is generated only for header cells. This is generated immediately before the first corresponding MSG-HEADING-DRAGGED event. EVENT-DATA-1 contains the column number of the cell where the user began dragging the mouse, and EVENT-DATA-2 contains the row number of that cell. The properties X and Y are set to match these values for the duration of this event. The properties START-X and START-Y are also set to match these values (note that unlike "X" and "Y", these settings are retained after this event finishes).
MSG-CANCEL-ENTRY (value 16394) This event occurs when the user leaves entry mode in a grid control by typing the "cancel" key (under Windows, this is the Escape key). The contents of the cell are restored to the cell's contents prior to the start of the entry. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event. This event also occurs in the special case where the user enters spaces (or nothing) into a cell that is in a record past the end of the last record added to the grid. This is to prevent variable-length grids (i.e. NUM-ROWS of "-1") from expanding when the user enters empty data.
MSG-COL-WIDTH-CHANGED (value 16410) This occurs when the user changes the width of a column in a grid control. For this to occur, the grid must have the ADJUSTABLE-COLUMNS style and must have only one row per record. EVENT-DATA-1 contains the column number being changed. EVENT-DATA-2 contains the new width (in characters).
MSG-END-DRAG (value 16407) This event indicates that the user has released the mouse button after dragging the mouse during a normal (non-header) drag operation in a grid control. EVENT-DATA-1 contains the column number of the cell where the user finished dragging the mouse. EVENT-DATA-2 contains that cell's row number. The properties X and Y are set to match these values for the duration of this event.
MSG-END-HEADING-DRAG (value 16409) This event indicates that the user has released the mouse button after dragging the mouse during a header drag operation in a grid control. EVENT-DATA-1 contains the column number of the cell where the user finished dragging the mouse. EVENT-DATA-2 contains that cell's row number. The properties X and Y are set to match these values for the duration of this event.
MSG-FINISH-ENTRY (value 16393) This event occurs when the user finishes editing a cell in a grid control. You can use this opportunity to validate the cell's contents and do any reformatting of the data. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event. This allows you to retrieve the entered data by simply performing an INQUIRE on CELL-DATA. To reformat the entered data, INQUIRE on CELL-DATA, perform the desired formatting, and MODIFY CELL-DATA with the reformatted data. Note that if you INQUIRE directly into a numeric or numeric-edited data item, you get automatic conversion similar to MOVE WITH CONVERSION (with simple truncation on overflow). For more sophisticated testing and reformatting, INQUIRE into an alphanumeric item and examine the data directly.
You can force the user to stay in entry mode on the current cell by setting EVENT-ACTION to EVENT-ACTION-FAIL. This is what you should usually do if the user enters invalid data.
You can prevent the user from entering the cell by setting EVENT-ACTION to EVENT-ACTION-FAIL. If you do this, the cursor remains in its previous cell. You can direct the cursor to a different cell by setting EVENT-ACTION to EVENT-ACTION-FAIL and then modifying CURSOR-X and CURSOR-Y directly.
MSG-GOTO-CELL-DRAG (value 16404) This is generated when the user moves the mouse into a new grid control cell while holding the left-button down. This event occurs only if the user clicks in a non-header cell first. Clicking outside of the grid and then dragging the mouse over the grid has no effect. Clicking in a header cell and then dragging the mouse over the grid generates MSG-HEADING-DRAGGED events instead.
Like most grid events, EVENT-DATA-1 contains the column number of the cell being moved to, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.
The default action taken for this event is to scroll the grid (if needed) and then place the cursor in the dragged-to cell. You can prevent the cursor from being moved by setting EVENT-ACTION to EVENT-ACTION-FAIL (the grid is scrolled regardless).
MSG-GOTO-CELL-MOUSE (value 16396) This is generated any time the user moves the cursor to a new grid control cell using the mouse. This event is identical to MSG-GOTO-CELL except for the use of the mouse instead of the keyboard. One reason you may want to know whether the user is moving to the cell via the mouse or the keyboard is if you are preventing the user from visiting a cell. You may want to leave the cursor in its original location if the user clicks on the cell with the mouse. But if the user types a key, you may want to skip over the field (you can tell which direction to skip by looking at the cell the user is starting from).
For details about the handling of this event, see MSG-GOTO-CELL.
MSG-GRID-RBUTTON-DOWN (value 16426) This event occurs in the grid control when the user depresses the right mouse button. EVENT-DATA-1 is set to the column number of the cell being clicked, EVENT-DATA-2 is set to the row number. If the grid is right-clicked outside of any cells, these values are set to zero. The grid properties X and Y are set to these same values for the duration of this event. If you respond to this event by setting EVENT-ACTION to EVENT-ACTION-COMPLETE, no further processing of this event occurs. Otherwise, the grid acts as if the user pressed the left mouse button.
MSG-GRID-RBUTTON-UP (value 16427) This event occurs when the user releases the right mouse button. The event behaves in the same manner as the MSG-GRID-RBUTTON-DOWN event described above. Once this event finishes processing, any pop-up menu associated with the grid is displayed normally.
One way you can use this event is to select an appropriate pop-up menu depending on the cell clicked. For example, you may want different pop-up menus for the headings and the body of the grid. You can examine the cell clicked in this event and set the appropriate pop-up menu for the control. The selected menu appears after the event has finished.
MSG-HEADING-CLICKED (value 16402) This event occurs when the user left-clicks on a row or column header in a grid control. EVENT-DATA-1 contains the column number of the cell clicked, and EVENT-DATA-2 contains the record number of that cell (one of these will be "1"). For convenience, the properties X and Y are set to match these values for the duration of the event.
MSG-HEADING-DBLCLICK (value 16403) This event occurs when the user double-clicks on a row or column header in a grid control. EVENT-DATA-1 contains the column number of the cell double-clicked, and EVENT-DATA-2 contains the record number of that cell (one of these will be "1"). For convenience, the properties X and Y are set to match these values for the duration of the event.
MSG-HEADING-DRAGGED (value 16405) This event occurs when the user moves the mouse into a grid control header cell while holding the left-button down. This event is generated only when the user first clicks in a header cell. If the user clicks in a header, and then drags the mouse over a non-header cell, MSG-HEADING-DRAGGED is generated and the closest header cell is used. These rules allow the user to be a bit "sloppy" when dragging the mouse.
EVENT-DATA-1 contains the column number of the cell dragged-to, and EVENT-DATA-2 contains the row number (one of these will be "1"). For convenience, the properties X and Y are set to match these values for the duration of the event.
MSG-PAGED-FIRST (value 16423) This event occurs for grids with the PAGED style. It indicates that the user has clicked on the "First Page" button (the same button as the "Previous Record" button with the Shift key held down). The runtime responds to this event by positioning the record pointer at the beginning of the data source. Assuming that the data source is an indexed file, a START statement sets the record pointer so that a READ NEXT would retrieve the first record in the file. If you set EVENT-ACTION to EVENT-ACTION-NORMAL (this is the default), the following occurs after this event has finished:
1. the control is emptied of data, except for any column headers; and
2. the control generates a page worth of MSG-PAGED-NEXT events to fill up the first page of data.
If you opted to fill up the first page itself in response to this event, set EVENT-ACTION to EVENT-ACTION-COMPLETE to inform the grid that it should not generate the MSG-PAGED-NEXT events to fill the first page. If you cannot start at the beginning of the file (because the file is empty), set EVENT-ACTION to EVENT-ACTION-FAIL.
MSG-PAGED-LAST (value 16424) This event occurs for grids with the PAGED style. It indicates that the user has clicked on the "Last Page" button (the "Next Record" button with the Shift key held down). This works in the same manner as the MSG-PAGED-FIRST event described above. You position the data source so that a MSG-PAGED-PREV event would retrieve the last record, and the grid handles the rest. See MSG-PAGED-FIRST and MSG-PAGED-PREV.
MSG-PAGED-NEXT (value 16419) This event occurs for grids with the PAGED style. It indicates that the user has clicked on the "Next Record" button. The expected response from the runtime is to supply the next record after the end of the grid's current data. To do this, add a new record at the end of the grid (using RECORD-TO-ADD). If the data is from an indexed file, the value of EVENT-DATA-2 is the number of READ NEXTs you need to perform to get to the appropriate record. This value is controlled by the property FILE-POS. See the discussion on the FILE-POS property under the grid control for details on how this works. If you cannot supply the next record (because you have reached the end of the file), respond by setting EVENT-ACTION to EVENT-ACTION-FAIL. When you do this, you receive no more MSG-PAGED-NEXT events.
MSG-PAGED-NEXTPAGE (value 16421) This event occurs for grids with the PAGED style. It indicates that the user has clicked on the "Next Page" button. If you do not define a specific action when this event occurs, the grid implements the logic itself by generating a page worth of MSG-PAGED-NEXT events. This is done with the MASS-UPDATE internally set to a non-zero value.
If you want to supply the logic by adding code to handle this event, set EVENT-ACTION to EVENT-ACTION-COMPLETE. This action-status informs the grid that it should not generate the MSG-PAGED-NEXT events because the "Next Page" has already been handled.
MSG-PAGED-PREV (value 16420) This event occurs for grids with the PAGED style. It indicates that the user has clicked the "Previous Record" button. The expected response from the runtime is to supply the record before the first record of the grid's current data. To do this, add a new record at the start of the grid (using RECORD-TO-ADD to add the record and INSERTION-INDEX to position the record before the first row of data, and making sure that the record is not inserted before any column headings in the grid). If the data is from an indexed file, the value in EVENT-DATA-2 is the number of READ PREVIOUS statements you need to perform to get to the appropriate record. This value is controlled by the property FILE-POS. See the discussion about the FILE-POS property under grid control. If you cannot supply the record (because you have reached the beginning of the file), respond by setting EVENT-ACTION to EVENT-ACTION-FAIL. When you do this, you will receive no more MSG-PAGED-PREV events.
MSG-PAGED-PREVPAGE (value 16422) This event occurs for grids with the PAGED style. It indicates that the user has clicked the "Previous Page" button. This works in the same manner as the MSG-PAGED-NEXTPAGE event described above. Although this event may be ignored, you may want to supply a specific action in response to this event. See MSG-PAGED-NEXTPAGE for details.
MSG-SB-NEXT (value 16385) This event occurs when the user clicks on the down/right button in a scroll bar. When this message is sent to the scroll bar's event procedure, the program should respond by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.
MSG-SB-NEXTPAGE (value 16387) This event occurs when the user clicks on the down/right page region in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.
MSG-SB-PREV (value 16386) This event occurs when the user clicks on the up/left button in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.
MSG-SB-PREVPAGE (value 16388) This event occurs when the user clicks on the up/left page region in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.
MSG-SB-THUMB (value 16389) This event occurs when the user repositions the scroll bar's slider, or "thumb." When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position to the value in EVENT-DATA-2. EVENT-DATA-1 is not used.
MSG-SB-THUMBTRACK (value 16390) This event occurs when the user moves a scroll bar's slider that has the TRACK-THUMB style. When this message is sent to the scroll bar's event procedure, the program does not reset the control's position in response. EVENT-DATA-2 contains the new position. EVENT-DATA-1 is not used. This scroll bar message is the only one that should not change the slider's position.
MSG-SPIN-DOWN (value 16417) This event occurs when the user clicks the down arrow of an entry field with the SPINNER style. The program responds to MSG-SPIN-DOWN by decrementing the entry field by a specific value, not necessarily 1. Similar to the MSG-SPIN-UP event described above, if the entry field has the AUTO-SPIN style, you can set the EVENT-ACTION to EVENT-ACTION-FAIL to prevent the control from decrementing the value itself.
MSG-SPIN-UP (value 16416) This event occurs when the user clicks the up arrow of an entry field with the SPINNER style. The program responds to this event by incrementing the value of the entry field. You are not limited to incrementing by one. You may increment the value of the field any way you want by inquiring the field's current value and then modifying it to have the desired value.
If the entry field has the AUTO-SPIN style, you can set EVENT-ACTION to EVENT-ACTION-FAIL in response to MSG-SPIN-UP to prevent the control from incrementing the value itself.
MSG-TV-DBLCLICK (value 16428) This event occurs when the user double-clicks an item in Tree-View control that has no children. Items that have children expand or collapse when double-clicked. The ID of the item clicked is in EVENT-DATA-2.
MSG-TV-EXPANDED (value 16414) This event occurs when an item in a Tree View control has expanded or collapsed. The ID of the parent item is in EVENT-DATA-2. One of the following two flags is in EVENT-DATA-1:
| TVFLAG EXPAND
| Item expanded to show children
|
| TVFLAG COLLAPSE
| Item collapsed to hide children
|
| TVFLAG MOUSE
| New item selected with mouse
|
| TVFLAG KEYBOARD
| New item selected with keyboard
|
| TVFLAG PROGRAM
| Program changed selected item |
MSG-VALIDATE (value 16391) This event occurs immediately after the runtime performs intrinsic validation of a field at data entry (for example, the REQUIRED phrase). Specifically, an MSG-VALIDATE event is generated whenever an activatable control terminates and the termination is not the result of:
1. an event, except for CMD-GOTO, or CMD-TABCHANGED
2. a message, except "status 95"
3. an exception, except for those that also cause movement between fields in a Screen Section
When the above conditions are met, it is a good point in the program to perform other validation of a control's data.
If the EVENT-ACTION element is set to EVENT-ACTION-CONTINUE (value 2), the control remains active so the user can correct any errors. Note that MSG-VALIDATE is not generated for controls with the SELF-ACT style, nor is it sent when the runtime does not normally perform validation (for example, in response to a function key). This message is generated for any control that is activated, even if it does not have a value. Due to the dynamic nature of graphical screens, a user can exit a screen without all the fields being validated, therefore, validation should also be performed after completion of data entry.
MSG-WB-BEFORE-NAVIGATE (value 16429) Occurs when the WEB-BROWSER control is about to navigate to a new URL. The NAVIGATE-URL property is set to the new URL. If you set EVENT-ACTION to EVENT-ACTION-FAIL, navigate will be cancelled.
MSG-WB-DOWNLOAD-BEGIN (value 16431) Occurs when a navigation operation is beginning, shortly after the BeforeNavigate event.
MSG-WB-DOWNLOAD-COMPLETE (value 16432) Occurs when a navigation operation is finished.
MSG-WB-NAVIGATE-COMPLETE (value 16430) Occurs after the browser has navigated to a new URL. The final URL is stored in the VALUE property.
MSG-WB-PROGRESS-CHANGE (value 16433) Occurs when the progress of a download is updated. The PROGRESS property is set to the current progress value. The MAX-PROGRESS property is set to maximum progress value
MSG-WB-STATUS-TEXT-CHANGE (value 16434) Occurs when the status bar text has changed. The STATUS-TEXT property is set to the new status text.
MSG-WB-TITLE-CHANGE (value 16435) Occurs when the title of a document in the WEB-BROWSER control becomes available or changes. The TITLE property is set to the new title
NTF-CHANGED (value 4100) Indicates that the value of an entry field may have been changed by the user. This occurs only for entry fields that have the NOTIFY-CHANGE style. EVENT-DATA-1 is the current position of the cursor in the entry field (starting at "1"). EVENT-DATA-2 is not used.
NTF-PL-FIRST (value 4105) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll to the top of the list. The normal response is to add the first "n" records to the list where "n" is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-LAST (value 4106) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll to the bottom of the list. The normal response is to add the last "n" records to the list where "n" is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-NEXT (value 4101) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll the list box one record in the downward direction. The normal response to this message is to add the next record in the list to the list box. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-NEXTPAGE (value 4103) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll the list box one page in the downward direction. The normal response is to add the next "n" records to the list box where "n" is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-PREV (value 4102) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll the list box one record in the upward direction. The normal response to this message is to add the previous record in the list to the top of the list box. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-PREVPAGE (value 4104) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll the list box one page in the upward direction. The normal response is to add the previous "n" records to the top of the list box, where "n" is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.
NTF-PL-SEARCH (value 4107) This event is generated only by list boxes with the PAGED style. It indicates that the user wants to scroll to the page that contains the text he or she has entered. The normal response is to locate the closest matching record and then to add a page of records to the list box, starting with the record found. EVENT-DATA-1 contains the length of the search text. EVENT-DATA-2 is not used. To determine the search text entered, use the INQUIRE verb on the SEARCH-TEXT property of the list box.
NTF-SELCHANGE (value 4099) Indicates that the user has selected a new item in a list box or in the list-box of a combo-box. This will only occur if the application requests it via the NOTIFY-SELCHANGE list-box and combo-box styles. EVENT-DATA-1 is the index of the selected item in the list (starting at "1"). EVENT-DATA-2 is not used.