source: project/wiki/eggref/4/qt-light @ 32241

Last change on this file since 32241 was 32241, checked in by felix winkelmann, 6 years ago

removed some call/cc.org links

File size: 12.8 KB
Line 
1[[tags: egg gui]]
2[[toc:]]
3
4== qt-light
5
6=== Introduction
7
8This extension provides a lightweight and relatively easy to use interface
9to [[http://www.trolltech.com|Trolltech's Qt 4]] GUI toolkit. It has currently only
10been tested on Linux and Windows.
11
12Memory management is completely manual (with the exception of child widgets, which are
13deleted when their parent is). To release the resources of a widget or other Qt objects,
14call {{qt:delete}}.
15
16This Qt binding is necessarily incomplete (since it is intended to be lightweight).
17If you miss certain functionality like widget-specific operations, contact the
18author.
19
20For a more complete interface to Qt, see the [[qt]] extension, which is currently
21under development and planned to contain much more functionality.
22
23=== Installation
24
25The {{QTDIR}} environment variable must be set to the installation directory of Qt,
26like this:
27
28 QTDIR=/usr/local/Trolltech/Qt-4.2.0 chicken-install qt-light
29
30If you instaled Qt on a debian-based system, setting QTDIR is not strictly
31necessary, as some default locations will be tried.
32
33==== Windows
34
35This extension has been tested with the binary distribution of Qt,
36based on the mingw compiler included in the Qt distribution. It is
37recommended to use a custom build of CHICKEN that uses this particular
38gcc version and which is installed directly in the Qt installation
39directory. So assuming Qt is installed in `c:\Qt\2010.01`, do the
40following:
41
42  <obtain chicken sources, and cd to that directory>
43 
44  c:\tmp\chicken> mingw32-make PREFIX=c:/Qt/2010.01 PLATFORM=mingw
45  c:\tmp\chicken> mingw32-make PREFIX=c:/Qt/2010.01 PLATFORM=mingw install
46  c:\tmp\chicken> chicken-install qt-light
47
48=== Classes
49
50The following [[protobj]] classes are exposed:
51
52 <qt>
53  <qt-object>
54   <at-application>
55   <qt-widget>
56    <qt-text-edit>
57   <qt-receiver>
58   <qt-timer>
59   <qt-sound>
60  <qt-pixmap>
61  <qt-action>
62
63=== General
64
65==== qt:init
66
67<procedure>(qt:init)</procedure>
68
69Initializes Qt (including any command-line processing) and returns the application object,
70an instance of {{<qt-application>}}. Performs an implicit
71
72 (qt:connect <application> "lastWindowClosed()" <application> "quit()")
73
74==== qt:run
75
76<procedure>(qt:run [ONCE])</procedure>
77
78Runs the Qt event loop. If {{ONCE}} is given and true, then the procedure returns once all
79pending events have been processed (use {{(qt:run #t)}} in a loop when you want to do some custom idle
80processing, for example).
81
82=== Widgets
83
84==== qt:widget
85
86<procedure>(qt:widget UIXML [PARENT])</procedure>
87
88Parses the UI description in the string {{UIXML}}, which should be the XML representation of a
89user interface created by the Qt {{designer}} application. Returns an instance of {{<qt-widget>}},
90the toplevel widget. If {{PARENT}} is given, the newly created widget will be a child of this.
91
92==== qt:delete
93
94<procedure>(qt:delete OBJECT)</procedure>
95
96Deletes {{OBJECT}}, which should be an instance of {{<qt-object>}} or {{<qt-pixmap>}}.
97
98==== qt:show
99
100<procedure>(qt:show WIDGET)</procedure>
101
102Shows the given widget.
103
104==== qt:hide
105
106<procedure>(qt:hide WIDGET)</procedure>
107
108Hides the widget from view.
109
110==== qt:find
111
112<procedure>(qt:find WIDGET NAME)</procedure>
113
114Returns the direct or indirect child widget of {{WIDGET}} named {{NAME}} (a string) or {{#f}} if no such
115child widget could be found.
116
117==== qt:pixmap
118
119<procedure>(qt:pixmap FILENAME)</procedure>
120
121Loads an image file and returns an instance of {{<qt-image>}}.
122
123==== qt:update
124
125<procedure>(qt:update WIDGET)</procedure>
126
127Schedules a repaint event for the given widget.
128
129=== Properties
130
131==== qt:property
132
133<procedure>(qt:property WIDGET PROP)</procedure>
134
135  (set! (qt:property WIDGET PROP) VALUE)
136
137Get or set a widget property with the name {{PROP}} (a string or symbol). See the Qt documentation for more
138information about which widget supports which properties. Value conversion is automatically, the following
139value types are supported:
140
141 Property (C++) type    Scheme type
142
143 QString                string
144 int                    integer
145 double                 number
146 bool                   boolean
147 char                   char
148 QPixmap                <qt-image>
149 Point                  s32vector
150 Size                   s32vector
151 Rect                   s32vector
152 PointF                 f64vector
153 SizeF                  f64vector
154 RectF                  f64vector
155
156=== Signals and receivers
157
158==== qt:receiver
159
160<procedure>(qt:receiver THUNK)</procedure>
161
162Returns an instance of {{<qt-receiver>}} that when connected to a Qt signal will invoke {{PROC}}
163once the signal is emitted.
164
165==== qt:connect
166
167<procedure>(qt:connect SOURCE SIGNAL DESTINATION [SLOT])</procedure>
168
169Connects the signal {{SIGNAL}} from the {{<qt-object>}} {{SOURCE}} to the slot {{SLOT}} from {{DESTINATION}}.
170If no slot is given, then {{"slot()"}} is assumed (which is the only slot implemented in {{<qt-receiver>}}
171instances). Signals and slots should be strings and follow the normal syntax used by Qt.
172
173=== Timers
174
175==== qt:timer
176
177<procedure>(qt:timer SECONDS)</procedure>
178
179Creates and returns a timer object which can be connected to a receiver and which will emit {{"timeout()"}} signals
180every {{SECONDS}}.
181
182==== qt:start
183
184<procedure>(qt:start TIMER)</procedure>
185
186Starts the given timer.
187
188==== qt:stop
189
190<procedure>(qt:stop TIMER)</procedure>
191
192Stops the given timer.
193
194=== Lists
195
196==== qt:clear
197
198<procedure>(qt:clear WIDGET)</procedure>
199
200Clears all entries from {{WIDGET}} which should be a {{QListWidget}}.
201
202==== qt:add
203
204<procedure>(qt:add WIDGET STRING)</procedure>
205
206Adds a new entry to a {{QListWidget}}, {{QComboBox}} or {{QTreeWidget}}.
207In the latter case, the columns should be separated by the {{|}} character (vertical bar).
208
209==== qt:item
210
211<procedure>(qt:item WIDGET INDEX)</procedure>
212
213Returns the text of the {{QListWidget}} item with the given index.
214
215==== qt:set-headers
216
217<procedure>(qt:set-headers WIDGET STRING)</procedure>
218
219Sets the column headers in a {{QTreeWidget}}. Columns should be separated by the {{|}} character
220(vertical bar).
221
222=== Text edit widgets
223
224==== qt:selection
225
226<procedure>(qt:selection TEXTEDIT)</procedure>
227
228Returns the text of the currently active selection, or the empty string, if
229no text is selected.
230
231==== qt:insert
232
233<procedure>(qt:insert TEXTEDIT STRING)</procedure>
234
235Inserts {{STRING}} at the current cursor location.
236
237=== Dialogs
238
239==== qt:message
240
241<procedure>(qt:message TEXT #!key caption parent button1 button2 button3)</procedure>
242
243Opens a {{QMessageBox}} with the given properties and returns the index of the pressed button.
244
245<procedure>(qt:get-open-filename CAPTION DIRECTORY #!key parent options filter)</procedure>
246
247Shows a modal file-selection dialog and returns the selected filename (or "", if the dialog
248was canceled). {{options}} should be a list with zero or more of the following keywords:
249
250 show-dirs-only:
251 dont-resolve-symlinks:
252 dont-confirm-overwrites:
253 dont-use-sheet:
254 dont-use-native-dialog:
255
256<procedure>(qt:get-save-filename CAPTION DIRECTORY #!key parent options filter)</procedure>
257
258Shows a modal file-selection for saving.
259
260<procedure>(qt:get-directory CAPTION DIRECTORY #!key parent options filter)</procedure>
261
262Shows a modal directory-selection dialog.
263
264=== Sound
265
266==== qt:sound
267
268<procedure>(qt:sound FILENAME)</procedure>
269
270Loads a sound-file and returns an instance of {{<qt-sound>}}.
271
272==== qt:play
273
274<procedure>(qt:play SOUND)</procedure>
275
276Plays the sound asynchronously.
277
278==== qt:stop
279
280<procedure>(qt:stop SOUND)</procedure>
281
282Stops a currently playing sound.
283
284=== Global keyboard shortcuts
285
286==== qt:shortcut
287
288<procedure>(qt:shortcut KEY)</procedure>
289
290Creates a keyboard-shortcut action for {{KEY}}, which should be a string
291naming a key-sequence, for example {{"Ctrl+E"}}. See the Qt documentation
292for the interpretation of this string. {{qt:shortcut}} returns an
293{{<qt-action>}} instance that can be added to a widget with {{qt:add-action}}.
294
295==== qt:add-action
296
297<procedure>(qt:add-action WIDGET ACTION)</procedure>
298
299Adds the given action to {{WIDGET}}.
300
301==== qt:remove-action
302
303<procedure>(qt:remove-action WIDGET ACTION)</procedure>
304
305Removes {{ACTION}} from {{WIDGET}}.
306
307=== Miscellaneous
308
309==== qt:char-encoding
310
311<procedure>(qt:char-encoding [ENCODING])</procedure>
312
313Selects the default character encoding for strings passed to and received from
314Qt. {{ENCODING}} may be one of the symbols {{ascii}}, {{latin1}} or {{utf8}}.
315The default is {{latin1}}. If no argument is given, then {{qt:char-encoding}}
316returns the current encoding.
317
318==== qt:gl
319
320<procedure>(qt:gl NAME PARENT INIT RESIZE PAINT)</procedure>
321
322Creates and returns a {{QGLWidget}}. {{INIT}} should be zero-argument procedure called to
323initialize the OpenGL context. {{RESIZE}} should be a two-argument procedure called when the
324widget is resized and receives the new width and height. {{PAINT}} is a zero-argument procedure
325called when the widget should repaint itself. GL output will be automatically flushed.
326
327==== qt:classname
328
329<procedure>(qt:classname OBJECT)</procedure>
330
331Returns the name of the Qt class of which {{OBJECT}} is an instance.
332
333=== Example
334
335Given the file {{hello.ui}}:
336
337 <ui version="4.0" >
338  <class>Form</class>
339  <widget class="QWidget" name="Form" >
340   <property name="geometry" >
341    <rect>
342     <x>0</x>
343     <y>0</y>
344     <width>295</width>
345     <height>144</height>
346    </rect>
347   </property>
348   <property name="windowTitle" >
349    <string/>
350   </property>
351   <widget class="QLabel" name="label" >
352    <property name="geometry" >
353     <rect>
354      <x>40</x>
355      <y>30</y>
356      <width>121</width>
357      <height>31</height>
358     </rect>
359    </property>
360    <property name="font" >
361     <font>
362      <pointsize>15</pointsize>
363      <weight>75</weight>
364      <bold>true</bold>
365     </font>
366    </property>
367    <property name="text" >
368     <string>Hello, world!</string>
369    </property>
370    <property name="alignment" >
371     <set>Qt::AlignCenter</set>
372    </property>
373   </widget>
374   <widget class="QPushButton" name="quitButton" >
375    <property name="geometry" >
376     <rect>
377      <x>180</x>
378      <y>90</y>
379      <width>75</width>
380      <height>31</height>
381     </rect>
382    </property>
383    <property name="text" >
384     <string>Quit</string>
385    </property>
386   </widget>
387  </widget>
388  <resources/>
389  <connections/>
390 </ui>
391
392Run this to display the Window:
393
394 (use qt-light utils)
395
396 (define a (qt:init))
397 (define w (qt:widget (read-all "hello.ui")))
398 (qt:connect (qt:find w "quitButton") "clicked()" a "quit()")
399 (qt:show w)
400 (qt:run)
401
402A more interesting example can be found here: [[http://www.call-with-current-continuation.org/egg-browser.zip|egg-browser.zip]].
403
404=== History
405
406; 0.99 : added better support for Mac OS - thanks to Jeremy Farnaud
407; 0.97 : fix for {{qt:stop}} with timers (thanks to ewfalor)
408; 0.96 : added include-path option to C++ build for CHICKEN 4.6.4
409; 0.95 : .setup script fixes
410; 0.94 : renamed this extension to qt-light, more build-fixes (this time for Windows)
411; 0.93 : (hopefully) fixed more build problems (thanks to Mario)
412; 0.9 : fixed Linux build problems and added {{qt:char-encoding}}
413; 0.8 : I forgot what I did for 0.8
414; 0.7 : added support for Windows
415; 0.6 : qt.pro is generated by setup script to force usage of correct {{csc}} (thanks to Mario Goulart)
416; 0.5 : fixed bug in string-result handling that caused random crashes (reported by Christian Kellermann and Mario Domenench Goulart)
417; 0.4 : ported to CHICKEN 4, removed Mac OS X support
418; 0.3 : generated application bundle on Mac OS X
419; 0.2 : added file dialogs and QSound support, fixed bug by making qt:show "safe"
420; 0.1 : initial release
421
422=== License
423
424 Copyright (c) 2006-2011, Felix L. Winkelmann
425 All rights reserved.
426 
427 Redistribution and use in source and binary forms, with or
428 without modification, are permitted provided that the following
429 conditions are met:
430 
431 Redistributions of source code must retain the above copyright
432 notice, this list of conditions and the following disclaimer.
433 
434 Redistributions in binary form must reproduce the above
435 copyright notice, this list of conditions and the following
436 disclaimer in the documentation and/or other materials provided
437 with the distribution.
438 
439 Neither the name of the author nor the names of its contributors
440 may be used to endorse or promote products derived from this
441 software without specific prior written permission.
442 
443 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
444 CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
445 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
446 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
447 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
448 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
449 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
450 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
451 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
452 AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
453 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
454 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
455 THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.