source: project/wiki/eggref/4/qt @ 28272

Last change on this file since 28272 was 28272, checked in by Mario Domenech Goulart, 8 years ago

qt (wiki): release notes for version 0.100.3

File size: 18.2 KB
Line 
1[[tags: egg gui]]
2[[toc:]]
3
4== qt
5
6=== Introduction
7
8This extension provides an easy to use interface to [[http://www.trolltech.com|Trolltech's Qt 4]] toolkit.
9It provides bindings for the GUI side of Qt, as well as for Qt's builtin networking and dbus libraries. A great way to get started with using this API is to check out the unit tests bundled with this egg, in tests.scm. They provide an example of many of the API calls described here and all of the more complex ones.
10
11Memory management is completely manual (with the exception of child widgets, which are
12deleted when their parent is). To release the resources of a widget or other Qt objects,
13call {{qt:delete}}.
14
15This Qt binding is necessarily incomplete since Qt is huge and testing every feature after adding it in would be too time consuming.
16If you miss certain functionality like widget-specific operations, contact the
17author. Most operations just need trivial 1 line changes to add.
18
19=== Installation
20
21The {{QTDIR}} environment variable must be set to the installation directory of Qt,
22like this:
23
24 QTDIR=/usr/local/Trolltech/Qt-4.2.0 chicken-install qt
25
26==== Windows
27
28This extension has been tested with the binary distribution of Qt,
29based on the mingw compiler included in the Qt distribution. It is
30recommended to use a custom build of CHICKEN that uses this particular
31gcc version and which is installed directly in the Qt installation
32directory. So assuming Qt is installed in `c:\Qt\2010.01`, do the
33following:
34
35  <obtain chicken sources, and cd to that directory>
36 
37  c:\tmp\chicken> mingw32-make PREFIX=c:/Qt/2010.01 PLATFORM=mingw
38  c:\tmp\chicken> mingw32-make PREFIX=c:/Qt/2010.01 PLATFORM=mingw install
39  c:\tmp\chicken> chicken-install qt
40
41Note that the author does not have a copy of Windows and as such will not provide any Windows support.
42
43==== N900
44
45This extension is known to work on at least one embedded device, the Nokia n900. More specific information is [[http://0xab.com/n900/|available here]].
46
47=== Classes
48
49The following [[/eggref/4/protobj|protobj]] classes are exposed:
50
51 <qt>
52  <qt-action>
53  <qt-dbus-connection>
54  <qt-http>
55  <qt-object>
56   <at-application>
57   <qt-widget>
58    <qt-text-edit>
59   <qt-receiver>
60   <qt-timer>
61   <qt-sound>
62  <qt-pixmap>
63  <qt-variant-list>
64
65=== General
66
67The basic mode of operation is that you create your UI using the qt designer, few bindings currently exist for creating widgets, and export them as an xml file. This file can then be read in to set up windows and widgets. By not having bindings for the widget creation routines we keep this egg at a manageable size, and the qt designer seems to be the best way to use Qt4 anyway. Widgets that must be created on the fly do have bindings.
68
69==== qt:init
70
71<procedure>(qt:init)</procedure>
72
73Initializes Qt (including any command-line processing) and returns the application object,
74an instance of {{<qt-application>}}. Performs an implicit
75
76 (qt:connect <application> "lastWindowClosed()" <application> "quit()")
77
78==== qt:run
79
80<procedure>(qt:run [ONCE])</procedure>
81
82Runs the Qt event loop. If {{ONCE}} is given and true, then the procedure returns once all
83pending events have been processed (use {{(qt:run #t)}} in a loop when you want to do some custom idle
84processing, for example).
85
86=== Widgets
87
88==== qt:widget
89
90<procedure>(qt:widget UIXML [PARENT])</procedure>
91
92Parses the UI description in the string {{UIXML}}, which should be the XML representation of a
93user interface created by the Qt {{designer}} application. Returns an instance of {{<qt-widget>}},
94the toplevel widget. If {{PARENT}} is given, the newly created widget will be a child of this.
95
96==== qt:delete
97
98<procedure>(qt:delete OBJECT)</procedure>
99
100Deletes {{OBJECT}}, which should be an instance of {{<qt-object>}} or {{<qt-pixmap>}}.
101
102==== qt:show
103
104<procedure>(qt:show WIDGET)</procedure>
105
106Shows the given widget.
107
108==== qt:hide
109
110<procedure>(qt:hide WIDGET)</procedure>
111
112Hides the widget from view.
113
114==== qt:find
115
116<procedure>(qt:find WIDGET NAME)</procedure>
117
118Returns the direct or indirect child widget of {{WIDGET}} named {{NAME}} (a string) or {{#f}} if no such
119child widget could be found.
120
121==== qt:pixmap
122
123<procedure>(qt:pixmap FILENAME)</procedure>
124
125Loads an image file and returns an instance of {{<qt-image>}}.
126
127==== qt:update
128
129<procedure>(qt:update WIDGET)</procedure>
130
131Schedules a repaint event for the given widget.
132
133=== Properties
134
135==== qt:property
136
137<procedure>(qt:property WIDGET PROP)</procedure>
138
139  (set! (qt:property WIDGET PROP) VALUE)
140
141Get or set a widget property with the name {{PROP}} (a string or symbol). See the Qt documentation for more
142information about which widget supports which properties. Value conversion is automatically, the following
143value types are supported:
144
145 Property (C++) type    Scheme type
146
147 QString                string
148 int                    integer
149 double                 number
150 bool                   boolean
151 char                   char
152 QPixmap                <qt-image>
153 Point                  s32vector
154 Size                   s32vector
155 Rect                   s32vector
156 PointF                 f64vector
157 SizeF                  f64vector
158 RectF                  f64vector
159
160=== Signals and receivers
161
162==== qt:receiver
163
164<procedure>(qt:receiver THUNK)</procedure>
165
166Returns an instance of {{<qt-receiver>}} that when connected to a Qt signal will invoke {{PROC}}
167once the signal is emitted.
168
169==== qt:connect
170
171<procedure>(qt:connect SOURCE SIGNAL DESTINATION [SLOT])</procedure>
172
173Connects the signal {{SIGNAL}} from the {{<qt-object>}} {{SOURCE}} to
174the slot {{SLOT}} from {{DESTINATION}}.  If no slot is given then slot
175will have the same signature and name as the {{SIGNAL}}.  Signals and
176slots should be strings and follow the normal syntax used by Qt.
177{{DESTINATION}} can be a {{<qt-object>}} or a scheme function.
178{{SLOT}} can have any number of arguments as long as they can be
179marshalled back to scheme, the types currently are: int, string, bool,
180uint and double.  Dispatch is handled entirely by Qt using a fake
181object per call to qt:connect meaning that all of the rules for
182matching types and numbers of arguments still apply.  Returns a
183procedure that disconnects and frees the memory used by this
184connection.
185
186==== qt:emit-signal
187
188<procedure>(qt:emit-signal OBJECT SLOT . ARGUMENTS)</procedure>
189
190Emit a signal to an object with any number of arguments.
191
192==== qt:invoke-method
193
194<procedure>(qt:invoke-method OBJECT SLOT [RESULT?] . ARGUMENTS)</procedure>
195
196Emit a signal to an object, if a {{RESULT?}} is true then the return
197value of the invoked singal will be returned.
198
199=== Timers
200
201==== qt:timer
202
203<procedure>(qt:timer SECONDS)</procedure>
204
205Creates and returns a timer object which can be connected to a receiver and which will emit {{"timeout()"}} signals
206every {{SECONDS}}.
207
208==== qt:start
209
210<procedure>(qt:start TIMER)</procedure>
211
212Starts the given timer.
213
214==== qt:stop
215
216<procedure>(qt:stop TIMER)</procedure>
217
218Stops the given timer.
219
220=== Lists
221
222==== qt:clear
223
224<procedure>(qt:clear WIDGET)</procedure>
225
226Clears all entries from {{WIDGET}} which should be a {{QListWidget}}.
227
228==== qt:add
229
230<procedure>(qt:add WIDGET STRING)</procedure>
231
232Adds a new entry to a {{QListWidget}}, {{QComboBox}} or {{QTreeWidget}}.
233In the latter case, the columns should be separated by the {{|}} character (vertical bar).
234
235==== qt:item
236
237<procedure>(qt:item WIDGET INDEX)</procedure>
238
239Returns the text of the {{QListWidget}} item with the given index.
240
241==== qt:set-headers
242
243<procedure>(qt:set-headers WIDGET STRING)</procedure>
244
245Sets the column headers in a {{QTreeWidget}}. Columns should be separated by the {{|}} character
246(vertical bar).
247
248=== Text edit widgets
249
250==== qt:selection
251
252<procedure>(qt:selection TEXTEDIT)</procedure>
253
254Returns the text of the currently active selection, or the empty string, if
255no text is selected.
256
257==== qt:insert
258
259<procedure>(qt:insert TEXTEDIT STRING)</procedure>
260
261Inserts {{STRING}} at the current cursor location.
262
263=== Dialogs
264
265==== qt:message
266
267<procedure>(qt:message TEXT #!key caption parent button1 button2 button3)</procedure>
268
269Opens a {{QMessageBox}} with the given properties and returns the index of the pressed button.
270
271<procedure>(qt:get-open-filename CAPTION DIRECTORY #!key parent options filter)</procedure>
272
273Shows a modal file-selection dialog and returns the selected filename (or "", if the dialog
274was canceled). {{options}} should be a list with zero or more of the following keywords:
275
276 #:show-dirs-only
277 #:dont-resolve-symlinks
278 #:dont-confirm-overwrites
279 #:dont-use-sheet
280 #:dont-use-native-dialog
281
282<procedure>(qt:get-save-filename CAPTION DIRECTORY #!key parent options filter)</procedure>
283
284Shows a modal file-selection for saving.
285
286<procedure>(qt:get-directory CAPTION DIRECTORY #!key parent options filter)</procedure>
287
288Shows a modal directory-selection dialog.
289
290=== Sound
291
292==== qt:sound
293
294<procedure>(qt:sound FILENAME)</procedure>
295
296Loads a sound-file and returns an instance of {{<qt-sound>}}.
297
298==== qt:play
299
300<procedure>(qt:play SOUND)</procedure>
301
302Plays the sound asynchronously.
303
304==== qt:stop
305
306<procedure>(qt:stop SOUND)</procedure>
307
308Stops a currently playing sound.
309
310=== Global keyboard shortcuts
311
312==== qt:shortcut
313
314<procedure>(qt:shortcut KEY)</procedure>
315
316Creates a keyboard-shortcut action for {{KEY}}, which should be a string
317naming a key-sequence, for example {{"Ctrl+E"}}. See the Qt documentation
318for the interpretation of this string. {{qt:shortcut}} returns an
319{{<qt-action>}} instance that can be added to a widget with {{qt:add-action}}.
320
321==== qt:add-action
322
323<procedure>(qt:add-action WIDGET ACTION)</procedure>
324
325Adds the given action to {{WIDGET}}.
326
327==== qt:remove-action
328
329<procedure>(qt:remove-action WIDGET ACTION)</procedure>
330
331Removes {{ACTION}} from {{WIDGET}}.
332
333=== Miscellaneous
334
335==== qt:char-encoding
336
337<procedure>(qt:char-encoding [ENCODING])</procedure>
338
339Selects the default character encoding for strings passed to and received from
340Qt. {{ENCODING}} may be one of the symbols {{ascii}}, {{latin1}} or {{utf8}}.
341The default is {{latin1}}. If no argument is given, then {{qt:char-encoding}}
342returns the current encoding.
343
344==== qt:gl
345
346<procedure>(qt:gl NAME PARENT INIT RESIZE PAINT)</procedure>
347
348Creates and returns a {{QGLWidget}}. {{INIT}} should be zero-argument procedure called to
349initialize the OpenGL context. {{RESIZE}} should be a two-argument procedure called when the
350widget is resized and receives the new width and height. {{PAINT}} is a zero-argument procedure
351called when the widget should repaint itself. GL output will be automatically flushed.
352
353==== qt:classname
354
355<procedure>(qt:classname OBJECT)</procedure>
356
357Returns the name of the Qt class of which {{OBJECT}} is an instance.
358
359=== DBus
360
361Most of the functionality of the DBus API is exposed by these bindings.
362
363==== qt:dbus-connect
364
365<procedure>(qt:dbus-connect BUS SERVICE OBJECT INTERFACE SIGNAL TO [SLOT])</procedure>
366
367Unfortunately dbus connections are handled differently in Qt from
368regular singal/slot connections and this has leaked over. This
369function works indentically to {{qt:connect}} and can connect to both
370Qt objects and scheme functions.
371
372==== qt:session-bus
373
374<procedure>(qt:session-bus)</procedure>
375
376Returns a handle to the session bus.
377
378==== qt:system-bus
379
380<procedure>(qt:system-bus)</procedure>
381
382Returns a handle to the system bus.
383
384==== qt:dbus-list-names
385
386<procedure>(qt:list-names BUS)</procedure>
387
388Returns the name of a bus (eg: (qt:dbus-list-names (qt:system-bus))
389returns "System bus"). The unfortunate name of this function was the
390choice of the DBus API not the maintainer of the bindings.
391
392==== qt:dbus-send-signal
393
394<procedure>(qt:dbus-send-signal BUS OBJECT INTERFACE SIGNAL . ARGUMENTS)</procedure>
395
396Send a signal to a bus.
397
398==== qt:dbus-register-method
399
400<procedure>(qt:dbus-register-method BUS PATH FUNCTION NAME)</procedure>
401
402Register a function on a bus with a name and a path, the function must
403be a scheme function, but it can take arguments and name must conform to
404the standard Qt slot naming rules.
405
406==== qt:dbus-call
407
408<procedure>(qt:dbus-call BUS SERVICE PATH INTERFACE METHOD . ARGUMENTS)</procedure>
409
410Call a method on a bus with any number of arguments.
411
412==== qt:dbus-call-with-callback
413
414<procedure>(qt:dbus-call-with-callback BUS SERVICE PATH INTERFACE METHOD FUNCTION SLOT . ARGUMENTS)</procedure>
415
416Call a method on a bus with any number of arguments and connect the
417output to a function on a slot. The destination must be a scheme
418function.
419
420==== qt:dbus-register-service
421
422<procedure>(qt:dbus-register-service bus service)</procedure>
423
424Register a service on a bus.
425
426==== qt:dbus-unregister-service
427
428<procedure>(qt:dbus-unregister-service bus service)</procedure>
429           
430Unregister a service on a bus.
431           
432=== Networking
433
434Currently their its infancy the networking bindings support only
435http. See the unit tests bundled in tests.scm for how to best use this
436functionality.
437
438==== qt:make-http
439
440<procedure>(qt:make-http)</procedure>
441
442Make an http object, will have to be destroyed in the end with qt:destroy-http.
443
444==== qt:destroy-http
445
446<procedure>(qt:destroy-http)</procedure>
447
448Destroy an http object.
449
450==== qt:http-set-host
451
452<procedure>(qt:http-set-host HTTP SERVER PORT)</procedure>
453
454Set the host of an http connection.
455
456==== qt:http-get
457
458<procedure>(qt:http-get HTTP PATH)</procedure>
459
460Send an HTTP GET.
461
462==== qt:http-read-string
463
464<procedure>(qt:http-read-string HTTP)</procedure>
465
466Read back a string from the object, this is non-blocking. The best way
467to use this is to connect to "done(bool)" and possibly
468"dataReadProgress(int,int)" on the http object to be notified when the
469data is available.
470
471=== Variant list
472
473The basic way of exchanging data with Qt is through QtVariantList.
474
475==== qt:make-variant-list
476
477<procedure>(qt:make-variant-list)</procedure>
478
479These will automatically be destroyed by the garbage collector when
480they are no longer referenced.
481
482==== qt:variant-list-remove-front
483
484<procedure>(qt:variant-list-remove-front VARIANTLIST)</procedure>
485
486Remove and return one element from the front of a variant list.
487
488==== qt:variant-list-insert-back
489
490<procedure>(qt:variant-list-insert-back VARIANTLIST OBJ [SIGNED?])</procedure>
491
492Insert one element to the back of a variant list. If {{SIGNED?}} is not
493provided it is assumed to be true, this only affects integers.
494
495==== qt:list->variant-list
496
497<procedure>(qt:list->variant-list LIST)</procedure>
498
499Convert a scheme list to a variant list.
500
501==== qt:variant-list->list
502
503<procedure>(qt:variant-list->list VARIANTLIST)</procedure>
504
505Convert a variant list to a scheme list.
506
507==== qt:variant-list-length
508
509<procedure>(qt:variant-list-length VARIANTLIST)</procedure>
510
511Return the length of a variant list.
512
513=== Example
514
515Given the file {{hello.ui}}:
516
517 <ui version="4.0" >
518 <class>Form</class>
519 <widget class="QWidget" name="Form" >
520  <property name="geometry" >
521   <rect>
522    <x>0</x>
523    <y>0</y>
524    <width>295</width>
525    <height>144</height>
526   </rect>
527  </property>
528  <property name="windowTitle" >
529   <string/>
530  </property>
531  <widget class="QLabel" name="label" >
532   <property name="geometry" >
533    <rect>
534     <x>40</x>
535     <y>30</y>
536     <width>121</width>
537     <height>31</height>
538    </rect>
539   </property>
540   <property name="font" >
541    <font>
542     <pointsize>15</pointsize>
543     <weight>75</weight>
544     <bold>true</bold>
545    </font>
546   </property>
547   <property name="text" >
548    <string>Hello, world!</string>
549   </property>
550   <property name="alignment" >
551    <set>Qt::AlignCenter</set>
552   </property>
553  </widget>
554  <widget class="QPushButton" name="quitButton" >
555   <property name="geometry" >
556    <rect>
557     <x>180</x>
558     <y>90</y>
559     <width>75</width>
560     <height>31</height>
561    </rect>
562   </property>
563   <property name="text" >
564    <string>Quit</string>
565   </property>
566  </widget>
567 </widget>
568 <resources/>
569 <connections/>
570 </ui>
571
572Run this to display the Window:
573
574 (use qt utils)
575 
576 (define a (qt:init))
577 (define w (qt:widget (read-all "hello.ui")))
578 (qt:connect (qt:find w "quitButton") "clicked()" a "quit()")
579 (qt:show w)
580 (qt:run)
581
582A more interesting example can be found here: [[http://www.call-with-current-continuation.org/egg-browser.zip|egg-browser.zip]].
583
584=== History
585
586; 0.100.3 : ported build system from the [[/egg/qt-light|qt-light]] egg.  This egg has been set as obsolete, see the [[/egg/qt-light|qt-light]] egg for qt bindings.
587; 1.0 : revamped the qt egg
588; 0.93 : (hopefully) fixed more build problems (thanks to Mario)
589; 0.9 : fixed Linux build problems and added {{qt:char-encoding}}
590; 0.8 : I forgot what I did for 0.8
591; 0.7 : added support for Windows
592; 0.6 : qt.pro is generated by setup script to force usage of correct {{csc}} (thanks to Mario Goulart)
593; 0.5 : fixed bug in string-result handling that caused random crashes (reported by Christian Kellermann and Mario Domenench Goulart)
594; 0.4 : ported to CHICKEN 4, removed Mac OS X support
595; 0.3 : generated application bundle on Mac OS X
596; 0.2 : added file dialogs and QSound support, fixed bug by making qt:show "safe"
597; 0.1 : initial release
598
599=== License
600
601 Copyright (c) 2010, Andrei Barbu
602 Copyright (c) 2006-2010, Felix L. Winkelmann
603 All rights reserved.
604
605 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
606 conditions are met:
607
608   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
609     disclaimer.
610   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
611     disclaimer in the documentation and/or other materials provided with the distribution.
612   Neither the name of the author nor the names of its contributors may be used to endorse or promote
613     products derived from this software without specific prior written permission.
614
615 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
616 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
617 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
618 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
619 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
620 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
621 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
622 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
623 POSSIBILITY OF SUCH DAMAGE.
624
625 Send bugs, suggestions and ideas to:
626
627 andrei@0xab.com
628
629 Andrei Barbu
630 Purdue University
Note: See TracBrowser for help on using the repository browser.