|
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 qtmac-as-native.html |
|
44 \title Qt is Mac OS X Native |
|
45 \brief An explanation of Qt's native features on Mac OS X. |
|
46 \ingroup platform-specific |
|
47 |
|
48 This document explains what makes an application native on Mac OS X. |
|
49 It shows the areas where Qt is compliant, and the grey areas where |
|
50 compliance is more questionable. (See also the document |
|
51 \l{mac-differences.html}{Qt for Mac OS X - Specific Issues}.) |
|
52 |
|
53 Normally when referring to a native Mac application, one really means an |
|
54 application that talks directly to the underlying window system, rather |
|
55 than one that uses some intermediary (for example Apple's X11 server, or a |
|
56 web browser). Qt applications run as first class citizens, just like |
|
57 Cocoa, and Carbon applications. In fact, we use Carbon and HIView |
|
58 internally to communicate with OS X. |
|
59 |
|
60 When an application is running as a first class citizen, it means that |
|
61 it can interact with specific components of the Mac OS X experience: |
|
62 |
|
63 \tableofcontents |
|
64 |
|
65 \section1 The Global Menu Bar |
|
66 |
|
67 Qt does this via the QMenuBar abstraction. Mac users expect to |
|
68 have a menu bar at the top of the screen and Qt honors this. |
|
69 |
|
70 Additionally, users expect certain conventions to be respected, for |
|
71 example the application menu should contain About, Preferences, |
|
72 Quit, etc. Qt handles this automatically, although it does not |
|
73 provide a means of interacting directly with the application menu. |
|
74 (By doing this automatically, Qt makes it easier to port Qt |
|
75 applications to other platforms.) |
|
76 |
|
77 \section1 Aqua |
|
78 |
|
79 This is a critical piece of Mac OS X (documentation can be found at |
|
80 \l{http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html}). |
|
81 It is a huge topic, but the most important guidelines for GUI |
|
82 design are probably these: |
|
83 |
|
84 \list |
|
85 \i \e{Aqua look} |
|
86 |
|
87 As with Cocoa/Carbon, Qt provides widgets that look like those |
|
88 described in the Human Interface Descriptions. Qt's widgets use |
|
89 Appearance Manager on Mac OS X 10.2 and the new HIThemes on Mac OS X 10.3 |
|
90 and higher to implement the look, in other words we use Apple's own API's |
|
91 for doing the rendering. |
|
92 |
|
93 \i \e{Aqua feel} |
|
94 |
|
95 This is a bit more subjective, but certainly Qt strives to |
|
96 provide the same feel as any Mac OS X application (and we |
|
97 consider situations where it doesn't achieve this to be bugs). |
|
98 Of course Qt has other concerns to bear in mind, especially |
|
99 remaining cross-platform. Some "baggage" that Qt carries is in |
|
100 an effort to provide a widget on a platform for which an |
|
101 equivelant doesn't exist, or so that a single API can be used to |
|
102 do something, even if the API doesn't make entire sense for a |
|
103 specific widget. |
|
104 |
|
105 \i \e{Aqua guides} |
|
106 |
|
107 This is the most subjective, but there are many suggestions and |
|
108 guidelines in the Aqua style guidelines. This is the area where Qt is |
|
109 of least assistance. The decisions that must be made to conform (widget |
|
110 sizes, widget layouts with respect to other widgets, window margins, |
|
111 placement of OK and Cancel, etc) must be made based on the user |
|
112 experience demanded by your application. If your user base is small or |
|
113 mostly comes from the Windows or Unix worlds, these are minor issues much |
|
114 less important than trying to make a mass market product. Qt for Mac OS X |
|
115 is fully API compatible with Qt for Windows and X11, but Mac OS X is a |
|
116 significantly different platform to Windows and some special |
|
117 considerations must be made based on your audience. |
|
118 |
|
119 \endlist |
|
120 |
|
121 \section1 Dock |
|
122 |
|
123 Interaction with the dock is possible. The icon can be set by calling |
|
124 QWidget::setWindowIcon() on the main window in your application. The |
|
125 setWindowIcon() call can be made as often as necessary, providing an |
|
126 icon that can be easily updated. |
|
127 \omit |
|
128 It is also possible to set a QMenu as the dock menu through the use of the |
|
129 qt_mac_set_dock_menu() function. |
|
130 \endomit |
|
131 |
|
132 \section1 Accessiblity |
|
133 |
|
134 Although many users never use this, some users will only interact with your |
|
135 applications via assistive devices. With Qt the aim is to make this |
|
136 automatic in your application so that it conforms to accepted practice on |
|
137 its platform. Qt uses Apple's accessibility framework to provide access |
|
138 to users with diabilities. |
|
139 |
|
140 \section1 Development Tools |
|
141 |
|
142 Mac OS X developers expect a certain level of interopability |
|
143 between their development toolkit and the platform's developer |
|
144 tools (for example Visual Studio, gmake, etc). Qt supports both Unix |
|
145 style Makefiles, and ProjectBuilder/Xcode project files by using |
|
146 the \l qmake tool. For example: |
|
147 |
|
148 \snippet doc/src/snippets/code/doc_src_qtmac-as-native.qdoc 0 |
|
149 |
|
150 will generate an Xcode project file from project.pro. With \l qmake |
|
151 you do not have to worry about rules for Qt's preprocessors (\l moc |
|
152 and \l uic) since \l qmake automatically handles them and ensures that |
|
153 everything necessary is linked into your application. |
|
154 |
|
155 Qt does not entirely interact with the development environment (for |
|
156 example plugins to set a file to "mocable" from within the Xcode |
|
157 user interface). Nokia is actively working on improving Qt's |
|
158 interoperability with various IDEs. |
|
159 */ |