source: project/wiki/qt @ 2880

Last change on this file since 2880 was 2880, checked in by svnwiki, 13 years ago

Changes applied for Daniel Sadilek (84.189.72.89) through svnwiki:

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