Interpreting Grid Notify Events: GML.NOTIFY%
Through the use of the GML_TPL$ template, GML procedures are used to initiate changes to controls within a specific grid set. When a grid control notify event occurs (event code of N with an object type of 107) , program GML_M manages the event by performing specific operations based on the event code number.
Certain events, such as event code 22 (TABLEUPDATE), are processed by program GML_M in a manner that do not require processing by the application. Other events, such as event code 18 (RCLICKED), are pre-processed by program GML_M and then passed to the application for additional optional processing. The determination of which grid notify event to act upon, and what type of additional processing to apply is application specific.
When a grid event is pre-processed by program GML_M, template GML_TPL$ is initialized and then loaded with the row data that corresponds to the grid row that was the source of the event. In addition, other variables within the GML_TPL$ template are updated with supplementary information that relates to the specific event. In certain cases several different notify events are combined into one GML.NOTIFY% value. The purpose of pre-processing the event is to prepare the GML_TPL$ template in a manner that allows the template to be executed with a GML procedure without requiring additional template preparation.
Other events, such as event code 2 (COLCHANGE), are considered by program GML_M as advisory events. In these cases, program GML_M initializes template GML_TPL$, but the template remains in the initialized state as indicated by the GML_TPL.ROW_N% variable containing a value of 0.
It should be noted that program GML_M uses the information contained in the event notice template to manage events through the use of the GML.NOTIFY% variable and associated GML_TPL$ template. The original information contained in the notice template is not changed by the GML. The application can use either the notice template event information, GML.NOTIFY%, or both to act upon grid events.
Program GML_M uses GML$ template variable GML.NOTIFY% to notify the application that an event has occurred. For all pre-processed events the GML_TPL$ template contains the following information, which is similar to using the FETCH procedure to obtain the row data:
|
Variable Name |
Contents |
|
GML_TPL.ROW_N% |
Event row number. |
|
GML_TPL.COL_N% |
Event column number (when applicable). |
|
GML_TPL.COL$[c] |
Cell text. |
|
GML_TPL.REL$[c] |
Related text. |
|
GML_TPL.T_COLOR$[c] |
Cell column text color. |
|
GML_TPL.B_COLOR$[c] |
Cell background color. |
|
GML_TPL.STYLE%[c] |
Cell style. |
|
GML_TPL.ALIGN%[c] |
Cell alignment. |
|
GML_TPL.IMAGE%[c] |
Index # of image displayed within the cell. |
|
GML_TPL.E_MODE%[c] |
Cell editable mode. |
|
GML_TPL.ROW_STAT% |
Value of 1 if all cells within the row are empty, or 0 If all cells are not empty. |
Other variables within the GML_TPL$ template contain supplementary values based on the specific event codes, and are as follows:
GML.NOTIFY% 6 - Special Key Pressed When Editing A Cell
|
GML_TPL.TEXT$ |
contains the edit control text. |
|
GML_TPL.FLAG% |
contains a value that corresponds to the special key that was pressed. The values are as follows |
|
1 |
Enter |
|
2 |
Tab |
|
3 |
Shift + Tab |
|
4 |
<Up Arrow> |
|
5 |
<Down Arrow> |
|
6 |
<Page Up> |
|
7 |
<Page Down> |
|
8 |
Esc |
|
11 |
F1 |
|
12 |
F2 |
|
13 |
F3 |
|
14 |
F4 |
|
15 |
F5 |
|
16 |
F6 |
|
17 |
F7 |
|
18 |
F8 |
|
19 |
F9 |
GML.NOTIFY% 9 :Start Edit Request:
|
GML_TPL.FLAG% = 3 |
Start edit request initiated by mouse double click. |
|
GML_TPL.FLAG% = 9 |
Start edit request initiated by pressing the enter key. |
|
GML_TPL.FLAG% = 12 |
Start edit request initiated by a key press, with the ASCII value of that key contained in template variable GML_TPL.OPTION%. |
GML.NOTIFY% 12 :Keyboard Key:
If the escape key was pressed, GML_TPL.FLAG% will contain a 27; GML_DEF_FLAG% will contain a 0 If the key was pressed when the cell was not in edit mode, or a 1 if the key was pressed when the cell was being edited.
If the delete key was pressed, GML_TPL.FLAG% will contain a 127.
GML.NOTIFY% 14 :Left Click:
GML_TPL.FLAG% contains a 1 when the mouse button is pressed, and a 0 when released.
GML.NOTIFY% 15 :Left Click (Current Cell):
If the Control and /or Shift keys are pressed when the mouse button is clicked, GML_TPL.FLAG% will contain one of the following values:
|
GML_TPL.FLAG% = 1 |
Control key pressed. |
|
GML_TPL.FLAG% = 2 |
Shift key pressed. |
|
GML_TPL.FLAG% = 3 |
Control and shift key pressed. |
GML.NOTIFY% 18 :Right Click:
GML_TPL.FLAG% contains a 1 when the mouse button is pressed, and a 0 when released.
GML.NOTIFY% 19 :Row Change:
GML_TPL.FLAG% contains the row number prior to the row change.
Example
Interpreting GML.NOTIFY% = 9 / GML_TPL.FLAG% = 3 Start Cell Edit:
In this example, the mouse was double left clicked on a cell located at row 2, column 4 in the main grid of grid set 1. The GML_TPL$ template has been prepared by program GML_M, and also contains the current row and attribute data. In this case, the pre-processing has performed the equivalent of the following:
GML.SET%=1
CALL "GML::TPL_PREP"
GML_TPL.ROW_N%=2
GML_TPL.COL_N%=4
CALL"GML::FETCH"
The application has been programmed to interpret this event as a start edit request. Since the pre-processing performed by program GML_M has prepared the GML_TPL$ template, it is passed directly to program GML with a call to the START_EDIT procedure:
IF EVENT.OBJTYPE%=107 THEN IF EVENT.CODE$="N"
THEN GOSUB GRID_MANAGER
.
GRID_MANAGER:
CALL "GML_M",SYSGUI,EVENT$,NOTICE$,GML_SET$,GML_TPL$,GML$,
GML_GM$[ALL],GML_GC$[ALL],GML_GR$[ALL]
SWITCH GML.NOTIFY%
.
CASE 9
SWITCH GML_TPL.FLAG%
.
CASE
3
CALL
"GML::START_EDIT"
BREAK
.
SWEND
.
SWEND
If the application was programmed to initiate the start edit in response to a mouse double click, pressing the enter key, or a key press on a cell, the logic would appear as follows.
SWITCH GML.NOTIFY%
.
CASE 9
SWITCH GML_TPL.FLAG%
.
CASE
3
CASE
9
CASE
12
CALL
"GML::START_EDIT"
BREAK
.
SWEND
.
SWEND