1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/mac.doc:36 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Qt/Mac Issues</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Qt/Mac Issues</h1>
<p> This file will outline known issues and possible workarounds for
limitations on Mac OS X with Qt. This list will not always be complete, so
please contact Trolltech support with issues you find to be missing.
<p> See also the document <a href="qtmac-as-native.html">Qt/Mac is Mac OS X
Native</a>.
<p> <!-- toc -->
<ul>
<li><a href="#1"> GUI Applications
</a>
<li><a href="#2"> QCursor
</a>
<li><a href="#3"> Anti-aliased text
</a>
<li><a href="#4"> Library Support
</a>
<ul>
<li><a href="#4-1"> Bundle-based Libraries
</a>
<li><a href="#4-2"> Combining Libraries
</a>
<li><a href="#4-3"> Initialization Order
</a>
<li><a href="#4-4"> Plugin Support
</a>
</ul>
<li><a href="#5"> Compiler Settings
</a>
<ul>
<li><a href="#5-1"> Compile-time Flags
</a>
</ul>
<li><a href="#6"> Building and Configuring Qt/Mac
</a>
<ul>
<li><a href="#6-1"> Problems building a static configuration
</a>
</ul>
<li><a href="#7"> Macintosh Native API Access
</a>
<ul>
<li><a href="#7-1"> Accessing the Bundle Path
</a>
<li><a href="#7-2"> Translating the Application Menu and native dialogs
</a>
</ul>
<li><a href="#8"> User Interface
</a>
<ul>
<li><a href="#8-1"> Right-Mouse Clicks
</a>
<li><a href="#8-2"> Menubar
</a>
</ul>
<li><a href="#9"> Limitations
</a>
<ul>
<li><a href="#9-1"> MenuItems
</a>
<li><a href="#9-2"> Unsupported Native Widgets
</a>
</ul>
</ul>
<!-- endtoc -->
<p> <h2> GUI Applications
</h2>
<a name="1"></a><p> GUI Applications must be run out of a bundle (something like widgets.app/)
or using the open(1) command. Mac OS X needs this to dispatch events correctly,
as well as gaining access to the menubar. If using GDB you must run with the
full path to the executable.
<p> <h2> <a href="qcursor.html">QCursor</a>
</h2>
<a name="2"></a><p> Due to Mac OS X having only 16x16 custom cursors QCursor is limited by this
as well. For now the only workaround to this problem is to use a small
cursor (16x16).
<p> <h2> Anti-aliased text
</h2>
<a name="3"></a><p> Qt/Mac (starting with 3.0.5) has introduced some support for smooth text as
suggested by Apple's Aqua Style Guildelines. This support is limited to Mac
OS X >10.1.4, when this version is not detected it will fallback to the old
text rendering library.
<p> <h2> Library Support
</h2>
<a name="4"></a><p> <h3> Bundle-based Libraries
</h3>
<a name="4-1"></a><p> If you want to incorporate dynamic libraries as part of your Mac OS X
application bundle (the application directory), then you place these into a
directory called Frameworks, a subdirectory of the application bundle.
<p> The application finds these dynamic libraries if the libraries have an
install name of "@executable_path/../Frameworks/libname.dylib.
<p> If you use qmake and Makefiles, use the QMAKE_LFFLAGS_SONAME setting:
<p> <pre>
QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/
</pre>
<p> In case of Project Builder, you set the Library targets to have their
install path (in the Build Settings of the target) set to
"@executable_path/.../Frameworks". You also need to add a custom build
setting called "SKIP_INSTALL" and set this to YES. In the Application
target you need to add a Copy Files build phase that will copy the library
product into the applications wrapper's Framework sub-folder.
<p> Note that DYLD_LIBRARY_PATH environment variables will override these
settings, same with any other default paths such as a lookup of dynamic
libraries inside /usr/lib and similar default locations.
<p> We still strongly recommend to build static applications where the library
code is incorporated into the Mac OS X binary. However, in case you ship
applications that require plugin support,then you need to use dynamic
libraries as part of your application.
<p> <h3> Combining Libraries
</h3>
<a name="4-2"></a><p> If you want to build a new dynamic library combining the Qt 3.1 dynamic
libraries, you need to introduce the ld -r flag so that relocation information
is stored in the the output file, so that this file could be the subject of
another ld run. This is done by setting the -r flag in the .pro file, and the
LFLAGS settings.
<p> <h3> Initialization Order
</h3>
<a name="4-3"></a><p> dyld(1) will call global static initializers in the order in which
they are linked into your application. If a library links against Qt
and references globals in Qt (from global initializers in your own
library) you should be sure to link against Qt before your library,
otherwise the result will be undefined (as Qt's global initializers
have not been called yet).
<p> <h3> Plugin Support
</h3>
<a name="4-4"></a><p> Note that it is not possible to build Qt plugins using Project Builder
or Xcode. Use <a href="qmake-manual.html">qmake</a> to configure and
build plugins.
<p> <h2> Compiler Settings
</h2>
<a name="5"></a><p> <h3> Compile-time Flags
</h3>
<a name="5-1"></a><p> If you want to wrap any specific Mac OS X code in a define, use the Q_OS_MACX
flag, as in:
<p> <pre>
#if defined(Q_OS_MACX)
// the code used
#endif
</pre>
<p> Note that when you build under Mac OS X 10.2, then the MACOSX_102 flag is
automatically included in the make builds.
<p> <h2> Building and Configuring Qt/Mac
</h2>
<a name="6"></a><p> <h3> Problems building a static configuration
</h3>
<a name="6-1"></a><p> If a static build fails with the following error messages during the
designer make phase:
<p> <pre>
QWidget::<a href="qwidget.html#sizeHint">sizeHint</a>() const referenced from libqui expected to be defined in @executable_path/../Frameworks/libqt-mt.3.dylib
non-virtual thunk [nv:-40] to QWidget::metric(int) const referenced from libqui
expected to be defined in @executable_path/../Frameworks/libqt-mt.3.dylib
</pre>
<p> then ensure that your library path does not have libqui libraries or
symbolic links. If you remove these, then the build will continue.
<p> <h2> Macintosh Native API Access
</h2>
<a name="7"></a><p> <h3> Accessing the Bundle Path
</h3>
<a name="7-1"></a><p> The Macintosh application is actually a directory (ending with .app). This
directory has various other sub-directories and sources. In case you want
to place for example the plugin directory inside this bundle, then you need
to find out where the bundle resides on the disk. The following code will
do this:
<p> <pre>
CFURLRef pluginRef = CFBundleCopyBundleURL(CFBundleGetMainBundle());
CFStringRef macPath = CFURLCopyFileSystemPath(pluginRef,
kCFURLPOSIXPathStyle);
const char *pathPtr = CFStringGetCStringPtr(macPath,
CFStringGetSystemEncoding());
<a href="qapplication.html#qDebug">qDebug</a>("Path = %s", pathPtr);
CFRelease(pluginRef);
CFRelease(macPath);
</pre>
<p> Do not forget to enclosure this in an #if defined(Q_OS_MACX) macro statement.
<p> <h3> Translating the Application Menu and native dialogs
</h3>
<a name="7-2"></a><p> You need to do a little extra to get the Application Menu and native dialogs
localized. This is a requirement of Mac OS X and not of Qt.
<p> First, you must add a localized resource folder inside the Bundle see:
<p> http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html
<p> And look for the heading: Adding Localized Resources
<p> The main thing you need to do is create a file called locversion.plist.
Here is an example one for Norwegian:
<p> <pre>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>LprojCompatibleVersion</key>
<string>123</string>
<key>LprojLocale</key>
<string>no</string>
<key>LprojRevisionLevel</key>
<string>1</string>
<key>LprojVersion</key>
<string>123</string>
</dict>
</plist>
</pre>
<p> Then when you run the application with your preferred language set to Norwegian
you should see menu items like "Avslutt" instead of "Quit"
<p> <h2> User Interface
</h2>
<a name="8"></a><p> <h3> Right-Mouse Clicks
</h3>
<a name="8-1"></a><p> If you want to provide right-mouse click support for Mac OS X, use the
<a href="qcontextmenuevent.html">QContextMenuEvent</a> class. This will map to a context menu event, in other
words a menu that will display a popup selection. This is the most common
use of right-mouse clicks, and maps to a control-click with the Mac OS X
one-button mouse support.
<p> <h3> Menubar
</h3>
<a name="8-2"></a><p> Qt/Mac will automatically detect your menubars for you and turn them
into Mac native menubars. Fitting this into your existing Qt application
will normally be automatic, however, if you have special needs the Qt/Mac
implementation currently selects a menubar by starting at the active window
(ie <a href="qapplication.html#activeWindow">QApplication::activeWindow</a>()), and applying:
<p> 1) If the window has a <a href="qmenubar.html">QMenuBar</a> then it is used.
2) If the window is a modal then its menubar is used. If no menubar is
specified then a default menubar is used (as documented below)
3) If the window has no parent then the default menubar is used (as documented below).
<p> The above 3 steps are applied all the way up the parent window chain until
one of the above are satisifed. If all else fails a default menubar will be
created, the default menubar on Qt/Mac is an empty menubar, however you can
create a different default menubar by creating a parentless QMenuBar, the
first one created will thus be designated the default menubar, and will be
used whenever a default menubar is needed.
<p> <h2> Limitations
</h2>
<a name="9"></a><p> <h3> MenuItems
</h3>
<a name="9-1"></a><p> <ul>
<p> <li> QCustomMenuItems are not supported in Mac native menubars, they are supported
in popupmenus that are not in the Mac native menubar.
<p> <li> Items with accelerators that have more than one keystroke
(<a href="qkeysequence.html">QKeySequence</a>) will not be honored, and the first key will be used.
<p> </ul>
<p> <h3> Unsupported Native Widgets
</h3>
<a name="9-2"></a><p> Qt/Mac 3.x has no support for sheets or drawers. Support for these types of windows is provided in Qt/Mac 4.x.
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt 3.3.8</div>
</table></div></address></body>
</html>
|
