← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/mac-differences.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/mac-differences.qdoc
1
 
/****************************************************************************
2
 
**
3
 
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
 
** Contact: Nokia Corporation (qt-info@nokia.com)
5
 
**
6
 
** This file is part of the documentation of the Qt Toolkit.
7
 
**
8
 
** $QT_BEGIN_LICENSE:LGPL$
9
 
** Commercial Usage
10
 
** Licensees holding valid Qt Commercial licenses may use this file in
11
 
** accordance with the Qt Commercial License Agreement provided with the
12
 
** Software or, alternatively, in accordance with the terms contained in
13
 
** a written agreement between you and Nokia.
14
 
**
15
 
** GNU Lesser General Public License Usage
16
 
** Alternatively, this file may be used under the terms of the GNU Lesser
17
 
** General Public License version 2.1 as published by the Free Software
18
 
** Foundation and appearing in the file LICENSE.LGPL included in the
19
 
** packaging of this file.  Please review the following information to
20
 
** ensure the GNU Lesser General Public License version 2.1 requirements
21
 
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22
 
**
23
 
** In addition, as a special exception, Nokia gives you certain
24
 
** additional rights. These rights are described in the Nokia Qt LGPL
25
 
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26
 
** package.
27
 
**
28
 
** GNU General Public License Usage
29
 
** Alternatively, this file may be used under the terms of the GNU
30
 
** General Public License version 3.0 as published by the Free Software
31
 
** Foundation and appearing in the file LICENSE.GPL included in the
32
 
** packaging of this file.  Please review the following information to
33
 
** ensure the GNU General Public License version 3.0 requirements will be
34
 
** met: http://www.gnu.org/copyleft/gpl.html.
35
 
**
36
 
** If you are unsure which license is appropriate for your use, please
37
 
** contact the sales department at http://www.qtsoftware.com/contact.
38
 
** $QT_END_LICENSE$
39
 
**
40
 
****************************************************************************/
41
 
 
42
 
/*!
43
 
    \page mac-differences.html
44
 
    \title Qt for Mac OS X - Specific Issues
45
 
    \brief A description of issues with Qt that are specific to Mac OS X.
46
 
    \ingroup platform-notes
47
 
 
48
 
    This file outlines known issues and possible workarounds when
49
 
    using Qt on Mac OS X. Contact Qt's technical support team if you find
50
 
    additional issues which are not covered here. (See also the
51
 
    document \l{qtmac-as-native.html} {Qt is Mac OS X Native}.)
52
 
 
53
 
    \tableofcontents
54
 
 
55
 
    \section1 GUI Applications
56
 
 
57
 
    Mac OS X handles most applications as "bundles". A bundle is a
58
 
    directory structure that groups related files together (e.g.,
59
 
    widgets.app/). GUI applications in particular must be run from a
60
 
    bundle or by using the open(1), because Mac OS X needs the bundle
61
 
    to dispatch events correctly, as well as for accessing the menu
62
 
    bar.
63
 
 
64
 
    If you are using older versions of GDB you must run with the full
65
 
    path to the executable.  Later versions allow you to pass the
66
 
    bundle name on the command line.
67
 
 
68
 
    \section1 Painting
69
 
 
70
 
    Mac OS X always double buffers the screen so the
71
 
    Qt::WA_PaintOnScreen attribute has no effect. Also it is
72
 
    impossible to paint outside of a paint event so
73
 
    Qt::WA_PaintOutsidePaintEvent has no effect either.
74
 
 
75
 
    \section1 Library Support
76
 
 
77
 
    \section2 Qt libraries as frameworks
78
 
 
79
 
    By default, Qt is built as a set of frameworks. Frameworks is the
80
 
    Mac OS X "preferred" way of distributing libraries. There are
81
 
    definite advantages to using them. See
82
 
    \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html}
83
 
    {Apple's Framework Programming Guide} for more information.
84
 
 
85
 
    In general, this shouldn't be an issue because qmake takes care of
86
 
    the specifics for you. The
87
 
    \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html}
88
 
    {Framework Programming Guide} discusses issues to keep in mind
89
 
    when choosing frameworks over the more typical, dynamic libraries.
90
 
    However, one point to remember is: \bold {Frameworks always link
91
 
    with "release" versions of libraries}.
92
 
 
93
 
    If you actually want to use a \e{debug} version of a Qt framework,
94
 
    you must ensure that your application actually loads that debug
95
 
    version. This is often done by using the DYLD_IMAGE_SUFFIX
96
 
    environment variables, but that way often doesn't work so well.
97
 
    Instead, you can temporarily swap your debug and release versions,
98
 
    which is documented in
99
 
    \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB}
100
 
    {Apple's "Debugging Magic" technical note}.
101
 
 
102
 
    If you don't want to use frameworks, simply configure Qt with
103
 
    \c{-no-framework}.
104
 
 
105
 
    \section2 Bundle-Based Libraries
106
 
 
107
 
    If you want to use some dynamic libraries in your Mac OS X
108
 
    application bundle (the application directory), create a
109
 
    subdirectory named "Frameworks" in the application bundle
110
 
    directory and place your dynamic libraries there. The application
111
 
    will find a dynamic library if it has the install name
112
 
    \e{@executable_path/../Frameworks/libname.dylib}.
113
 
 
114
 
    If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting:
115
 
 
116
 
    \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0
117
 
 
118
 
    Alternatively, you can modify the install name using the
119
 
    install_name_tool(1) on the command line. See its manpage for more
120
 
    information.
121
 
 
122
 
    Note that the \c DYLD_LIBRARY_PATH environment variable will
123
 
    override these settings, and any other default paths, such as a
124
 
    lookup of dynamic libraries inside \c /usr/lib and similar default
125
 
    locations.
126
 
 
127
 
    \section2 Combining Libraries
128
 
 
129
 
    If you want to build a new dynamic library combining the Qt 4
130
 
    dynamic libraries, you need to introduce the \c{ld -r} flag. Then
131
 
    relocation information is stored in the output file, so that
132
 
    this file could be the subject of another \c ld run. This is done
133
 
    by setting the \c -r flag in the \c .pro file, and the \c LFLAGS
134
 
    settings.
135
 
 
136
 
    \section2 Initialization Order
137
 
 
138
 
    dyld(1) calls global static initializers in the order they are
139
 
    linked into your application. If a library links against Qt and
140
 
    references globals in Qt (from global initializers in your own
141
 
    library), be sure to link your application against Qt before
142
 
    linking it against the library.  Otherwise the result will be
143
 
    undefined because Qt's global initializers have not been called
144
 
    yet.
145
 
 
146
 
    \section1 Compile-Time Flags
147
 
 
148
 
    The follewing flags are helpful when you want to define Mac OS X specific
149
 
    code:
150
 
 
151
 
    \list
152
 
 
153
 
    \o Q_OS_DARWIN is defined when Qt detects you are on a
154
 
    Darwin-based system (including the Open Source version)
155
 
 
156
 
    \o Q_WS_MAC is defined when the Mac OS X GUI is present.
157
 
 
158
 
    \o QT_MAC_USE_COCOA is defined when Qt is built to use the Cocoa framework.
159
 
    If it is not present, then Qt is using Carbon.
160
 
 
161
 
    \endlist
162
 
 
163
 
    A additional flag, Q_OS_MAC, is defined as a convenience whenever
164
 
    Q_OS_DARWIN is defined.
165
 
 
166
 
    If you want to define code for specific versions of Mac OS X, use
167
 
    the availability macros defined in /usr/include/AvailabilityMacros.h.
168
 
 
169
 
    See QSysInfo for information on runtime version checking.
170
 
 
171
 
    \section1 Mac OS X Native API Access
172
 
 
173
 
    \section2 Accessing the Bundle Path
174
 
 
175
 
    The Mac OS X application is actually a directory (ending with \c
176
 
    .app).  This directory contains sub-directories and files. It may
177
 
    be useful to place items (e.g. plugins, online-documentation,
178
 
    etc.) inside this bundle. You might then want to find out where
179
 
    the bundle resides on the disk. The following code returns the
180
 
    path of the application bundle:
181
 
 
182
 
    \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 1
183
 
 
184
 
    Note: When OS X is set to use Japanese, a bug causes this sequence
185
 
    to fail and return an empty string. Therefore, always test the
186
 
    returned string.
187
 
 
188
 
    For more information about using the CFBundle API, see
189
 
    \l{http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html}
190
 
    {Apple's Developer Website}.
191
 
 
192
 
    \section2 Translating the Application Menu and Native Dialogs
193
 
 
194
 
    The items in the Application Menu will be merged correctly for
195
 
    your localized application, but they will not show up translated
196
 
    until you 
197
 
    \l{http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/Concepts/BundleAnatomy.html#//apple_ref/doc/uid/20001119-105003-BAJFDAAG}
198
 
    {add a localized resource folder} to the application bundle.
199
 
    The main thing you need to do is create a file called
200
 
    locversion.plist.  Here is an example for Norwegian:
201
 
 
202
 
    \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 2
203
 
 
204
 
    Now when you run the application with your preferred language set
205
 
    to Norwegian, you should see menu items like "Avslutt" instead of
206
 
    "Quit".
207
 
 
208
 
    \section1 User Interface
209
 
 
210
 
    \section2 Right-Mouse Clicks
211
 
 
212
 
    If you want to provide right-mouse click support for Mac OS X, use
213
 
    the QContextMenuEvent class. This will map to a context menu
214
 
    event, i.e., a menu that will display a pop-up selection. This is
215
 
    the most common use of right-mouse clicks, and maps to a
216
 
    control-click with the Mac OS X one-button mouse support.
217
 
 
218
 
    \section2 Menu Bar
219
 
 
220
 
    Qt will automatically detect your menu bars for you and turn
221
 
    them into Mac native menu bars. Fitting this into your existing Qt
222
 
    application will normally be automatic. However, if you have
223
 
    special needs, the Qt implementation currently selects a menu
224
 
    bar by starting at the active window
225
 
    (i.e. QApplication::activeWindow()) and applying the following
226
 
    tests:
227
 
 
228
 
    \list 1
229
 
 
230
 
    \i If the window has a QMenuBar, then it is used.
231
 
 
232
 
    \i If the window is modal, then its menu bar is used. If no menu
233
 
       bar is specified, then a default menu bar is used (as
234
 
       documented below).
235
 
 
236
 
    \i If the window has no parent, then the default menu bar is used
237
 
       (as documented below).
238
 
 
239
 
    \endlist
240
 
 
241
 
    These tests are followed all the way up the parent window chain
242
 
    until one of the above rules is satisifed. If all else fails, a
243
 
    default menu bar will be created. Note the default menu bar on
244
 
    Qt is an empty menu bar. However, you can create a different
245
 
    default menu bar by creating a parentless QMenuBar. The first one
246
 
    created will be designated the default menu bar and will be used
247
 
    whenever a default menu bar is needed.
248
 
 
249
 
    Note that using native menu bars introduces certain limitations on
250
 
    Qt classes.  See the \l{#Limitations}{list of limitations} below
251
 
    for more information about these.
252
 
 
253
 
    \section2 Special Keys
254
 
 
255
 
    To provide the expected behavior for Qt applications on Mac OS X,
256
 
    the Qt::Meta, Qt::MetaModifier, and Qt::META enum values
257
 
    correspond to the Control keys on the standard Macintosh keyboard,
258
 
    and the Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values
259
 
    correspond to the Command keys.
260
 
 
261
 
    \section1 Limitations
262
 
 
263
 
    \section2 Menu Actions
264
 
 
265
 
    \list
266
 
 
267
 
    \o Actions in a QMenu with accelerators that have more than one
268
 
       keystroke (QKeySequence) will not display correctly, when the
269
 
       QMenu is translated into a Mac native menu bar. The first key
270
 
       will be displayed. However, the shortcut will still be
271
 
       activated as on all other platforms.
272
 
 
273
 
    \o QMenu objects used in the native menu bar are not able to
274
 
       handle Qt events via the normal event handlers.
275
 
       For Carbon, you will have to install a Carbon event handler on
276
 
       the menu bar in order to receive Carbon events that are similar
277
 
       to \l{QMenu::}{showEvent()}, \l{QMenu::}{hideEvent()}, and
278
 
       \l{QMenu::}{mouseMoveEvent()}. For Cocoa, you will have to
279
 
       install a delegate on the menu itself to be notified of these
280
 
       changes. Alternatively, consider using the QMenu::aboutToShow()
281
 
       and QMenu::aboutToHide() signals to keep track of menu visibility;
282
 
       these provide a solution that should work on all platforms
283
 
       supported by Qt.
284
 
 
285
 
    \endlist
286
 
 
287
 
    \section2 Native Widgets
288
 
 
289
 
    Qt has support for sheets and drawers, represented in the
290
 
    window flags by Qt::Sheet and Qt::Drawer respectiviely. Brushed
291
 
    metal windows can also be created by using the
292
 
    Qt::WA_MacMetalStyle window attribute.
293
 
 
294
 
*/
295
 
 
296
 
/*!
297
 
    \page qt-mac-cocoa-licensing.html
298
 
 
299
 
    \title Contributions to the Following QtGui Files: qapplication_cocoa_p.h, qapplication_mac.mm, qdesktopwidget_mac.mm qeventdispatcher_mac.mm qeventdispatcher_mac_p.h qmacincludes_mac.h qt_cocoa_helpers.mm qt_cocoa_helpers_p.h qwidget_mac.mm qsystemtrayicon_mac.mm
300
 
 
301
 
    \contentspage {Other Licenses Used in Qt}{Contents}
302
 
 
303
 
    \ingroup licensing
304
 
    \brief License information for contributions by Apple, Inc. to specific parts of the Qt/Mac Cocoa port.
305
 
 
306
 
    \legalese
307
 
 
308
 
    Copyright (C) 2007-2008, Apple, Inc.
309
 
 
310
 
    All rights reserved.
311
 
 
312
 
    Redistribution and use in source and binary forms, with or without
313
 
    modification, are permitted provided that the following conditions are met:
314
 
 
315
 
    \list
316
 
    \o Redistributions of source code must retain the above copyright notice,
317
 
       this list of conditions and the following disclaimer.
318
 
    \o Redistributions in binary form must reproduce the above copyright notice,
319
 
       this list of conditions and the following disclaimer in the documentation
320
 
       and/or other materials provided with the distribution.
321
 
    \o Neither the name of Apple, Inc. nor the names of its contributors
322
 
       may be used to endorse or promote products derived from this software
323
 
       without specific prior written permission.
324
 
    \endlist
325
 
 
326
 
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
327
 
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
328
 
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
329
 
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
330
 
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
331
 
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
332
 
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
333
 
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
334
 
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
335
 
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
336
 
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
337
 
 
338
 
    \endlegalese
339
 
*/