<commit_before>Input Events
------------

Input events are somehow tied to the link:backends.html[backends]. Possibly in
contrast with other libraries there is not always 1:1 correspondence between
input driver and backend graphics driver. That means that you can, for
example, use linux input events together with X Window without any problems.
You can even write application that doesn't draw any graphics at all and still
use some of the input drivers. There are, of course, cases where input driver
is created only together with graphics driver, this is the case for example
for X Window backends or SDL backends.

The basic structure is roughly modeled after Linux kernel input API. The main
difference is that events that belongs together are delivered together. For
example mouse coordinates are bundled in one event.

For example usage see backend link:example_input.html[example].

Event Structure Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <GP.h>
/* or */
#include <input/GP_Event.h>

typedef struct GP_Event {
	/* event */
	uint16_t type;
	uint32_t code;
	union GP_EventValue val;

	/* input device id */
	uint32_t dev_id;
	
	/* event timestamp */
	struct timeval time;

	/* 
	 * Cursor position, possition on screen accumulated
	 * from all pointer devices
	 */
	uint32_t cursor_x;
	uint32_t cursor_y;

	/* 
	 * Bitmap of pressed keys including mouse buttons
	 * accumulated for all input devices.
	 */
	uint8_t keys_pressed[GP_EVENT_KEYMAP_BYTES];
} GP_Event;
-------------------------------------------------------------------------------

The GP_Event structure is basic block that describes input event (i.e. key was
pressed/released, mouse was moved, window was resized by user).

[source,c]
-------------------------------------------------------------------------------
enum GP_EventType {
	GP_EV_KEY, /* key/button press event */
	GP_EV_REL, /* relative event */
	GP_EV_ABS, /* absolute event */
	GP_EV_SYS, /* system events window close, resize... */
	GP_EV_MAX = GP_EV_SYS, /* maximum, greater values are free */
};
-------------------------------------------------------------------------------

The event 'type' determines highlevel nature of the event.

* Key events covers keyboard button presses, mouse buttons, etc.
* Relative events covers mostly mouse coordinates
* Absolute events covers touchscreens and tablets
* System events are used mostly for propagating window close and window
  resize events
* Values greater than 'GP_EV_MAX' are free for user events

[source,c]
-------------------------------------------------------------------------------
enum GP_EventKeyCode {
	GP_EV_KEY_UP,
	GP_EV_KEY_DOWN,
	GP_EV_KEY_REPEAT,
};

enum GP_EventRelCode {
	GP_EV_REL_POS,
	GP_EV_REL_WHEEL,
};

enum GP_EventAbsCode {
	GP_EV_ABS_POS,
};

enum GP_EventSysCode {
	GP_EV_SYS_QUIT,
	GP_EV_SYS_RESIZE,
};
-------------------------------------------------------------------------------

The event 'code' specifies the event nature more closely, it has different
meaning for each event type. The names are (hopefully) self explanatory.

[source,c]
-------------------------------------------------------------------------------
union GP_EventValue {
	/* generic one integer value */
	int32_t val;
	/* key */
	struct GP_EventKey key;
	/* position */
	struct GP_EventPosRel rel;
	struct GP_EventPosAbs abs;
	/* system event */
	struct GP_EventSys sys;
};

struct GP_EventPosRel {
	int32_t rx;
	int32_t ry;
};

struct GP_EventPosAbs {
	uint32_t x, x_max; /* the x is between 0 and x_max */
	uint32_t y, y_max;
	uint32_t pressure, pressure_max;
};

struct GP_EventKey {
	uint32_t key;
	char ascii;
};

struct GP_EventSys {
	uint32_t w, h;
};
-------------------------------------------------------------------------------

The event value is a union that could hold different information. The right
format of the data is known from the 'type' and 'code'. For some types of the
events it's not used at all.
  
* The relative coordinates are used for 'GP_EV_REL_POS' and absolute coordinates
  for 'GP_EV_ABS_POS'.

* The key event value is used for keypresses, additionally it holds the key
  value mapped to ASCII if conversion is applicable otherwise it's set to
  zero. You should consult the header 'input/GP_Event.h' for comprehensive
  list of key values.

* And finally the system event is used with 'GP_EV_SYS_RESIZE' and informs you
  of the new window size.

The 'dev_id' is not used at the moment and may be removed.

The timeval structure 'time' holds time when the event was created (or
received by GFXprim input driver).

The 'cursor_x' and 'cursor_y' holds pointer coodinates merged from all input
sources.

The 'key_pressed' is bitflag array of currently pressed keys which is useful
for using keys as modificators. The array holds most of the standard keyboard
keys and mouse buttons.

Event API
~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <GP.h>
/* or */
#include <input/GP_Event.h>

unsigned int GP_EventsQueued(void);
-------------------------------------------------------------------------------

The 'GP_EventsQueued' returns number of queued events.
<commit_msg>doc: input: Clarify wording in few cases.<commit_after>Input Events
------------

Input events are somehow tied to the link:backends.html[backends]. Possibly in
contrast with other libraries there is not always 1:1 correspondence between
input driver and backend graphics driver. That means that you can, for
example, use linux input events together with X Window without any problems.
You can even write application that doesn't draw any graphics at all and still
use some of the input drivers. There are, of course, cases where input driver
is created only together with graphics driver, this is the case for example
for X Window backends or SDL backends.

The basic structure is roughly modeled after Linux kernel input API. The main
difference is that events that belongs together are delivered together (the
kernel input API sends one event for each value i.e. x or y coordinate and has
sync event that finalizes the changes in the values).

For example usage see input events link:example_input.html[example].

Event Structure Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <GP.h>
/* or */
#include <input/GP_Event.h>

typedef struct GP_Event {
	/* event */
	uint16_t type;
	uint32_t code;
	union GP_EventValue val;

	/* input device id */
	uint32_t dev_id;
	
	/* event timestamp */
	struct timeval time;

	/* 
	 * Cursor position, possition on screen accumulated
	 * from all pointer devices
	 */
	uint32_t cursor_x;
	uint32_t cursor_y;

	/* 
	 * Bitmap of pressed keys including mouse buttons
	 * accumulated for all input devices.
	 */
	uint8_t keys_pressed[GP_EVENT_KEYMAP_BYTES];
} GP_Event;
-------------------------------------------------------------------------------

The GP_Event structure is basic block that describes input event (i.e. key was
pressed/released, mouse was moved, window was resized by user).

[source,c]
-------------------------------------------------------------------------------
enum GP_EventType {
	GP_EV_KEY, /* key/button press event */
	GP_EV_REL, /* relative event */
	GP_EV_ABS, /* absolute event */
	GP_EV_SYS, /* system events window close, resize... */
	GP_EV_MAX = GP_EV_SYS, /* maximum, greater values are free */
};
-------------------------------------------------------------------------------

The event 'type' determines highlevel nature of the event.

* Key events covers keyboard button presses, mouse buttons, etc.
* Relative events covers mostly mouse coordinates
* Absolute events covers touchscreens and tablets
* System events are used mostly for propagating window close and window
  resize events
* Values greater than 'GP_EV_MAX' are free for user events

[source,c]
-------------------------------------------------------------------------------
enum GP_EventKeyCode {
	GP_EV_KEY_UP,
	GP_EV_KEY_DOWN,
	GP_EV_KEY_REPEAT,
};

enum GP_EventRelCode {
	GP_EV_REL_POS,
	GP_EV_REL_WHEEL,
};

enum GP_EventAbsCode {
	GP_EV_ABS_POS,
};

enum GP_EventSysCode {
	GP_EV_SYS_QUIT,
	GP_EV_SYS_RESIZE,
};
-------------------------------------------------------------------------------

The event 'code' specifies the event nature more closely, it has different
meaning for each event type. The names are (hopefully) self explanatory.

[source,c]
-------------------------------------------------------------------------------
union GP_EventValue {
	/* generic one integer value */
	int32_t val;
	/* key */
	struct GP_EventKey key;
	/* position */
	struct GP_EventPosRel rel;
	struct GP_EventPosAbs abs;
	/* system event */
	struct GP_EventSys sys;
};

struct GP_EventPosRel {
	int32_t rx;
	int32_t ry;
};

struct GP_EventPosAbs {
	uint32_t x, x_max; /* the x is between 0 and x_max */
	uint32_t y, y_max;
	uint32_t pressure, pressure_max;
};

struct GP_EventKey {
	uint32_t key;
	char ascii;
};

struct GP_EventSys {
	uint32_t w, h;
};
-------------------------------------------------------------------------------

The event value is a union that could hold different information. The right
format of the data is known from the 'type' and 'code'. For some types of the
events it's not used at all.
  
* The relative coordinates are used for 'GP_EV_REL_POS' and absolute coordinates
  for 'GP_EV_ABS_POS'.

* The key event value is used for keypresses, additionally it holds the key
  value mapped to ASCII if conversion is applicable otherwise it's set to
  zero. You should consult the header 'input/GP_Event.h' for comprehensive
  list of key values.

* And finally the system event is used with 'GP_EV_SYS_RESIZE' and informs you
  of the new window size.

The 'dev_id' is not used at the moment and may be removed.

The timeval structure 'time' holds time when the event was created (or
received by GFXprim input driver).

The 'cursor_x' and 'cursor_y' holds current pointer coodinates. (All relative
and absolute events are mixed together to compute current cursor position.)

The 'key_pressed' is bitflag array of currently pressed keys which is useful
for using keys as modificators. The array always holds state of the standard
keyboard keys and mouse buttons.

Event API
~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <GP.h>
/* or */
#include <input/GP_Event.h>

unsigned int GP_EventsQueued(void);
-------------------------------------------------------------------------------

The 'GP_EventsQueued' returns number of queued events.

{'fraction_non_alphanumeric': 0.21162096623764223, 'fraction_numerical': 0.005595970900951315, 'mean_word_length': 2.2066387559808613, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2429034', 'n_tokens_mistral': 2908, 'n_tokens_neox': 2783, 'n_words': 1198}