You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
270 lines
9.9 KiB
270 lines
9.9 KiB
/****************************************************************************
|
|
**
|
|
** Qt/Mac documentation
|
|
**
|
|
** Copyright (C) 2002-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the TQt 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 TQt 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 TQt 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 TQt (from global initializers in your own
|
|
library) you should be sure to link against TQt 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 TQt 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
|
|
TQWidget::sizeHint() const referenced from libtqui expected to be defined in @executable_path/../Frameworks/libtqt-mt.3.dylib
|
|
non-virtual thunk [nv:-40] to TQWidget::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());
|
|
tqDebug("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
|
|
<?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 TQt 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 TQMenuBar 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 TQMenuBar, 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.
|
|
*/
|