[BRLTTY] [Feature request] Improved raw key codes API

[Aura Kelloniemi]

Hello list,

Now that raw key code input with BrlAPI works as it is inteded, I would like
to start talking about improving the API. My wish is that the API would be
completely driver-independent – i.e. the client can query all possible
information about the keys that the braille device has.

One very important step towards this goal has already been taken by
implementing the key names look up.

As I have pointed out earlier, the routing keys are not well handled by this
API. Could we come up with a solution, which would allow the client code to
get the base key group name (e.g. "Routing key" or "Navrow key") from BrlAPI,
along with an additional numeric index which uniquely identifies the key –
e.g. "Routing key"[3] for the 4th routing key.

As this information can be decoded from the raw key code, a new function to
BrlAPI could be added. On C level the API might look something like this:

/// Stores information about a single raw key press/release event.
typedef struct {
    // Key codes
    uint32_t key_group;
    uint32_t key;

    bool pressed; // 1 if pressed, 0 if released
} brlapi_raw_key_event_t;

/// This function decodes a raw key code returned by brlapi__readKey family of
/// functions.
/// On success, return 0 and store raw key event description to the
/// brlapi_raw_key_event_t struct given as a parameter.
int brlapi__describe_raw_key_event (brlapi_handle_t *handle,
                                    brlapi_keyCode_t key_code,
                                    brlapi_raw_key_event_t *description);
There is already a way to get the name of the key based on the key code. There
should also be a way to get a list of key groups along with their properties.

typedef struct {
    uint32_t key_group; // The same value as in brlapi_raw_key_event_t
    char *key_group_name; // Human- and machine readable/comparable name of this group – e.g. "RoutingKey"
    int key_count; // Total number of keys in this group
} brlapi_raw_key_group_description_t;

Now there should be a function which provides the caller a list of
brlapi_raw_key_group_description_t instances.

The above is meant to be a starting point for the possible discussion. I
believe this API enhancement would be useful, but there might well be a better
way to resolve the issue.

This is probably stuff for the post 6.2 era, but I bring it up now as I would
already have use for this API.

-- 
Aura