add GC for QGET, QFUN return values; fix possible memory leaks (e.g. overridden metho...
[eql:eql.git] / doc / auto-doc.htm
1 <html><body><p>
2 <b>QADD-EVENT-FILTER (object event function)\r</b>
3 <p>Adds a Lisp function to be called on a given event type. The event type has to be passed as integer value. If the object argument is <code>NIL</code>, the event will be captured for any object. If the Lisp function returns <code>NIL</code>, the event will be processed by Qt afterwards.\r</p>
4 <pre>
5   (qadd-event-filter nil +mouse-button-press+ (lambda (obj ev) (print obj) nil))\r
6 </pre>
7 </p><br>
8 <p>
9 <b>QAPP ()\r</b>
10 <p>Convenience function returning <code>qApp</code>.\r</p>
11 </p><br>
12 <p>
13 <b>QAPROPOS (&optional search class)\r</b>
14 <p>Finds all occurrencies of the given search term in the given object's meta information.<br>Constructors are listed under <b>Methods</b>.\r</p>
15 <pre>
16   (qapropos "html" "QTextEdit")\r
17   (qapropos nil "QWidget")\r
18   (qapropos)\r
19 </pre>
20 </p><br>
21 <p>
22 <b>QAPROPOS* (&optional search class)</b>
23 <p>Similar to <code>qapropos</code>, returning the results as nested list.</p>
24 </p><br>
25 <p>
26 <b>QCLEAR-EVENT-FILTERS ()\r</b>
27 <p>Clears all added event filters.\r</p>
28 </p><br>
29 <p>
30 <b>QCONNECT (caller signal receiver slot)\r</b>
31 <p>Connects either a Qt signal to a Qt slot, or a Qt signal to a Lisp function.\r</p>
32 <pre>
33   (qconnect edit "textChanged(QString)" label "setText(QString)")\r
34   (qconnect edit "textChanged(QString)" (lambda (txt) (print txt)))\r
35 </pre>
36 </p><br>
37 <p>
38 <b>QCOPY (object)\r</b>
39 <p>Copies object if possible. Only few Qt classes allow copying.\r</p>
40 <pre>
41   (qcopy pixmap)\r
42 </pre>
43 </p><br>
44 <p>
45 <b>QDELETE (object)\r</b>
46 <br>
47 <b>QDEL\r</b>
48 <p>Deletes any Qt object, and sets the <code>pointer</code> value to <code>0</code>.\r</p>
49 <pre>
50   (qdel widget)\r
51 </pre>
52 </p><br>
53 <p>
54 <b>QEQL (object1 object2)</b>
55 <p>Returns <code>T</code> for same instances of a Qt class.</p>
56 </p><br>
57 <p>
58 <b>QESCAPE (string)\r</b>
59 <p>Calls <code>Qt::escape()</code>.\r</p>
60 </p><br>
61 <p>
62 <b>QEXEC ()\r</b>
63 <p>Convenience function to call <code>QApplication::exec()</code>.\r</p>
64 </p><br>
65 <p>
66 <b>QFIND-CHILD (object name)\r</b>
67 <p>Calls <code>qFindChild&lt;QObject*&gt;()</code>. Can be used to get the single widgets of a UI (see <code>qload-ui</code>), identified by <code>objectName</code>.\r</p>
68 </p><br>
69 <p>
70 <b>QFROM-UTF8 (byte-array)\r</b>
71 <p>Returns the byte array (vector of octets) converted using <code>QString::fromUtf8()</code>.\r</p>
72 </p><br>
73 <p>
74 <b>QGUI (&optional process-events)</b>
75 <p>Launches the <code>EQL</code> convenience GUI.<br>If you don't have an interactive environment, you can pass <code>T</code> to run a pseudo Qt event loop. A better option is to start the tool like so:<br><code>./eql -qgui</code>, in order to run the Qt event loop natively.</p>
76 </p><br>
77 <p>
78 <b>QID (name)\r</b>
79 <p>Returns the internally used ID of the object name. Non QObject classes have negative ids.\r</p>
80 <pre>
81   (qid "QWidget")\r
82 </pre>
83 </p><br>
84 <p>
85 <b>QINVOKE-METHOD (object name &rest arguments)\r</b>
86 <br>
87 <b>QFUN\r</b>
88 <p>Calls any of Qt methods, slots, signals ("emit" in jargon). Static methods can be called by passing the string name of an object.<br>For overloaded Qt methods you may need to pass the argument types (as for <code>qconnect</code> and <code>qoverride</code>). In these (very few) ambiguous cases you will see a runtime error message, together with a list of all possible candidates.\r</p>
89 <pre>
90   (qfun item "setText" 0 "Some objects are EQL.")\r
91   (qfun "QDateTime" "currentDateTime") ; static method\r
92   (qfun slider "valueChanged" 10) ; emit signal\r
93 </pre>
94 </p><br>
95 <p>
96 <b>QINVOKE-METHOD* (object class name &rest arguments)</b>
97 <br>
98 <b>QFUN*</b>
99 <p>Similar to <code>qinvoke-method</code>, additionally passing a class name, enforcing a cast to that class.</p>
100 <pre>
101   (qfun* event "QKeyEvent" "key")
102   (qfun* graphics-text-item "QGraphicsItem" "setPos" (list x y)) ; multiple inheritance problem
103   (qfun* *qt-main* :qt "foo") ; call embedded Qt/C++ function (see Qt_EQL)
104 </pre>
105 </p><br>
106 <p>
107 <b>QLET (((var exp) ...) ...)</b>
108 <p>Similar to <code>let*</code>. Creates temporary Qt objects, deleting them at the end of the <code>qlet</code> body. If <code>exp</code> is a string, it will be substituted with <code>(qnew exp)</code>, optionally including constructor arguments.</p>
109 <pre>
110   (qlet ((painter "QPainter")) ...)
111   (qlet ((reg-exp "QRegExp(QString)" "^\\S+$")) ...)
112 </pre>
113 </p><br>
114 <p>
115 <b>QLOAD-UI (file)\r</b>
116 <p>Calls a custom <code>QUiLoader::load()</code> function, loading a UI file created by Qt Designer. Returns the top level widget of the UI. Use <code>qfind-child</code> to retrieve the child widgets.\r</p>
117 </p><br>
118 <p>
119 <b>QLOCAL8BIT (string)\r</b>
120 <p>Returns the string converted using <code>QString::toLocal8Bit()</code> (see <code>QLocale</code> settings).<br>Depending on the OS, this can be necessary if you get a filename from Qt and want to use it in Lisp.\r</p>
121 </p><br>
122 <p>
123 <b>QMESSAGE-BOX (x)</b>
124 <br>
125 <b>QMSG</b>
126 <p>Convenience function, calling: (converting x to a string if necessary)</p>
127 <pre>
128   (qfun "QMessageBox" "information" nil "EQL" x))
129 </pre>
130 </p><br>
131 <p>
132 <b>QNEW-INSTANCE (name &rest arguments)\r</b>
133 <br>
134 <b>QNEW\r</b>
135 <p>Creates a new Qt object, optionally passing the given arguments to the constructor. Additionally you can pass any number of property/value pairs.<br>Please note how you can abbreviate long type lists.\r</p>
136 <pre>
137   (qnew "QWidget")\r
138   (qnew "QPixmap(int,int)" 50 50)\r
139   (qnew "QLabel" "text" "I love me.")\r
140   (qnew "QMatrix4x4(qreal...)" 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4)\r
141 </pre>
142 </p><br>
143 <p>
144 <b>QNULL-OBJECT (object)</b>
145 <p>Checks for a <code>0</code> Qt object pointer.</p>
146 </p><br>
147 <p>
148 <b>QOBJECT-NAMES (&optional type)\r</b>
149 <p>Returns all supported object names. Passing either <code>:q</code> or <code>:n</code> returns only the QObject inherited, or not QObject inherited names, respectively.\r</p>
150 </p><br>
151 <p>
152 <b>QOK ()\r</b>
153 <p>Needed to get the boolean <b>ok</b> value in cases like this:\r</p>
154 <pre>
155   (qfun "QFontDialog" "getFont(bool*)" nil)\r
156 </pre>
157 </p><br>
158 <p>
159 <b>QOVERRIDE (object name function)\r</b>
160 <p>Sets a Lisp function to be called on a virtual Qt method. If the Lisp function returns <code>NIL</code>, the default Qt method will be called afterwards.<br><br>To remove a function, pass <code>NIL</code> instead of the function argument.\r</p>
161 <pre>
162   (qoverride edit "keyPressEvent(QKeyEvent*)" (lambda (ev) (print (qfun ev "key")) nil))\r
163 </pre>
164 </p><br>
165 <p>
166 <b>QPROCESS-EVENTS ()\r</b>
167 <p>Convenience function to call <code>QApplication::processEvents()</code>.\r</p>
168 </p><br>
169 <p>
170 <b>QPROPERTY (object name)\r</b>
171 <br>
172 <b>QGET\r</b>
173 <p>Gets a Qt property. Enumerator values are returned as <code>int</code> values.\r</p>
174 <pre>
175   (qget label "text")\r
176 </pre>
177 </p><br>
178 <p>
179 <b>QQUIT ()\r</b>
180 <br>
181 <b>QQ\r</b>
182 <p>Quits both Qt and ECL.\r</p>
183 </p><br>
184 <p>
185 <b>QREQUIRE (module)\r</b>
186 <p>Loads an EQL module, corresponding to a Qt module. Returns the module name if both loading and initializing have been successful.\r</p>
187 <pre>
188   (qrequire :network)\r
189 </pre>
190 </p><br>
191 <p>
192 <b>QSENDER ()\r</b>
193 <p>Corresponding to <code>QObject::sender()</code>. To use inside a Lisp function connected to a Qt signal.\r</p>
194 </p><br>
195 <p>
196 <b>QSET-NULL (object)</b>
197 <p>Sets the Qt object pointer to <code>0</code>. This function is called automatically after <code>qdel</code>.</p>
198 </p><br>
199 <p>
200 <b>QSET-PROPERTY (object name value)\r</b>
201 <br>
202 <b>QSET\r</b>
203 <p>Sets a Qt property. Enumerator values have to be passed as <code>int</code> values.\r</p>
204 <pre>
205   (qset label "alignment" |Qt.AlignCenter|)\r
206 </pre>
207 </p><br>
208 <p>
209 <b>QSINGLE-SHOT (milliseconds function)\r</b>
210 <p>Convenience function: a single shot timer for Lisp functions (using <code>QTimer::singleShot</code>). You can use only 1 at a time, so if you need real timers, use <code>QTimer</code> directly.\r</p>
211 <pre>
212   (qsingle-shot 0 'on-qt-idle)\r
213 </pre>
214 </p><br>
215 <p>
216 <b>QSTATIC-META-OBJECT (name)\r</b>
217 <p>Returns the static QMetaObject of the given QObject name.\r</p>
218 <pre>
219   (qstatic-meta-object "QWidget")\r
220 </pre>
221 </p><br>
222 <p>
223 <b>QSUPER-CLASS-NAME (name)\r</b>
224 <p>Returns the super class of an object name, or <code>NIL</code> if the class doesn't inherit another Qt class.<br>Returns <code>T</code> as second return value for successful calls.\r</p>
225 <pre>
226   (qsuper-class-name "QGraphicsLineItem")\r
227 </pre>
228 </p><br>
229 <p>
230 <b>QT-OBJECT-NAME (object)\r</b>
231 <p>Returns the Qt class name.\r</p>
232 </p><br>
233 <p>
234 <b>QUI-CLASS (file &optional name)\r</b>
235 <p>Finds the class name for the given user-defined object name in the given UI file.<br>Omitting the object name will return the top level class name of the UI.\r</p>
236 <pre>
237   (qui-class "examples/data/main-window.ui" "edit") ; returns "QTextEdit"\r
238 </pre>
239 </p><br>
240 <p>
241 <b>QUI-NAMES (file)\r</b>
242 <p>Finds all user-defined object names in the given UI file.\r</p>
243 <pre>
244   (qui-names "examples/data/main-window.ui")\r
245 </pre>
246 </p><br>
247 <p>
248 <b>QUTF8 (string)\r</b>
249 <p>Returns the string converted using <code>QString::toUtf8()</code>.<br>Depending on the OS, this can be necessary if you get a filename from Qt and want to use it in Lisp.\r</p>
250 </p><br>
251 <p>
252 <b>QVERSION  ()\r</b>
253 <p>Returns the EQL version number as "&lt;year&gt;.&lt;month&gt;.&lt;counter&gt;", analogous to the ECL version number.<br>The second return value is the Qt version as returned by <code>qVersion()</code>.\r</p>
254 </p><br>
255 <p>
256 <b>TR (source &optional context n)</b>
257 <p>Macro expanding to <code>qtranslate</code>, which calls <code>QCoreApplication::translate()</code>. Both <code>source</code> and <code>context</code> can be Lisp forms evaluating to constant strings (at compile time).<br>The <code>context</code> argument defaults to the Lisp file name, and the <code>n</code> argument is a plural indicator (see Qt Assistant).</p>
258 </p><br>
259 </body></html>