/**************************************************************************** ** ** Qt/Mac documentation ** ** Copyright (C) 2002-2008 Trolltech ASA. All rights reserved. ** ** This file is part of the Qt GUI Toolkit. ** ** This file may be used under the terms of the GNU General ** Public License versions 2.0 or 3.0 as published by the Free ** Software Foundation and appearing in the files LICENSE.GPL2 ** and LICENSE.GPL3 included in the packaging of this file. ** Alternatively you may (at your option) use any later version ** of the GNU General Public License if such license has been ** publicly approved by Trolltech ASA (or its successors, if any) ** and the KDE Free Qt Foundation. ** ** Please review the following information to ensure GNU General ** Public Licensing requirements will be met: ** http://trolltech.com/products/qt/licenses/licensing/opensource/. ** If you are unsure which license is appropriate for your use, please ** review the following information: ** http://trolltech.com/products/qt/licenses/licensing/licensingoverview ** or contact the sales department at sales@trolltech.com. ** ** This file may be used under the terms of the Q Public License as ** defined by Trolltech ASA and appearing in the file LICENSE.QPL ** included in the packaging of this file. Licensees holding valid Qt ** Commercial licenses may use this file in accordance with the Qt ** Commercial License Agreement provided with the Software. ** ** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, ** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR ** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted ** herein. ** **********************************************************************/ /*! \page mac-differences.html \title Qt/Mac Issues 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. See also the document \link qtmac-as-native.html Qt/Mac is Mac OS X Native\endlink. \tableofcontents \section1 GUI Applications 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. \section1 QCursor 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). \section1 Anti-aliased text 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. \section1 Library Support \section2 Bundle-based Libraries 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. The application finds these dynamic libraries if the libraries have an install name of "@executable_path/../Frameworks/libname.dylib. If you use qmake and Makefiles, use the QMAKE_LFFLAGS_SONAME setting: \code QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/ \endcode 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. 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. 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. \section2 Combining Libraries 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. \section2 Initialization Order 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). \section2 Plugin Support Note that it is not possible to build Qt plugins using Project Builder or Xcode. Use \link qmake-manual.book qmake\endlink to configure and build plugins. \section1 Compiler Settings \section2 Compile-time Flags If you want to wrap any specific Mac OS X code in a define, use the Q_OS_MACX flag, as in: \code #if defined(Q_OS_MACX) // the code used #endif \endcode Note that when you build under Mac OS X 10.2, then the MACOSX_102 flag is automatically included in the make builds. \section1 Building and Configuring Qt/Mac \section2 Problems building a static configuration If a static build fails with the following error messages during the designer make phase: \code QWidget::sizeHint() 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 \endcode then ensure that your library path does not have libqui libraries or symbolic links. If you remove these, then the build will continue. \section1 Macintosh Native API Access \section2 Accessing the Bundle Path 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: \code CFURLRef pluginRef = CFBundleCopyBundleURL(CFBundleGetMainBundle()); CFStringRef macPath = CFURLCopyFileSystemPath(pluginRef, kCFURLPOSIXPathStyle); const char *pathPtr = CFStringGetCStringPtr(macPath, CFStringGetSystemEncoding()); qDebug("Path = %s", pathPtr); CFRelease(pluginRef); CFRelease(macPath); \endcode Do not forget to enclosure this in an #if defined(Q_OS_MACX) macro statement. \section2 Translating the Application Menu and native dialogs 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. First, you must add a localized resource folder inside the Bundle see: http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html And look for the heading: Adding Localized Resources The main thing you need to do is create a file called locversion.plist. Here is an example one for Norwegian: \code LprojCompatibleVersion 123 LprojLocale no LprojRevisionLevel 1 LprojVersion 123 \endcode Then when you run the application with your preferred language set to Norwegian you should see menu items like "Avslutt" instead of "Quit" \section1 User Interface \section2 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, 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. \section2 Menubar 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 QApplication::activeWindow()), and applying: 1) If the window has a QMenuBar 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). 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. \section1 Limitations \section2 MenuItems \list \i QCustomMenuItems are not supported in Mac native menubars, they are supported in popupmenus that are not in the Mac native menubar. \i Items with accelerators that have more than one keystroke (QKeySequence) will not be honored, and the first key will be used. \endlist \section2 Unsupported Native Widgets Qt/Mac 3.x has no support for sheets or drawers. Support for these types of windows is provided in Qt/Mac 4.x. */