Inserting, Changing, and Deleting Event Code-Event Function Pairs

The function used to modify an event table during run-time is the event table replace event function, et_rplevnt(). The calling sequence for this function is as follows:

EVENTFP et_rplevnt(eventcode, event_fp, etp)

USHORT eventcode;

/* Event code to add or modify

*/

EVENTFP event_fp;

/* Pointer to event function to install

*/

ETPTR etp;

/* Pointer to event table 

*/

The event code specified in the call is searched for in the event table and, if found, assigned the new function. If it is not found, the event code and the specified function are placed in an empty entry in the event table. (It is a development error if you attempt to insert an event code-event function pair in a full event table.)

et_rplevnt() returns a pointer to the function currently installed for the event code, or a NULLFP if no function is installed.

When you are writing your event functions, you must decide what event will trigger your function. Most event functions are triggered by the user pressing a particular key. To attach your event function to a particular key, use the keycode for eventcode. For example, to attach a function my_func to KEY_F5 in the event table FMETP, the call to et_rplevnt() would be:

et_rplevnt(KEY_F5, my_func, FMETP);

You can also attach event functions to other types of events. To do this, write the event function and install it in the appropriate event table as described above. Then, if the event code is not a keycode, you must ensure that the event is posted from one of your functions. The function that posts the event can be an interrupt function, another event function attached to a keycode, or a user function such as a begin-field or end-field function. For more information about posting events, see Chapter 42, "Posting Events From Your Code."

Inserting an Event Code-Event Function Pair

To insert an event code-event function pair into an event table, you specify the desired event code, event function and event table in the call to et_rplevnt(). If an event function already exists for that event code in that table, it will be replaced. For example, to place KEY_PGDN and KEY_PGUP in the DRAGETP event table with their own functions, call:

et_rplevnt(KEY_PGDN, my_pgdn_func, DRAGETP);

et_rplevnt(KEY_PGUP, my_pgup_func, DRAGETP);

Changing the Function Attached to an Event Code

To change the function attached to an event code, you again use the function et_rplevnt(). Specify the event code you wish to change, the new function to associate with this event code, and the event table. et_rplevnt() returns a pointer to the function that was previously associated with this event code. If you want to restore that function in the event table later, you should save this pointer.

For example, to change the function associated with KEY_RIGHT in the DRAGETP event table, and then later restore the existing function, make these calls:

EVENTFP former_eventfp;

/* Change assignment for KEY_RIGHT, saving old value    */

former_eventfp = et_rplevnt(KEY_RIGHT, new_function, DRAGETP);

...

...

/* Restore old value for KEY_RIGHT            */

et_rplevnt(KEY_RIGHT, former_eventfp, DRAGETP);

Deleting an Event Code-Event Function Pair From an Event Table

To delete an event code-function pair from an event table, call et_rplevnt(), and specify a NULLFP as the function. The call to delete an event code and its associated function from an event table would be as follows:

et_rplevnt(eventcode, NULLFP, ETP);

where eventcode is the event code to delete from event table ETP. A pointer to the function previously assigned to that event code is returned. If there was no event function assigned to the specified event code, a NULLFP is returned.

For instance, to delete the event code KEY_F10 from the drag event table, call:

EVENTFP former_fp;

former_fp = et_rplevnt(KEY_F10, NULLFP, DRAGETP);

former_fp now points to the function that was previously associated with KEY_F10.

Note: This does not create an empty entry in the event table. The event table still contains an entry for KEY_F10; the event function for that event code is NULLFP. To add empty entries to an event table, see the section "Adding Empty Entries to Event Tables," earlier in this chapter.