--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/platforms/qtmac-as-native.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,159 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** 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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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.
+*/