Next: , Previous: Gdk Extras, Up: Top

7 Gtk Module

The Gtk interface module can be used with

     (use-modules (gtk-2.0 gtk))

Calls to gtk_init and gtk_set_locale are made automatically, an application doesn't need to make them itself. Standard Gtk command line options are taken from the program command line (eg. ‘--gtk-module’), and removed from there, leaving other options and the rest of the command line for the application. see Runtime Environment.

The following rules apply to the various Gtk types.

The following field accessors and setters are provided.
— Function: gtk-adjustment-value adj
— Function: gtk-adjustment-lower adj
— Function: gtk-adjustment-upper adj
— Function: gtk-adjustment-step-increment adj
— Function: gtk-adjustment-page-increment adj
— Function: gtk-adjustment-page-size adj
— Function: gtk-adjustment-set-lower adj val
— Function: gtk-adjustment-set-upper adj val
— Function: gtk-adjustment-set-step-increment adj val
— Function: gtk-adjustment-set-page-increment adj val
— Function: gtk-adjustment-set-page-size adj val

These only set the respective fields, it's up to an application to emit the standard changed signal when ready (eg. using gtk-adjustment-changed).

Note that gtk-adjustment-set-value is instead the corresponding standard Gtk function. It sets the value field and emits the value_changed signal.

The following field accessors are provided.
— Function: gtk-clist-selection clist

Return a list of integers, being the selected rows.

Values for GtkResponseType are represented just as integers, and in particular are passed that way in the GtkDialog response signal. The following variables hold pre-defined values.
— Variable: gtk-response-none
— Variable: gtk-response-reject
— Variable: gtk-response-accept
— Variable: gtk-response-delete-event
— Variable: gtk-response-ok
— Variable: gtk-response-cancel
— Variable: gtk-response-close
— Variable: gtk-response-yes
— Variable: gtk-response-no
— Variable: gtk-response-apply
— Variable: gtk-response-help

The following field accessors are provided.
— Function: gtk-style-white st
— Function: gtk-style-black st
— Function: gtk-style-fg st
— Function: gtk-style-bg st
— Function: gtk-style-light st
— Function: gtk-style-dark st
— Function: gtk-style-mid st
— Function: gtk-style-text st
— Function: gtk-style-base st

Return GdkColor objects.

— Function: gtk-style-white-gc st
— Function: gtk-style-black-gc st
— Function: gtk-style-fg-gc st
— Function: gtk-style-bg-gc st
— Function: gtk-style-light-gc st
— Function: gtk-style-dark-gc st
— Function: gtk-style-mid-gc st
— Function: gtk-style-text-gc st
— Function: gtk-style-base-gc st

Return GdkGC objects.

Signal names are strings, the same as at the C level, for instance "clicked" or "map_event".

Signal handler procedures are passed the same parameters as the C code functions, except the object and client-data are omitted. The return value is used when the signal expects a return value.

For instance the clicked signal from a GtkButton passes no parameters,

          (define (my-click-handler)
            (display "hello\n"))
          (gtk-signal-connect button "clicked" my-click-handler)

Or an expose_event passes just a GdkEvent, and expects a return value.

          (define (my-expose-handler)
            #f)  ;; propagate event to other handlers
          (gtk-signal-connect drawarea "expose_event" my-expose-handler)

The object and client data parameters in the C level calls are deliberately omitted. Such things can be handled in a more Scheme-like and flexible way with a closure, ie. captured variables with desired values (see The Concept of Closure).

Signal handler calls are made via a trampoline to facilitate error handling, see Gtk Extras.

The following standard Gtk functions have particular notes for the Guile Gtk interface.
— Function: gtk-box-pack-start box child [expand [fill [padding]]]
— Function: gtk-box-pack-end box child [expand [fill [padding]]]

expand and fill default to #f, padding defaults to 0.

— Function: gtk-color-selection-get-color colorsel

Return a GdkColor object with red, green and blue fields set to the current colour from colorsel. The colour is not allocated in any colormap and the pixel field is zero.

Note that unfortunately this is not the same as the C function gtk_color_selection_get_color, but instead like the Gtk 2 gtk_color_selection_get_current_color.

— Function: gtk-color-selection-set-color colorsel color

Set the current colour in colorsel to the red, green and blue fields of the given GdkColor object. The opacity is set to 1.0, when in use.

Note that unfortunately this is not the same as the C function gtk_color_selection_set_color, but instead like the Gtk 2 gtk_color_selection_set_current_color.

— Function: gtk-exit [exitcode]

exitcode defaults to 0, meaning normal successful termination.

— Function: gtk-idle-add proc
— Function: gtk-idle-add-priority priority proc
— Function: gtk-idle-add-full priority proc

As per the signal handlers, there's no “data” parameter to the idle callbacks. proc is simply called (proc) and should return non-#f to continue being called, or #f to stop.

Currently there's no destroy notify callback procedure for gtk-idle-add-full, perhaps this will change in the future.

— Function: gtk-input-add port inputconds proc

Register proc to be called when inputconds is satisfied on port, and return the input source ID.

As per the signal handlers, there's no “data” parameter to the input handler, it's called as (proc fdes conds).

This function doesn't offer the destroy notify callback available from gtk_input_add_full, perhaps this will change in the future.

— Function: gtk-main
— Function: gtk-main-iteration
— Function: gtk-main-iteration-do

In a signal handler or other callback, an application cannot use an exception or new continuation to escape from gtk-main and friends, since Gtk has no understanding of such things. There are no restrictions on control flow within a callback, just on escaping out of it.

One possibility for applications wanting such things is to have an explicit loop calling gtk-main-iteration and hold a list of pending actions to be taken outside that function. This is done in the sample program continuations.scm (see Example Programs). The callback trampoline feature might be able to help with this (see Gtk Extras).

— Function: gtk-menu-popup menu parentmenushell parentmenuitem button time

There's no position function accepted, instead NULL is used, which means put the menu under the current mouse position. Perhaps this will change in the future.

— Function: gtk-object-get object prop

Get an object property. The prop property name can be either a keyword or symbol. The property value is returned, or #f if there's no such property or it cannot be read.

gtk-object-get only gets one property value, unlike the C function gtk_object_get which can get multiple property values in one call.

— Function: gtk-object-new type [prop value]...
— Function: gtk-object-set object [prop value]...
— Function: gtk-widget-new type [prop value]...
— Function: gtk-widget-set widget [prop value]...

The prop property names are taken as either keywords or symbols, followed by suitable values. This is in contrast to the C functions, where strings are used for property names. For example,

          (gtk-widget-new 'GtkButton #:label "some words" #:relief 'half)

The values set are type checked and converted in the usual way, they must correspond to the property type.

— Variable: gtk-major-version
— Variable: gtk-minor-version
— Variable: gtk-micro-version
— Variable: gtk-binary-age
— Variable: gtk-interface-age

These are set from the corresponding Gtk library variables gtk_major_version etc, 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: gtk-pixmap-new pixmap [bitmap]
— Function: gtk-pixmap-set pixmap [bitmap]

bitmap defaults to #f, meaning no mask.

— Function: gtk-scrolled-window-new [hadjustment [vadjustment]]

hadjustment and vadjustment default to #f, meaning create new adjustment objects.

— Function: gtk-set-locale

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

— Function: gtk-signal-connect object name func [objectsignal [after]]

objectsignal has no purpose and should always be #f, which is its default. after defaults to #f, meaning func is called before object runs the default handler for this signal.

It will be noted that gtk-signal-connect has the objectsignal and after parameters like gtk_signal_connect_full, but currently there's no access to the destroy notify callback.

— Function: gtk-table-attach table child left right top bottom [xopts [yopts [xpad [ypad]]]]

xopts and yopts each default to (expand fill), xpad and ypad default to 0.

— Function: gtk-text-insert text font foreground background string [length]

The default length is -1, meaning the whole string.

— Function: gtk-widget-size-request widget

The requisition is returned as a pair (width . height).

The following standard Gtk functions are not provided.
— Function: gtk-container-foreach

This iterator is not provided, instead the suggestion is to apply the standard Scheme for-each to the return from gtk-container-children. (That's probably how gtk-container-foreach would be implemented anyway, to make it safe for continuations and exceptions.)

— Function: gtk-init

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