source: project/wiki/qt @ 12333

Last change on this file since 12333 was 12333, checked in by ecloud, 12 years ago

Changes applied for ecloud (72.208.148.99) through svnwiki:

note about QMAKESPEC on MacOS

File size: 10.7 KB
Line 
1[[tags: egg gui]]
2[[toc:]]
3
4== qt
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 Mac OS X.
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 leightweight).
17If you miss certain functionality like widget-specific operations, contact the
18author.
19
20=== Installation
21
22The {{QTDIR}} environment variable must be set to the installation directory of Qt,
23like this:
24
25 QTDIR=/usr/local/Trolltech/Qt-4.2.0 chicken-setup qt
26
27Under Mac OS X, an application bundle named {{ChickenQt.app}} is generated (and no dynamically
28loadable extension as such). The bundle will load and evaluate a Scheme file named {{init.scm}} from it's
29{{Contents/MacOS}} directory that can be modified to contain the actual application, or further load
30compiled code. Use {{(qt:bundle-path)}} to obtain the bundle directory. An example initialization
31file is provided that just pops up a dialog and asks for a file to load and execute. You can modify it to load another file (e.g. "egg-browser.scm") that is placed in the same directory:
32
33 (require-extension chicken-more-macros)
34 (require 'match)
35 (define basedir (pathname-directory (qt:bundle-path)))
36 (load (make-pathname basedir "egg-browser.scm"))
37
38If you find that when chicken-setup runs qmake, an XCode project is generated rather than a Makefile, you need to modify QMAKESPEC like this:
39
40 export QMAKESPEC=macx-g++
41
42=== Classes
43
44The following TinyCLOS classes are exposed:
45
46 <qt>
47  <qt-object>
48   <at-application>
49   <qt-widget>
50   <qt-receiver>
51   <qt-timer>
52   <qt-sound>
53  <qt-pixmap>
54
55=== General
56
57==== qt:init
58
59 [procedure] (qt:init)
60
61Initializes Qt (including any command-line processing) and returns the application object,
62an instance of {{<qt-application>}}. Performs an implicit
63
64 (qt:connect <application> "lastWindowClosed()" <application> "quit()")
65
66==== qt:run
67
68 [procedure] (qt:run [ONCE])
69
70Runs the Qt event loop. If {{ONCE}} is given and true, then the procedure returns once all
71pending events have been processed (use {{(qt:run #t)}} in a loop when you want to do some custom idle
72processing, for example).
73
74=== Widgets
75
76==== qt:widget
77
78 [procedure] (qt:widget UIXML [PARENT])
79
80Parses the UI description in the string {{UIXML}}, which should be the XML representation of a
81user interface created by the Qt {{designer}} application. Returns an instance of {{<qt-widget>}},
82the toplevel widget. If {{PARENT}} is given, the newly created widget will be a child of this.
83
84==== qt:delete
85
86 [generic] (qt:delete OBJECT)
87
88Deletes {{OBJECT}}, which should be an instance of {{<qt-object>}} or {{<qt-pixmap>}}.
89
90==== qt:show
91
92 [procedure] (qt:show WIDGET)
93
94Shows the given widget.
95
96==== qt:hide
97
98 [procedure] (qt:hide WIDGET)
99
100Hides the widget from view.
101
102==== qt:find
103
104 [procedure] (qt:find WIDGET NAME)
105
106Returns the direct or indirect child widget of {{WIDGET}} named {{NAME}} (a string) or {{#f}} if no such
107child widget could be found.
108
109==== qt:pixmap
110
111 [procedure] (qt:pixmap FILENAME)
112
113Loads an image file and returns an instance of {{<qt-image>}}.
114
115==== qt:update
116
117 [procedure] (qt:update WIDGET)
118
119Schedules a repaint event for the given widget.
120
121=== Properties
122
123==== qt:property
124
125 [procedure] (qt:property WIDGET PROP)
126 [setter] (set! (qt:property WIDGET PROP) VALUE)
127
128Get or set a widget property with the name {{PROP}} (a string or symbol). See the Qt documentation for more
129information about which widget supports which properties. Value conversion is automatically, the following
130value types are supported:
131
132 Property (C++) type    Scheme type
133
134 QString                string
135 int                    integer
136 double                 number
137 bool                   boolean
138 char                   char
139 QPixmap                <qt-image>
140 Point                  s32vector
141 Size                   s32vector
142 Rect                   s32vector
143 PointF                 f64vector
144 SizeF                  f64vector
145 RectF                  f64vector
146
147=== Signals and receivers
148
149==== qt:receiver
150
151 [procedure] (qt:receiver THUNK)
152
153Returns an instance of {{<qt-receiver>}} that when connected to a Qt signal will invoke {{PROC}}
154once the signal is emitted.
155
156==== qt:connect
157
158 [procedure] (qt:connect SOURCE SIGNAL DESTINATION [SLOT])
159
160Connects the signal {{SIGNAL}} from the {{<qt-object>}} {{SOURCE}} to the slot {{SLOT}} from {{DESTINATION}}.
161If no slot is given, then {{"slot()"}} is assumed (which is the only slot implemented in {{<qt-receiver>}}
162instances). Signals and slots should be strings and follow the normal syntax used by Qt.
163
164=== Timers
165
166==== qt:timer
167
168 [procedure] (qt:timer SECONDS)
169
170Creates and returns a timer object which can be connected to a receiver and which will emit {{"timeout()"}} signals
171every {{SECONDS}}.
172
173==== qt:start
174
175 [procedure] (qt:start TIMER)
176
177Starts the given timer.
178
179==== qt:stop
180
181 [generic] (qt:stop TIMER)
182
183Stops the given timer.
184
185=== Lists
186
187==== qt:clear
188
189 [procedure] (qt:clear WIDGET)
190
191Clears all entries from {{WIDGET}} which should be a {{QListWidget}}.
192
193==== qt:add
194
195 [procedure] (qt:add WIDGET STRING)
196
197Adds a new entry to a {{QListWidget}}, {{QComboBox}} or {{QTreeWidget}}.
198In the latter case, the columns should be separated by the {{|}} character (vertical bar).
199
200==== qt:item
201
202 [procedure] (qt:item WIDGET INDEX)
203
204Returns the text of the {{QListWidget}} item with the given index.
205
206==== qt:set-headers
207
208 [procedure] (qt:set-headers WIDGET STRING)
209
210Sets the column headers in a {{QTreeWidget}}. Columns should be separated by the {{|}} character
211(vertical bar).
212
213=== Dialogs
214
215==== qt:message
216
217 [procedure] (qt:message TEXT #!key caption parent button1 button2 button3)
218
219Opens a {{QMessageBox}} with the given properties and returns the index of the pressed button.
220
221 [procedure] (qt:get-open-filename CAPTION DIRECTORY #!key parent options filter)
222
223Shows a modal file-selection dialog and returns the selected filename (or "", if the dialog
224was canceled). {{options}} should be a list with zero or more of the following keywords:
225
226 show-dirs-only:
227 dont-resolve-symlinks:
228 dont-confirm-overwrites:
229 dont-use-sheet:
230 dont-use-native-dialog:
231
232 [procedure] (qt:get-save-filename CAPTION DIRECTORY #!key parent options filter)
233
234Shows a modal file-selection for saving.
235
236 [procedure] (qt:get-directory CAPTION DIRECTORY #!key parent options filter)
237
238Shows a modal directory-selection dialog.
239
240=== Sound
241
242==== qt:sound
243
244 [procedure] (qt:sound FILENAME)
245
246Loads a sound-file and returns an instance of {{<qt-sound>}}.
247
248==== qt:play
249
250 [procedure] (qt:play SOUND)
251
252Plays the sound asynchronously.
253
254==== qt:stop
255
256 [generic] (qt:stop SOUND)
257
258Stops a currently playing sound.
259
260=== Miscellaneous
261
262==== qt:gl
263
264 [procedure] (qt:gl NAME PARENT INIT RESIZE PAINT)
265
266Creates and returns a {{QGLWidget}}. {{INIT}} should be zero-argument procedure called to
267initialuze the OpenGL context. {{RESIZE}} should be a two-argument procedure called when the
268widget is resized and receives the new width and height. {{PAINT}} is a zero-argument procedure
269called when the widget should repaint itself. GL output will be automatically flushed.
270
271==== qt:classname
272
273 [procedure] (qt:classname OBJECT)
274
275Returns the name of the Qt class of which {{OBJECT}} is an instance.
276
277=== Example
278
279Given the file {{hello.ui}}:
280
281 <ui version="4.0" >
282  <class>Form</class>
283  <widget class="QWidget" name="Form" >
284   <property name="geometry" >
285    <rect>
286     <x>0</x>
287     <y>0</y>
288     <width>295</width>
289     <height>144</height>
290    </rect>
291   </property>
292   <property name="windowTitle" >
293    <string/>
294   </property>
295   <widget class="QLabel" name="label" >
296    <property name="geometry" >
297     <rect>
298      <x>40</x>
299      <y>30</y>
300      <width>121</width>
301      <height>31</height>
302     </rect>
303    </property>
304    <property name="font" >
305     <font>
306      <pointsize>15</pointsize>
307      <weight>75</weight>
308      <bold>true</bold>
309     </font>
310    </property>
311    <property name="text" >
312     <string>Hello, world!</string>
313    </property>
314    <property name="alignment" >
315     <set>Qt::AlignCenter</set>
316    </property>
317   </widget>
318   <widget class="QPushButton" name="quitButton" >
319    <property name="geometry" >
320     <rect>
321      <x>180</x>
322      <y>90</y>
323      <width>75</width>
324      <height>31</height>
325     </rect>
326    </property>
327    <property name="text" >
328     <string>Quit</string>
329    </property>
330   </widget>
331  </widget>
332  <resources/>
333  <connections/>
334 </ui>
335
336Run this to display the Window:
337
338 (use qt utils)
339
340 (define a (qt:init))
341 (define w (qt:widget (read-all "hello.ui")))
342 (qt:connect (qt:find w "quitButton") "clicked()" a "quit()")
343 (qt:show w)
344 (qt:run)
345
346A more interesting example can be found here: [[http://www.call-with-current-continuation.org/egg-browser.zip|egg-browser.zip]]. On Mac OS X change the reference in egg-browser.scm to "egg-browser.ui" to (make-pathname basedir "egg-browser.ui").
347
348=== History
349
350; 0.3 : generated application bundle on Mac OS X
351; 0.2 : added file dialogs and QSound support, fixed bug by making qt:show "safe"
352; 0.1 : initial release
353
354=== License
355
356 Copyright (c) 2006, Felix L. Winkelmann
357 All rights reserved.
358
359 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
360 conditions are met:
361
362   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
363     disclaimer.
364   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
365     disclaimer in the documentation and/or other materials provided with the distribution.
366   Neither the name of the author nor the names of its contributors may be used to endorse or promote
367     products derived from this software without specific prior written permission.
368
369 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
370 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
371 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
372 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
373 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
374 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
375 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
376 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
377 POSSIBILITY OF SUCH DAMAGE.
378
379 Send bugs, suggestions and ideas to:
380
381 felix@call-with-current-continuation.org
382
383 Felix L. Winkelmann
384 Unter den Gleichen 1
385 37130 Gleichen
386 Germany
Note: See TracBrowser for help on using the repository browser.