Function:     ScheduleKeyevent

Purpose:      Register a function to be called whenever Hermes generates an
              event associated with the specified user input keyword.

Category:     SYSTEM, USER-INTERFACE

File:         keyevents.c

Author:       J.P. Terlouw

Use:          #include "keyevents.h"
              ident id;
              id = ScheduleKeyevent(proc, key, mask, arg);
              
              KeyeventProc proc  -  pointer to function
              char         *key  -  user input keyword
              int          mask  -  event mask: the bitwise OR of any of
                                    the key events defined in taskcom.h
              void         *arg  -  'client' data

Description:  ScheduleKeyevent registers a function to be called by MainLoop
              whenever Hermes generates an event which meets the specified
              keyword and mask.
              In this call, 'arg' will be passed to 'proc'.
              The return value is a unique identification code corresponding
              with the registration, which will also be passed as an
              argument to 'proc'.
               
              The prototype of 'proc' is:
                  void proc(ident id, char *key, int code, void *arg);

              The argument 'key' is the keyword for which the event was
              generated. This argument can be used to discriminate between
              keywords when the same function is registered for multiple
              keywords. The argument 'code' is the actual event code.
              (KEYCHANGE, KEYCANCEL or KEYREJECT as defined in taskcom.h)

Example:      The following program illustrates how the function can be used.
              It waits for (re)definition of any of the keywords STOP=, TEST=
              or CONT=. When such an event occurs, the function 'handle_key'
              is called, which prints the argument specified when the function
              was scheduled, reads the value of the input, prints it,
              and finally deschedules itself for this keyword.
              When all three keywords have been specified, everything has
              been descheduled causing MainLoop to return.

         #include "cmain.h"
         #include "gipsyc.h"
         #include "init.h"
         #include "finis.h"
         #include "usertext.h"
         #include "anyout.h"
         #include "keyevents.h"
         
         static fint zero=0;
         
         static void handle_key(ident id, char *key, int code, void *arg)
         {
            fchar value;
            char  valstr[40];
             
            value.a = valstr;
            value.l = 40;
             
            anyout_c(&zero, tofchar((char*)arg));
            (void)usertext_c(value, &zero, tofchar(key), tofchar(" "));
            anyout_c(&zero, value);
            DescheduleKeyevent(&id);
         }
         
         MAIN_PROGRAM_ENTRY
         {
            init_c();
            (void)ScheduleKeyevent(handle_key, "STOP=", KEYCHANGE, "Stop");
            (void)ScheduleKeyevent(handle_key, "TEST=", KEYCHANGE, "Test");
            (void)ScheduleKeyevent(handle_key, "CONT=", KEYCHANGE, "Cont");
            MainLoop();
            finis_c();
         }

Related Docs: DescheduleKeyevent.dc2, events.dc3

Updates:      Apr 18, 1997: JPT, Document created.