fix bug in QOVERRIDE (adding new function QCALL-DEFAULT); update examples & docu...
[eql:eql.git] / doc / auto-doc.htm
1 <html><body><p>
2 <b>DEFVAR-UI (main-widget &rest variable-names)</b>
3 <p>This macro simplifies the definition of UI variables:</p>
4 <pre>
5   (defvar-ui *main* *line-edit* ...) ; this will expand to:
6   (progn (defvar *line-edit* (qfind-child *main* "line_edit")) ...)
7 </pre>
8 </p><br>
9 <p>
10 <b>QADD-EVENT-FILTER (object event function)\r</b>
11 <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>
12 <pre>
13   (qadd-event-filter nil +mouse-button-press+ (lambda (obj ev) (print obj) nil))\r
14 </pre>
15 </p><br>
16 <p>
17 <b>QAPP ()\r</b>
18 <p>Convenience function returning <code>qApp</code>.\r</p>
19 </p><br>
20 <p>
21 <b>QAPROPOS (&optional search class)\r</b>
22 <p>Finds all occurrencies of the given search term in the given object's meta information.<br>Constructors are listed under <b>Methods</b>.<br>To list the user defined functions of external C++ classes (see Qt_EQL), pass the object instead of the class name.\r</p>
23 <pre>
24   (qapropos "html" "QTextEdit")\r
25   (qapropos nil "QWidget")\r
26   (qapropos)\r
27   (qapropos nil *qt-main*) ; embedded C++ (see Qt_EQL)\r
28 </pre>
29 </p><br>
30 <p>
31 <b>QAPROPOS* (&optional search class)</b>
32 <p>Similar to <code>qapropos</code>, returning the results as nested list.</p>
33 </p><br>
34 <p>
35 <b>QCALL-DEFAULT ()\r</b>
36 <p>To use inside an overriden function (see <code>qoverride</code>).<br>Calls the base implementation of the virtual Qt method.\r</p>
37 </p><br>
38 <p>
39 <b>QCLEAR-EVENT-FILTERS ()\r</b>
40 <p>Clears all added event filters.\r</p>
41 </p><br>
42 <p>
43 <b>QCONNECT (caller signal receiver slot)\r</b>
44 <p>Connects either a Qt signal to a Qt slot, or a Qt signal to a Lisp function.\r</p>
45 <pre>
46   (qconnect edit "textChanged(QString)" label "setText(QString)")\r
47   (qconnect edit "textChanged(QString)" (lambda (txt) (print txt)))\r
48 </pre>
49 </p><br>
50 <p>
51 <b>QCOPY (object)\r</b>
52 <p>Copies object if possible. Only few Qt classes allow copying.\r</p>
53 <pre>
54   (qcopy pixmap)\r
55 </pre>
56 </p><br>
57 <p>
58 <b>QDELETE (object &optional later)\r</b>
59 <br>
60 <b>QDEL\r</b>
61 <p>Deletes any Qt object, and sets the <code>pointer</code> value to <code>0</code>. Deleting a widget deletes all its child widgets, too.<br>If <code>later</code> is not <code>NIL</code>, the function <code>QObject::deleteLater()</code> will be called instead.<br>See <code>qlet</code> for local Qt objects.<br>Returns <code>T</code> if the object has effectively been deleted.\r</p>
62 <pre>
63   (qdel widget)\r
64   (qdel socket :later)\r
65 </pre>
66 </p><br>
67 <p>
68 <b>QEQL (object1 object2)</b>
69 <p>Returns <code>T</code> for same instances of a Qt class.</p>
70 </p><br>
71 <p>
72 <b>QESCAPE (string)\r</b>
73 <p>Calls <code>Qt::escape()</code>.\r</p>
74 </p><br>
75 <p>
76 <b>QEXEC ()\r</b>
77 <p>Convenience function to call <code>QApplication::exec()</code>.\r</p>
78 </p><br>
79 <p>
80 <b>QFIND-CHILD (object name)\r</b>
81 <p>Calls <code>qFindChild&lt;QObject*&gt;()</code>.<br>Can be used to get the child objects of any Qt object (typically from a UI, see <code>qload-ui</code>), identified by <code>objectName</code>.\r</p>
82 </p><br>
83 <p>
84 <b>QFROM-UTF8 (byte-array)\r</b>
85 <p>Returns the byte array (vector of octets) converted using <code>QString::fromUtf8()</code>.\r</p>
86 </p><br>
87 <p>
88 <b>QGUI (&optional process-events)</b>
89 <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>
90 </p><br>
91 <p>
92 <b>QID (name)\r</b>
93 <p>Returns the internally used ID of the object name. Non QObject classes have negative ids.\r</p>
94 <pre>
95   (qid "QWidget")\r
96 </pre>
97 </p><br>
98 <p>
99 <b>QINVOKE-METHOD (object name &rest arguments)\r</b>
100 <br>
101 <b>QFUN\r</b>
102 <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>
103 <pre>
104   (qfun item "setText" 0 "Some objects are EQL.")\r
105   (qfun "QDateTime" "currentDateTime") ; static method\r
106   (qfun slider "valueChanged" 10) ; emit signal\r
107 </pre>
108 </p><br>
109 <p>
110 <b>QINVOKE-METHOD* (object class name &rest arguments)</b>
111 <br>
112 <b>QFUN*</b>
113 <p>Similar to <code>qinvoke-method</code>, additionally passing a class name, enforcing a cast to that class.</p>
114 <pre>
115   (qfun* event "QKeyEvent" "key")
116   (qfun* graphics-text-item "QGraphicsItem" "setPos" (list x y)) ; multiple inheritance problem
117   (qfun* *qt-main* :qt "foo") ; embedded Qt/C++ (see Qt_EQL)
118 </pre>
119 </p><br>
120 <p>
121 <b>QLET (((var exp) ...) ...)</b>
122 <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>
123 <pre>
124   (qlet ((painter "QPainter")) ...)
125   (qlet ((reg-exp "QRegExp(QString)" "^\\S+$")) ...)
126 </pre>
127 </p><br>
128 <p>
129 <b>QLOAD-UI (file)\r</b>
130 <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>
131 </p><br>
132 <p>
133 <b>QLOCAL8BIT (string)\r</b>
134 <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>
135 </p><br>
136 <p>
137 <b>QMESSAGE-BOX (x)</b>
138 <br>
139 <b>QMSG</b>
140 <p>Convenience function, calling: (converting x to a string if necessary)</p>
141 <pre>
142   (qfun "QMessageBox" "information" nil "EQL" x))
143 </pre>
144 </p><br>
145 <p>
146 <b>QNEW-INSTANCE (name &rest arguments)\r</b>
147 <br>
148 <b>QNEW\r</b>
149 <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>
150 <pre>
151   (qnew "QWidget")\r
152   (qnew "QPixmap(int,int)" 50 50) ; constructor\r
153   (qnew "QLabel" "text" "I love me.") ; set property\r
154   (qnew "QMatrix4x4(qreal...)" 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4)\r
155 </pre>
156 </p><br>
157 <p>
158 <b>QNULL-OBJECT (object)</b>
159 <p>Checks for a <code>0</code> Qt object pointer.</p>
160 </p><br>
161 <p>
162 <b>QOBJECT-NAMES (&optional type)\r</b>
163 <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>
164 </p><br>
165 <p>
166 <b>QOK ()\r</b>
167 <p>Needed to get the boolean <b>ok</b> value in cases like this:\r</p>
168 <pre>
169   (qfun "QFontDialog" "getFont(bool*)" nil)\r
170 </pre>
171 </p><br>
172 <p>
173 <b>QOVERRIDE (object name function)\r</b>
174 <p>Sets a Lisp function to be called on a virtual Qt method.<br>To remove a function, pass <code>NIL</code> instead of the function argument.<br>Use <code>qcall-default</code> inside your function to call the base implementation.\r</p>
175 <pre>
176   (qoverride edit "keyPressEvent(QKeyEvent*)" (lambda (ev) (print (qfun ev "key")) (qcall-default)))\r
177 </pre>
178 </p><br>
179 <p>
180 <b>QPROCESS-EVENTS ()\r</b>
181 <p>Convenience function to call <code>QApplication::processEvents()</code>.\r</p>
182 </p><br>
183 <p>
184 <b>QPROPERTY (object name)\r</b>
185 <br>
186 <b>QGET\r</b>
187 <p>Gets a Qt property. Enumerator values are returned as <code>int</code> values.\r</p>
188 <pre>
189   (qget label "text")\r
190 </pre>
191 </p><br>
192 <p>
193 <b>QQUIT ()\r</b>
194 <br>
195 <b>QQ\r</b>
196 <p>Quits both Qt and ECL.\r</p>
197 </p><br>
198 <p>
199 <b>QREQUIRE (module)\r</b>
200 <p>Loads an EQL module, corresponding to a Qt module. Returns the module name if both loading and initializing have been successful.\r</p>
201 <pre>
202   (qrequire :network)\r
203 </pre>
204 </p><br>
205 <p>
206 <b>QSENDER ()\r</b>
207 <p>Corresponding to <code>QObject::sender()</code>. To use inside a Lisp function connected to a Qt signal.\r</p>
208 </p><br>
209 <p>
210 <b>QSET-NULL (object)</b>
211 <p>Sets the Qt object pointer to <code>0</code>. This function is called automatically after <code>qdel</code>.</p>
212 </p><br>
213 <p>
214 <b>QSET-PROPERTY (object name value)\r</b>
215 <br>
216 <b>QSET\r</b>
217 <p>Sets a Qt property. Enumerators have to be passed as <code>int</code> values.\r</p>
218 <pre>
219   (qset label "alignment" |Qt.AlignCenter|)\r
220 </pre>
221 </p><br>
222 <p>
223 <b>QSINGLE-SHOT (milliseconds function)\r</b>
224 <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>
225 <pre>
226   (qsingle-shot 0 'on-qt-idle)\r
227 </pre>
228 </p><br>
229 <p>
230 <b>QSTATIC-META-OBJECT (name)\r</b>
231 <p>Returns the static QMetaObject of the given QObject name.\r</p>
232 <pre>
233   (qstatic-meta-object "QWidget")\r
234 </pre>
235 </p><br>
236 <p>
237 <b>QSUPER-CLASS-NAME (name)\r</b>
238 <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>
239 <pre>
240   (qsuper-class-name "QGraphicsLineItem")\r
241 </pre>
242 </p><br>
243 <p>
244 <b>QT-OBJECT-NAME (object)\r</b>
245 <p>Returns the Qt class name.\r</p>
246 </p><br>
247 <p>
248 <b>QUI-CLASS (file &optional name)\r</b>
249 <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>
250 <pre>
251   (qui-class "examples/data/main-window.ui" "edit") ; returns "QTextEdit"\r
252 </pre>
253 </p><br>
254 <p>
255 <b>QUI-NAMES (file)\r</b>
256 <p>Finds all user-defined object names in the given UI file.\r</p>
257 <pre>
258   (qui-names "examples/data/main-window.ui")\r
259 </pre>
260 </p><br>
261 <p>
262 <b>QUTF8 (string)\r</b>
263 <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>
264 </p><br>
265 <p>
266 <b>QVERSION  ()\r</b>
267 <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>
268 </p><br>
269 <p>
270 <b>TR (source &optional context n)</b>
271 <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>
272 </p><br>
273 </body></html>