Thu Jun 4 23:20:49 CEST 2009 Tobias Rautenkranz <tobias@rautenkranz.ch>

* interactive development

--- old-doc/introduction.xml 2014-10-30 06:55:13.000000000 +0100

+++ new-doc/introduction.xml 2014-10-30 06:55:13.000000000 +0100

@@ -14,17 +14,16 @@

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

</itemizedlist>

</section>

-<section><title>Status</title>

-<para>

-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++ (<code>QList</code> etc.).

-</para>

-

<section><title>Limitations</title>

<itemizedlist>

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

- </para></listitem>

+ <listitem><para>Ownership transfer to / from C++ of non QObject objects is seldom known to cl-smoke.

+ E.g.: cl-smoke might delete an instance even though it is still needed by C++.

+ (One that is known is <ulink url="http://doc.qtsoftware.com/4.5-snapshot/qundostack.html#push">QUndoStack::push()</ulink>.)

+ </para></listitem>

+ <listitem><para>Limited conversions to and from C++. You will get an NO-APPLICABLE-CXX-METHOD error

+ when a Lisp to C++ conversion is missing and a pointer will be returned when there is no C++ to Lisp

+ conversion.

+ </para></listitem>

<listitem><para>10 seconds startup time<footnote>

<para>

Using an image it is around 1 second.

@@ -33,13 +32,10 @@

(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>Does not recover well from errors

- <footnote><para>Thus you often need to restart the Lisp process

- during interactive development.</para></footnote>.</para></listitem>

+ <listitem><para>Could be faster</para></listitem>

<listitem><para>No const-correctness</para></listitem>

</itemizedlist>

</section>

-</section>

<section><title>Installation</title>

<section><title>Dependencies</title>

<itemizedlist>

@@ -106,7 +102,7 @@

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

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

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

done

</programlisting>

@@ -146,7 +142,7 @@

in the <filename>smoke/</filename> and <filename>qt/</filename> directories.

</para>

<note><para>

- Some examples get the paths for files to load from their Mudballs system (ui and i18n) and thus will not work.

+ Some examples get the paths for the files to load from their Mudballs system (ui and i18n) and thus will not work.

</para></note>

</section>

</section>

--- old-doc/kde.xml 2014-10-30 06:55:13.000000000 +0100

+++ new-doc/kde.xml 2014-10-30 06:55:13.000000000 +0100

@@ -15,7 +15,7 @@

<programlisting>

(mb:load <package>:kde.examples</package>)

</programlisting>

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

+And then running the function of the example; e.g.:

<programlisting>

(<methodname>kde.examples:mandelbrot</methodname>)

</programlisting>

--- old-doc/qt.xml 2014-10-30 06:55:13.000000000 +0100

+++ new-doc/qt.xml 2014-10-30 06:55:13.000000000 +0100

@@ -47,6 +47,20 @@

a <classname>qt:application</classname> instance exists. When there are, for example, <classname>qt:widget</classname> instances

at the end of <macro>qt:with-app</macro>, they are deleted by the <classname>qt:application</classname> destructor.

</para>

+<section><title>Interactive Development</title>

+<para>

+The <package>:cl-smoke.repl</package> allows you to start a <classname>qt:application</classname> event loop in the background for

+interactive development in SLIME.

+To start the event loop use <methodname>cl-smoke.repl:start-event-loop-in-background</methodname> (or

+<methodname>cl-smoke.repl:start-event-loop-in-repl</methodname>).

+<footnote>

+<para>

+Currently <code>START-EVENT-LOOP-IN-BACKGROUND</code> is recommended.

+</para>

+</footnote>

+As long as you do not kill the thread or unwind over a foreign function, you should be fine.

+</para>

+</section>

</section>

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

@@ -66,7 +80,8 @@

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

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

+allows to pass a Lisp object as is from a Lisp signal to a Lisp slot.

</para>

<para>

@@ -132,7 +147,7 @@

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.

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

</para>

</section>

--- old-doc/smoke.xml 2014-10-30 06:55:13.000000000 +0100

+++ new-doc/smoke.xml 2014-10-30 06:55:13.000000000 +0100

@@ -10,9 +10,11 @@

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

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

</para>

+<informalexample>

<para>

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

</para>

+</informalexample>

</section>

<section><title>Class</title>

@@ -46,7 +48,7 @@

<section><title>Methods</title>

<para>

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

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

</para>

<para>

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

@@ -116,10 +118,13 @@

Make sure you have the right number of arguments when adding a method; otherwise it will

not be called.

</para></note>

+<caution><para>

+The arguments of the method might have dynamic extend; i.e.: they are only valid in the body of the method.

+</para></caution>

<section><title>Condition</title>

<para>

Unwinding of the C++ stack is not supported. This means that you must not invoke a restart that skips any foreign function.

-You will most likely encounter this problem when an error is signaled in a virtual method you have overwritten

+You will most likely encounter this problem when an error is signaled in a virtual method you have overwritten.

<footnote>

<para>

For example an event handler that is called from the C++ library.

@@ -196,10 +201,10 @@

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

</para>

<para>

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

+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 <classname>qt:object</classname> has a parent, a strong

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

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

</para>

<caution>

<para>

@@ -214,6 +219,11 @@

with the <code>QObject</code>.

</para>

</caution>

+<caution>

+<para>

+ Ownership transfer for non QObject instances is mostly unimplemented.

+</para>

+</caution>

</section>

<section id="core-image"><title>Saving a Core Image</title>