Initial import of statemachine branch from the old kinetic repository

1 files changed, 202 insertions, 0 deletions

diff --git a/doc/src/qtmac-as-native.qdoc b/doc/src/qtmac-as-native.qdoc
new file mode 100644
index 0000000..ecbc64c
--- /dev/null
+++ b/doc/src/qtmac-as-native.qdoc
@@ -0,0 +1,202 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/****************************************************************************
+**
+** Qt for Mac OS X documentation
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@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-notes
+
+    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.
+*/