As described in The wvEvent( ) Routine, you can generate user events with the wvEvent( ) routine.¹ This user event can contain a buffer of data that is logged when the event occurs. You can customize the Show Event dialog box so that it displays this buffer in a format that is appropriate for your needs.

Suppose you have the following structure that you would like to place in a particular user-defined event buffer:

#include "wvLib.h" 
#define INFORMATION_EVENT 10      /* user-defined event #10 */ 
 
typedef struct 
    { 
    char     nodeName [4]; 
    int      nodeValue; 
    } EVENT_INFO;

The following example shows how you might use this structure in a call to wvEvent( ):

void postEvent 
    ( 
    char *     name, 
    int        value 
    ) 
 
    { 
    EVENT_INFO eventInfo; 
 
    strncpy (eventInfo.nodeName, name, 4); 
    eventInfo.nodeValue = value; 
 
    wvEvent (INFORMATION_EVENT, (char *) &eventInfo,  
            sizeof (eventInfo)); 
    }

If postEvent( ) is called from an application while WindView is running, you will see the icon for user10 in the event log. If you open the Show Event dialog box on that event, you might see something like the left-hand side of Figure F-1. 

Figure F-1:  User Event 10

From this, you can see which event it was (number 10), and when and in what context it occurred.

However, to see the data that was posted with the event, you must define an element of the Tcl array wvUserEventFormat to specify how to unpack and display the buffer foruser10. This Tcl definition must be placed in the Tcl initialization file eventbase.tcl introduced in F.2 Customizing WindView Tcl Initialization Files. The array index into wvUserEventFormat must match the event number; thus, for user event n, you must define wvUserEventFormat(n).

The following is an example Tcl specification for the event data just described:

set wvUsrEventFormat(10) { 
    {"node name" string<4>}  
    {"node value" int} 
}

The example specifies a list of (name, type) pairs for user10. This list constitutes a Tcl representation of the EVENT_INFO structure shown on the previous page: the field "node name" corresponds to "char nodeName [4]", and the field "node value" corresponds to "int nodeValue".

You can use anything for the name of a field (if it contains special characters or spaces, it should be quoted as shown). The types shown in Table F-1 can be used.

Table F-1:  Field Types for wvUserEventFormat 

Type Label		Description
string<k>		String of length no greater than k, where k is an integer. If the string contains a null character, the string is considered to end there, although any remaining bytes are discarded until exactly k characters have been consumed from the user event buffer.
string		String of indeterminate length. Bytes from the buffer are treated as part of the string until a null character is reached or the buffer is exhausted.
int		Signed, 4-byte integer. The value is displayed in decimal.
uint		Unsigned, 4-byte integer. The value is displayed in hexadecimal.
short		Signed, 2-byte integer. The value is displayed in decimal.
ushort		Unsigned, 2-byte integer. The value is displayed in hexadecimal.
char		Character. The value is displayed as a character enclosed in single quotes; for example, 'x'.
byte		Signed, 1-byte integer. The value is displayed in decimal.
ubyte		Unsigned, 1-byte integer. The value is displayed in hexadecimal.

To see the effect of a new user-event specification, you must restart WindView so that it reads the eventbase.tcl initialization file.

After wvUsrEventFormat(10) is defined as shown above, an event generated by a call to postEvent( ) with arguments "RUN" and 99 looks like the right-hand side of Figure F-1 when displayed in the Show Event dialog box.

Note that the Tcl specification does not imply an alignment for the internal members of the structure. WindView regards the user event buffer as a stream of bytes, and each item in the list consumes a certain number of those bytes. If the structure you send with wvEvent( ) has alignment "holes," you must create a wvUsrEventFormat list with the holes made explicit. The following example shows a C structure that is likely to produce an alignment "hole":

struct  
    { 
    char c; 
    short n1; 
    }

The following Tcl definition shows how to allow for the "hole" while unpacking:

set wvUsrEventFormat(11) {  
    {c char} 
    {(padding) ubyte} 
    {n1 short} 
}

In this example, a padding byte is inserted. This is because in the structure above, a typical C compiler inserts one byte of padding between the char value and the short value. (The exact amount of padding added depends on both the compiler, and the target architecture you are using.)

1:  You can also set eventpoints with the e( ) routine; see The e( ) Routine.