About cursors and GrKeys

* Graphics cursors

The library provides support for the creation and usage of an unlimited number of graphics cursors. An application can use these cursors for any purpose. Cursors always save the area they occupy before they are drawn. When moved or erased they restore this area. As a general rule of thumb, an application should erase a cursor before making changes to an area it occupies and redraw the cursor after finishing the drawing. Cursors are created with the 'GrBuildCursor' function:

GrCursor *GrBuildCursor(char far *pixels,int pitch,int w,int h, int xo,int yo,GrColorTableP c); GrCursor *GrBuildCursor(char *data,int w,int h,int xo,int yo,GrColorTableP c);

The 'pixels', 'w' (=width), 'h' (=height) and 'c' (= color table) arguments are similar to the arguments of the pixmap building library function 'GrBuildPixmap' (see that paragraph for a more detailed explanation.), but with two differences. First, is not assumed that the pixels data is 'w' x 'h' sized, the 'pitch'argument set the offset between rows. Second, the pixmap data is interpreted slightly differently, any pixel with value zero is taken as a "transparent" pixel, i.e. the background will show through the cursor pattern at that pixel. A pixmap data byte with value = 1 will refer to the first color in the table, and so on.

The 'xo' (= X offset) and 'yo' (= Y offset) arguments specify the position (from the top left corner of the cursor pattern) of the cursor's "hot point".

The 'GrCursor' data structure:

typedef struct _GR_cursor { struct _GR_context work; /* work areas (4) */ int xcord,ycord; /* cursor position on screen */ int xsize,ysize; /* cursor size */ int xoffs,yoffs; /* LU corner to hot point offset */ int xwork,ywork; /* save/work area sizes */ int xwpos,ywpos; /* save/work area position on screen */ int displayed; /* set if displayed */ } GrCursor;

is typically not used (i.e. read or changed) by the application program, it should just pass pointers to these structures to the appropriate library functions. Other cursor manipulation functions:

void GrDisplayCursor(GrCursor *cursor); void GrEraseCursor(GrCursor *cursor); void GrMoveCursor(GrCursor *cursor,int x,int y); void GrDestroyCursor(GrCursor *cursor);

* Keyboard input

GRX can handle platform independant key input. The file "grxkeys.h" defines the keys to be used in the user's program. This is an extract:

#define GrKey_Control_A 0x0001 #define GrKey_Control_B 0x0002 #define GrKey_Control_C 0x0003 ... #define GrKey_A 0x0041 #define GrKey_B 0x0042 #define GrKey_C 0x0043 ... #define GrKey_F1 0x013b #define GrKey_F2 0x013c #define GrKey_F3 0x013d ... #define GrKey_Alt_F1 0x0168 #define GrKey_Alt_F2 0x0169 #define GrKey_Alt_F3 0x016a

But you can be confident that the standard ASCII is right maped.

The 'GrKeyType' type is defined to store keycodes:

typedef unsigned short GrKeyType;

This function:

int GrKeyPressed(void);

returns non zero if there are any keycode waiting, that can be read with:

GrKeyType GrKeyRead(void);

The function:

int GrKeyStat(void);

returns a keyboard status word, or-ing it with the next defines it can be known the status of some special keys:

#define GR_KB_RIGHTSHIFT 0x01 /* right shift key depressed */ #define GR_KB_LEFTSHIFT 0x02 /* left shift key depressed */ #define GR_KB_CTRL 0x04 /* CTRL depressed */ #define GR_KB_ALT 0x08 /* ALT depressed */ #define GR_KB_SCROLLOCK 0x10 /* SCROLL LOCK active */ #define GR_KB_NUMLOCK 0x20 /* NUM LOCK active */ #define GR_KB_CAPSLOCK 0x40 /* CAPS LOCK active */ #define GR_KB_INSERT 0x80 /* INSERT state active */ #define GR_KB_SHIFT (GR_KB_LEFTSHIFT | GR_KB_RIGHTSHIFT)