[-- Attachment #1: Type: text/plain, Size: 984 bytes --]
Marko Rauhamaa <marko@pacujo.net> writes:
>
> Ah, ok. I mentioned this to Marius, and he expressed the wish that it
> should be enough to read the GTK+ C library documentation.
Of course you have to know the transformations for names and types and
stuff.
Below is where I'm up to (text output of .texi). It basically
represents an expansion of various bits of the README. There's
various issues to be considered about what's meant to be documented
features and not. For instance I'm not sure if the (gtk threads)
module is to be considered experimental or final.
I haven't got around to saying anything about GdkPixbuf. And nothing
about Glade yet either (partly because I only know a little about how
it's supposed to work).
If the TODO file entry about integration with gnome-guile comes to
pass then I'd be happy to add words about that stuff too. (I think
it'd be a good thing to be all-in-one. It's easy with autoconf to
build only what's possible or what's desired.)
[-- Attachment #2: guile-gtk.txt --]
[-- Type: text/plain, Size: 20491 bytes --]
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 <guile-gtk@sources.redhat.com>.
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...