START-INFO-DIR-ENTRY * gtk-guile: (gtk-guile). Guile interface to Gtk. END-INFO-DIR-ENTRY Gtk Guile ********* This manual describes how to install and use the Guile interface to Gtk, version {No value for `VERSION'}. Copyright 2003 Kevin Ryde. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by Free Software Foundation. ...Table of Contents... Introduction ************ Guile Gtk makes the Gtk+, Gdk Pixbuf, Glade and Gtk GL graphical user interface libraries available from within Guile. This manual makes no attempt to document those libraries, only how to use them from Guile. (*note The Guile Reference Manual: (guile)Top.) Currently Guile Gtk supports Gtk version 1.2, and versions of Gdk Pixbuf, Glade and Gtk GL corresponding to that. The Guile Gtk home page is `http://non-gnu.org/guile-gtk'. A mailing list for users and developers is available, see the home page for details. As a taste of Guile Gtk style, here is a hello world program. Those familiar with Gtk should find it straightforward. (use-modules (gtk gtk)) (define top (gtk-window-new 'toplevel)) (gtk-signal-connect top "destroy" gtk-exit) (define label (gtk-label-new " Hello world! ")) (gtk-container-add top label) (gtk-widget-show-all top) (gtk-main) Installing ********** To build and install you will need Guile 1.6.4 or higher, and Gtk version 1.2.x. Gdk Pixbuf, Glade and Gtk GL are optional, support for them will be built if they're available. Guile Gtk uses an Autoconf, Automake and Libtool based configuration system. A basic build can be made with, ./configure make Some self-tests can be run with make check And you can install (under `/usr/local' by default) with make install The file `INSTALL' has generic information about `./configure'. Running `./configure --help' will print a summary of the usage and options. The following Guile Gtk specific options are available. `--with-gdk-pixbuf=yes/no' `--with-libglade=yes/no' `--with-gtkgl=yes/no' Enable or disable Gdk Pixbuf, Glade, or Gtk GL support, respectively. The default for each is to enable it if available. Known Problems ************** `app' Don't be tempted to define `app' to some sort of widget or the like. In Guile 1.6.4 `app' is used for the implementation of the module system. Reporting Bugs ************** If you think you've found a bug in Guile Gtk, please investigate and make a full report. Include the following in any report, * System and CPU type, obtained from running `./config.guess' (or `uname -a' if your system is unknown). * The versions of Guile and Guile Gtk, the configuration options used, and if patched or packaged then say so. * The build compiler and its version. * A test program illustrating the problem. Describe how to run it, what it does, and what you think it should do. * If you get a Scheme level error, include the backtrace obtained from running with `guile --debug'. * If you get a C level crash, try running under the debugger and include a backtrace (`where' in GDB) if it's informative. * If the bug is related to `./configure', then the contents of `config.log'. Send your report to . General Conventions ******************* Unless otherwise stated, Gtk+ functions and variables are made available in Guile with names transformed to Guile conventions. This means underscores become hyphens, and only lower case is used. For instance the C function `gtk_label_new' is `gtk-label-new' in Guile, or `GTK_WIDGET_FLAGS' is `gtk-widget-flags'. The following general rules are applied to parameters and return values. `NULL' `NULL' is represented as `#f' within Guile, for functions which accept or return `NULL'. `int', `gint', etc All Glib integer types are simply Guile integers. Range checks are applied to parameters, and "inexact" values are not accepted, even if they happen to be integers. (*note Exact and Inexact Numbers: (guile)Exactness.) `gboolean' Booleans are returned as the usual Guile `#t' and `#f'. Any non-`#f' value is taken to be true in a parameter. `GList', `GSList' etc Are passed and returned as Guile lists. For instance `gtk-container-children' returns a list of widgets. Arrays Are passed or returned as Guile lists. For instance `gtk-curve-set-vector' takes a list of floats. `enum' enumerations Enumerations are represented in Guile as symbols, with names corresponding to the C definitions but without the prefix indicating their type. For instance `GtkWindowType' value `GTK_WINDOW_TOPLEVEL' is just the symbol `toplevel'. `enum' flags Sets of flags are represented in Guile as a list of symbols, possibly an empty list, with names corresponding to the C definitions but without the prefix indicating their type. For example a `GdkModifierType' value could be a list `(shift-mask control-mask)'. Signal names Signal names are Guile strings, for instance `"clicked"' or `"map_event"'. Signal handler functions At the Guile level 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 `GtkEvent', and expects a return value. (define (my-expose-handler) (do-some-drawing) #f) ;; propagate event to other handlers (gtk-signal-connect drawarea "expose_event" my-expose-handler) The object and client data parameters 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. *note The Concept of Closure: (guile)About Closure.. Multiple return values A list of values is returned for functions with multiple return values. For example at the C level `gtk_pixmap_get' returns a `GdkPixmap' and a `GdkBitmap' via pointers. Guile Gtk `gtk-pixmap-get' returns these in a two-element list. Threading Guile threads can be used by a Guile Gtk program, and the Glib library thread primitives are setup to use the Guile functionality. Gtk functions are not thread-safe, but Guile Gtk avoids problems in this area by preventing other threads running while it's in Gtk. This means an application doesn't have to follow the normal rules for threaded Gtk programs in the use of `gdk-threads-enter' and `gdk-threads-leave', but those functions are still available and still work in the usual way. Gdk Module ********** The Gdk interface module can be used with (use-modules (gtk gdk)) A call to `gdk_init' is made automatically, an application doesn't need to do that itself. The program command line is searched for standard Gdk arguments and removed when found (for instance `--display'. *note Runtime Environment: (guile)Runtime Environment.. The following rules apply to the various Gdk types. Equality Currently Gdk objects are not uniquely represented by a single Guile level object, meaning they cannot be compared with `eq?', and unfortunately currently `equal?' cannot be used either. Gdk functions like `gdk-font-equal' and `gdk-color-equal' can be used in the usual way though. `GdkAtom' Is passed and returned as a Guile symbol, for example `WM_NAME'. `GdkColor' As a convenience, functions expecting a `GdkColor' object can be passed a string, which will be parsed and allocated to a pixel in the default colormap, as per `gdk-color-intern' (*note Gdk Extras::). `GdkCursor' As a convenience, functions expecting a `GdkCursor' object can be passed a Guile symbol, which will be converted to a cursor object as per `gdk-cursor-new'. The symbol should be from the `GdkCursorType' enumeration, translated to Guile form in the usual Guile Gtk fashion. For example `GDK_CROSS_REVERSE' would be `cross-reverse'. `GdkFont' As a convenience, functions expecting a `GdkFont' object can be passed a string, which will be loaded as per `gdk-font-intern' (*note Gdk Extras::). `GdkPoint' Is represented as a pair, with `x' in the `car' and `y' in the `cdr'. (*note Pairs: (guile)Pairs.) 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-pixmap-new drawable width height [depth] DEPTH defaults to -1, meaning copy from DRAWABLE. Gdk Extras ********** The following are extra Gdk level functions provided by Guile Gtk. - Function: gdk-color-intern color If COLOR is a `GdkColor' object, return it. If it's a string then parse it using `gdk-color-parse' and allocate a pixel in the default colormap using `gdk-color-alloc'. A program can use `gdk-color-intern' as an easy way to convert strings to `GdkColor' objects, so as to avoid repeatedly having that done when calling functions expecting a color. - Function: gdk-font-intern font If FONT is a `GdkFont' object, return it. If it's a string then load that font using `gdk-font-load', throwing an error if that function fails. A program can use `gdk-font-intern' as an easy way to convert strings to `GdkFont' objects, so as to avoid repeatedly having that done when calling functions expecting a font. Gtk Module ********** The Gtk interface module can be used with (use-modules (gtk gtk)) A call to `gtk_init' is made automatically, an application doesn't need to do that itself. The program command line is searched for standard Gtk arguments, and removed when found (for instance `--gtk-module'. *note Runtime Environment: (guile)Runtime Environment.. The following rules apply to the various Gtk types. Gtk Objects Type predicates like `GTK_IS_CHECK_BUTTON' are implemented as for instance `gtk-check-button?'. There are no type checking casts like in C, Guile functions expecting a particular object class always check they get that class, or a sub-class. Each Gtk object is represented uniquely at the Scheme level, so widgets etc can be compared or hashed with `eq?'. An object will be destroyed when garbage collected, assuming it's not otherwise in use by Gtk. `GtkAdjustment' All the fields can be read or set directly, for instance `gtk-adjustment-page-size' or `gtk-adjustment-set-lower'. Note that `gtk-adjustment-set-value' is the corresponding C function, and will emit the `value_changed' signal. The other `set' functions are Guile Gtk field setters and an application should call the standard `gtk-adjustment-changed' when ready to emit the `changed' signal. 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-exit [exitcode] EXITCODE defaults to 0, meaning normal successful termination. - 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 `GtkAdjustment' objects. - 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. (*note General Conventions::, for how FUNC is called.) - 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. Gtk Extras ********** The following are extra Gtk level functions provided by Guile Gtk. - Function: gtk-callback-trampoline [tramp] Get or set the trampoline procedure for Gtk callbacks. With no arguments, the current trampoline is returned. With an argument, the trampoline procedure is set, and the old procedure returned. When making a callback for a signal or similar, Guile Gtk goes through this trampoline. TRAMP is called as `(TRAMP proc args)', where `proc' is the application procedure to call, and `args' is a list of arguments for it (possibly empty). A minimal trampoline would be, (define (my-trampoline proc args) (apply proc args)) which could also be written as `(define my-trampoline apply)'. The default trampoline uses `catch' to trap errors from the callback, and displays them in a window (*note Catching Exceptions: (guile)Catch.). A stack backtrace is included if the Guile `debug' option is enabled (*note Debugger options: (guile)Debugger options.) The aim is to give the user some feedback, in the GUI, about what has gone wrong, rather than suddenly terminating. An application can set a new trampoline to do this in its preferred way. - Function: gtk-color-selection-get-current-color colorsel Return a `GdkColor' with the current color from the COLORSEL widget. This color is not allocated to any colormap, so the `pixel' field is unspecified. This is a standard function in Gtk 2, and Guile Gtk makes it available under Gtk 1.2 also. The following functions are provided by (use-modules (gtk threads)) - Function: gtk-threads-ensure-handler Start a Gtk main loop in a new Guile thread, if this function has not previously been called. This is a convenient way for an application ensure a main loop, but go on to do other things. The main loop is started within a `gdk-threads-enter' / `gdk-threads-leave' pair in the usual way for a threaded program, as per the following code. (Though in fact it's done with a `dynamic-wind' so enters and leaves are correctly handled if a continuation is captured in `gtk-main'.) (gdk-threads-enter) (gtk-main) (gdk-threads-leave) - Function: gtk-threads-handler? Return true if `gtk-threads-ensure-handler' has started a Gtk main loop. Obsolete Features ***************** The following functions are considered obsolete and are not recommended for use in new programs. - Function: gtk-standalone? Return true if Guile Gtk is running as a standalone program. This is now always true. In the past a `guile-gtk' executable existed and had an option to indicate an interactive read-eval-print loop should be started, in which case `gtk-standalone?' returned `#f'. - Function: gtk-standalone-main top-widget When running standalone (`gtk-standalone?' returns true), run `gtk-main' and connect the `destroy' signal of TOP-WIDGET to `gtk-exit' so the program will exit when that widget is destroyed. When not standalone, do nothing and return immediately. Since `gtk-standalone?' is now always true, an application can just as easily connect the signal and run `gtk-main' itself. (gtk-signal-connect top-widget "destroy" gtk-exit) (gtk-main) Example Programs **************** The `examples' subdirectory in the sources contains various programs illustrating Guile Gtk. `calc.scm' A HP48 style desk calculator. This takes quite a bit of code by the time all the widgets are setup, but it's well commented. A `.calcrc' in the user's home directory can add new buttons. The ability to load user extensions is a powerful feature and a significant advantage Guile Gtk has over the regular C interface to Gtk. `calendar.scm' A tiny program showing the `GtkCalendar' widget. `clist.scm' Display the password file in a window. (You might need to enlarge the window manually.) `continuations.scm' Illustrate the use of Scheme continuations to have application code wait for a dialog to return, but all the while run the usual Gtk main loop. `hello-world.scm' A simple program illustrating a button which can be pressed to print a familiar message. `metaspline.scm' A Metafont style bezier spline editor, using the Gdk drawing primitives. `simple.scm' Another simple program, with a label and a button. `run-glade.scm' Load and run a Glade application. For instance `simple.glade', guile -s run-glade.scm simple.glade `test-dnd.scm' `test-gdk.scm' `test-glade.scm' `test-gtk.scm' Test programs for drag-and-drop, Gdk, Glade and Gtk respectively. These are primarily for the developers' use, but can be run to see something happen and to test Guile Gtk is working. Concept Index ************* Booleans: See ``General Conventions''. Bugs: See ``Reporting Bugs''. Bugs, known: See ``Known Problems''. Check: See ``Installing''. Configure: See ``Installing''. Conventions: See ``General Conventions''. Example programs: See ``Example Programs''. Gdk extras: See ``Gdk Extras''. Gdk module <1>: See ``Gdk Extras''. Gdk module: See ``Gdk Module''. Gtk extras: See ``Gtk Extras''. Gtk module <1>: See ``Gtk Extras''. Gtk module: See ``Gtk Module''. Home page: See ``Introduction''. Installing: See ``Installing''. Introduction: See ``Introduction''. Known problems: See ``Known Problems''. Mailing list: See ``Introduction''. NULL: See ``General Conventions''. Obsolete features: See ``Obsolete Features''. Reporting bugs: See ``Reporting Bugs''. Self tests: See ``Installing''. Web page: See ``Introduction''. Function and Type Index *********************** gdk-color-intern: See ``Gdk Extras''. gdk-font-intern: See ``Gdk Extras''. gdk-pixmap-new: See ``Gdk Module''. GdkAtom: See ``Gdk Module''. GdkColor: See ``Gdk Module''. GdkCursor: See ``Gdk Module''. GdkFont: See ``Gdk Module''. GdkPoint: See ``Gdk Module''. gtk-box-pack-end: See ``Gtk Module''. gtk-box-pack-start: See ``Gtk Module''. gtk-callback-trampoline: See ``Gtk Extras''. gtk-color-selection-get-current-color: See ``Gtk Extras''. gtk-exit: See ``Gtk Module''. gtk-pixmap-new: See ``Gtk Module''. gtk-pixmap-set: See ``Gtk Module''. gtk-scrolled-window-new: See ``Gtk Module''. gtk-signal-connect: See ``Gtk Module''. gtk-standalone-main: See ``Obsolete Features''. gtk-standalone?: See ``Obsolete Features''. gtk-table-attach: See ``Gtk Module''. gtk-threads-ensure-handler: See ``Gtk Extras''. gtk-threads-handler?: See ``Gtk Extras''. GtkAdjustment: See ``Gtk Module''. ...Table of Contents...