Creating and Using a New Event Table

The following code example shows the six steps to build and use an event table to convert an event code to an action. Note that this is not a complete program; code for the four different user functions is not included, and the data structure my_datastruct is never initialized.

#include <vv_key.h>

#include <vv_main.h>

/* Event function prototypes

*/

int usr_help(PTR, EVENTPTR);    

int usr_quit(PTR, EVENTPTR);

int usr_save(PTR, EVENTPTR);

int usr_print(PTR, EVENTPTR);

struct my_data

/* Data structure passed to event

*/

{

/* functions

*/

    char name[40];

    char phone[14];

} my_datastruct;

int main(void);

{

    ETPTR etp;

/* Pointer to event table

*/

    PTR datap;

/* Data to pass to functions

*/

    EVENT event;    

/* Pointer to event structure

*/

    int done = FALSE;

    vv_init();

/* Initialize Vermont Views

*/

    vs_clr();

/* Clear screen

*/

/* Create example key table

*/

    etp = et_def(4, NULLFP);

/* Assign event functions to event codes 

*/

    et_rplevnt(KEY_F1, usr_help, etp);

    et_rplevnt(KEY_F2, usr_quit, etp);

    et_rplevnt(KEY_F3, usr_save, etp);

    et_rplevnt(KEY_F4, usr_print, etp);

    datap = &my_datastruct;

/* Initialize datap

*/

/* Process one event 

*/

    while (! done)

    {

        if (evnt_get(&event))

        {

            et_proc(&event, etp, datap);

            done = TRUE;

        }

    }

    et_free(etp);

/* Free event table

*/

    vv_exit();

/* Exit Vermont Views

*/

    return(0);

}

The steps are as follows:

Step 1: Declare a pointer to an event table and an event structure.

A pointer to an event table is of type ETPTR. An event table is an array of individual event table structures, each containing an event code-function pair.

An event structure is of type EVENT. An event structure contains information about the current event.

Step 2: Create an empty event table with et_def().

The define event table function, et_def(), allocates memory for an event table and initializes the values in the table. The call for et_def() is as follows:

ETPTR et_def(size, default_fp);

int size;

/* Number of entries in table

*/

KEYFP default_fp;

/* Pointer to default function

*/

This function creates an event table with entries enough for the specified number of event codes. Specify as the default function the function that you want called if the event code to be processed cannot be found in the event table.

The call to et_def() in the code example creates an event table with 4 empty spaces. An end-of-table marker is placed after the specified number of spaces. The end-of-table marker contains a NULLFP. The example event table in the code example will look something like this:

{0, NULLFP},

{0, NULLFP},

{0, NULLFP},

{0, NULLFP},

{ET_END, NULLFP}

Step 3: Specify the event table entries with et_rplevnt().

Use et_rplevnt() to fill the event table with event code-event function pairs.

From the code example, the event table would look like this after the event table entries are specified with the four et_rplevnt() calls:

{KEY_F1, usr_help},

{KEY_F2, usr_quit},

{KEY_F3, usr_save},

{KEY_F4, usr_print},

{ET_END, NULLFP}

Step 4: Read an event with evnt_get().

Get the next event to process by reading the event queue or keyboard buffer with evnt_get(). evnt_get() returns the next event from the event queue, if an event is present, or reads the keyboard buffer and creates an event of type AC_KEYPRESS, if there is a keystroke available.

Normally, reading the event and processing the event code is in an event processing loop. The event function should set some value to indicate that event processing should stop. In our system, the event function sets an action code, which is a member of the structure whose pointer was passed to the event function. The calling routine then checks that member of the structure and acts appropriately.

Step 5: Process the event with et_proc().

To process the user's keystroke, call the process event table function, et_proc():

int et_proc(eventp, etp, datap);

EVENTPTR eventp;

/* Event code to process

*/

ETPTR etp;

/* Event table to search

*/

PTR datap;

/* Pointer to data to pass to event function

*/

This function searches the specified event table for the event code, which is contained in the event structure member type. One of three things may happen:

(1) The event code is found. In this case, the user data pointer and the event pointer are passed to the event function associated with the event code and the event function is invoked. et_proc() returns the value returned by the event function.

(2) The event code is not found, and the event table contains a default function. In this case, the default function is called. The default event function is passed the event pointer and the user data pointer in the et_proc() call. et_proc() returns the value returned by the default function.

(3) The event code is not found, and the event table does not contain a default function. In this case, et_proc() returns a -1.

Step 6: Free the event table with et_free()

To free the memory allocated for the event table, call the free event table function, et_free():

void et_free(etp);

ETPTR etp;            /* Pointer to event table to free            */

The function et_free() frees the memory allocated for the event table. You should call this function only for event tables that have been allocated with et_def().