Re: texinfo documentation

[Kevin Ryde <user42@zip.com.au>]

[-- 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...