|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
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-specific |
|
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 */ |