/[lambda-gtk]/lambda-gtk/lambda-gtk.html
ViewVC logotype

Contents of /lambda-gtk/lambda-gtk.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (show annotations)
Wed Dec 21 13:48:53 2005 UTC (8 years, 4 months ago) by htaube
Branch: MAIN
CVS Tags: HEAD
Changes since 1.2: +15 -37 lines
File MIME type: text/html
updated stale docs
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3 <head>
4 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
5 <style type="text/css" media="all">
6 body {
7 margin: 1em;
8 padding: 0px;
9 color: black;
10 background-color: white;
11 font: normal 100% sans-serif;
12 }
13 h1 {
14 font: bold 200% sans-serif;
15 color: #666;
16 }
17 h2 {
18 font: bold 168% sans-serif;
19 color: #555;
20 }
21 h3 {
22 font: bold 141% sans-serif;
23 color: #444;
24 }
25 h4 {
26 font: bold 119% sans-serif;
27 color: #333;
28 }
29 h5 {
30 font: bold 100% sans-serif;
31 color: #222;
32 }
33 div#content {
34 padding: 2em 3em;
35 }
36 table {
37 border-top: 1px solid gray;
38 border-bottom: 1px solid gray;
39 }
40
41 th {
42 padding: .25em 2em;
43 border-bottom: 1px solid silver;
44 }
45 td {
46 padding: 0em 2em;
47 }
48
49
50 </style>
51
52 <title>&lambda;gtk</title>
53
54 </head>
55
56 <body>
57
58
59 <div id="content">
60
61 <h1 style="font-size:64px;;"><span>&lambda;</span><span style="color:red">g</span><span style="color:green">t</span><span style="color:blue">k</span></h1>
62
63 <p style="text-align:right;margin-bottom:3em;"><em><span
64 style="font-size:small;">It's GTK in a Lispy way</span></em></p>
65
66 <p>
67 &lambda;gtk is a cross-platform Lisp interface to the complete <a
68 href="http://www.gtk.org">GTK+2</a> family of shared libraries. &lambda;gtk
69 currently runs in the following Lisp environments:
70 </p>
71
72 <ul id="ports">
73 <li>
74 PPC/Darwin <a href="http://openmcl.clozure.com/">OpenMCL</a> 0.14.3 or higher</li>
75 <li>x86/Linux <a href="http://sbcl.sourceforge.net/">SBCL</a> 0.9.7 or higher </li>
76 <li>x86/Linux <a href="http://www.cons.org/cmucl/">CMUCL</a> 19a or higher</li>
77 </ul>
78 <p>
79 and is released under the <a
80 href="http://opensource.franz.com/preamble.html">Lisp Lesser General
81 Public License</a> (LLGPL).
82 </p>
83
84 <p>
85 If you are familiar with Lisp function call syntax and the <a
86 href="http://www.gtk.org/api/">GTK API</a> then programming with
87 &lambda;gtk is straightforward. See <a
88 href="examples/examples.lisp">examples.lisp</a> for some demonstrations
89 translated from the GTK tutorial.
90 </p>
91
92 <h2 id="design">Design</h2>
93
94 <p>
95 Because GTK is so large and complex &lambda;gtk generates its Lisp FFI
96 interfaces from a GTK definition file (gtk.ffi, output by Gary
97 Byers' <a
98 href="http://openmcl.clozure.com/Doc/ch09s07.html">ffigen</a> program)
99 and an API control file (gtk.api) that you can edit and customize in
100 order to generate more or less inclusive interfaces to
101 GTK. &lambda;gtk is organized into two parts: a common file
102 (lambda-gtk-common.lisp) and an implementation file for each target
103 FFI (lambda-gtk-openmcl.lisp, lambda-gtk-cmusbcl.lisp, and so on).
104 With the exception of callbacks (which are required by GTK itself)
105 &lambda;gtk uses only a modest set of features from its host
106 environment and is readily portable to other Lisps, including
107 reasonably featured Schemes.
108 </p>
109
110 <h2 id="features">Features</h2>
111
112 <p>
113 &lambda;gtk provides Lisp programmers with the following set of features:
114 </p>
115
116 <ul>
117 <li>
118 Portable GUI programming across the supported Lisp environments.
119 </li>
120
121 <li>
122 Automatic conversion between Lisp data (booleans, numbers, strings)
123 and their equivalent GTK types. Function arguments that involve C
124 pointers to ints, floats and doubles are also handled automatically:
125 foreign values are allocated and initialized by the wrappers, the
126 pointers are passed to GTK and then dereferenced and returned to the
127 Lisp caller as multiple values.
128 </li>
129
130 <li>
131 Lisp names for GTK's enums, structs and functions. Lisp names are
132 formed by substituting "-" for "_" and (possibly) converting C library
133 prefixes into exported Lisp package prefixes (see documentation
134 section below).
135 </li>
136
137 <li>
138 Lisp accessor functions to read/write slot values in GTK structs.
139 Accessors are named <em>struct.slot</em> but may include more than one
140 slot name, e.g. <code>gtk:Widget.allocation.width</code>. The first
141 argument to all accessors is a pointer to a struct; if the referenced
142 slot is an array then a second required argument provides the index.
143 The last argument to all accessors is an optional <em>value</em>,
144 that, if specified, replaces the current value in the slot. For
145 example:
146 <blockquote>
147 <pre>(gdk:Rectangle.x rect) <span style="color:gray;font-style:italic;">; return rect's x value</span>
148 (gdk:Rectangle.x rect 100) <span style="color:gray;font-style:italic;">; set rect's x value</span>
149 </pre>
150 </blockquote>
151 </li>
152
153 <li>Lisp symbol package(s) that export the GTK API and a read time
154 conditional #+:gtk in *features*.</li>
155
156 <li>A small set of utilities for working with GTK pointers, callbacks
157 and foreign storage in a portable way (see documentation below).
158 </li>
159 </ul>
160
161 <h2 id="lacunae">Lacun&aelig;</h2>
162
163 <p>
164 The project provides a complete FFI to GTK in several different Lisps
165 but is missing some obvious functionality. Here is a list of some
166 missing features tagged by implementation difficulty:
167 </p>
168
169 <ul>
170 <li>[Easy] Add lisp error handling to gtk:define-signal-handler.
171 </li>
172
173 <li>[Medium] Add support for CLISP and/or UFFI and make sure it works
174 on Windows GTK.
175 </li>
176
177 <li>[Hard] Bitfields and slot accessors to bitfields are not supported
178 in SBCL or CMU. This is actually more of a bug than a missing feature
179 since currently the allocation size and slot offsets of a few structs
180 are incorrect. See next point.
181 </li>
182
183 <li>[Hard?] Generate a gtk-x86.ffi definition file for lambda-gtk,
184 possibly using ffigen. That way lambda-gtk could generate bitfields
185 and bitfield accessors in CMU and SBCL.
186 </li>
187
188 <li>[Medium] Add accessors for "struct array" slots in
189 OpenMCL.
190 </li>
191
192 <li>[Medium?] Port &lambda;gtk to Guile. Bill Schottstaedt at CCRMA
193 has a Guile GTK binding already so hopefully his code could be used or
194 adapted.
195 </li>
196
197 <li>[Easy] Define an ASDF installation mechanism for &lambda;gtk.
198 </li>
199
200 <li>[Easy] Implement all the examples in the GTK tutorial for testing
201 purposes.
202 </li>
203
204 </ul>
205
206 <p>Please <a href="#contact">contact me</a> if you would like to help
207 out!</p>
208
209 <h2 id="installation">Installation</h2>
210
211 <ol>
212
213 <li>
214 <p>
215 Download the
216 <a
217 href="ftp://common-lisp.net/pub/project/lambda-gtk/lambda-gtk-0.1.tar.gz">&lambda;gtk
218 sources</a> and restore it to a directory on your machine.
219 </p>
220 </li>
221
222 <li>
223 <p>
224 If you are using OpenMCL, download either:
225 </p>
226 <ul>
227 <li>
228 <a href="ftp://common-lisp.net/pub/project/lambda-gtk/openmcl-darwin-gtk.tar.gz">openmcl-darwin-gtk.tar.gz</a>
229 </li>
230 <li><a href="ftp://common-lisp.net/pub/project/lambda-gtk/openmcl-linux-gtk.tar.gz">openmcl-linux-gtk.tar.gz</a>
231 </li>
232 </ul>
233 <p>
234 and untar it inside either OpenMCL's ccl/darwin-headers/ or
235 ccl/headers/ folder:
236 </p>
237 <blockquote>
238 <pre>$ cd /path/to/ccl/darwin-headers
239 $ tar -zxf openmcl-darwin-gtk.tar.gz
240 </pre>
241 </blockquote>
242 <p>
243 Untarring either archive restores a gtk2/ directory containing seveal
244 .cdb files for the GTK interface.
245 </p>
246 </li>
247
248 <li>
249 Use ASDF to generate the system for your host lisp:
250
251 <blockquote>
252 <pre>
253 (require :asdf)
254 (push "/path/to/lambda-gtk/" asdf:*central-registry*)
255 (asdf:operate 'asdf:load-op :lambda-gtk)
256 (quit)
257 </pre>
258 </blockquote>
259 </li>
260
261 <li>
262 Restart lisp and compile/load the generated FFI. Compiling a full
263 interface will probably take between two and twelve minutes, depending
264 on your Lisp implementation and processor speed. Once the interface
265 is loaded you can start programming in GTK.
266 The <a href="examples/examples.lisp">examples.lisp</a> file is a fine
267 place to start:
268 <blockquote>
269 <pre>
270 (asdf:operate 'asdf:load-op :lambda-gtk-examples)
271 (hello-world)
272 </pre>
273 </blockquote>
274
275 <p>
276 Examples range from the canonical "Hello World" to "Scribble Simple",
277 the most complex demo in the GTK tutorial.
278 </p>
279 </li>
280
281 </ol>
282
283 <h2>Documentation</h2>
284
285 <p>
286 Reading the GTK API reference is the best way to learn how to use
287 &lambda;gtk: other than the simple symbol translations described in
288 this document and the handful of glue functions shown below
289 &lambda;gtk does not add any additional syntax or features of its own
290 to GTK. The generation process is equally simple, there is only one
291 entry point, the lambda-gtk function itself:
292 </p>
293
294 <!-- p>
295 You are looking at it. &lambda;gtk is designed to be used by program
296 developers; the code is reasonably well commented and if you can't
297 figure it out from reading this file and browsing the source code then
298 this project probably isn't for you. There is only one entry point,
299 the lambda-gtk function itself:
300 < /p -->
301
302 <dl>
303 <dt><code>(lambda-gtk <var>file . lib-packaging</var>)</code></dt>
304 <dd>
305 <p>
306 Outputs a Lisp/GTK FFI
307 into <var>file</var>. If <var>lib-packaging</var> is true (the
308 default) then GTK symbols are striped of their C library prefixes and
309 placed in Lisp package named after the libraries: GTK, GDK, G, ATK and
310 PANGO. If <var>lib-packaging</var> is false then only the GTK package
311 is created and the Lisp symbols preserve their GTK library prefix. (It
312 is assumed in this case that the user will use the FFI symbols without
313 any package prefixing whatsoever.) Regardless of
314 how <var>lib-packaging</var> is set, Lisp names always substitute the
315 Lisp hyphen "-" in place of the C underbar "_".
316 </p>
317 <p>
318 The following table shows the effect of <var>lib-packaging</var> on
319 a few representative symbols:
320 </p>
321
322
323 <table>
324 <tr>
325 <th>C name</th>
326 <th>lib-packaging true</th>
327 <th>lib-packaging false</th>
328 </tr>
329 <tr>
330 <td></td>
331 <td><code>gtk:+true+</code></td>
332 <td><code>+gtk-true+</code></td>
333 </tr>
334 <tr>
335 <td><code>gtk_main</code></td>
336 <td><code>gtk:main</code></td>
337 <td><code>gtk-main</code></td>
338 </tr>
339 <tr>
340 <td><code>GdkRectangle.x</code></td>
341 <td><code>gdk:Rectangle.x</code></td>
342 <td><code>GdkRectangle.x</code></td>
343 </tr>
344 </table>
345
346 </dd>
347 </dl>
348
349 In addition to exporting the symbols that GTK itself defines,
350 &lambda;gtk also provides a handful of constants and functions for
351 working with pointers and foreign objects in a portable way. This
352 "glue code" consists of the following list of symbols:
353 <code style="font-size:smaller;"> gtk:+true+, gtk:+false+,
354 gtk:init-ensure, g:nullptr, g:nullptr?,
355 g:callback,gtk:define-signal-handler, gtk:struct-alloc,
356 gtk:struct-free, gtk:cstring-&gt;string,
357 gtk:string-&gt;cstring, gtk:cstring-free.
358 </code>
359
360
361 <h2 id="download">Downloads</h2>
362
363 <ul>
364 <li>
365 <a href="ftp://common-lisp.net/pub/project/lambda-gtk/lambda-gtk-0.1.tar.gz">Latest &lambda;gtk source tarball</a>
366 </li>
367 <li>
368 <a href="ftp://common-lisp.net/pub/project/lambda-gtk/sbcl-af-2004-10-22.tgz">
369 Thomas Burdick's Alien Function package for SBCL</a>
370 </li>
371 <li>
372 <a href="ftp://common-lisp.net/pub/project/lambda-gtk/openmcl-darwin-gtk.tar.gz">
373 OpenMCL GTK Interface</a>
374 </li>
375 </ul>
376
377 <h2 id="cvs">CVS</h2>
378
379 <p>
380 You can <a
381 href="http://common-lisp.net/cgi-bin/viewcvs.cgi/?cvsroot=lambda-gtk">
382 browse the CVS repository</a> or download the current development tree
383 via anonymous cvs, as described <a
384 href="http://common-lisp.net/faq.shtml#checkout">here</a>
385 </p>
386
387 <h2 id="mail">Mailing Lists</h2>
388 <ul>
389 <li>
390 <a href="http://www.common-lisp.net/mailman/listinfo/lambda-gtk-devel">
391 lambda-gtk-devel</a><br/>for developers
392 </li>
393 <li>
394 <a href="http://www.common-lisp.net/mailman/listinfo/lambda-gtk-devel">
395 lambda-gtk-cvs</a><br/>CVS log feed.</li>
396 <li>
397 <a href="http://www.common-lisp.net/mailman/listinfo/lambda-gtk-devel">
398 lambda-gtk-announce</a><br/>for announcements.</li>
399 </ul>
400
401
402 <h2 id="pictures">Pretty Pictures</h2>
403
404 <p>If you use &lambda;gtk to develop a GUI interface in Lisp please send a pretty picture!
405 </p>
406 <p>Here is mine:
407 </p>
408 <ul>
409 <li><a href="http://pinhead.music.uiuc.edu:/~hkt/cm/doc/dict/plotter-topic.html#examples">Plotter</a> </li>
410 </ul>
411
412 <p>
413 <span style="color:silver;">[Stable links only, please!]</span>
414 </p>
415
416 <h2>Acknowledgments</h2>
417 <p>
418 I would never have attempted this interface without the FFI tools that
419 Gary Byers provides in his OpenMCL distribution. The callback
420 mechanism for SBCL is written Thomas Burdick. Several of the GTK
421 examples are adapted from Mario Mommer's <a
422 href="http://common-lisp.net/project/lgtk/">l-gtk distribution</a>.
423 </p>
424
425
426 <h2 id="contact">Contact</h2>
427 <p>
428 Rick Taube<br/>
429 Associate Professor, Composition/Theory<br/>
430 School of Music, University of Illinois<br/>
431 Urbana, IL 61801 USA<br/>
432 Net: taube@uiuc.edu<br/>
433 Fax: 1 217 244-4585<br/>
434 Vox: 1 217 244-2684<br/>
435 </p>
436 </div> <!-- End "Content" -->
437
438 <hr/>
439 <p>
440 <a href="http://validator.w3.org/check?uri=referer">
441 <img style="border:none;" src="http://www.w3.org/Icons/valid-xhtml10"
442 alt="Valid XHTML 1.0!" height="31" width="88" />
443 </a>
444 </p>
445 </body>
446 </html>

  ViewVC Help
Powered by ViewVC 1.1.5