diff options
Diffstat (limited to 'doc/mac.doc')
| -rw-r--r-- | doc/mac.doc | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/doc/mac.doc b/doc/mac.doc new file mode 100644 index 000000000..56bf0b159 --- /dev/null +++ b/doc/mac.doc @@ -0,0 +1,269 @@ +/**************************************************************************** +** +** 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 retquirements 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 retquire 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 libtqui expected to be defined in @executable_path/../Frameworks/libtqt-mt.3.dylib +non-virtual thunk [nv:-40] to QWidget::metric(int) const referenced from libtqui + expected to be defined in @executable_path/../Frameworks/libtqt-mt.3.dylib +\endcode + +then ensure that your library path does not have libtqui 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 retquirement 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 +<?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> +\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. +*/ |