Next: , Previous: General Conventions, Up: Top

5 Gdk Module

The Gdk interface module can be used with

     (use-modules (gtk-2.0 gdk))

A call to gdk_init is made automatically, an application doesn't need to do that itself. Standard Gdk command line options are taken from the program command line (eg. ‘--display’), and removed from there, leaving other options and the rest of the command line for the application. see Runtime Environment.

Currently, the (gtk-2.0 gdk) module also initializes Gtk (gtk_init etc, see Gtk Module). Perhaps this will change in the future.

The following rules apply to the various Gdk types.

Type predicates are implemented as for instance gdk-window?. These test only for an object of the type, so when say a string is automatically converted for GdkFont, the corresponding gdk-font? is false for a string, it's true only for an actual font object.
Most Gdk objects are subtypes of GObject and the rules for it apply to them (see General Conventions). But those few not like this, such as GdkFont, are not uniquely represented by a single Scheme level object and so cannot be compared with eq? (nor with equal?). Standard Gdk functions like gdk-font-equal and gdk-color-equal can be used in the usual way though.
Atoms are passed and returned as Guile symbols, for example WM_NAME.
Bitmap and pixmap objects are the same type. When a function expects a bitmap currently Guile-Gtk doesn't check the depth is 1, and generally an X level BadMatch error will occur if it's not.
As a convenience, functions expecting a GdkColor object can be passed a string, which will be parsed and allocated in the default colormap, using gdk-color-intern (see Gdk Extras).

The following field accessors and setters are provided,

— Function: gdk-color-red color
— Function: gdk-color-blue color
— Function: gdk-color-green color
— Function: gdk-color-pixel color
— Function: gdk-color-set-red color red
— Function: gdk-color-set-blue color blue
— Function: gdk-color-set-green color green
— Function: gdk-color-set-pixel color pixel

The following field accessors are provided,
— Function: gdk-drag-context-action
— Function: gdk-drag-context-actions
— Function: gdk-drag-context-dest-window
— Function: gdk-drag-context-is-source
— Function: gdk-drag-context-source-window
— Function: gdk-drag-context-start-time
— Function: gdk-drag-context-suggested-action
— Function: gdk-drag-context-targets

The following field accessors are provided. Consult the Gdk documentation for which fields are available in which event types.
— Function: gdk-event-type e
— Function: gdk-event-area e
— Function: gdk-event-atom e
— Function: gdk-event-button e
— Function: gdk-event-count e
— Function: gdk-event-crossing-mode e
— Function: gdk-event-drag-context e
— Function: gdk-event-focus e
— Function: gdk-event-in e
— Function: gdk-event-is-hint e
— Function: gdk-event-keyval e
— Function: gdk-event-notify-detail e
— Function: gdk-event-send-event e
— Function: gdk-event-property e
— Function: gdk-event-requestor e
— Function: gdk-event-selection e
— Function: gdk-event-source e
— Function: gdk-event-string e
— Function: gdk-event-subwindow e
— Function: gdk-event-target e
— Function: gdk-event-time e
— Function: gdk-event-window e
— Function: gdk-event-x-root e
— Function: gdk-event-y-root e
— Function: gdk-event-x e
— Function: gdk-event-y e

Mouse pointer positions as floating point numbers, eg. for motion notify events.

— Function: gdk-event-configure-x e
— Function: gdk-event-configure-y e
— Function: gdk-event-configure-width e
— Function: gdk-event-configure-height e

Window position and sizes as exact integers, for a configure notify event.

— Function: gdk-event-state e

GdkModifierType flags, eg. for a key press event.

— Function: gdk-event-visibility-state e

GdkVisibilityState symbol, for visibility notify events.

— Function: gdk-event-message e
— Function: gdk-event-message-type e

gdk-event-message returns its data as a vector of 5, 10 or 20 integers, according to the data format (32, 16, or 8 bits, respectively).

As a convenience, functions expecting a GdkFont object can be passed the name of a font as a string, which will be loaded as per gdk-font-intern (see Gdk Extras).
A points is represented as a pair (x . y). (see Pairs)
A rectangles is represented as a pair of pairs ((x . y) . (width . height)). Notice the (x . y) pair corresponds to the way a GdkPoint is represented.
A segment is represented as a pair of pairs ((x1 . y1) . (x2 . y2)). Notice each (x . y) corresponds to the way a GdkPoint is represented.
Currently GdkWChar values are represented as integers, and GdkWChar strings as vectors of integers. So for instance gdk-wcstombs expects such a vector.

This representation might change in the future if Guile gets its own notion of characters bigger than 8 bits.

An application must call gdk-window-destroy to destroy a window which it created and no longer needs. This is not done automatically by the garbage collector, a window forgotten will continue to exist until the program exits. Windows from a Gtk widget should not be destroyed, that's done by the widget code when the widget is destroyed or unrealized.

Note that the final release of memory only actually takes place under the Gtk main loop (gtk-main etc), so be sure it runs (periodically at least) when creating and destroying.

Pixels are represented as integers, in the usual Gdk fashion. Guile Gtk makes no attempt to track what pixels are allocated in what colormaps, any management of that is left to applications.

The following standard Gdk functions have particular notes for the Guile Gtk interface.
— Function: gdk-bitmap-create-from-data window data width height

Return a new GdkBitmap of widthxheight created from raw data bytes in XBM format (which is bits of each row packed into bytes, least significant bit first, and each row padded to a byte boundary). data can be a string, a vector of integers, or a uniform vector of bytes. In each case the length must be what widthxheight implies.

— Function: gdk-color-black colormap
— Function: gdk-color-white colormap

The return value is a GdkColor object with red/green/blue fields set and the pixel allocated in the given colormap, or #f if allocation fails.

— Function: gdk-colormap-alloc-colors colormap colors writable bestmatch

colors is a list or vector of GdkColor objects which are to be allocated in colormap. writable and bestmatch are booleans.

The pixel field of each GdkColor is changed to the allocated color. And if bestmatch is true then the red, green and blue fields are changed to the actual color allocated.

The return is a list (failcount statuslist). failcount is the number of allocations which failed, statuslist is a list of #t or #f flags, one for each entry in colors, indicating which colors were successfully allocated or not.

colors can contain strings, the same as other functions taking GdkColor parameters. In this case those entries are changed to new GdkColor objects, with fields set as per gdk-color-parse. Those objects are then allocated and modified as described above.

— Function: gdk-gc-get-values gc

The GdkGCValues type is not used, instead the return is a list,

          (foreground background font function fill
           tile stipple clip-mask subwindow-mode
           ts-x-origin ts-y-origin clip-x-origin clip-y-origin
           graphics-exposures line-width line-style cap-style join-style)
— Function: gdk-gc-new-with-values window [#:background color] [#:cap-style cs] [#:clip-mask pixmap] [#:clip-x-origin x] [#:clip-y-origin y] [#:fill fill] [#:font font] [#:foreground color] [#:function f] [#:graphics-exposures bool] [#:join-style js] [#:line-style ls] [#:line-width n] [#:stipple pixmap] [#:subwindow-mode swm] [#:tile pixmap] [#:ts-x-origin x] [#:ts-y-origin y]

The GdkGCValues type is not used, instead keyword arguments are taken corresponding to the fields of that structure.

For example,

          (gdk-gc-new-with-values my-window
                                  #:foreground "orange"
                                  #:line-width 5
                                  #:graphics-exposures #f)
— Function: gdk-image-new-bitmap visual data width height

Create a GdkImage bitmap of widthxheight using the given data. data is raw byte values, either as a string, a vector of integers, or a uniform vector of bytes. In each case the length of data must be what widthxheight implies. The data format is not well documented by Gdk, but the bits of each row are packed into bytes (most significant bit first), and each row padded out so the next starts on a byte boundary.

data is copied to form the image, so changes with gdk-image-put-pixel etc don't alter the original data. (Unlike at the C level, where the data space there is acquired and used directly by the image.)

— Variable: gdk-major-version
— Variable: gdk-minor-version

These are set from the corresponding Gtk library variables gtk_major_version and gtk_minor_version, rather than the compile-time constants GTK_MAJOR_VERION etc. This means the values seen in Scheme code are the library actually used at run time, not merely the one Guile Gtk was compiled against.

— Function: gdk-mbstowc str

Convert a string of multi-byte characters to wide characters. The return is a vector of integers (per notes for GdkWChar above), or #f if conversion failed.

— Function: gdk-pixmap-create-from-xpm window bitmaploc transpcolor filename
— Function: gdk-pixmap-colormap-create-from-xpm window colormap bitmaploc transpcolor filename
— Function: gdk-pixmap-create-from-xpm-d window bitmaploc transpcolor string
— Function: gdk-pixmap-colormap-create-from-xpm-d window colormap bitmaploc transpcolor string

Return a GdkPixmap created from an XPM file or string data.

bitmaploc is a vector or list of length 1, into which the GdkBitmap created for the transparency mask is stored. If the bitmap is not wanted, bitmaploc can be #f.

— Function: gdk-pixmap-new drawable width height [depth]

depth defaults to -1, meaning copy from drawable.

— Function: gdk-rectangle-intersect rect1 rect2

The return is a rectangle which is the intersection of rect1 and rect2, or #f for no intersection.

— Function: gdk-set-locale

gdk-set-locale is called automatically when the (gtk-2.0 gdk) module is loaded, so applications don't need to do so explicitly.

— Function: gdk-window-get-deskrelative-origin window
— Function: gdk-window-get-origin window
— Function: gdk-window-get-position window
— Function: gdk-window-get-root-origin window
— Function: gdk-window-get-size window

Unlike other multiple-return values functions, these return a pair (x . y) or (width . height), rather than a list.

— Function: gdk-window-new parent width height event-mask wclass wtype [#:colormap colormap] [#:cursor cursor] [#:title title] [#:visual visual] [#:wmclass name class] [#:x x] [#:y y]

The GdkWindowAttr structure is not used, instead mandatory fields are taken as fixed arguments, and the optional fields in keyword form. For example, for a top-level window,

          (gdk-window-new #f 200 100 '(exposure-mask) 'input-output 'toplevel
                          #:title "my window")
— Function: gdk-window-set-geometry-hints window [#:aspect min max] [#:base-size width height] [#:max-size width height] [#:min-size width height] [#:pos] [#:user-pos] [#:user-size] [#:win-gravity grav] [#:resize-inc width height]

The GdkGeometry structure is not used, instead optional keyword arguments are taken. The keyword names correspond to the GdkWindowHints enumeration, and the arguments are the values for the fields of the GdkGeometry structure.

For example,

          (gdk-window-set-geometry-hints my-window
                                         #:min-size 20 10
                                         #:aspect 1.0 2.0
                                         #:win-gravity 'south-east)
— Variable: pango-scale

The PANGO_SCALE constant.

The following standard Gdk functions are not provided, for the reasons outlined.
— Function: gdk-init
— Function: gdk-init-check

There are no separate init functions to call, all initializations are done automatically when the (gtk-2.0 gdk) module is loaded.

— Function: gdk-window-get-user-data window
— Function: gdk-window-set-user-data window data

Gtk sets the “user data” on a window to point to the associated widget, and uses this for event dispatch. Non-widget windows need NULL to avoid another value being treated as a widget pointer. On this basis the user data generally cannot be used by applications.

If some sort of attached data is required then the suggestion is to use Guile object properties (see Object Properties). Because the Scheme-level object is kept alive as long as the window exists, such properties remain until the window is destroyed.