Sun Apr 5 19:58:25 CEST 2009 Tobias Rautenkranz <tobias@rautenkranz.ch>

* initial import

--- old-doc/Makefile 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/Makefile 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,22 @@

+#

+# Dependancies:

+# xmllint xsltproc docbook

+#

+

+all: manual.html index.html

+

+DEPENDANCIES := *docbook *.xsl ../qt.examples/src/*.lisp ../kde.examples/src/*.lisp

+

+manual.html: $(DEPENDANCIES)

+ xmllint --xinclude --postvalid manual.docbook > /dev/null

+ xsltproc --xinclude -o $@ manual.xsl manual.docbook

+

+index.html: $(DEPENDANCIES)

+# xsltproc --xinclude --stringparam base.dir "manual/" chunk.xsl manual.docbook

+ xsltproc --xinclude chunk.xsl manual.docbook

+

+

+

+.PHONY: clean

+clean:

+ rm -f -- *.html

--- old-doc/chunk.xsl 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/chunk.xsl 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,14 @@

+<?xml version='1.0'?>

+<xsl:stylesheet version="1.0"

+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

+

+<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl"/>

+<xsl:import href="link-apidoc.xsl"/>

+

+<!--

+<xsl:param name="admon.graphics" select="1"/>

+!-->

+<xsl:param name="use.id.as.filename" select="1"/>

+

+

+</xsl:stylesheet>

Binary files old-doc/class-browser.png and new-doc/class-browser.png differ

Binary files old-doc/hello-world.png and new-doc/hello-world.png differ

Binary files old-doc/i18n-hello-world.png and new-doc/i18n-hello-world.png differ

--- old-doc/introduction.docbook 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/introduction.docbook 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,76 @@

+<?xml version="1.0"?>

+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

+<chapter id="introduction">

+<title>Introduction</title>

+<para>

+ CL-Smoke provides CLOS bindings for the Qt and KDE libraries.

+</para>

+<section><title>Related</title>

+<itemizedlist>

+ <listitem><para><ulink url="http://common-lisp.net/project/commonqt/">

+ CommonQt</ulink> (No CLOS, no startup overhead)</para></listitem>

+ <listitem><para><ulink url="http://sourceforge.net/projects/lisp-cffi-qt4">

+ Lisp-CFFI-Qt4</ulink> (dead)</para></listitem>

+</itemizedlist>

+</section>

+<section><title>Limitations</title>

+<itemizedlist>

+ <listitem><para>Bad multithreaded performance

+ due to a lock for the global hash-tables.</para></listitem>

+ <listitem><para>No C++ style argument conversion.</para></listitem>

+ <listitem><para>No custom overloading methods by argument count.</para></listitem>

+ <listitem><para>Limited conversions. E.g. <code>QList&lt;T&gt;</code> is missing.

+ </para></listitem>

+ <listitem><para>10 seconds startup time (for <package>qt.examples</package>) on a

+ Pentium M 1.7GHz. (Compilation ~20 seconds)</para></listitem>

+ <listitem><para>Needs to be recompiled when the Smoke library is updated.</para></listitem>

+ <listitem><para>Saving a core image is not supported.</para></listitem>

+</itemizedlist>

+</section>

+<section><title>Installation</title>

+<section><title>Dependencies</title>

+<itemizedlist>

+ <listitem><para><ulink

+ url="http://techbase.kde.org/Development/Languages/Smoke">Smoke2</ulink>

+ bindings 4.2 or later</para></listitem>

+ <listitem><para><ulink url="http://qtsoftware.com">Qt</ulink>

+ (development package)</para></listitem>

+ <listitem><para>

+ <ulink url="http://cmake.org">CMake</ulink> 2.6

+ </para></listitem>

+ <listitem><para>a make program (preferably Gnu Make)</para></listitem>

+ <listitem><para>a C++ compiler (GCC)</para></listitem>

+</itemizedlist>

+<para>

+On the Lisp side you need <ulink url="http://mudballs.com">mudballs</ulink>

+and <ulink url="http://tobias.rautenkranz.ch/lisp/sysdef.cmake">sysdef.cmake</ulink>.

+</para>

+</section>

+

+<section><title>Supported Platforms</title>

+<para>

+ SBCL on Linux x86 in works; CMUCL and CLisp currently do not.

+ It should be possible to get it to work (with SBCL) on

+ other platforms. Contact me if you have any questions.

+</para>

+</section>

+<section><title>Installation</title>

+<para>

+ You need to checkout the darcs repositories:

+ <programlisting>

+cd <userinput>SOME_DIR</userinput>

+for r in smoke qt qt.test qt.tests qt.examples qt.uitools qt.webkit kde kde.tests kde.examples; do

+ darcs get "http://tobias.rautenkranz.ch/lisp/cl-smoke/$r"

+done

+ </programlisting>

+ Then add the directory <userinput>SOME_DIR</userinput> to the mudballs search paths by adding

+ <programlisting>

+(push (wildcard-searcher "<userinput>SOME_DIR</userinput>/*/*.mbd")

+ *custom-search-modules*)

+ </programlisting>

+ to <filename>~/.mudballs</filename>.

+</para>

+</section>

+</section>

+</chapter>

--- old-doc/kde.docbook 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/kde.docbook 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,64 @@

+<?xml version="1.0"?>

+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

+<chapter id="kde">

+<title>KDE</title>

+<para>

+Besiedes the <package>:kde</package> package there

+is <package>:kde.tests</package> for the unit tests and

+<package>:kde.examples</package> containing the examples.

+</para>

+

+<section><title>Examples</title>

+<para>

+The examples can be run with:

+<programlisting>

+(mb:load :kde.examples)

+</programlisting>

+An the running the function of the example; e.g.:

+<programlisting>

+(kde.examples:mandelbrot)

+</programlisting>

+</para>

+<example>

+<title>Hello World</title>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="kde.hello-world.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+<programlisting language="lisp">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"

+ href="../kde.examples/src/hello-world.lisp" parse="text" />

+</programlisting>

+</example>

+

+<example>

+<title>KMandelbrot</title>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="kmandelbrot.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+<para>

+ A port of the

+ <ulink url="http://doc.trolltech.com/4.5/threads-mandelbrot.html">

+ Qt Mandelbrot example</ulink> to KDE.

+ <blockquote>

+ <para>

+The Mandelbrot example shows how to use a worker thread to perform heavy computations without blocking the main thread's event loop.

+ </para>

+ </blockquote>

+ The sources can be found in the

+ <filename><ulink url="../kde.examples/src/mandelbrot/">src/mandelbrot/</ulink></filename>

+ directory of the <package>:kde.examples</package> package

+

+</para>

+</example>

+</section>

+

+</chapter>

Binary files old-doc/kde.hello-world.png and new-doc/kde.hello-world.png differ

Binary files old-doc/kmandelbrot.png and new-doc/kmandelbrot.png differ

--- old-doc/link-apidoc.xsl 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/link-apidoc.xsl 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,52 @@

+<?xml version='1.0'?>

+<xsl:stylesheet version="1.0"

+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

+

+<!-- TODO move common stuff to a function (we need 2.0 for this) !-->

+<xsl:param name="apidoc-baseurl" select="string('../api-doc/')"/>

+

+<!-- linkify classname !-->

+<xsl:template match="classname">

+ <xsl:call-template name="ulink">

+ <xsl:with-param name="url" select="concat($apidoc-baseurl,

+ substring-before(current(),':'),

+ '/',

+ substring-after(current(),':'),

+ '-class.html')"/>

+ </xsl:call-template>

+</xsl:template>

+

+<!-- linkify methodname !-->

+<xsl:template match="methodname">

+ <xsl:call-template name="ulink">

+ <xsl:with-param name="url" select="concat($apidoc-baseurl,

+ substring-before(current(),':'),

+ '/',

+ substring-after(current(),':'),

+ '-function.html')"/>

+ </xsl:call-template>

+</xsl:template>

+

+<!-- linkify constant !-->

+<xsl:template match="constant">

+ <xsl:call-template name="ulink">

+ <xsl:with-param name="url" select="concat($apidoc-baseurl,

+ substring-before(current(),':'),

+ '/',

+ translate(substring-after(current(),':'), '.+', ''),

+ '-constant.html')"/>

+ </xsl:call-template>

+</xsl:template>

+

+<!-- linkify package !-->

+<xsl:template match="package">

+ <xsl:call-template name="ulink">

+ <xsl:with-param name="url" select="concat($apidoc-baseurl,

+ substring-after(current(),':'),

+ '/',

+ translate(substring-after(current(),':'), '.', ''),

+ '-package.html')"/>

+ </xsl:call-template>

+</xsl:template>

+

+</xsl:stylesheet>

--- old-doc/manual.docbook 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/manual.docbook 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,35 @@

+<?xml version="1.0" encoding="UTF-8" ?>

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

+<book id="cl-smoke" lang="en">

+

+<bookinfo>

+<title>CL-Smoke</title>

+<authorgroup>

+<author>

+<firstname>Tobias</firstname>

+<surname>Rautenkranz</surname>

+<email>mail #\@ tobias #\. rautenkranz #\. ch</email>

+</author>

+</authorgroup>

+

+<copyright>

+<year>2009</year>

+<holder>Tobias Rautenkranz</holder>

+</copyright>

+<legalnotice><para>FDL</para></legalnotice>

+<date>2009-03-25</date>

+<releaseinfo>0.0.1</releaseinfo>

+<abstract>

+<para>

+Common Lisp bindings for Qt and KDE using Smoke.

+</para>

+</abstract>

+</bookinfo>

+

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.docbook" />

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="smoke.docbook" />

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="qt.docbook" />

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kde.docbook" />

+

+</book>

--- old-doc/manual.xsl 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/manual.xsl 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,8 @@

+<?xml version='1.0'?>

+<xsl:stylesheet version="1.0"

+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

+

+<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>

+<xsl:import href="link-apidoc.xsl"/>

+

+</xsl:stylesheet>

--- old-doc/qt.docbook 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/qt.docbook 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,174 @@

+<?xml version="1.0"?>

+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

+<chapter id="qt">

+<title>Qt</title>

+<para>

+Besieds the <package>:qt</package> there are these packages: with

+<itemizedlist>

+ <listitem><para>

+ <package>:qt.uitools</package>

+ <ulink url="http://doc.trolltech.com/4.5/qtuitools.html">

+ QtUiTools</ulink></para></listitem>

+ <listitem><para><package>:qt.test</package>

+ <ulink url="http://doc.trolltech.com/4.5/qttest.html">

+ QtTest</ulink></para></listitem>

+ <listitem><para><package>:qt.webkit</package>

+ <ulink url="http://doc.trolltech.com/4.5/qtwebkit.html">

+ QtWebKit</ulink>

+ </para></listitem>

+</itemizedlist>

+which provied bindings for their Qt module.

+Additionally there is the <package>:qt.tests</package> system, containing

+the unit tests and <package>:qt.examples</package> for various examples.

+</para>

+

+<section><title>QApplication</title>

+<para>

+The <classname>qt:application</classname> object should created with:

+<code>qt:with-app</code>. In its body the event loop can be

+started with <methodname>qt:exec</methodname>.

+</para>

+<example>

+<title>Hello World</title>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="hello-world.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+<programlisting language="lisp">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../qt.examples/src/hello-world.lisp" parse="text" />

+</programlisting>

+</example>

+</section>

+

+<section><title>Signal-Slot</title>

+<para>

+<methodname>qt:connect</methodname> connects a signal to a slot.

+The signal is either a <classname>qt:qsignal</classname> created with

+<methodname>qt:make-signal</methodname> or a C++ signal by using

+<methodname>qt:get-signal</methodname>.

+The slot can be a slot returned by <classname>qt:make-slot</classname>, a function

+or a C++ slot a return from <methodname>qt:get-slot</methodname>.

+</para>

+<example><title>Quit</title>

+<programlisting>

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../qt.examples/src/hello-world-quit.lisp" parse="text" />

+</programlisting>

+</example>

+<para>

+When the argument types for a slot or signal are not specified they are determined when

+the first connection is made. Note that when connecting a <classname>qt:qsignal</classname>

+to a <classname>qt:qslot</classname> at least one must have its arguments types specified.

+</para>

+

+<para>

+The functionality of the Qt <code>SIGNAL</code> and <code>SLOT</code> macros is

+provided by <methodname>qt:qsignal</methodname> and <methodname>qt:qslot</methodname>.

+</para>

+</section>

+

+<section><title>Properties</title>

+<para>

+<classname>qt:object</classname> properties can be accessed with

+<methodname>qt:property</methodname> (setf-able).

+The name of the property can be either a string in C++ style or a symbol in Lisp style.

+</para>

+<informalexample>

+<programlisting>

+(let ((object (make-instance '<classname>qt:object</classname>)))

+ (setf (<methodname>qt:property</methodname> object 'object-name) "Foo")

+ (assert (string= "Foo" (<methodname>qt:property</methodname> object "objectName"))))

+</programlisting>

+</informalexample>

+

+</section>

+

+

+<section><title>i18n</title>

+<para>

+You can use <methodname>qt:tr</methodname> to translate strings.

+</para>

+<example>

+<title>i18n Hello World</title>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="i18n-hello-world.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+

+<programlisting language="po">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"

+href="../qt.examples/src/i18n-hello-world.lisp" parse="text" />

+</programlisting>

+

+<formalpara>

+<title><filename>hello-world_de.po</filename></title>

+<para>

+<programlisting language="po">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../qt.examples/src/hello-world_de.po" parse="text" />

+</programlisting>

+</para>

+</formalpara>

+</example>

+

+<para>

+Gettext is used to extract the i18n strings and compile the message catalog.

+See <filename><ulink url="../qt.examples/src/CMakeLists.txt">CMakeLists.txt</ulink></filename>

+and <filename><ulink url="../qt.examples/src/UseClQti18n.cmake">UseClQti18n.cmake</ulink></filename>

+in the <filename class="directory">src</filename> directory of <package>:qt.examples</package> how to do this.

+</para>

+</section>

+

+<section><title>Examples</title>

+<para>

+You can run the examples with:

+<programlisting>

+(mb:load :qt.examples)

+(qt.examples:launcher)

+</programlisting>

+</para>

+

+<example>

+<title>Repl</title>

+<para>

+Use a <classname>qt:string-list-model</classname> with a <classname>qt:list-view</classname>

+to show evaluated lisp expressions.

+</para>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="repl.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+<programlisting language="lisp">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../qt.examples/src/repl.lisp" parse="text" />

+</programlisting>

+</example>

+

+<example>

+<title>Class Browser</title>

+<para>Qt Classes browser using <package>:qt.webkit</package> to display the

+API doc and a custom <classname>qt:list-model</classname>

+for the <classname>qt:list-view</classname> of the available classes.

+</para>

+<screenshot>

+<mediaobject>

+<imageobject>

+ <imagedata fileref="class-browser.png" format="PNG"/>

+</imageobject>

+</mediaobject>

+</screenshot>

+<programlisting language="lisp">

+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../qt.examples/src/class-browser.lisp" parse="text" />

+</programlisting>

+</example>

+

+</section>

+

+</chapter>

Binary files old-doc/repl.png and new-doc/repl.png differ

--- old-doc/smoke.docbook 1970-01-01 01:00:00.000000000 +0100

+++ new-doc/smoke.docbook 2014-10-30 06:55:37.000000000 +0100

@@ -0,0 +1,101 @@

+<?xml version="1.0"?>

+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

+<chapter id="smoke">

+<title>Usage</title>

+<para></para>

+<section><title>Symbols</title>

+<para>

+C++ names are converted to Lisp symbols by converting <code>camelCase</code>

+to <code>camel-case</code>. Underscores <code>#\_</code> are replaced with

+<code>#\-</code> and a leading uppercase K or Q is removed.

+</para>

+<para>

+E.g.: <code>QHelloWorld_foo</code> becomes <code>hello-world-foo</code>.

+</para>

+</section>

+

+<section><title>Class</title>

+<para>

+C++ classes have a corresponding CLOS class. The can be used like any CLOS class; E.g:

+to make a <code>QObject</code> instance:

+<informalexample>

+<programlisting>

+(make-instance '<classname>qt:object</classname>)

+</programlisting>

+</informalexample>

+Suppy arguments as list to the <code>:args</code> keyword:

+<informalexample>

+<programlisting>

+(let ((parent (make-instance '<classname>qt:object</classname>)))

+ (make-instance '<classname>qt:object</classname> :args (list parent)))

+</programlisting>

+</informalexample>

+</para>

+<para>

+To extend a C++ class you have to use <classname>cxx:class</classname> as metaclass:

+<informalexample>

+<programlisting>

+(defclass my-object (<classname>qt:object</classname>)

+ ()

+ (:metaclass <classname>cxx:class</classname>))

+</programlisting>

+</informalexample>

+</para>

+</section>

+

+<section><title>Methods</title>

+<para>

+The C++ methods are generic functions in the <code>:cxx</code> package.

+Their lambda list is: <code>(object &amp;rest args)</code>.

+</para>

+<para>

+The C++ method call: <code>myInstance->frob(1);</code> is in Lisp:

+<informalexample>

+<programlisting>(frob my-instance 1)</programlisting>

+</informalexample>

+</para>

+<para>

+You can extend the <package>:cxx</package> generic functions by

+adding methods. <code>:around</code>, <code>:before</code>, <code>:after</code>

+and <code>(call-next-method)</code> are supported.

+</para>

+</section>

+

+<section><title>Static Methods</title>

+<para>

+The static C++ method <code>QByteArray::number(int n, int base=10)</code>

+can be called by:

+<informalexample>

+<programlisting>(<methodname>qt:byte-array.number</methodname> 37)</programlisting>

+</informalexample>

+which is equivalent to the C++ code <code>QByteArray::number(37);</code>.

+Or with:

+<informalexample>

+<programlisting>(cxx:number (find-class '<classname>qt:byte-array</classname>) 37)</programlisting>

+</informalexample>

+

+</para>

+</section>

+

+<section><title>Constants</title>

+<para>

+ C++ Class enums available as constants. E.g.:

+ <code>QColor::Rgb</code> is <constant>qt:color.+rgb+</constant>.

+ See <package>:cxx-support</package>.

+</para>

+</section>

+

+<section><title>Garbage Collection</title>

+<para>

+You should be able to use C++ Class instances like normal Lisp object.

+</para>

+<para>

+C++ classes are automaticly deleted when their lisp object gets garbage collected;

+except when they (QObjects) have a parent and thus the parent is responsible for

+their deletion. When a <classname>qt:object</classname> has a parent, a strong

+reference is kept to prevent its garbage collection until the parent is deleted.

+</para>

+</section>

+

+</chapter>