Table events and functions¶
Contents
Event function¶
event = func_id
The name of the function to be called when an event occurs for the table.
The arguments sent to the function vary according to the event code. The line and column both count from 1.
func_id(event_code, table_id, line) |
|
EV_CREATE |
The table has just been created. |
EV_DESTROY |
The table has just been destroyed. |
EV_GAIN_FOCUS |
The table has gained focus. |
EV_LOSE_FOCUS |
The table has lost focus. |
EV_UNSELALL |
All currently selected lines in the table have been deselected. This is particularly useful with tables that can have multiple selections ( edit mode EM_MULTIPLE). When a single line is selected, EV_UNSELALL is sent, informing the program that all previously selected lines have been unselected. EV_SELECT is then sent for the newly selected line. |
A keystroke is typed while the table has focus. From V 5.1 onwards, a new syntax is used when this event is generated for an editable table. See below. |
|
EV_DOUBLE_CLICK |
A double mouse click on the table. This event is generated even if the table has the mode flag EM_READONLY set. See Table edit mode. |
EV_SUPPLY_COLOUR |
Generated when a table is created or scrolled, to set foreground and background colours for cells in the line. See Table cell colour. This event can also be used to modify data values that are about to be displayed. It is generated after Sculptor has placed values in the display object, but before these values have been transferred to the actual visual display. The EV_SUPPLY_COLOUR event can, therefore, be used to modify these values or even to set values that need to be calculated. For example, a table might have a “Total” column, the value of which was not directly available from the source object but which needed to be calculated using the value of two or more values in the source object. This event function would be a suitable place to perform the calculation and assign the value. |
func_id(event_code, table_id, line, display object) |
|
EV_SUPPLY_VALUE |
Generated when a table whose source object is a function is created or scrolled, so that the event function can assign values to the cells in the line. |
func_id(event_code, table_id, line, state, column) |
|
EV_SELECT |
The user has selected or deselected a line in the table. The state argument is set to zero if the line has been deselected, or to non-zero if it has been selected. The column argument means that the exact cell clicked on can be identified if required. Note that if the cell is editable the column can also be obtained from the EV_FOCUS_CELL event. See also EV_MULTIPLE_SELECT below. If the edit mode flag EM_SYNC_SOURCE is set, the source object is synchronised to the display object before this event is sent. |
func_id(event_code, table_id, line, column, type) |
|
EV_FOCUS_CELL |
The user has clicked on a cell that can be edited, or the cell has been given focus by the table_focus_cell() function. The line and column are the co-ordinates of the cell. The type is the current edit type of the column. Edit types are set by assignment to the cell property record and have the prefix TCT_. The EV_FOCUS_CELL event is not called if the cell is in a column that has the default edit type TCT_READONLY, or if the edit mode flag EM_READONLY is set. If the edit type is TCT_DYNAMIC, the event function must set the required edit type in the cell property record before returning. The function must return OKAY to give focus to the cell or ERROR to refuse it. |
func_id(event_code, table_id, line, column) |
|
EV_NOFOCUS_CELL |
This event is generated when a cell loses focus. A likely use for the event is to restore the edit type TCT_DYNAMIC to a column, by assignment to the appropriate element of the cell property record. The return value from this event function should be OKAY (which is the default). If the edit mode flag EM_SYNC_SOURCE is set, the source object is synchronised to the display object before this event is sent. |
func_id(event_code, table_id, line, column, data) |
|
EV_VALIDATE |
This event is called when a cell is about to lose focus, before the EV_NOFOCUS_CELL event. The data argument contains the value in the cell, which may have changed. The function should return OKAY if the value is valid, otherwise ERROR. If ERROR is returned, focus is locked on the cell and the user must enter another value. If the edit mode flag EM_SYNC_SOURCE is set, the source object is synchronised to the display object before this event is sent. |
func_id(event_code, table_id, line, column, keycode) |
|
A keystroke is typed while the table has focus (editable tables only). This syntax was introduced in V 5.1 for consistency with other editable table events. It is only used if the program has been compiled with scc version 5.1 or later, and the interpreter is also version 5.1 or later. Otherwise the syntax: func_id(event_code, table_id, line) is used. EV_KEYSTROKE is not generated by default and must be explicitly requested using the event_enable clause. |
|
func_id(event_code, table_id, line, column, xctrl, yctrl, xwin, ywin, virtkey) |
|
The mouse has passed over the table while the program is in a dialog. EV_MOUSE_OVER is not generated by default and must be explicitly requested using the event_enable clause. The xctrl, yctrl, xwin and ywin and virtkey arguments are the same as for other controls. The line indicates the line number clicked. 0 indicates a click on the headings, -1 that the click was below the last line. The column indicates the column number clicked. 0 indicates that the click was to the left of the first column, -1 that it was to the right of the last. |
|
func_id(event_code, table_id, line, column, xctrl, yctrl, xwin, ywin) |
|
The user has clicked the right mouse button down over the table (EV_RIGHT_MOUSE_DOWN) or released the right mouse button over the table (EV_RIGHT_MOUSE_UP). These events are not generated by default and must be explicitly requested using the event_enable clause. The xctrl, yctrl, xwin and ywin arguments are the same as for other controls. The line indicates the line number clicked. 0 indicates a click on the headings, -1 that the click was below the last line. The column indicates the column number clicked. 0 indicates that the click was to the left of the first column, -1 that it was to the right of the last. |
|
func_id(event_code, table_id, firstline, state, lastline) |
|
EV_MULTIPLE_SELECT |
The user has selected a block of lines by means of SHIFT-CLICK. The table must be multiple selection - that is, it must have the edit mode flag EM_MULTIPLE assigned. firstline and lastline contain the numbers of the first and last lines in the block. If the table source object is a file, firstline and lastline are approximate and the difference between these line numbers is not guaranteed to be the number of records in the block. To count the number of records accurately, it is necessary to call the table_first_selected_key() function, followed by calls to table_next_selected_key(). If the source object is anything other than a file, firstline and lastline are accurate. This event was introduced in Sculptor 5.3. Before that, the event EV_SELECT was sent separately for each selected line. This, however, caused problems, since only 255 lines could be processed, and sending so many events degraded performance. Sculptor recommends that programs using tables with EM_MULTIPLE be modified to make use of EV_MULTIPLE_SELECT, before being recompiled with the latest version of scc. If this is not practical, add the !compat evselect declaration to the program, or, if all programs are to retain backward compatibility, to a common include file such as local.h. EV_SELECT is still sent when a single line is selected. |
New events may be added in the future. See Event functions.
NOTES
Interactive code such as the prompt command should not be used in an EV_DOUBLE_CLICK event function. If a prompt is placed in an EV_SELECT function, it is not possible to generate a double click event.
A function may also be used as the source object of the table.
Help function¶
help = func_id
The table’s help function. The function is called as follows:
func_id(EV_HELP, table_id)
See Help functions.
Column heading event function¶
heading_event = &func_id
A table column heading event function is defined in the table’s cell property record, which allows properties to be set for each column in the table. If the heading_type for a column is set to TCT_BUTTON, the column heading is a push button with the heading text as its label. In this case, the cell property record’s heading_event field may be used to set an event function for the heading control. The function is called as follows:
func_id(event_code, table_id, line, column)
Currently, the only possible value for event_code is EV_BUTTON_CLICKED. However, the function should test the event code, since new events may be added in the future. The column argument is the number of the column. The line argument is set to 0 (zero).
The only other possible value for heading_type is 0, the default. This produces a standard text heading. In this case, no events are generated for the column heading.
Event enable function¶
event_enable = flags
This clause is used to select the event codes which are to be enabled for the table.
Default: The standard set of events listed under the event = clause above.
RELATED TOPICS |