VAppendCharacter

 
Name
  VAppendCharacter - reads the key pressed at the keyboard and appends it
to a string.
 
Synopsis
  VAppendCharacter(win, event, fg, keylen, string, key, xloc, yloc)
  Window win;
  XEvent *event;
  unsigned long fg;
  int *keylen;                          /*RETURN*/
  char **string;                        /*RETURN*/
  char *key;                            /*RETURN*/
  int xloc, yloc;
 
Description
  VAppendCharacter reads the key pressed at the keyboard, appends it to a
string and displays the resulting string. If *keylen is zero,
VAppendCharacter allocates memory space for *string, else it assumes
*string points to memory previously allocated and appends the key to
*string. VAppendCharacter then returns the key that was pushed to *key,
the new string to *string, and the new string length to *keylen. If the
key is carriage return, VAppendCharacter appends "\0" to *string. If the
key is delete or back space, VAppendCharacter will erase the right most
character from the string and decrease *keylen by 1, unless *keylen is
already zero. If a special key like Caps, control Left, control Right etc.,
is pushed, VAppendCharacter returns "@" to *key, does not append key to
*string, and does not increase *keylen by 1. To free the space allocated
by VAppendCharacter, one should use free(). Also VSelectEvents should be
called to select KeyPress events in the specified window. If the string
is out of the window, VAppendCharacter does not append the current character
to *string, but returns an error code.
 
Return Value
  0 - work successfully.
  1 - memory allocation error.
  6 - invalid window ID.
  224 - message displayed is out of window.
  226 - cannot get event from image window.
  227 - cannot get event from dialog window.
  234 - foreground is the same as background color.
  235 - exceeds the maximum of the array size.
 
Parameters
  win - specifies the ID of the window to get the key.
  event - specifies the current event removed from the event queue.
  fg - specifies the foreground color of the text to be displayed.
  keylen - the length of the string.
  string - specifies a character string.
  key - specifies the key that was pressed.
  xloc,yloc - specifies the starting location of the string to be displayed.
 
Side Effects
  None.
 
Entry Conditions
  If xloc or yloc is not valid, or keylen, string, or key is NULL, or
VCreateColormap is not called earlied, VAppendCharacter prints an error 
message to the standard error stream, produces a core dump file and exits 
from the current process.
 
Related Functions