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