Navigation C API Pages Python bindings Applications

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_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_event_handler_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_RESIZE

No

Emitted when widget is resized.

GP_WIDGET_EVENT_INPUT

No

Can be used to redirect unused input events.

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.

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_event_handler_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 widget 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.