Widget events
-------------

Widget events is how the library interacts with the application code, e.g. if
button is pressed the button `on_event` callback handler is called with a
pointer to a `gp_widget_event` structure that describes the event.

.Widget event handler and event structure
[source,c]
-------------------------------------------------------------------------------

struct gp_widget {
...
	int (*on_event)(gp_widget_event *);
	void *priv;
...
};

struct gp_widget_event {
	gp_widget *self;
	uint16_t type;
	uint16_t sub_type;
	union {
		void *ptr;
		long val;
		gp_bbox *bbox;
		gp_event *input_ev;
	};
};
-------------------------------------------------------------------------------

The event handler is part of the widget structure, the `priv` field is a user
pointer that is not touched by the widget library.

The event handler is passed `gp_widget_event` structure and returns integer, in
most cases the value is not used and it's customary to return 0 in these
cases.

Each widget also has a event mask that can be used to enable or disable
particular events. There is also a default mask new widgets are initialized
with.

.Function to set a widget handler and priv pointer
[source,c]
-------------------------------------------------------------------------------
void gp_widget_on_event_set(gp_widget *self,
                            int (*on_event)(gp_widget_event *),
                            void *priv);
-------------------------------------------------------------------------------

.Functions to manipulate widget event mask
[source,c]
-------------------------------------------------------------------------------
void gp_widget_event_mask(gp_widget *self, enum gp_widget_event_type ev_type);

void gp_widget_event_unmask(gp_widget *self, enum gp_widget_event_type ev_type);
-------------------------------------------------------------------------------

.Widget events
[cols=",,3",options="header"]
|============================================================================
|        Event name      | Unmasked | Description
| GP_WIDGET_EVENT_NEW    |   Yes    | Emitted after widget has been created from a json description.
| GP_WIDGET_EVENT_FREE   |   Yes    | Emitted before widget is freed.
| GP_WIDGET_EVENT_WIDGET |   Yes    | Default action, e.g. button pressed, checkbox changed, etc.
| GP_WIDGET_EVENT_INPUT  |    No    | Can be used to redirect unused input events.
| GP_WIDGET_EVENT_REDRAW |    No    | Emitted when widget needs to be repainted.
| GP_WIDGET_EVENT_RESIZE |    No    | Emitted when widget is resized.
|============================================================================

The 'GP_WIDGET_EVENT_NEW' is send when widget is created from the JSON
description. It's mainly used to set properties that cannot be known, or
shouldn't be set in the JSON itself.

The 'GP_WIDGET_EVENT_FREE' is send before widget is freed, it can be used for
a cleanup.

The 'GP_WIDGET_EVENT_WIDGET' is a widget specific event, e.g. button has been
pressed, or text was appended into a textbox. In this case the event sub_type
may be set. In most of the cases though widget has only one type of event to
send and in this case the sub_type is set to zero.

The 'GP_WIDGET_EVENT_RESIZE' is mainly used for the pixmap widget, where the
resized pixmap has tobe repainted by the user code. It can be enabled for any
widget though.

The 'GP_WIDGET_EVENT_INPUT' can be used to redirect unused input events, i.e.
when widget is focused and gets input events, unhandled events can be send to
the widget event handler. In this case the return value from the handler is
important. If input event was used by the handler it should return 1 and zero
should be returned otherwise, so that the library knows if the event should be
propagated to the upper layers or not.

.Input event injection
[source,c]
-------------------------------------------------------------------------------
int gp_widget_input_inject(gp_widget *self, gp_widget_event *ev);
-------------------------------------------------------------------------------

This function takes a widget event and if the event type is
'GP_WIDGET_EVENT_INPUT' the input event is injected to the widget input event
handler, i.e. the widget will get the input (e.g. keypresses) as if it was
focused.

This is useful in cases where we want to redirect unhandled input events to a
specifid widget as a shorcut. For example when we have a file open dialog any
text we type that is not processes by curently focused widget is redirected to
the filter textbox.

This of course works only for key presses and unicode input events as
relative or absolute coordinates are normalized as events pass down the
widget tree, i.e. for any event widget receives the widget top level corner
has coordinate [0,0]. Hence these kinds of events are not injected.

Application events
------------------

Similarily to widgets there is one special application event handler that can
propagate event such as application exit to the application code.

[source,c]
-------------------------------------------------------------------------------
void gp_app_on_event_set(int (*on_event)(gp_widget_event *ev));
-------------------------------------------------------------------------------

Sets an application event handler. The handler then will be called on
application events.

The `ev->self` will be set to NULL for all application events.

.Functions to manipulate app event mask
[source,c]
-------------------------------------------------------------------------------
void gp_app_event_mask(enum gp_widget_event_type ev_type);

void gp_app_event_unmask(enum gp_widget_event_type ev_type);
-------------------------------------------------------------------------------

.Application events
[cols=",,3",options="header"]
|===================================================
|       Event name      | Unmasked | Description
| GP_WIDGET_EVENT_FREE  |   Yes    | Emitted application exit.
| GP_WIDGET_EVENT_INPUT |    No    | Can be used to redirect unused input events.
|===================================================
