High level drawing api
This module provides a high-level drawing interface which automatically handles redrawing on exposure, and bundles the most likely events to be needed.
- hl_gtk_drawing_area_new; Create the drawing area.
- hl_gtk_drawing_area_expose_cb; Default callback for expose events.
- hl_gtk_pixbuf_cairo_new; Create a cairo context attached to the pixbuf.
- hl_gtk_pixbuf_cairo_destroy; Update the pixbuf and destroy the context.
- is_big_endian; Utility function to determine endianness. (GTK2 only)
function hl_gtk_drawing_area_new(scroll, size, ssize, expose_event, &
& data_expose, button_press_event, data_button_press, &
& button_release_event, data_button_release, scroll_event, &
& data_scroll, motion_event, data_motion, realize, data_realize, &
& configure_event, data_configure, key_press_event, data_key_press, &
& key_release_event, data_key_release, enter_event, data_enter, &
& leave_event, data_leave, event_mask, event_exclude, auto_add_mask, &
& tooltip, has_alpha, use_pixbuf) result(plota)
type(c_ptr) :: plota
type(c_ptr), intent(out), optional :: scroll
integer(kind=c_int), intent(in), optional, dimension(2) :: size, ssize
type(c_funptr), optional :: expose_event, button_press_event, &
& button_release_event, scroll_event, key_press_event, &
& key_release_event, motion_event, realize, configure_event,&
& enter_event, leave_event
type(c_ptr), intent(in), optional :: data_expose, data_button_press, &
& data_button_release, data_scroll, data_motion, data_realize, &
& data_configure, data_key_press, data_key_release, data_enter, &
& data_leave
integer(kind=c_int), intent(in), optional :: event_mask, event_exclude
integer(kind=c_int), intent(in), optional :: auto_add_mask
character(kind=c_char), dimension(*), optional, intent(in) :: tooltip
integer(kind=c_int), intent(in), optional :: has_alpha, use_pixbuf
A high-level drawing area
| Argument | Type | Required? | Description |
|---|---|---|---|
| SCROLL | c_ptr | optional | If present, then the drawing area will be placed in a scrollable window, whose pointer will be returned here. If it is present, then it rather than the drawable should be used for packing. |
| SIZE | c_int() | optional | The requested size for the area. If no size is given then a default size of 256x256 is used. |
| SSIZE | c_int() : | optional | The requested size for a scrolling window |
| EXPOSE_EVENT | c_funptr | optional | Callback for expose-event signal N.B. In GTK3 the signal is called "draw". If this is not given and a pixbuf backing is requested, then a default handler is provided which copies the pixbuf to the drawing area. |
| DATA_EXPOSE | c_ptr | optional | Data for expose_event callback |
| BUTTON_PRESS_EVENT | c_funptr | optional | Callback for button-press-event signal |
| DATA_BUTTON_PRESS | c_ptr | optional | Data for button_press_event callback |
| BUTTON_RELEASE_EVENT | c_funptr | optional | Callback for button-release-event signal |
| DATA_BUTTON_RELEASE | c_ptr | optional | Data for button_release_event callback |
| SCROLL_EVENT | c_funptr | optional | Callback for scroll-event signal |
| DATA_SCROLL | c_ptr | optional | Data for scroll_event callback |
| REALIZE | c_funptr | optional | Callback for realize signal |
| DATA_REALIZE | c_ptr | optional | Data for realize callback |
| CONFIGURE_EVENT | c_funptr | optional | Callback for configure-event signal |
| DATA_CONFIGURE | c_ptr | optional | Data for configure_event callback |
| KEY_PRESS_EVENT | c_funptr | optional | Callback for key-press-event signal |
| DATA_KEY_PRESS | c_ptr | optional | Data for key_press_event callback |
| KEY_RELEASE_EVENT | c_funptr | optional | Callback for key-release-event signal |
| DATA_KEY_RELEASE | c_ptr | optional | Data for key_release_event callback |
| MOTION_EVENT | c_funptr | optional | Callback for the motion-notify-event signal |
| DATA_MOTION | c_ptr | optional | Data for motion_event |
| ENTER_EVENT | c_funptr | optional | Callback for the enter-notify-event signal |
| DATA_ENTER | c_ptr | optional | Data for enter_event |
| LEAVE_EVENT | c_funptr | optional | Callback for the leave-notify-event signal |
| DATA_LEAVE | c_ptr | optional | Data for leave_event |
| EVENT_MASK | c_int | optional | Mask for which events to pass. |
| EVENT_EXCLUDE | c_int | optional | Mask for events not to pass (this might used to prevent auto-enabling an event that should only be enabled by user actions) |
| AUTO_ADD_MASK | boolean | optional | Set to FALSE to disable automatically adding events to the event mask if a handler is provided. |
| TOOLTIP | string | optional | Tooltip for the drawing area. |
| HAS_ALPHA | boolean | optional | If a pixbuf is used, should it have an alpha (transparency) channel (default=FALSE) |
| USE_PIXBUF | boolean | optional | Set to FALSE to disable the backing store pixbuf |
Odd notes on mask interactions and other things.
- Scroll (wheel) events, are enabled by GDK_SCROLL_MASK or GDK_BUTTON_PRESS_MASK, thus (as far as I can see) there is no way to mask wheel events while allowing button presses to be processed.
- It does not appear to be possible to remove events by unsetting bits in the event mask.
- Adding a tooltip looks to implicitly enables some events.
- If you want to get at the backing pixbuf explicitly, then use pixbuf = g_object_get_data(area, "backing-pixbuf").
- An example where an explict EVENT_MASK and EVENT_EXCLUDE might be useful would be to enable motion events only if a button is down.
function hl_gtk_drawing_area_expose_cb(area, event, data) bind(c) &
& result(rv)
integer(kind=c_int) :: rv
type(c_ptr), value :: area, event, data
Default callback for exposing a drawing area. For this to be connected a pixbuf must be requested, and no explicit expose callback should be specified.
| Argument | Type | Required? | Description |
|---|---|---|---|
| AREA | c_ptr | required | The drawing area |
| EVENT | c_ptr | required | GTK2 = event structure, GTK3 = a cairo context Since this differs between versions, we won't use it. |
| DATA | c_ptr | required | A pointer to user data (not used). |
function hl_gtk_pixbuf_cairo_new(area, key) result(cr)
type(c_ptr) :: cr
type(c_ptr), intent(in) :: area
type(cairo_user_data_key_t), intent(in), target :: key
Create a cairo context which will draw into the pixbuf Based on C code posted to GtkForums by "tadeboro".
| Argument | Type | Required? | Description |
|---|---|---|---|
| PIXBUF | c_ptr | required | The pixbuf to which we will draw. |
| KEY | cairo_user_data_key_t | required | A key to identify the user
data between this and hl_gtk_pixbuf_cairo_destroy.
After the drawing operations, you must call |
subroutine hl_gtk_pixbuf_cairo_destroy(cr, key)
type(c_ptr), intent(inout) :: cr
type(cairo_user_data_key_t), intent(in), target :: key
Update the pixbuf and destroy the cairo context Based on C code posted to GtkForums by "tadeboro".
| Argument | Type | Required? | Description |
|---|---|---|---|
| CR | c_ptr | required | The cairo context to put in the pixbuf |
| KEY | cairo_user_data_key_t | required | The key to find the pixbuf (just has to be the same variable as KEY in hl_gtk_pixbuf_cairo_new |
This is called following drawing operations to the context created by
hl_gtk_pixbuf_cairo_new.
Because GDK-2 does not have the gdk_pixbuf_get_from_surface function
for GDK2 a manual pixel copy must be made.
function is_big_endian()
logical is_big_endian
Determine if the machine is big-endian or not. This routine is only present in the GTK+-2 version
