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

Last change on this file since 15653 was 15653, checked in by felix winkelmann, 11 years ago

updates; added qt, irc and xosd

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