Introduction

Mon May 11 22:23:03 CEST 2009 Tobias Rautenkranz * Rename *.docbook -> *.xml diff -rN -u old-doc/Makefile new-doc/Makefile --- old-doc/Makefile 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/Makefile 2014-10-30 07:13:12.000000000 +0100 @@ -5,15 +5,15 @@ all: manual.html index.html -DEPENDANCIES := *docbook *.xsl ../qt.examples/src/*.lisp ../kde.examples/src/*.lisp *.dtd +DEPENDANCIES := *.xml *.xsl ../qt.examples/src/*.lisp ../kde.examples/src/*.lisp *.dtd manual.html: $(DEPENDANCIES) - xmllint --xinclude --postvalid manual.docbook > /dev/null - xsltproc --xinclude -o $@ manual.xsl manual.docbook + xmllint --xinclude --postvalid manual.xml > /dev/null + xsltproc --xinclude -o $@ manual.xsl manual.xml index.html: $(DEPENDANCIES) -# xsltproc --xinclude --stringparam base.dir "manual/" chunk.xsl manual.docbook - xsltproc --xinclude chunk.xsl manual.docbook +# xsltproc --xinclude --stringparam base.dir "manual/" chunk.xsl manual.xml + xsltproc --xinclude chunk.xsl manual.xml diff -rN -u old-doc/introduction.docbook new-doc/introduction.docbook --- old-doc/introduction.docbook 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/introduction.docbook 1970-01-01 01:00:00.000000000 +0100 @@ -1,93 +0,0 @@ - - - -Introduction - - CL-Smoke provides CLOS bindings for the Qt and KDE libraries. - -

Related - - - CommonQt (No CLOS, no startup overhead) - - Lisp-CFFI-Qt4 (dead) - -

Status - -GUI creation should work and API will probably remain compatible. -The next goal is to reorganize the argument conversion / overload resolution and to -integrate more conversions between Lisp and C++ (QList etc.). - - -

Limitation - - Bad multithreaded performance - due to a lock for the global hash-tables. - Limited conversions. E.g. QList<T> is missing. - - 10 seconds startup time (for qt.examples) on a - Pentium M 1.7GHz. (Compilation ~20 seconds) - Needs to be recompiled when the Smoke library is updated. - Saving a core image is not supported. - Does not recover well from errors - Thus you often need to restart the Lisp process - during interactive developement.. - -

Installation -

Dependencies - - Smoke2 - bindings 4.2 or later - Qt - (development package) - - CMake 2.6 - - a make program (preferably Gnu Make) - a C++ compiler (GCC) - - -On the Lisp side you need mudballs -and sysdef.cmake. - -

- -

Supported Platforms - - 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. - -

Installation - - You need to checkout the darcs repositories: - -cd SOME_DIR -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 - - Then add the directory SOME_DIR to the mudballs search paths by adding - -(push (wildcard-searcher "SOME_DIR/*/*.mbd") - *custom-search-modules*) - - to ~/.mudballs. - - - - Loading the packages with mb:load compiles the C wrapper libraries as needed. - - -

- diff -rN -u old-doc/introduction.xml new-doc/introduction.xml --- old-doc/introduction.xml 1970-01-01 01:00:00.000000000 +0100 +++ new-doc/introduction.xml 2014-10-30 07:13:12.000000000 +0100 @@ -0,0 +1,93 @@ + + + +Introduction + + CL-Smoke provides CLOS bindings for the Qt and KDE libraries. + +

Related + + + CommonQt (No CLOS, no startup overhead) + + Lisp-CFFI-Qt4 (dead) + +

Status + +GUI creation should work and API will probably remain compatible. +The next goal is to reorganize the argument conversion / overload resolution and to +integrate more conversions between Lisp and C++ (QList etc.). + + +

Limitation + + Bad multithreaded performance + due to a lock for the global hash-tables. + Limited conversions. E.g. QList<T> is missing. + + 10 seconds startup time (for qt.examples) on a + Pentium M 1.7GHz. (Compilation ~20 seconds) + Needs to be recompiled when the Smoke library is updated. + Saving a core image is not supported. + Does not recover well from errors + Thus you often need to restart the Lisp process + during interactive developement.. + +

Installation +

Dependencies + + Smoke2 + bindings 4.2 or later + Qt + (development package) + + CMake 2.6 + + a make program (preferably Gnu Make) + a C++ compiler (GCC) + + +On the Lisp side you need mudballs +and sysdef.cmake. + +

+ +

Supported Platforms + + 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. + +

Installation + + You need to checkout the darcs repositories: + +cd SOME_DIR +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 + + Then add the directory SOME_DIR to the mudballs search paths by adding + +(push (wildcard-searcher "SOME_DIR/*/*.mbd") + *custom-search-modules*) + + to ~/.mudballs. + + + + Loading the packages with mb:load compiles the C wrapper libraries as needed. + + +

+ diff -rN -u old-doc/kde.docbook new-doc/kde.docbook --- old-doc/kde.docbook 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/kde.docbook 1970-01-01 01:00:00.000000000 +0100 @@ -1,64 +0,0 @@ - - - -KDE - -Besides the :kde package there -is :kde.tests for the unit tests and -:kde.examples containing the examples. - - -

Examples - -The examples can be run with: - -(mb:load :kde.examples) - -An the running the function of the example; e.g.: - -(kde.examples:mandelbrot) - - - -Hello World - - - - - - - - - - - - - -KMandelbrot - - - - - - - - - A port of the - - Qt Mandelbrot example to KDE. -

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

- The sources can be found in the - src/mandelbrot/ - directory of the :kde.examples package - - - -

- - diff -rN -u old-doc/kde.xml new-doc/kde.xml --- old-doc/kde.xml 1970-01-01 01:00:00.000000000 +0100 +++ new-doc/kde.xml 2014-10-30 07:13:12.000000000 +0100 @@ -0,0 +1,64 @@ + + + +KDE + +Besides the :kde package there +is :kde.tests for the unit tests and +:kde.examples containing the examples. + + +

Examples + +The examples can be run with: + +(mb:load :kde.examples) + +An the running the function of the example; e.g.: + +(kde.examples:mandelbrot) + + + +Hello World + + + + + + + + + + + + + +KMandelbrot + + + + + + + + + A port of the + + Qt Mandelbrot example to KDE. +

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

+ The sources can be found in the + src/mandelbrot/ + directory of the :kde.examples package + + + +

+ + diff -rN -u old-doc/manual.docbook new-doc/manual.docbook --- old-doc/manual.docbook 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/manual.docbook 1970-01-01 01:00:00.000000000 +0100 @@ -1,47 +0,0 @@ - - - %link-api; - ]> - - - -CL-Smoke - - -Tobias -Rautenkranz -mail #\@ tobias #\. rautenkranz #\. ch - - - - -2009 -Tobias Rautenkranz - - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled "GNU -Free Documentation License". - -2009-03-25 -0.0.1 - - -Common Lisp bindings for Qt and KDE using Smoke. - - - - - - - - - - - - diff -rN -u old-doc/manual.xml new-doc/manual.xml --- old-doc/manual.xml 1970-01-01 01:00:00.000000000 +0100 +++ new-doc/manual.xml 2014-10-30 07:13:12.000000000 +0100 @@ -0,0 +1,47 @@ + + + %link-api; + ]> + + + +CL-Smoke + + +Tobias +Rautenkranz +mail #\@ tobias #\. rautenkranz #\. ch + + + + +2009 +Tobias Rautenkranz + + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled "GNU +Free Documentation License". + +2009-03-25 +0.0.1 + + +Common Lisp bindings for Qt and KDE using Smoke. + + + + + + + + + + + + diff -rN -u old-doc/qt.docbook new-doc/qt.docbook --- old-doc/qt.docbook 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/qt.docbook 1970-01-01 01:00:00.000000000 +0100 @@ -1,181 +0,0 @@ - - - -Qt - -Besides the :qt there are these packages: with - - - :qt.uitools - - QtUiTools - :qt.test - - QtTest - :qt.webkit - - QtWebKit - - -which provide bindings for their Qt module. -Additionally there is the :qt.tests system, containing -the unit tests and :qt.examples for various examples. - - -

qt:application - -The qt:application object should created with: -qt:with-app. In its body the event loop can be -started with qt:exec. - - -Hello World - - - - - - - - - - - -

- -

Signal-Slot - -qt:connect connects a signal to a slot. -The signal is either a qt:qsignal created with -qt:make-signal or a C++ signal by using -qt:get-signal. -The slot can be a slot returned by qt:make-slot, a function -or a C++ slot a return from qt:get-slot. - -Quit - - - - - -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 qt:qsignal -to a qt:qslot at least one must have its arguments types specified. - - - -The functionality of the Qt SIGNAL and SLOT macros is -provided by qt:qsignal and qt:qslot. - -

- -

Properties - -qt:object properties can be accessed with -qt:property (setf-able). -The name of the property can be either a string in C++ style or a symbol in Lisp style. - - - -(let ((object (make-instance 'qt:object))) - (setf (qt:property object 'object-name) "Foo") - (assert (string= "Foo" (qt:property object "objectName")))) - - - -

- -

Variant - -A qt:variant can be constructed with qt:make-variant -or to pass a Lisp object with qt:make-lisp-variant. -Its value is returned by qt:value. - -

- -

i18n - -You can use qt:tr to translate strings. - - -i18n Hello World - - - - - - - - - - - - - -<filename>hello-world_de.po</filename> - - - - - - - - - -Gettext is used to extract the i18n strings and compile the message catalog. -See CMakeLists.txt -and UseClQti18n.cmake -in the src directory of :qt.examples how to do this. - -

- -

Examples - -You can run the examples with: - -(mb:load :qt.examples) -(qt.examples:launcher) - - - - -Repl - -Use a qt:string-list-model with a qt:list-view -to show evaluated lisp expressions. - - - - - - - - - - - - - - -Class Browser -Qt Classes browser using :qt.webkit to display the -API doc and a custom qt:list-model -for the qt:list-view of the available classes. - - - - - - - - - - - - - -

- - diff -rN -u old-doc/qt.xml new-doc/qt.xml --- old-doc/qt.xml 1970-01-01 01:00:00.000000000 +0100 +++ new-doc/qt.xml 2014-10-30 07:13:12.000000000 +0100 @@ -0,0 +1,181 @@ + + + +Qt + +Besides the :qt there are these packages: with + + + :qt.uitools + + QtUiTools + :qt.test + + QtTest + :qt.webkit + + QtWebKit + + +which provide bindings for their Qt module. +Additionally there is the :qt.tests system, containing +the unit tests and :qt.examples for various examples. + + +

qt:application + +The qt:application object should created with: +qt:with-app. In its body the event loop can be +started with qt:exec. + + +Hello World + + + + + + + + + + + +

+ +

Signal-Slot + +qt:connect connects a signal to a slot. +The signal is either a qt:qsignal created with +qt:make-signal or a C++ signal by using +qt:get-signal. +The slot can be a slot returned by qt:make-slot, a function +or a C++ slot a return from qt:get-slot. + +Quit + + + + + +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 qt:qsignal +to a qt:qslot at least one must have its arguments types specified. + + + +The functionality of the Qt SIGNAL and SLOT macros is +provided by qt:qsignal and qt:qslot. + +

+ +

Properties + +qt:object properties can be accessed with +qt:property (setf-able). +The name of the property can be either a string in C++ style or a symbol in Lisp style. + + + +(let ((object (make-instance 'qt:object))) + (setf (qt:property object 'object-name) "Foo") + (assert (string= "Foo" (qt:property object "objectName")))) + + + +

+ +

Variant + +A qt:variant can be constructed with qt:make-variant +or to pass a Lisp object with qt:make-lisp-variant. +Its value is returned by qt:value. + +

+ +

i18n + +You can use qt:tr to translate strings. + + +i18n Hello World + + + + + + + + + + + + + +<filename>hello-world_de.po</filename> + + + + + + + + + +Gettext is used to extract the i18n strings and compile the message catalog. +See CMakeLists.txt +and UseClQti18n.cmake +in the src directory of :qt.examples how to do this. + +

+ +

Examples + +You can run the examples with: + +(mb:load :qt.examples) +(qt.examples:launcher) + + + + +Repl + +Use a qt:string-list-model with a qt:list-view +to show evaluated lisp expressions. + + + + + + + + + + + + + + +Class Browser +Qt Classes browser using :qt.webkit to display the +API doc and a custom qt:list-model +for the qt:list-view of the available classes. + + + + + + + + + + + + + +

+ + diff -rN -u old-doc/smoke.docbook new-doc/smoke.docbook --- old-doc/smoke.docbook 2014-10-30 07:13:12.000000000 +0100 +++ new-doc/smoke.docbook 1970-01-01 01:00:00.000000000 +0100 @@ -1,204 +0,0 @@ - - - -Usage - -

Symbols - -C++ names are converted to Lisp symbols by converting camelCase -to camel-case. Underscores #\_ are replaced with -#\- and a leading uppercase K or Q is removed. - - -E.g.: QHelloWorld_foo becomes hello-world-foo. - -

- -

Class - -C++ classes have a corresponding CLOS class. The can be used like any CLOS class; E.g: -to make a QObject instance: - - -(make-instance 'qt:object) - - -Supply arguments as list to the :args keyword: - - -(let ((parent (make-instance 'qt:object))) - (make-instance 'qt:object :args (list parent))) - - - - -To extend a C++ class you have to use cxx:class as metaclass: - - -(defclass my-object (qt:object) - () - (:metaclass cxx:class)) - - - -

- -

Methods - -C++ methods are generic functions in the :cxx package. - - -The C++ method call: myInstance->frob(1); is in Lisp: - -(frob my-instance 1) - - -

Overload Resolution - -C++ style overload resolution with conversion sequences is suppored. For example this: - - -(cxx:set-pen (make-instance 'qt:painter) (make-instance 'qt:color :args '("green"))) - - -is equivalent to: - - -(cxx:set-pen (make-instance 'qt:painter) "green") - - -In the second case a temporary qt:color instance is implicitly created. - -

- -

Setter Methods - -Instead of calling a setter method that takes no additional arguments, - - -(cxx:set-object-name (make-instance 'qt:object) "foo") - - -you can use its setfable getter. - - -(setf (cxx:object-name (make-instance 'qt:object)) "foo") - - - -

- -

<code>defmethod</code> - -You can extend the :cxx generic functions by -adding methods. :around, :before, :after -and (call-next-method) are supported. - - -(defclass the-object-does-nothing (qt:object) - () - (:metaclass cxx:class)) - -(defmethod cxx:timer-event ((object the-object-does-nothing) event) - (declare (ignore object event)) - (call-next-method)) - - - -:cxx generic functions can be overload by argument count. Lambda list -keywords (e.g.: &rest and &key) are not supported. - - -Make sure you have the right number of arguments when adding a method; otherwise it will -not be called. - -

Operators - -Instead of using the various cxx:operator methods you can use their Lisp equivalent -in the :cxx package. - -cxx:> -cxx:>= - - -cxx:= -cxx:/= - - -cxx:<= -cxx:< - - -cxx:+ -cxx:- -cxx:* -cxx:/ -cxx:1+ -cxx:1- - - -cxx:incf -cxx:decf - - -cxx:aref - - -

- -

Static Methods - -The static C++ method QByteArray::number(int n, int base=10) -can be called by: - -(qt:byte-array.number 37) - -which is equivalent to the C++ code QByteArray::number(37);. -Or with: - -(cxx:number (find-class 'qt:byte-array) 37) - -or: - -(cxx:number (make-instance 'qt:byte-array) 37) - - -

- -

Constants - - C++ Class enums available as constants. E.g.: - QColor::Rgb is qt:color.+rgb+. - See :cxx-support. - -

- -

Garbage Collection - -You should be able to use C++ Class instances like normal Lisp object. - - -C++ classes are automatically 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 qt:object has a parent, a strong -reference is kept to prevent its garbage collection until the parent is deleted. - - - -An instance may depend on an other one. -It is a bad idea to do something like this: - -(defvar *meta* (cxx:meta-object (make-instance 'qt:object))) - -*meta* references a qt:meta-class -that can become invalid at any time, since the qt:object instance can -be garbage collected, and then the QMetaObject instance is deleted along -with the QObject. - - -

- - diff -rN -u old-doc/smoke.xml new-doc/smoke.xml --- old-doc/smoke.xml 1970-01-01 01:00:00.000000000 +0100 +++ new-doc/smoke.xml 2014-10-30 07:13:12.000000000 +0100 @@ -0,0 +1,204 @@ + + + +Usage + +

Symbols + +C++ names are converted to Lisp symbols by converting camelCase +to camel-case. Underscores #\_ are replaced with +#\- and a leading uppercase K or Q is removed. + + +E.g.: QHelloWorld_foo becomes hello-world-foo. + +

+ +

Class + +C++ classes have a corresponding CLOS class. The can be used like any CLOS class; E.g: +to make a QObject instance: + + +(make-instance 'qt:object) + + +Supply arguments as list to the :args keyword: + + +(let ((parent (make-instance 'qt:object))) + (make-instance 'qt:object :args (list parent))) + + + + +To extend a C++ class you have to use cxx:class as metaclass: + + +(defclass my-object (qt:object) + () + (:metaclass cxx:class)) + + + +

+ +

Methods + +C++ methods are generic functions in the :cxx package. + + +The C++ method call: myInstance->frob(1); is in Lisp: + +(frob my-instance 1) + + +

Overload Resolution + +C++ style overload resolution with conversion sequences is suppored. For example this: + + +(cxx:set-pen (make-instance 'qt:painter) (make-instance 'qt:color :args '("green"))) + + +is equivalent to: + + +(cxx:set-pen (make-instance 'qt:painter) "green") + + +In the second case a temporary qt:color instance is implicitly created. + +

+ +

Setter Methods + +Instead of calling a setter method that takes no additional arguments, + + +(cxx:set-object-name (make-instance 'qt:object) "foo") + + +you can use its setfable getter. + + +(setf (cxx:object-name (make-instance 'qt:object)) "foo") + + + +

+ +

<code>defmethod</code> + +You can extend the :cxx generic functions by +adding methods. :around, :before, :after +and (call-next-method) are supported. + + +(defclass the-object-does-nothing (qt:object) + () + (:metaclass cxx:class)) + +(defmethod cxx:timer-event ((object the-object-does-nothing) event) + (declare (ignore object event)) + (call-next-method)) + + + +:cxx generic functions can be overload by argument count. Lambda list +keywords (e.g.: &rest and &key) are not supported. + + +Make sure you have the right number of arguments when adding a method; otherwise it will +not be called. + +

Operators + +Instead of using the various cxx:operator methods you can use their Lisp equivalent +in the :cxx package. + +cxx:> +cxx:>= + + +cxx:= +cxx:/= + + +cxx:<= +cxx:< + + +cxx:+ +cxx:- +cxx:* +cxx:/ +cxx:1+ +cxx:1- + + +cxx:incf +cxx:decf + + +cxx:aref + + +

+ +

Static Methods + +The static C++ method QByteArray::number(int n, int base=10) +can be called by: + +(qt:byte-array.number 37) + +which is equivalent to the C++ code QByteArray::number(37);. +Or with: + +(cxx:number (find-class 'qt:byte-array) 37) + +or: + +(cxx:number (make-instance 'qt:byte-array) 37) + + +

+ +

Constants + + C++ Class enums available as constants. E.g.: + QColor::Rgb is qt:color.+rgb+. + See :cxx-support. + +

+ +

Garbage Collection + +You should be able to use C++ Class instances like normal Lisp object. + + +C++ classes are automatically 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 qt:object has a parent, a strong +reference is kept to prevent its garbage collection until the parent is deleted. + + + +An instance may depend on an other one. +It is a bad idea to do something like this: + +(defvar *meta* (cxx:meta-object (make-instance 'qt:object))) + +*meta* references a qt:meta-class +that can become invalid at any time, since the qt:object instance can +be garbage collected, and then the QMetaObject instance is deleted along +with the QObject. + + +

+ +