repos / doc / annotate_shade
summary | shortlog | log | tree | commit | commitdiff | headdiff | annotate | headblob | headfilediff | filehistory
normal | plain | shade | zebra
phonon & :arg0
Annotate for file smoke.xml
2009-04-05 tobias 1 <?xml version="1.0"?>
17:58:25 ' 2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
' 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2009-07-06 tobias 4 <chapter id="usage">
2009-04-05 tobias 5 <title>Usage</title>
17:58:25 ' 6 <para></para>
' 7 <section><title>Symbols</title>
' 8 <para>
' 9 C++ names are converted to Lisp symbols by converting <code>camelCase</code>
' 10 to <code>camel-case</code>. Underscores <code>#\_</code> are replaced with
' 11 <code>#\-</code> and a leading uppercase K or Q is removed.
' 12 </para>
2009-06-04 tobias 13 <informalexample>
2009-04-05 tobias 14 <para>
17:58:25 ' 15 E.g.: <code>QHelloWorld_foo</code> becomes <code>hello-world-foo</code>.
' 16 </para>
2009-06-04 tobias 17 </informalexample>
2009-04-05 tobias 18 </section>
17:58:25 ' 19
2009-07-06 tobias 20 <section id="classes"><title>Class</title>
2009-04-05 tobias 21 <para>
17:58:25 ' 22 C++ classes have a corresponding CLOS class. The can be used like any CLOS class; E.g:
' 23 to make a <code>QObject</code> instance:
' 24 <informalexample>
2009-06-05 tobias 25 <programlisting language="lisp">
2009-04-05 tobias 26 (make-instance '<classname>qt:object</classname>)
17:58:25 ' 27 </programlisting>
' 28 </informalexample>
2009-04-17 tobias 29 Supply arguments as list to the <code>:args</code> keyword:
2009-04-05 tobias 30 <informalexample>
2009-06-05 tobias 31 <programlisting language="lisp">
2009-04-05 tobias 32 (let ((parent (make-instance '<classname>qt:object</classname>)))
2009-08-30 tobias 33 (make-instance '<classname>qt:object</classname> :args (list parent)))
2009-04-05 tobias 34 </programlisting>
17:58:25 ' 35 </informalexample>
2009-07-22 tobias 36 or use <code>:arg0</code>, <code>:arg1</code> and <code>:arg2</code>.
22:53:41 ' 37 <informalexample>
' 38 <programlisting language="lisp">
' 39 (let ((parent (make-instance '<classname>qt:object</classname>)))
' 40 (make-instance '<classname>qt:object</classname> :arg0 parent))
' 41 </programlisting>
' 42 </informalexample>
2009-04-05 tobias 43 </para>
17:58:25 ' 44 <para>
' 45 To extend a C++ class you have to use <classname>cxx:class</classname> as metaclass:
' 46 <informalexample>
2009-06-05 tobias 47 <programlisting language="lisp">
2009-04-05 tobias 48 (defclass my-object (<classname>qt:object</classname>)
2009-08-30 tobias 49 ()
14:26:13 ' 50 (:metaclass <classname>cxx:class</classname>))
2009-04-05 tobias 51 </programlisting>
17:58:25 ' 52 </informalexample>
' 53 </para>
' 54 </section>
' 55
2009-07-06 tobias 56 <section id="methods"><title>Methods</title>
2009-04-05 tobias 57 <para>
2009-06-04 tobias 58 C++ methods are generic functions in the <package>:cxx</package> package.
2009-04-05 tobias 59 </para>
17:58:25 ' 60 <para>
' 61 The C++ method call: <code>myInstance->frob(1);</code> is in Lisp:
' 62 <informalexample>
2009-06-05 tobias 63 <programlisting language="lisp">(frob my-instance 1)</programlisting>
2009-04-05 tobias 64 </informalexample>
17:58:25 ' 65 </para>
2009-04-17 tobias 66 <section><title>Overload Resolution</title>
15:32:31 ' 67 <para>
2009-05-12 tobias 68 C++ style overload resolution with conversion sequences is supported. For example this:
2009-04-17 tobias 69 <informalexample>
2009-06-05 tobias 70 <programlisting language="lisp">
2009-05-11 tobias 71 (<genericfunction>cxx:set-pen</genericfunction> (make-instance '<classname>qt:painter</classname>) (make-instance '<classname>qt:color</classname> :args '("green")))
2009-04-17 tobias 72 </programlisting>
15:32:31 ' 73 </informalexample>
' 74 is equivalent to:
' 75 <informalexample>
2009-06-05 tobias 76 <programlisting language="lisp">
2009-05-11 tobias 77 (<genericfunction>cxx:set-pen</genericfunction> (make-instance '<classname>qt:painter</classname>) "green")
2009-04-17 tobias 78 </programlisting>
15:32:31 ' 79 </informalexample>
' 80 In the second case a temporary <classname>qt:color</classname> instance is implicitly created.
' 81 </para>
2009-09-02 tobias 82 <para>
12:08:06 ' 83 User defined conversions for return values are currently not supported (in <code>defmethods</code>).
' 84 </para>
2009-04-17 tobias 85 </section>
15:32:31 ' 86
2009-05-11 tobias 87 <section><title>Setter Methods</title>
20:19:30 ' 88 <para>
' 89 Instead of calling a setter method that takes no additional arguments,
' 90 <informalexample>
2009-06-05 tobias 91 <programlisting language="lisp">
2009-05-11 tobias 92 (<genericfunction>cxx:set-object-name</genericfunction> (make-instance '<classname>qt:object</classname>) "foo")
20:19:30 ' 93 </programlisting>
' 94 </informalexample>
' 95 you can use its <code>setf</code>able getter.
' 96 <informalexample>
2009-06-05 tobias 97 <programlisting language="lisp">
2009-05-11 tobias 98 (setf (<genericfunction>cxx:object-name</genericfunction> (make-instance '<classname>qt:object</classname>)) "foo")
20:19:30 ' 99 </programlisting>
' 100 </informalexample>
' 101 </para>
' 102 </section>
' 103
' 104 <section><title><code>defmethod</code></title>
2009-04-05 tobias 105 <para>
17:58:25 ' 106 You can extend the <package>:cxx</package> generic functions by
' 107 adding methods. <code>:around</code>, <code>:before</code>, <code>:after</code>
' 108 and <code>(call-next-method)</code> are supported.
' 109 </para>
2009-04-12 tobias 110 <informalexample>
2009-06-05 tobias 111 <programlisting language="lisp">(defclass the-object-does-nothing (<classname>qt:object</classname>)
2009-08-30 tobias 112 ()
14:26:13 ' 113 (:metaclass <classname>cxx:class</classname>))
2009-04-12 tobias 114
2009-04-12 tobias 115 (defmethod <genericfunction>cxx:timer-event</genericfunction> ((object the-object-does-nothing) event)
2009-08-30 tobias 116 (declare (ignore object event))
14:26:13 ' 117 (call-next-method))
2009-04-12 tobias 118 </programlisting>
14:50:23 ' 119 </informalexample>
' 120 <para>
' 121 <package>:cxx</package> generic functions can be overload by argument count. Lambda list
' 122 keywords (e.g.: <code>&amp;rest</code> and <code>&amp;key</code>) are not supported.
' 123 </para>
' 124 <note><para>
' 125 Make sure you have the right number of arguments when adding a method; otherwise it will
' 126 not be called.
' 127 </para></note>
2009-06-04 tobias 128 <caution><para>
21:20:49 ' 129 The arguments of the method might have dynamic extend; i.e.: they are only valid in the body of the method.
' 130 </para></caution>
2009-06-03 tobias 131 <section><title>Condition</title>
22:31:34 ' 132 <para>
' 133 Unwinding of the C++ stack is not supported. This means that you must not invoke a restart that skips any foreign function.
2009-06-04 tobias 134 You will most likely encounter this problem when an error is signaled in a virtual method you have overwritten.
2009-06-03 tobias 135 <footnote>
22:31:34 ' 136 <para>
' 137 For example an event handler that is called from the C++ library.
' 138 </para>
' 139 </footnote>. For this case restarts are provide that allow to return a value for the failed method,
' 140 call the default C++ implementation instead (something like <code>#'call-next-method</code>) or retry.
' 141 </para>
' 142 </section>
2009-04-05 tobias 143 </section>
2009-04-12 tobias 144 <section><title>Operators</title>
20:56:16 ' 145 <para>
2009-05-11 tobias 146 Instead of using the various <code>cxx:operator</code> methods you can use their Lisp equivalent
2009-04-12 tobias 147 in the <package>:cxx</package> package.
2009-04-14 tobias 148 <simplelist type='horiz' columns='4'>
14:08:15 ' 149 <member><code>cxx:&gt;</code></member> <!-- FIXME mb.document handling of no alphnum chars !-->
' 150 <member><code>cxx:&gt;=</code></member>
' 151 </simplelist>
' 152 <simplelist type='horiz' columns='4'>
' 153 <member><code>cxx:=</code></member>
' 154 <member><code>cxx:/=</code></member>
' 155 </simplelist>
' 156 <simplelist type='horiz' columns='4'>
' 157 <member><code>cxx:&lt;=</code></member>
' 158 <member><code>cxx:&lt;</code></member>
' 159 </simplelist>
' 160 <simplelist type='horiz' columns='4'>
' 161 <member><code>cxx:+</code></member>
' 162 <member><code>cxx:-</code></member>
' 163 <member><code>cxx:*</code></member>
' 164 <member><code>cxx:/</code></member>
' 165 <member><code>cxx:1+</code></member>
' 166 <member><code>cxx:1-</code></member>
' 167 </simplelist>
' 168 <simplelist type='horiz' columns='4'>
' 169 <member><methodname>cxx:incf</methodname></member>
' 170 <member><methodname>cxx:decf</methodname></member>
' 171 </simplelist>
' 172 <simplelist>
' 173 <member><methodname>cxx:aref</methodname></member>
' 174 </simplelist>
2009-04-12 tobias 175 </para>
20:56:16 ' 176 </section>
' 177 </section>
2009-04-05 tobias 178
2009-07-06 tobias 179 <section id="static_methods"><title>Static Methods</title>
2009-04-05 tobias 180 <para>
17:58:25 ' 181 The static C++ method <code>QByteArray::number(int n, int base=10)</code>
' 182 can be called by:
' 183 <informalexample>
2009-06-05 tobias 184 <programlisting language="lisp">(<methodname>qt:byte-array.number</methodname> 37)</programlisting>
2009-04-05 tobias 185 </informalexample>
17:58:25 ' 186 which is equivalent to the C++ code <code>QByteArray::number(37);</code>.
' 187 Or with:
' 188 <informalexample>
2009-06-05 tobias 189 <programlisting language="lisp">(<genericfunction>cxx:number</genericfunction> (find-class '<classname>qt:byte-array</classname>) 37)</programlisting>
2009-05-11 tobias 190 </informalexample>
20:19:30 ' 191 or:
' 192 <informalexample>
2009-06-05 tobias 193 <programlisting language="lisp">(<genericfunction>cxx:number</genericfunction> (make-instance '<classname>qt:byte-array</classname>) 37)</programlisting>
2009-04-05 tobias 194 </informalexample>
17:58:25 ' 195 </para>
' 196 </section>
' 197
2009-07-06 tobias 198 <section id="constants"><title>Constants</title>
2009-04-05 tobias 199 <para>
2009-08-30 tobias 200 C++ Class enums available as constants. E.g.:
14:26:13 ' 201 <code>QColor::Rgb</code> is <constant>qt:color.+rgb+</constant>.
' 202 See <package>:cxx-support</package>.
2009-04-05 tobias 203 </para>
17:58:25 ' 204 </section>
' 205
2009-07-06 tobias 206 <section id="gc"><title>Garbage Collection</title>
2009-04-05 tobias 207 <para>
17:58:25 ' 208 You should be able to use C++ Class instances like normal Lisp object.
' 209 </para>
' 210 <para>
2009-06-04 tobias 211 C++ classes are automatically deleted when their Lisp object gets garbage collected;
2009-04-05 tobias 212 except when they (QObjects) have a parent and thus the parent is responsible for
17:58:25 ' 213 their deletion. When a <classname>qt:object</classname> has a parent, a strong
2009-06-04 tobias 214 reference is kept to prevent the garbage collection removing it until the parent is deleted.
2009-04-05 tobias 215 </para>
2009-04-12 tobias 216 <caution>
2009-04-09 tobias 217 <para>
2009-08-02 tobias 218 An instance may depend on an other one.
11:24:57 ' 219 It is a bad idea to do something like this:
' 220 <programlisting language="lisp">
' 221 (defvar *meta* (<genericfunction>cxx:meta-object</genericfunction> (make-instance 'qt:object)))
' 222 </programlisting>
' 223 <code>*meta*</code> references a <classname>qt:meta-class</classname>
' 224 that can become invalid at any time, since the <classname>qt:object</classname> instance can
' 225 be garbage collected, and then the <code>QMetaObject</code> instance is deleted along
' 226 with the <code>QObject</code>.
' 227 </para>
' 228 </caution>
' 229 <caution>
' 230 <para>
2009-08-30 tobias 231 Ownership transfer for non QObject instances is mostly unimplemented.
2009-06-04 tobias 232 </para>
21:20:49 ' 233 </caution>
2009-04-05 tobias 234 </section>
2009-05-19 tobias 235
2009-05-14 tobias 236 <section id="core-image"><title>Saving a Core Image</title>
12:56:16 ' 237 <para>
2009-05-19 tobias 238 For near instant startup you can save an image. Since saving C++ instances is not supported,
14:44:30 ' 239 it is best to save the image immediately after loading the packages.
2009-05-14 tobias 240 </para>
2009-05-19 tobias 241
14:44:30 ' 242 <note><para>
' 243 Initializing the Smoke bindings when the image is loaded is implementation dependent. It is implemented
' 244 for SBCL and Clozure CL.
' 245 </para></note>
' 246
' 247 <section><title>SBCL</title>
' 248 <para>To save an image in SBCL you can use:
' 249 <ulink url="http://www.sbcl.org/manual/Saving-a-Core-Image.html"><code>sb-ext:save-lisp-and-die</code></ulink>
' 250 </para>
' 251
2009-05-14 tobias 252 <section><title>Bundle</title>
12:56:16 ' 253 <para>
' 254 To create a bundle containing an SBCL image and the required C wrappers libraries you can use
' 255 <methodname>smoke:save-bundle</methodname>.
' 256 The bundle is created using <ulink url="http://megastep.org/makeself/">makeself</ulink>.
' 257 See
' 258 <ulink url="http://tobias.rautenkranz.ch/darcsweb/darcsweb.cgi?r=cl-smoke/qt.examples;a=headblob;f=/make-bundle.sh">make-bundle.sh</ulink> in <package>:qt.examples</package> for an example.
' 259 </para>
' 260 </section>
' 261 </section>
2009-04-05 tobias 262
2009-05-19 tobias 263 <section><title>Clozure CL</title>
14:44:30 ' 264 <para>
' 265 To save an image in CCL
' 266 <ulink url="http://ccl.clozure.com/manual/chapter4.7.html#Saving-Applications">
' 267 <code>ccl:save-application</code></ulink> is usually used.
' 268 </para>
' 269 <caution>
' 270 <para>
' 271 To allow the image to find the C wrapper libraries, they have to be installed with:
' 272 <informalexample>
' 273 <programlisting>
' 274 sudo make install
' 275 </programlisting>
' 276 </informalexample>
' 277 run in the <filename>smoke/</filename> and <filename>qt/</filename> directory.
' 278 </para>
' 279 </caution>
' 280 </section>
' 281
' 282 </section>
' 283
2009-04-05 tobias 284 </chapter>
Crece desde el pueblo el futuro / crece desde el pie