/****************************************************************************
**
** Qt/Mac documentation
**
** Copyright (C) 2002-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/

/*!

\page qtmac-as-native.html

\title Qt/Mac is Mac OS X Native

This document explains what makes an application "native" on Mac OS X.
It shows the areas where Qt/Mac is compliant, and the grey areas where
compliance is more questionable. (See also the document 
\link mac-differences.html Qt/Mac Issues\endlink.)

Normally when referring to a native application, one really means an
application that talks directly to the underlying window system and
operating system, rather than one that uses some intermediary (for
example the X11 server, or a web browser). Qt/Mac applications run as
first class citizens, just like Cocoa, Java, and Carbon applications. 

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:

\list
\i <b>The global menubar</b><br>

   Qt/Mac does this via the QMenuBar abstraction. Mac users expect to
   have a menubar at the top of the screen and Qt/Mac honors this.

   Additionally, users expect certain conventions to be respected, for
   example the application menu should contain About, Preferences,
   Quit, etc. Qt/Mac handles this automatically, although it does not
   provide a means of interacting directly with the application menu.
   (By doing this automatically, Qt/Mac makes it easier to port Qt/Mac
   applications to other platforms.)

\i <b>Aqua</b><br>

   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}<br>

      As with Cocoa/Carbon Qt/Mac provides widgets that look like
      those described in the Human Interface Descriptions. Qt/Mac's
      widgets use the Appearance Manager to implement the look, so
      Apple's own API's are doing the rendering (Qt/Mac \<3.1 used an
      emulation style with pixmaps, however this quickly proved to be
      cumbersome, and unable to keep up with style changes at Apple).

    \i \e{Aqua feel}<br>

      This is a bit more subjective, but certainly Qt/Mac 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 multiplatform. 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 (for example pushbuttons with a popup menu are
      really bevel buttons in Mac OS X, but Qt/Mac cannot guess that
      this bevel button is right next to other real pushbuttons).

    \i \e{Aqua guides}<br>

      This is the most subjective, but there are many suggestions and
      guidelines in the Aqua style guidelines. This is the area where
      Qt/Mac is of least assistance. The decisions that must be made
      to conform (widget sizes, widget layouts with respect to other
      widgets, window margins, 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/Mac is fully API compatible with Qt/Windows
      and Qt/X11, but Mac OS X is a significantly different platform
      to Windows and some special considerations must be made based on
      your audience.

    \endlist

\i <b>Dock</b><br>

   Interaction with the dock is limited, but at the very least the icon
   should be able to be interacted with. This can be achieved with
   QWidget::setIcon(). The setIcon() call can be made as often as
   necessary, so can be used to provide a constantly updating pixmap
   that works as expected.

\i <b>Accessiblity</b><br>

   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 (X11 accessiblity support is
   still in the works due to the developing nature of its
   accessibility design). With Qt 3.3 Qt/Mac will support
   accessiblity, and hopefully a host of assistive devices.

\i <b>Build tools</b><br>

   Mac OS X developers expect a certain level of interopability
   between their development toolkit and the platform's developer
   tools (for example MSVC, gmake, etc). Qt/Mac supports both Unix
   style Makefiles, and ProjectBuilder/Xcode project files by using
   the qmake tool. For example:

   \code
   qmake -spec macx-pbuilder project.pro
   \endcode

   will generate an Xcode project file from project.pro. With qmake
   you do not have to worry about rules for Qt's preprocessors (moc
   and uic) since 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). Trolltech is actively working on improving Qt's
   interoperability with various IDEs, so hopefully this will be
   supported soon.

\endlist

*/