GFXprim

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


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

void gp_widget_on_event_set(gp_widget *self,
                            int (*on_event)(gp_widget_event *),
                            void *priv);

Functions to manipulate widget event mask

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);

Table 1. Widget events
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

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.

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

void gp_app_event_mask(enum gp_widget_event_type ev_type);

void gp_app_event_unmask(enum gp_widget_event_type ev_type);

Table 2. Application events
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.