diff options
Diffstat (limited to 'doc/html/mac-differences.html')
| -rw-r--r-- | doc/html/mac-differences.html | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/doc/html/mac-differences.html b/doc/html/mac-differences.html new file mode 100644 index 0000000..bbbe861 --- /dev/null +++ b/doc/html/mac-differences.html @@ -0,0 +1,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> |