-all: doc.html index.html tutorial.html
+all: doc.html tutorial.html
doc.html: doc.xml
xsltproc -o $@ /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl $<
--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>CL-GTK2 - a Gtk+ binding for Common Lisp</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="CL-GTK2 - a Gtk+ binding for Common Lisp"><div class="titlepage"><div><div><h1 class="title"><a name="id89019"></a>CL-GTK2 - a Gtk+ binding for Common Lisp</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Dmitry</span> <span class="surname">Kalyanov</span></h3></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#id298361">1. TODO</a></span></dt><dt><span class="chapter"><a href="#id298401">2. Introduction</a></span></dt><dt><span class="chapter"><a href="#id298412">3. Goals</a></span></dt><dt><span class="chapter"><a href="#id298460">4. Development history</a></span></dt><dt><span class="chapter"><a href="#id298515">5. Features</a></span></dt><dt><span class="chapter"><a href="#id298563">6. GObject binding</a></span></dt></dl></div><div class="chapter" title="Chapter 1. TODO"><div class="titlepage"><div><div><h2 class="title"><a name="id298361"></a>Chapter 1. TODO</h2></div></div></div><p>Installation and requirements</p><p>*Introduction</p><p>Goals</p><p>Development History</p><p>Features</p><p>*Examples</p><p>*GObject binding: using objects, handling memory</p><p>*Using Gtk+ in Lisp: Gtk+, Widgets, main loop, threading</p><p>*Advanced GObject: defining objects, creating custom gobject classes, overriding and implementing methods and properties</p><p>*Internals: how gobject binding is implemented</p></div><div class="chapter" title="Chapter 2. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="id298401"></a>Chapter 2. Introduction</h2></div></div></div><p>CL-GTK2 package is a Common Lisp binding for Gtk+ and related libraries. This package enables Lisp developers to develop Gtk+-based GUI applications.</p></div><div class="chapter" title="Chapter 3. Goals"><div class="titlepage"><div><div><h2 class="title"><a name="id298412"></a>Chapter 3. Goals</h2></div></div></div><p>The goal of CL-GTK2 is to provide portable (modulo threading, metaobject protocol, FFI), extensible and feature-complete binding for Gtk+ and set of related libraries (GLib, GObject, Gdk, Pango, Cairo, GdkPixbuf, GtkSourceView, etc.)</p><p>Gtk+ is writtent in C and uses object-oriented style of programming with support of GObject library. GObject provides classes, objects, memory management via reference counters, classes introspection, signals, properties. Goal includes "lispy" interface to GObject-based libraries. This means that GObject classes should map into CLOS classes, GObject instance into CLOS instances, properties should match to slots, it should be possible to attach closures as signal handlers. It should be possible to define GObject classes, implement properties, methods, signals, interfaces from lisp.</p><p>All memory management (object instances, closures, signal handlers, etc.) should be automatic. When applicable, optional support for manual management (using refcounts) should be provided for perfomance reasons.</p><p>All Gtk+ classes should be mapped, and the rest of the API should be mapped in lispy way. Support for NIH features should not be provided (e.g., do not expose GSList, GList, GHashtable, GUri but rather transparently convert to/from them).</p><p>Error handling should be provided; GObject/Gtk warnings and errors should be exposed as conditions. It should not be possible to bring Gtk+ into incostistent state when error in lisp code called from Gtk occurs (e.g., error in signal handler should not cause fatal errors but rather should be handleable).</p><p>CL-GTK2 should be threadsafe: it should be possible to make actions under the Gdk lock, and make actions from withing the GUI thread.</p><p>Ease of extending and updating to reflect progress of Gtk+ is also important.</p><p>CL-GTK2 should run main-loop threadedly; it should be possible to interactively modify the code while the GUI program is running.</p></div><div class="chapter" title="Chapter 4. Development history"><div class="titlepage"><div><div><h2 class="title"><a name="id298460"></a>Chapter 4. Development history</h2></div></div></div><p>This project was started by Kalyanov Dmitry in 2008. It was a hobby project to address the (perceived or real) lack of good portable GUI libraries for Common Lisp and to be able to use it for writing diploma (or is it called "graduate"?) project during final course of the university.</p><p>Initial intent was to use SWIG<sup>[<a name="id298473" href="#ftn.id298473" class="footnote">1</a>]</sup> in order to be able to generate all of the code. After some experimenting, it was found out that use of SWIG would not help to achieve the goals. First of all, in order to create "lispy" bindings, a lot of integration should be done: object systems, memory management, passing closure and values, type mapping (G(S)List to list, GCallback/GCLosure to functions, etc.). SWIG is not of much help here.</p><p>So, it was decided to use CFFI and manually map all of the API. First, base infrastructure was created (definition of basic types, maps for basic types, integration with GObject object system and memory management, introspection of GObject types). Then large chunks of API were mapped with automatic generation of classes definitions. Then missing properties were added and functions were mapped.</p><p>In order to map GtkTreeModel, preliminary support for subclassing and implementing GObjects was introduced. With its help, lispy ArrayListStore (analog for GtkListStore) was implemented.</p><p>At the moment, next version of GObject binding using the CLOS MOP is being developed. It pretty much obsoletes class generation macroses and is neede in order to be able to make lispy maps of GObject methods into CLOS generic functions and to subclass GObject classes.</p><p>For future development, using GObjectIntrospection seems the definite way.</p><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id298473" href="#id298473" class="para">1</a>] </sup><a class="ulink" href="http://www.swig.org/" target="_top">Simplified Wrapper and Interface Generator</a>; a program that automatically parses C and C++ header files and generates the binding code for many languages, including Common Lisp (targetting CFFI).</p></div></div></div><div class="chapter" title="Chapter 5. Features"><div class="titlepage"><div><div><h2 class="title"><a name="id298515"></a>Chapter 5. Features</h2></div></div></div><p>Short summary of features provided by CL-GTK2:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Mapping from GObject to CLOS with (partial) support for creating subclasses, overriding methods</p></li><li class="listitem"><p>Automatic memory management (with optional support for manual reference counting)</p></li><li class="listitem"><p>Lispy interface to related libraries (currently only to GLib, GObject, Gdk, Gtk)</p></li><li class="listitem"><p>Lispy mapping of Gtk+ API</p></li><li class="listitem"><p>Custom ListStore (TreeStore to be done) for GtkTreeModel</p></li><li class="listitem"><p>Partial error management (closures are invoked with restarts making it possible to cancel signal handling without crashing Gtk+)</p></li><li class="listitem"><p>Some high-level features based on Gtk+ API: with-progress-bar, with-message-error-handler</p></li></ul></div></div><div class="chapter" title="Chapter 6. GObject binding"><div class="titlepage"><div><div><h2 class="title"><a name="id298563"></a>Chapter 6. GObject binding</h2></div></div></div><p>At the base of Gtk+ is the GObject library. This library provides basic object-oriented system and various services. </p></div></div></body></html>
--- /dev/null
+<?xml version="1.0"?>
+<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
+ <uri resource="index.html" typeId="DocBook"/>
+</locatingRules>
--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>CL-GTK2 Tutorial</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="CL-GTK2 Tutorial"><div class="titlepage"><div><div><h2 class="title"><a name="id256750"></a>CL-GTK2 Tutorial</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Dmitry</span> <span class="surname">Kalyanov</span></h3><code class="email"><<a class="email" href="mailto:Kalyanov.Dmitry@gmail.com">Kalyanov.Dmitry@gmail.com</a>></code></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id466095">TODO</a></span></dt><dt><span class="section"><a href="#id466114">Installation</a></span></dt><dt><span class="section"><a href="#id466249">"Hello world" example</a></span></dt><dt><span class="section"><a href="#id466326">Example walk-through</a></span></dt></dl></div><div class="section" title="TODO"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id466095"></a>TODO</h2></div></div></div><p>Introduction</p><p>More involved example: simple text editor</p><p>More involved example walk-through: widgets, properties, packing, child properties</p><p>TreeView example</p></div><div class="section" title="Installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id466114"></a>Installation</h2></div></div></div><p>CL-GTK2 is in alpha stage and is unstable and not feature-complete. It is being developed on x86-64 gentoo linux with SBCL. It should, in general, work with other lisp compilers and on other platforms. CL-GTK2 requires some features not present in the Common Lisp Standard, namely it requires CFFI support with callbacks and long-long support (most modern lisp implementations are supported, including clisp) and it requires CLOS MOP (MetaObject Protocol) which is also is present (or is being added to) most modern lisp implementations.</p><p>CL-GTK2 requires Gtk+ version 2.16 or later. CL-GTK2 was tested on SBCL-1.0.18 and SBCL-1.0.28</p><p>If you have any difficulties installing or using CL-GTK2, contact me (the author of this tutorial and of CL-GTK2) via email Kalyanov.Dmitry@gmail.com or via jabber mo3r@jabber.ru.</p><p>First, install CL-GTK2 dependcies. CL-GTK2 has the following dependencies (CL-GTK2 was tested with specified versions; it would probably not work with earlier versions but should work with later versions):</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://common-lisp.net/project/cffi" target="_top">CFFI</a> (version 0.10.4)</p></li><li class="listitem"><p><a class="ulink" href="http://www.cliki.net/trivial-garbage" target="_top">Trivial-Garbage</a> (version 0.18)</p></li><li class="listitem"><p><a class="ulink" href="http://common-lisp.net/project/iterate/" target="_top">Iterate</a> (version 1.4.3)</p></li><li class="listitem"><p><a class="ulink" href="http://common-lisp.net/project/bordeaux-threads/" target="_top">Bordeaux-Threads</a> (version 0.6.0)</p></li><li class="listitem"><p><a class="ulink" href="http:/common-lisp.net/project/closer/closer-mop.html/" target="_top">Closer-MOP</a> (version 0.55)</p></li></ul></div><p>Currently, CL-GTK2 is only available in Git repository at <a class="ulink" href="http://repo.or.cz/w/cl-gtk2.git" target="_top">http://repo.or.cz/w/cl-gtk2.git</a>. If you do not want or can not to use Git, download the snapshot from <a class="ulink" href="http://repo.or.cz/w/cl-gtk2.git?a=snapshot;h=HEAD;sf=tgz" target="_top">http://repo.or.cz/w/cl-gtk2.git?a=snapshot;h=HEAD;sf=tgz</a>.</p><p>Unpack the CL-GTK2 sources, and add them to <code class="varname">asdf:*central-registry*</code>:</p><pre class="programlisting">
+ (push "/path/to/cl-gtk2/glib/" asdf:*central-registry*)
+ (push "/path/to/cl-gtk2/gdk/" asdf:*central-registry*)
+ (push "/path/to/cl-gtk2/gtk/" asdf:*central-registry*)
+ </pre><p>Now you should be able to load the CL-GTK2:</p><pre class="programlisting">(asdf:oos 'asdf:load-op :gtk)</pre><p>When the system is loaded, run <code class="varname">(gtk-demo:demo-text-editor)</code>. A text editor window should pop up:</p><div><img src="lisp_ide.png"></div><p>This is a very simple text editor written in CL-GTK2. Apart from editing the text, it can evaluate expressions: select expression and press the "execute" button. Expression will be evaluated and its result will be put into text view.</p></div><div class="section" title='"Hello world" example'><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id466249"></a>"Hello world" example</h2></div></div></div><p>Let's start from a simple example.</p><div><img src="hello_world.png"></div><p>Start Slime, type the following code in the REPL:</p><pre class="programlisting">
+(asdf:oos 'asdf:load-op :gtk)
+
+(gtk:within-main-loop
+ (let ((window (make-instance 'gtk:gtk-window :title "Hello, world!")))
+ (gtk:widget-show window)))
+ </pre><p>The empty window with title "Hello, world!" should appear.</p><p>Let's analyze this example line-by-line.</p><p><code class="varname">(asdf:oos 'asdf:load-op :gtk)</code> loads the GTK system into Lisp.</p><p>CL-GTK2 runs Gtk+ main loop in background thread (because Lisp development is interactive in its nature; if main loop would block the REPL thread, you would have to restart the Lisp image too often). Because all access to Gtk+ should come from Gtk+ thread, we should run the code in that thread. Macro <code class="varname">gtk:within-main-loop</code> does exactly that: it schedules the code to be tun in the Gtk+ thread. You should use this macro whenever you want evaluate the code from the REPL or when you start you application.</p><p>Next, we create the window with <code class="varname">make-instance</code> and set its <code class="varname">title</code> property to <code class="varname">"Hello, world!"</code>.</p><p>When the window is created, it is not yet shown on the screen. To show it, we call <code class="varname">(gtk:widget-show window)</code>.</p><p>After this code executes, you should get back to the REPL (rememer, Gtk+ runs in background thread) and the window should appear on the screen.</p></div><div class="section" title="Example walk-through"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id466326"></a>Example walk-through</h2></div></div></div><p>Let's analyze the example step by step.</p><p>CL-GTK2 runs the Gtk main loop in background thread. This is done so you could have your application running and interacting with the Lisp system through the REPL.</p><p>To execute some code and ensure that Gtk+ main loop is started, WITH-MAIN-LOOP macro is used. It runs the body of code within the Gtk+ main loop. Because all calls to Gtk+ functions require locking, it is neccessary to run this code from th main loop. Because we are running the code in another thread, its dynamic bindings (including *standard-output*) will be lost. To be able to print at REPL, we save reference to the standard output stream in the closure.</p><p>Gtk+ objects are created with make-instance and are properly garbage-collected.</p><p>Object have properties, which are represented as slots in CL-GTK2. Some properties (slots) of objects are constructor-only properties and can only be set at object construction time. For example, "type" property of GtkWindow can only be set during its creation. To access properties, you may use <code class="varname">slot-value</code> function or slot accessor methods. For property <code class="varname">Y</code> declared on class <code class="varname">X</code>, method <code class="varname">X-Y</code> returns the value of the property. Properties are setfable (with exception of read-only and constructor-only properties).</p><p>Call to container-add puts button as a child widget into window, and widget-show shows all widgets of window.</p><p>In Gtk+, objects have "signals", to which handlers can be attached. When something happens that results in "emitting" the signal (e.g., button being clicked emits "clicked" signal), all handlers of this signal are called. Handler of GtkButton's "clicked" signal has only one argument - the button that was clicked. CL-GTK2 allows attaching any function (including closures) as signal handlers and ensures that closure is freed properly.</p></div></div></body></html>
projects / cl-gtk2.git / commitdiff