From: Andrew Apted <ajapted@netspace.net.au>
  To  : ggi-develop@eskimo.com
  Date: Mon, 21 Sep 1998 17:45:12 +1000

Events and Joysticks

Hi all,

At the IRC meeting Andy and me discussed what joystick events should
look like.  We didn't get very far though... so here is a concrete
proposal for further discussion and (hopefully) implementation.

1. Joysticks use `evValAbsolute' events, which look like this :

    typedef struct ggi_val_event {
    
        COMMON_DATA;
    
        uint32          first;      /* first valuator reported      */
        uint32          count;      /* number of valuators reported */
        sint32          value[32];  /* absolute/relative values     */
    
    } ggi_val_event;

Note that I replaced `changed' with `count'.  That `changed' field in the
old one was a real bitch.  Much more complexity (making both generating
and using these events harder) without any benefit as far as I can see.

2. Joysticks are described by an initial `evValInfo' event (or multible
events) that LibGGI automatically generates at start up.  This describes
the kinds of values that appear in ev.val.value[N], as well as the total
number of values.  It looks like this:

    typedef struct ggi_valinfo_event {

        COMMON_DATA;

        uint32          first;      /* first valuator reported */
        uint32          count;      /* number of valuators reported */
        uint32          total;      /* total number of valuators */

        ggi_input_type  dev_type;   /* type of device */

        struct {
            ggi_value_type    val_type;    /* type of valuator */
            uint32            range;       /* (depends on val_type) */
        }               desc[16];   /* valuator descriptors */
	
    } ggi_valinfo_event;

    typedef num ggi_value_type {

            GGI_VALTYPE_DELTA;      /* changes are relative (mice) */
            GGI_VALTYPE_CENTRED;    /* -range <= value <= +range */
            GGI_VALTYPE_BOXED;      /* 0 <= value <= ranged */

    } ggi_value_type;

(ggi_input_type is what's already in event.h).

Now ggi_value_type describes each valuator:

    GGI_VALTYPE_DELTA indicates relative motion (i.e. mice), and the
    range indicates the maximum delta (-range <= value <= +range).  

    GGI_VALTYPE_CENTRED is for joysticks and spaceorbs.  Here the value
    is `0' when in the normal position, `-range' when pushed at (or
    near) one end, and `+range' when pushed at (or near) the other end.  

    GGI_VALTYPE_BOXED is for graphics tablets.  The valuator value lies
    between 0 and +range.  (For `pen off the tablet', maybe -1 could be
    used -1 ?).
 
(In fact, all that suggests just one event `evValuator' would be
enough... I don't know).

(Possibly ggi_value_type values could be OR'd with other sets of values
to indicate stuff like force vs linear etc...  food for thought).

3. Joystick buttons use `evValButtonPress' and `evValButtonRelease'
events, which look like this :

    typedef struct ggi_vbutton_event {
    
        COMMON_DATA;
    
        uint32    button;      /* button number (0,1,2,...) */
    
    } ggi_vbutton_event;

The old way was to just use key events, but having tried that I really
disliked it.  The KT_BUTTON thang was an ugly hack, which just got in
the way of normal keyboard usages.  And non-keyboard devices don't need
all that sym, label, & modifier stuff.  IMHO evValButtonPress/Release is
a much cleaner and more consistent solution.

Now the `button' field is a button *number*, not a bitmask.  This is the
nicest way to do it (IMHO).  And a 32 button limit of a bitmask may well
be too restrictive for some devices.

[Here's a wacky (and offtopic) idea: rename `code' in key events to
`button' which is what it really represents: a button on the keyboard !]

OK, that's it.  Andy, what do you think ?

Cheers,
_____________________________________________  ____
                                               \  /
  Andrew Apted   <andrew@ggi-project.org>       \/