diff options
Diffstat (limited to 'doc/src/platforms/qtmac-as-native.qdoc')
| -rw-r--r-- | doc/src/platforms/qtmac-as-native.qdoc | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/doc/src/platforms/qtmac-as-native.qdoc b/doc/src/platforms/qtmac-as-native.qdoc new file mode 100644 index 0000000..265d222 --- /dev/null +++ b/doc/src/platforms/qtmac-as-native.qdoc @@ -0,0 +1,202 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Qt for Mac OS X documentation +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +**********************************************************************/ + +/*! + \page qtmac-as-native.html + \title Qt is Mac OS X Native + \brief An explanation of Qt's native features on Mac OS X. + \ingroup platform-specific + + This document explains what makes an application native on Mac OS X. + It shows the areas where Qt is compliant, and the grey areas where + compliance is more questionable. (See also the document + \l{mac-differences.html}{Qt for Mac OS X - Specific Issues}.) + + Normally when referring to a native Mac application, one really means an + application that talks directly to the underlying window system, rather + than one that uses some intermediary (for example Apple's X11 server, or a + web browser). Qt applications run as first class citizens, just like + Cocoa, and Carbon applications. In fact, we use Carbon and HIView + internally to communicate with OS X. + + When an application is running as a first class citizen, it means that + it can interact with specific components of the Mac OS X experience: + + \tableofcontents + + \section1 The Global Menu Bar + + Qt does this via the QMenuBar abstraction. Mac users expect to + have a menu bar at the top of the screen and Qt honors this. + + Additionally, users expect certain conventions to be respected, for + example the application menu should contain About, Preferences, + Quit, etc. Qt handles this automatically, although it does not + provide a means of interacting directly with the application menu. + (By doing this automatically, Qt makes it easier to port Qt + applications to other platforms.) + + \section1 Aqua + + This is a critical piece of Mac OS X (documentation can be found at + \l{http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html}). + It is a huge topic, but the most important guidelines for GUI + design are probably these: + + \list + \i \e{Aqua look} + + As with Cocoa/Carbon, Qt provides widgets that look like those + described in the Human Interface Descriptions. Qt's widgets use + Appearance Manager on Mac OS X 10.2 and the new HIThemes on Mac OS X 10.3 + and higher to implement the look, in other words we use Apple's own API's + for doing the rendering. + + \i \e{Aqua feel} + + This is a bit more subjective, but certainly Qt strives to + provide the same feel as any Mac OS X application (and we + consider situations where it doesn't achieve this to be bugs). + Of course Qt has other concerns to bear in mind, especially + remaining cross-platform. Some "baggage" that Qt carries is in + an effort to provide a widget on a platform for which an + equivelant doesn't exist, or so that a single API can be used to + do something, even if the API doesn't make entire sense for a + specific widget. + + \i \e{Aqua guides} + + This is the most subjective, but there are many suggestions and + guidelines in the Aqua style guidelines. This is the area where Qt is + of least assistance. The decisions that must be made to conform (widget + sizes, widget layouts with respect to other widgets, window margins, + placement of OK and Cancel, etc) must be made based on the user + experience demanded by your application. If your user base is small or + mostly comes from the Windows or Unix worlds, these are minor issues much + less important than trying to make a mass market product. Qt for Mac OS X + is fully API compatible with Qt for Windows and X11, but Mac OS X is a + significantly different platform to Windows and some special + considerations must be made based on your audience. + + \endlist + + \section1 Dock + + Interaction with the dock is possible. The icon can be set by calling + QWidget::setWindowIcon() on the main window in your application. The + setWindowIcon() call can be made as often as necessary, providing an + icon that can be easily updated. + \omit + It is also possible to set a QMenu as the dock menu through the use of the + qt_mac_set_dock_menu() function. + \endomit + + \section1 Accessiblity + + Although many users never use this, some users will only interact with your + applications via assistive devices. With Qt the aim is to make this + automatic in your application so that it conforms to accepted practice on + its platform. Qt uses Apple's accessibility framework to provide access + to users with diabilities. + + \section1 Development Tools + + Mac OS X developers expect a certain level of interopability + between their development toolkit and the platform's developer + tools (for example Visual Studio, gmake, etc). Qt supports both Unix + style Makefiles, and ProjectBuilder/Xcode project files by using + the \l qmake tool. For example: + + \snippet doc/src/snippets/code/doc_src_qtmac-as-native.qdoc 0 + + will generate an Xcode project file from project.pro. With \l qmake + you do not have to worry about rules for Qt's preprocessors (\l moc + and \l uic) since \l qmake automatically handles them and ensures that + everything necessary is linked into your application. + + Qt does not entirely interact with the development environment (for + example plugins to set a file to "mocable" from within the Xcode + user interface). Nokia is actively working on improving Qt's + interoperability with various IDEs. +*/ |