File: README

package info (click to toggle)
guile-gtk-1.2 0.31-3
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 2,544 kB
  • ctags: 2,413
  • sloc: sh: 11,073; ansic: 3,380; lisp: 1,058; makefile: 106
file content (393 lines) | stat: -rw-r--r-- 13,101 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
README for guile-gtk-1.2
************************

This is some glue code to make Gtk accessible from Guile.  It provides
a convenient interface for Scheme programmers to develop graphical
user interfaces.  This version of guile-gtk is stripped down and
intended for people who want to use Gtk+-1.2 without Gnome.

Guile-gtk was started by Marius Vollmer <mvo@zagadka.ping.de> and is
currently mantained by Ariel Rios<ariel@arcavia.com> and other
intrepid Guile hackers around the world.

Guile-gtk is free software licensed under the GPL.

New versions of this package will be available from

    http://www.ping.de/sites/zagadka/guile-gtk/

or in one of the mirrors:

    http://linux.cem.itesm.mx/~ariel/guile-gtk.php        (MEXICO)

You can also get at the most recent development sources thru the Gnome
CVS repository.  Guile-gtk is contained in the gnome-guile module.
See www.gnome.org for details.

Guile-gtk was made with the idea of making it as generic as possible.
As a result, it should be easy to extend it to new widgets and other Gtk
extensions.

It might even be possible to use some of this code for wrapping
completely different C libraries, but that was not the goal.

To somewhat unify the different high-level language bindings (such as
the ones for Perl, Python, Objective C, maybe Java, etc.) Marius
Vollmer tried to collect the salient bits of the Gtk API into a formal
description.

You should be able to generate large parts of the language specific
glue code from it.  Unfortunately, this formal description hasn't
stabilized yet and we are currently more interested in completeness than
in generality.

   Table of Contents

   - Acknowledgements
   - Bugs
   - Mailing List
   - Gtk versions
   - Related stuff
   - Installing
   - Testing
   - Wrapping Your Own Widgets      
   - Composite Types and `call-by-reference'
   - Documentation


Acknowledgements
----------------

Many people have contributed to guile-gtk by now.  Many thanks to all
of them!  Please refer to the ChangeLog for details.


Bugs
----

The main aim still is robustness, with an eye towards completeness.  It
should not be possible to crash your program from Scheme.  Guile-gtk
has to cope with anything.  So if you find that your program crashes
and you think it is due to a bug in your Scheme code, you have
actually found a bug in guile-gtk or Gtk.

Please report these bugs to the current maintainer,Ariel Rios,
<ariel@arcavia.com> or to the mailing list <guile-gtk@sourceware.cygnus.com>

Mailing List
------------
To subscribe to the list send mail to:
<guile-gtk-subscribe@sourceware.cygnus.com>

To post messages please write to:
<guile-gtk@sourceware.cygnus.com>

Gtk Versions
------------

This version of guile-gtk only supports Gtk+-1.2.  For Gtk+-2.0 and
for Gnome support use the main version of gnome-guile.

Related Stuff
-------------

Jeff Dike is writing a layer of macros/functions on top of guile-gtk
that makes it simpler and fairly uniform to create widgets within
Guile.  It is available here

     http://www.mv.com/ipusers/karaya/simple-gtk/simple-gtk.scm

David Lutterkort is writing a tool that makes it easy to give command
line programs with too many options a nice GUI.  Available here

     http://www.cs.purdue.edu/homes/lutterdc/software/wickel.html

There is also a list of applications developed using guile-gtk in:

     http://erin.netpedia.net/guile-gtk/apps.html

Installing
----------

See INSTALL for generic installation instructions.

This package will build and install a new shared library,
"libguilegtk-1.2", that contains the glue between Guile and Gtk+.
This library is used to implement most of the (gtk gtk) module.

The package will also install "build-guile-gtk", a program for
generating glue code for arbitrary *.defs files.

NOTE: This package installs its Scheme code in a location determined
by the prefix given to the configure script.  It does not pay
attention to where your Guile is installed.  When Guile and this
package are installed under the same prefix, everything is fine.  When
you use a different prefix for this package, you need to make sure
that Guile knows about this location.  For example, when you install
this package under /usr/local/stuff/guile-gtk, you may want to add
GUILE_LOAD_PATH=/usr/local/stuff/guile-gtk/share/guile to your
environment.  Or you might want to make some symlinks.  This package
does not try to be clever about these issues, as there are too many
variations and potential solutions.

Testing
-------

    % cd examples/
    % guile -s test-gtk.scm

should pop up a familiar pile of buttons.  Not every test has been
implemented, tho.  All unexpected behaviour is probably a bug and I
would be glad if you would tell me about it.

Wrapping Your Own Widgets
-------------------------

There is a complete autoconfed/automade example for this.

After installing the guile-gtk package, change to the examples/foo/
directory:

  % cd examples/foo
  % aclocal
  % autoconf
  % automake -a
  % ./configure
  % make

Again: you need to have guile-gtk installed for this to work!

Now you should have a new module `(gtk-1.2 foo)'.  You can test it
thus:

  % guile -s test-foo.scm

Here is the general procedure:

When you have some Gtk widgets that are not described in gtk-1.2.defs
or gdk-1.2.defs, you can use build-guile-gtk to automatically generate
glue code for them.  Here is how to wrap the hypothetical GtkFoo
widget and its related function gtk-foo-new.  They are assumed to live
in gtkfoo.h and libfoo.

- Write the foo.defs file

  ;; We use the types defined in gtk-1.2.defs

  (import "gtk-1.2.defs")

  (define-object GtkFoo (GtkWidget))

  (define-func gtk_foo_new
    GtkFoo
    ())

  (options
    ;; Includes needed to compile code that uses GtkFoo.
    (includes "#include <gtkfoo.h>")
    ;; The name of the generated initialization function.
    (init-func "foo_init_glue")
    ;; Libraries needed to link. libguile-gtk-foo will contain
    ;; the glue code and libfoo contains the widget itself.
    (libs "-lguile-gtk-foo -lfoo"))

- Write the foo.scm file

  (define-module (gtk-1.2 foo)
    :use-module (gtk-1.2 dynlink))

  ;; Call the init function, either using a pre-linked -lguilefoo or
  ;; dynamically linking it.
  (merge-compiled-code "foo_init_glue" "libguile-gtk-foo")

- Generate the glue code

  % build-guile-gtk-1.2 glue foo.defs >foo-glue.c

- Compile the glue code into a shared library, using libtool

  [This will be simplified and then explained.  Right now, keep in
   mind to use gtk-config and build-guile to get all necessary flags and
   libraries.]

  % libtool --mode=link ... -o libguile-gtk-foo.la ...

- Install the shared library, again using libtool.

  % libtool --mode=install cp libguile-gtk-foo.la <exec_prefix>/lib/

- Install the foo.scm file

  % cp foo.scm <prefix>/share/guile/gtk-1.2/foo.scm

- Install the *.defs files for other people to use.

  % cp foo.defs foo.defs.guile <prefix>/share/guile-gtk/

Now you should be able to just (use-modules (gtk-1.2 foo)).

Composite Types and `call-by-reference'
---------------------------------------

Guile-gtk has (still experimental) support for composite types like
lists and vectors.  On the Gtk+ side, the types GSList (singly linked
list), GList (doubly linked list), and counted and fixed length
vectors are supported.  On the Scheme side, you can use Scheme lists
and Scheme vectors.  You can mix these types freely.  That is, you can
use a list on the Scheme side to represent a vector on the Gtk+ side,
and vice versa.

Composite types have modes associated with them.  They can be `in',
`out', or `inout'.  When a composite type is marked with a `in' mode,
the Gtk+ side is not allowed to make changes to the contents of the
composite.  When it is `out', it must initialize the contents before
it returns and is not allowed to read it prior to initialization.
Consequently, mode `inout' indicates that the Gtk+ side may both read
and write the composite freely, and that the contents has been
initialized by the caller.  On the Scheme side, mode `out' turns off
type checking for the contents of composites and the initial values of
the composite passed to Gtk+ will be undefined.

The default mode is `in'.

The available variations are:

  [ *.defs file syntax ]             [ C side function arguments ]
  [ Comment ]

  (slist <type> [<mode>])            GSList *lst
  For singly linked lists.  Scheme owns the memory of the list nodes.

  (list <type> [<mode>])             GList *lst
  For doubly linked lists.  Scheme owns the memory of the list nodes.

  (cvec <type> [<mode>])             int len, <type>* vec
  For counted vectors.  The length of the Scheme composite is passed
  to the Gtk+ function.  Scheme owns the memory of the vector.

  (cvecr <type> [<mode>])            <type>* vec, int len
  For counted vectors, reverse order of arguments.  Scheme owns the
  memory of the vector.

  (fvec <type> <len> [<mode>])       <type>* vec
  For fixed length vectors.  The Scheme composite must be of length <len>.
  Scheme owns the memory of the vector.
  
  (ret <type>)                       <type>* vec
  Abbreviation for (fvec <type> 1 out)

These composite types are also intended to be used for
call-by-reference arguments.  Neither Scheme nor C really has these
call-by-reference arguments, so guile-gtk wont either.  In C, you
would pass a pointer to the desired object; in Scheme you use a
one-element list or a vector of length one.  For guile-gtk, these
types are modelled with a `fvec' composite type of length one and mode
out, or equivalently but shorter with the `ret' type.

For example, when you have a Gtk+ function with a prototype like

    void gtk_foo (char **strptr);

that deposits some string in *STRPTR (whose memory should be taken
over by the caller), you can wrap it like this:

     (define-func gtk_foo
       none
       ((ret string) strptr))

Usage is a little cumbersome from Scheme.  This code snippet

     (let ((strptr (list #f)))
       (gtk-foo strptr)
       (car strptr))

would yield the returned string.


Documentation
-------------

Nothing available yet, but the Scheme interface to Gtk is very similar
to the C one.  Almost all functions take the same arguments as their C
counterparts.  Exceptions are:

- To access the Gtk functions, you need to use the `(gtk gtk)'
  module.  You can do this with

    (use-modules (gtk gtk))

  or

    (define-module (your module)
      :use-modules (gtk gtk))

  Likewise, you need to use the `(gtk gdk)' module if you want to use
  functions from Gdk.

- Booleans are expressed with Scheme's real boolean values #f and #t.

- Enumerations are expressed with symbols.  For example
  GTK_WINDOW_TOPLEVEL is written as 'toplevel.  The symbols should be
  easy to guess from their C counterparts, but they are not completely
  systematic.  See gtk.defs for the definite details.

- Flags (or bitmasks) are expressed as lists of symbols.  For example
  GTK_EXPAND|GTK_FILL is '(expand fill).

- Callbacks don't take a client-data argument, so you don't have to
  specify one to gtk_signal_connect, or gtk_timeout_add, etc.

- Signal handlers don't get the Object as their first argument.  In my
  view, this would be more often annoying than helpful.

- NULL pointers are expressed as #f.

- Some parameters are optional and get a default value when left
  unspecified.

- Each type that is derived from GtkObject has an associated predicate
  function to test whether a Scheme value is of that type.  The
  predicate for GtkObject is called `gtk-object?', the one for
  GtkRadioButton `gtk-radio-button?', etc.

- gtk-radio-button-new and gtk-radio-button-new-with-label don't take
  a list as their group argument but a GtkWidget whose group is used
  instead.

- Likewise for gtk-radio-menu-item.

- Colors and fonts can be specified with strings, like "red" or
  "fixed".  If you want to convert from these strings to the real
  values (for efficiency reasons, say) you can use the functions
  `gdk-color-intern' and `gdk-font-intern'.

- It might be that your code is loaded into an application that
  already has an event loop running (or will run one after
  initialization is complete).  You should then restrain from calling
  `gtk-main' yourself (except maybe for modal dialog boxes) and you
  should not terminate the program.

  You can use the function `gtk-standalone?' to find out whether your
  code is `standalone', i.e. whether you should call `gtk-main'
  yourself.

  For convenience you can also use

     gtk-standalone-main TOPLEVEL

  This will arrange things so that the program is terminated with
  `gtk-exit' when the TOPLEVEL widget is destroyed and will call
  `gtk-main'.  All these things will only happen when
  `gtk-standalone?' returns true.


And all the things I forgot about.  Be sure to read the NEWS file as
it is currently the only place that documents most details.
"examples/calc.scm" is quite heavily commented, but does not explain
Gtk programming.  It is more an example about extensibility.

Have fun!

Marius Vollmer
Ariel Rios