GFXprim

Pixmap widget

Pixmap widget is a widget that can show a picture.

The struct gp_widget_pixmap can be accessed as widget->pixmap.

Pixmap widget constructor

gp_widget *gp_widget_pixmap_new(unsigned int w, unsigned int h,
                                int (*on_event)(gp_widget_event *ev),
                                void *priv);

Pixmap repaint modes

The pixmap widget is allocated as an empty container and there are two different repaint strategies for pixmap widget.

Buffered mode

In this mode a pixmap in the size of the widget is allocated, by the application, before any drawing is done. The content of the pixmap is preserved i.e. not modified by the library.

The allocation is deffered for when the application has been started and the pixel format, we are using for drawing, is known. Only then the library will call the pixmap event handler with a resize event and render context pointer, which could be used to allocate right backing pixmap and set the pixmap pointer in the struct gp_widget_pixmap.

The pixmap has to be resized properly on each resize event as well.

The GP_WIDGET_EVENT_RESIZE has to be enabled manually in the pixmap event mask before the application starts.

void gp_widget_pixmap_redraw(gp_widget *self,
                             gp_coord x, gp_coord y,
                             gp_size w, gp_size h);

Requests a partiall update of the pixmap widget. The position is relative to the top left corner of the pixmap widget and the rectangle is clipped to the actuall widget size so it’s safe to pass values outside of the widget itself.

void gp_widget_pixmap_redraw_all(gp_widget *self);

Requests full update of the pixmap widget. Can be used to override previous partiall update.

gp_size gp_widget_pixmap_w(gp_widget *self);
gp_size gp_widget_pixmap_h(gp_widget *self);

Returns pixmap width and height.

See example.

Unbuffered mode

In this mode the application is passed a temporary buffer in the size of the widget and a bouding box that describes an inner rectangle that has to be repainted. To pass the pointer the pixmap member in struct gp_widget_pixmap is set temporarily, for the duration of the event handler, and the bounding box is passed down in the bbox member of the widget event structure.

The application is free to ignore the bounding box and repaint the whole pixmap.

The content of the pixmap buffer is not preserved between calls in this case so this is only useful when pixmap is repainted periodically and the data is not worth caching.

The GP_WIDGET_EVENT_REDRAW has to be enabled manually in the pixmap event mask before the application starts.

You may as well enable the GP_WIDGET_EVENT_RESIZE if you want to be notified when the pixmap is resized.

See example.

Table 1. Pixmap JSON attributes
Attribute	Type	Default	Description
`w`	uint		Pixmap width
`h`	uint		Pixmap height