Event enable clause

event_enable = flags

Applicable to:

Applicable to: windows, buttons, graphics, listboxes, OLE controls, static text, tables, textboxes

DEFAULT

The standard events for the object type.

The events which are to be sent to a window or window control may be specified by means of the event_enable = clause. It consists of a list of flags which list the events to be sent to the object. The flags are the event codes required. Any combination of flags may be used, and the flags may appear in any order.

If the clause is omitted, the standard events for the object type are sent. These are listed under the event = clause for each object in the section on that object (Button events and event functions, Textbox events and event functions, etc). If an event is not standard, this is stated.

If more than one flag is required, they must be separated by the character |, as shown in this example:

event_enable = EV_DEFAULT | EV_KEYSTROKE

Note the following general event codes:

EV_ALL

Requests all events.

EV_DEFAULT

Requests the default events, i.e. those sent if there is no event_enable clause defined.

EV_KEYSTROKE

This event is generated when a keystroke is typed while the object has focus. It is not generated by default; it must always be specifically requested by means of the event_enable = clause in the window or window control definition.

The event function is called as follows:

func_id(EV_KEYSTROKE, object_id, keycode, row)

The keycode value is the same as that returned by the keycode(0) function; negative for a special key (a key defined in Section 5 of the terminal parameter file), otherwise the ASCII number of the character typed.

The row contains the current row number if the keystroke occurs inside a textbox. Otherwise it is zero.

If the object is an editable table, then from V. 5.1 onwards the function is called as follows:

func_id(EV_KEYSTROKE, table_id, line, column, keycode)

See Editable tables; Table events and functions.

EV_KEYSTROKE may be enabled for a window or for a control. Note that if a window has keystroke events enabled, the window’s event function is called for every keystroke in that window, unless the keystroke event is more specifically trapped by a control. This may cause considerable overheads.

Even when enabled for a specific control, this event should be used sparingly and the event function should execute quickly; otherwise the response to keystrokes will slow down.

If the control is a textbox and the event function transfers focus to a new control, any new content that was typed into the textbox is not saved unless the save_text command is used within the event function.

EXAMPLE

!function MyEvent(EventCode, Object, KeyCode) {
     if (EventCode = EV_KEYSTROKE) {
          switch (KeyCode) {
               case = -F4:
                    code for F4 key
                    break
               case = -F5:
                    code for F5 key
                    break
          }
     }
}

EV_MOUSE_OVER

If this event is enabled for a window or control, and the program is in a dialog, the object receives a stream of EV_MOUSE_OVER events as the mouse passes over it. EV_MOUSE_OVER is not generated by default, and must be specifically requested by means of the event_enable = clause in the window or window control definition.

The event function is called as follows:

func_id(EV_MOUSE_OVER, object_id, xctrl, yctrl, xwin, ywin, virtkey)

func_id(EV_MOUSE_OVER, object_id, line, column, xctrl, yctrl, xwin, ywin, virtkey) (tables only)

The xctrl and yctrl arguments contain the x and y position in pixels, relative to the control.

The xwin and ywin arguments contain the x and y position relative to the control’s effective parent window. The values are in pixels or characters, depending on the program grid type. See Pixel and character positioning. The effective parent is the highest window in the parent window chain that has no further parent, or has the window style WS_OWNED. See Hierarchy of windows; Window parent clause.

The virtkey argument is a virtual key code that indicates the state of mouse buttons, the shift key and the control key. A set of definitions for key and mouse states is provided in sculptor.h with the prefix MK_. These can be tested by means of the & operator. e.g.:

if (VirtKeyCode & MK_LBUTTON)

When this event is are generated for a table, additional arguments are sent to indicate the line and column. See Table events and functions.

EV_RIGHT_MOUSE_UP
EV_RIGHT_MOUSE_DOWN

These events are generated when the right mouse button is clicked down (EV_RIGHT_MOUSE_DOWN) or released (EV_RIGHT_MOVE_UP) while the object has focus. They may be enabled for a window or for a control. They is not generated by default; they must always be specifically requested by means of the event_enable = clause in the window or window control definition.

The event function is called as follows:

func_id(EV_RIGHT_MOUSE_UP | EV_RIGHT_MOUSE_DOWN, object_id, xctrl, yctrl, xwin, ywin)

func_id(EV_RIGHT_MOUSE_UP | EV_RIGHT_MOUSE_DOWN, line, column, object_id, xctrl, yctrl, xwin, ywin) (tables only)

The xctrl and yctrl arguments contain the x and y position of the mouse click in pixels, relative to the object clicked on. If the object was a top-level window or a window with style WS_OWNED, the xctrl and yctrl arguments are identical to the xwin and ywin arguments.

The xwin and ywin arguments contain the x and y position of the mouse relative to the control’s effective, parent window. The values are in pixels or characters, depending on the program grid type. See Pixel and character positioning. The effective parent is the highest window in the parent window chain that has no further parent, or that has the window style WS_OWNED. A common use for EV_RIGHT_MOUSE_UP is to open a popup menu; the effective parent is the window in which the menu should be opened. See Hierarchy of windows; Window parent clause; Popup menus.

Note that the EV_RIGHT_MOUSE_UP event was previously called EV_RIGHT_MOUSE. The two events are identical, but EV_RIGHT_MOUSE should be treated as obsolescent.

When this event is are generated for a table, additional arguments are sent to indicate the line and column. See Table events and functions.

Further events may be added in the future.


Modifying enabled events at run time

The events which are enabled for an object can be removed and added at run time. As several events may be enabled at any time, the | (bitwise or) and &~ (bitwise and not) operators are used to add and remove them. Changes to an object’s enabled events should therefore use the constructions:

Adding an event
object_id->event_enable = object_id->event_enable | flag [ | flag] …
Removing an event
object_id->event_enable = object_id->event_enable &~ ( flag [ | flag] …)

The changes are effected immediately; the object need not be re-created.

RELATED TOPICS

Modifying a property at run time


Testing if an event is enabled at run time

Use the following form to test if an event is enabled for an object at run time:

object_id->event_enable &

The bitwise and operator (&) is used rather than the equals to operator (=) because several events may be enabled at any one time. The clause evaluates to non-zero (TRUE) if the object receives the event code, otherwise zero (FALSE).

EXAMPLE

switch(wintask->event_enable & EV_MINIMISED) {
     case !=0:
          statements to be executed if the event is enabled
          break
     default:
          statements to be executed if the event is not enabled
          break
}

RELATED TOPICS

Retrieving a property at run time


RELATED TOPICS

Property clauses

Event functions