Function:     ScheduleGgiPlotCursor

Purpose:      Register a callback routine receiving cursor events.

Category:     USER-INTERFACE, GRAPHICS

File:         ggi.src

Author:       J.P. Terlouw   

Use:
              #include "ggi.h"
              ident plotfield, result;
              GgiCursorProc proc;
              void *arg;

              result = ScheduleGgiPlotCursor(proc, plotfield, arg);

                result     -  registration identification (NULL when failed)
                proc       -  pointer to function.
                plotfield  -  plotfield created by GgiPlotField.
                arg        -  'client' data.

Description:  ScheduleGgiPlotCursor registers a function to be called
              when a cursor event occurs in the specified plot field.
              Such an event can be a mouse click, a pointer move or a
              key press.
               
              The prototype of 'proc' is:
                  void proc(ident id, GgiPlotInfo info, void *arg);

              Arguments:
                  id   - the registration identification.
                  info - pointer to struct described below.
                  arg  - the 'arg' argument from the registration call.

              The layout of the info struct is defined in ggi.h
              Relevant elements are:

                ident plotfield  -  Ggi element id
                char  *name      -  PGPLOT device name
                float x, y       -  cursor position in world coordinates
                int   button     -  identification of event-causing button
                int   state      -  mask of all active buttons and modifiers
                char  key        -  keyboard character
                
              Buttons and modifiers can be any of the following:
              
                ggiButn1  -  mouse button 1
                ggiButn2  -  mouse button 2
                ggiButn3  -  mouse button 3
                ggiShift  -  shift key
                ggiCtrl   -  control key
                ggiKeybd  -  other keyboard key
                
              Element 'state' contains the bit-wise OR of all buttons and
              modifiers depressed *before* the event occurred.
              If e.g. (only) mouse button 1 is depressed, 'button' will have
              the value ggiButn1 and 'state' will be zero. When button 1
              subsequently released, the callback function will be called
              again, but now with both 'button' and 'state' having the
              value ggiButn1.
              If instead of releasing the button, the mouse is moved,
              'state' will have the value ggiButn1 and 'button' will be zero.
              If an ASCII or an arrow key is typed, element 'button'
              will have the value ggiKeybd and element 'key' will contain the
              ASCII value or arrow code. The following symbolic constants
              have been defined for arrows: ggiLeftArrow, ggiUpArrow,
              ggiRightArrow and ggiDownArrow.


Updates:      Feb 25, 1998: JPT, Document created.
              Apr 13, 2000: JPT, Function is now also called for mouse moves
                                 without any button depressed.
              Apr 28, 2000: JPT, Implemented keyboard interaction.
              Mar 22, 2001: JPT, Arrow keys added.
              Nov 04, 2004: JPT, When scheduled, keyboard focus follows mouse.