Qt for Mac OS X - Specific Issues
This file outlines known issues and possible workarounds when using Qt on Mac OS X. Contact Qt's technical support team if you find additional issues which are not covered here. (See also the document Qt is Mac OS X Native.)
GUI Applications
Mac OS X handles most applications as "bundles". A bundle is a directory structure that groups related files together (e.g., widgets.app/). GUI applications in particular must be run from a bundle or by using the open(1), because Mac OS X needs the bundle to dispatch events correctly, as well as for accessing the menu bar.
If you are using older versions of GDB you must run with the full path to the executable. Later versions allow you to pass the bundle name on the command line.
Painting
Mac OS X always double buffers the screen so the Qt::WA_PaintOnScreen attribute has no effect. Also it is impossible to paint outside of a paint event so Qt::WA_PaintOutsidePaintEvent has no effect either.
Library Support
Qt libraries as frameworks
By default, Qt is built as a set of frameworks. Frameworks is the Mac OS X "preferred" way of distributing libraries. There are definite advantages to using them. See Apple's Framework Programming Guide for more information.
In general, this shouldn't be an issue because qmake takes care of the specifics for you. The Framework Programming Guide discusses issues to keep in mind when choosing frameworks over the more typical, dynamic libraries. However, one point to remember is: Frameworks always link with "release" versions of libraries.
If you actually want to use a debug version of a Qt framework, you must ensure that your application actually loads that debug version. This is often done by using the DYLD_IMAGE_SUFFIX environment variables, but that way often doesn't work so well. Instead, you can temporarily swap your debug and release versions, which is documented in Apple's "Debugging Magic" technical note.
If you don't want to use frameworks, simply configure Qt with -no-framework.
Bundle-Based Libraries
If you want to use some dynamic libraries in your Mac OS X application bundle (the application directory), create a subdirectory named "Frameworks" in the application bundle directory and place your dynamic libraries there. The application will find a dynamic library if it has the install name @executable_path/../Frameworks/libname.dylib.
If you use qmake and Makefiles, use the QMAKE_LFLAGS_SONAME setting:
QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/
Alternatively, you can modify the install name using the install_name_tool(1) on the command line. See its manpage for more information.
Note that the DYLD_LIBRARY_PATH environment variable will override these settings, and any other default paths, such as a lookup of dynamic libraries inside /usr/lib and similar default locations.
Combining Libraries
If you want to build a new dynamic library combining the Qt 4 dynamic libraries, you need to introduce the ld -r flag. Then relocation information is stored in 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.
Initialization Order
dyld(1) calls global static initializers in the order they are linked into your application. If a library links against Qt and references globals in Qt (from global initializers in your own library), be sure to link your application against Qt before linking it against the library. Otherwise the result will be undefined because Qt's global initializers have not been called yet.
Compile-Time Flags
The follewing flags are helpful when you want to define Mac OS X specific code:
- Q_OS_DARWIN is defined when Qt detects you are on a Darwin-based system (including the Open Source version)
- Q_WS_MAC is defined when the Mac OS X GUI is present.
- QT_MAC_USE_COCOA is defined when Qt is built to use the Cocoa framework. If it is not present, then Qt is using Carbon.
A additional flag, Q_OS_MAC, is defined as a convenience whenever Q_OS_DARWIN is defined.
If you want to define code for specific versions of Mac OS X, use the availability macros defined in /usr/include/AvailabilityMacros.h.
See QSysInfo for information on runtime version checking.
Mac OS X Native API Access
Accessing the Bundle Path
The Mac OS X application is actually a directory (ending with .app). This directory contains sub-directories and files. It may be useful to place items (e.g. plugins, online-documentation, etc.) inside this bundle. You might then want to find out where the bundle resides on the disk. The following code returns the path of the application bundle:
#ifdef Q_WS_MAC
CFURLRef appUrlRef = CFBundleCopyBundleURL(CFBundleGetMainBundle());
CFStringRef macPath = CFURLCopyFileSystemPath(appUrlRef,
kCFURLPOSIXPathStyle);
const char *pathPtr = CFStringGetCStringPtr(macPath,
CFStringGetSystemEncoding());
qDebug("Path = %s", pathPtr);
CFRelease(appUrlRef);
CFRelease(macPath);
#endif
Note: When OS X is set to use Japanese, a bug causes this sequence to fail and return an empty string. Therefore, always test the returned string.
For more information about using the CFBundle API, see Apple's Developer Website.
Translating the Application Menu and Native Dialogs
The items in the Application Menu will be merged correctly for your localized application, but they will not show up translated until you add a localized resource folder to the application bundle. The main thing you need to do is create a file called locversion.plist. Here is an example for Norwegian:
<?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>
Now when you run the application with your preferred language set to Norwegian, you should see menu items like "Avslutt" instead of "Quit".
User Interface
Right-Mouse Clicks
If you want to provide right-mouse click support for Mac OS X, use the QContextMenuEvent class. This will map to a context menu event, i.e., a menu that will display a pop-up 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.
|
|
Best Of
Actualités les plus lues
Le blog Digia au hasard
Le blog Digia est l'endroit privilégié pour la communication sur l'édition commerciale de Qt, où des réponses publiques sont apportées aux questions les plus posées au support. Lire l'article.
Communauté
Ressources
Liens utiles
Contact
- Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).
Qt dans le magazine
|
