Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-team into 4.7

Conflicts:
	doc/src/platforms/supported-platforms.qdoc

2 files changed, 423 insertions, 52 deletions

diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc
new file mode 100644
index 0000000..96337c9
--- /dev/null
+++ b/doc/src/howtos/scalabilityintro.qdoc
@@ -0,0 +1,297 @@
+
+/*!
+    \title Scalability
+    \page scalability.html
+
+    \omit preliminary docs for next SDK release \endomit
+    \omit Somewhere I need to mention applications with more than
+          one page (top-level layouts). \endomit
+
+    A scalable application is an application that can run on more than
+    one form factor. In particular, it can cope with different screen
+    sizes, DPI, and aspect ratios. You need to consider scalability
+    when:
+
+    \list
+        \o your application will be deployed to more than one device
+           handset, or more than one device form factor.
+        \o your application will be deployed for a long period of time,
+           so that new device handsets might appear on the market after
+           your initial deployment.
+    \endlist
+
+    This document discusses how scalable applications can be created.
+
+    \section1 Developing Scalable UIs
+
+    This section shows the basics of how we advice scalable
+    applications to be implemented using QML. We recommend that you
+    follow these techniques:
+
+    \list
+        \o Create separate top-level layout
+           definitions for each form factor.
+        \o Keep the layouts small and let components
+           scale relative to their immediate parent.
+        \o Define device independent measurements, such as dp
+           (device independent pixels), and use
+           these to scale components and for layout measurement.
+        \o Define layouts in a
+           proportional way using the built-in layout features of QML.
+    \endlist
+
+    Using small top-level layouts makes your codebase smaller and
+    easier to maintain. Also, components that scales relative to their
+    parent are more reusable. The layouts should be children of the
+    applications root item. You can change between them by, for
+    instance, using the opacity property of Item; that is, if your
+    application has more tham one top-level layout.
+
+    You should define the measurements separate from the UI, for
+    instance by using a JavaScript object that you fill in with a
+    script on application start up.
+
+    QML's provides several ways of laying out components, e.g, using
+    anchor based layout, the more classic Grid; Column; and Row
+    elements, and by setting the dimensions of Items directly. When
+    laying out components in scalable applications, you should
+    generally prefer using anchors and set width and height based on
+    parent size where possible. Layouts are not only relevant to
+    top-level layouts; components often contain child Items.
+
+    The following sections describe in more detail the different
+    aspects of scalability that should be considered in order to
+    achieve the desired level of flexibility within your application. 
+
+    \section1 Implementing the Top-Level Layouts
+
+    As mentioned, each application should use separate top-level
+    layout QML definitions to support separate layout configurations /
+    form factors.
+
+    Consider an application that has to be deployed to at least two
+    devices, which both have very different screen sizes and DPI
+    values. The two form factors of the application will share many
+    common components and attributes, and will most likely connect to
+    the same data model.
+
+    Therefore, the top level definitions should be quite
+    straightforward and short, with the majority of the functionality
+    refactored into contained Components. It is important to try to
+    avoid unnecessary duplication between these top level definitions,
+    in order to improve maintainability.
+
+    There are some patterns that you might consider when designing
+    your top level layouts:
+
+    \list
+    \o In some cases, the contents of an entire page in a smaller
+     handset could form a component element of a layout in a
+     larger device. Therefore, consider making that a separate
+     component (i.e. defined in a separate QML file), and in the
+     smaller handset, the Page will simply contain an instance of
+     that component. On the larger device, there may be enough
+     space to show two separate items. For example, in an email
+     viewer, if the screen is large enough, it may be possible to
+     show the email list view, and the email reader view side by
+     side.
+    \o In some cases, the contents of a view might be quite similar
+     on all screen sizes, but with an expanded content area. In
+     this case, it may be possible to re-use the same layout
+     definition, if defined appropriately using anchors. 
+    \endlist
+
+    The Loader component can be used to load separate QML files based
+    on some criteria, such as Device Profile resolution. In the case
+    of form factor, this information will not change during the
+    application's lifetime, therefore there is no issue with memory
+    usage or performance.
+
+    \section1 Defining Measurements
+
+    When you are defining the measurements within an application or
+    component layout, there are a number aspects to consider:
+
+    \list
+    \o The layout structure, the high level relationship between
+     items. Which item is the parent? How are the items arranged
+     relatively on the screen? Are they in a grid or column?
+    \o The layout measurements. How big is an item, or a margin
+     inside the edge of an item, or an anchor between items?
+    \o The constraints imposed by the container. This might be
+     ApplicationWindow contents in the case of a Page, or it may
+     be some other container in the case of a Button.
+    \o The implicit size of contained items. Some child items will
+     require a certain amount of space, such as a button
+     containing a text. That may also depend on the current
+     platform and style. How do you ensure that you leave enough
+     space, and what happens if your children change size? 
+    \endlist
+
+    These aspects combine together to resolve the final layout for a
+    given Device Profile. However, although there are dependencies
+    between them, it is important to manage and control the different
+    aspects separately.
+
+    It is strongly recommended that Layout measurements should be
+    stored in a separate place from the component layout structure
+    definition files. The reason for this is that layout structure,
+    for a given form factor, can be re-used for different Device
+    Profiles. However, measurements will almost always vary between
+    Device Profiles or Device Categories.
+
+    If the opposite approach (complete duplication of entire QML
+    files) was taken, then all of the layout states and structure
+    definitions would be duplicated between the copied QML files, and
+    only the measurement values would change.
+
+    The main benefit of using separate measurement definition files
+    are:
+
+    \list
+    \o To reduce the amount of duplication, and hence increase
+      maintainability.
+    \o It becomes much easier to change the layout structure,
+     perhaps due to subsequent specification changes. In that
+     case, the layout structure can be modified once, and many or
+     all of the layout measurements would remain unchanged.
+    \o It becomes much easier to add support for additional Device
+     Profiles, simply by adding another measurement definition
+     file. 
+    \endlist
+
+    \section1 Using QML's Layout Features
+
+    For a given form factor, top level Layouts structure definitions,
+    or component layout structure definitions, should in general be
+    defined in a proportional way using a combination of
+
+    \list
+    \o \l{Item::}{anchors} within an Item
+    \o \l{Row} / \l{Column} / \l{Grid}
+    \o simple javascript expressions such as width: Math.round(parent.width / 3.0). 
+    \endlist
+
+    These basic building blocks, along with the powerful evaluation
+    capabilities of javascript expressions within every QML binding,
+    are designed to allow the majority of the layout structure
+    definition to be defined in a Device Profile independent way.
+
+    There are some limitations of the basic grid type layouts. They
+    are designed to accommodate a number of Items, but use the current
+    sizes of those items. There is a similar issue with the basic
+    anchor type layout. In particular, it can be difficult to spread a
+    number of child items proportionately across an area of their
+    container.
+
+    By combining the features of the layout managers with simple
+    javascript expressions, a richer variety of designs can be
+    expressed, without having to resort to additional layout
+    measurement parameters or measurement values.
+
+    Here are some things not to do with layouts:
+
+    \list
+    \o Don't define complex javascript functions that are regularly
+     evaluated. This will cause poor performance, particularly
+     during animated transitions.
+    \o Don't define all of your layouts using x, y, width and
+     height. Reserve this for items that cannot easily be defined
+     using anchors (anchors are evaluated in a more efficient
+     way).
+    \o Don't make assumptions about the container size, or about
+     the size of child items. Try to make flexible layout
+     definitions that can absorb changes in the available space. 
+    \endlist
+
+    \section1 Orientation Switches
+
+    Application top level page definitions, and reusable component
+    definitions, should use one QML layout definition for the layout
+    structure. This single definition should include the layout design
+    for separate Device Orientations and Aspect Ratios. The reason for
+    this is that performance during an orientation switch is critical,
+    and it is therefore a good idea to ensure that all of the
+    components needed by both orientations are loaded when the
+    orientation changes.
+
+    On the contrary, you should perform thorough tests if you choose
+    to use a Loader to load additional QML that is needed in separate
+    orientations, as this will affect the performance of the
+    orientation change.
+
+    In order to enable layout animations between the orientations, the
+    anchor definitions must reside within the same containing
+    component. Therefore the structure of an page or a component
+    should consist of a common set of child components, a common set
+    of anchor definitions, and a collection of states (defined in a
+    StateGroup) representing the different aspect ratios supported by
+    the component. (However note that orientation change animations
+    are not possible on Symbian due to compatibility support for S60
+    applications).
+
+    If a component, contained within a Page element, needs to be
+    hosted in numerous different form factor definitions, then the
+    layout states of the view should depend on the aspect ratio of the
+    page (its immediate container). Similarly, different instances of
+    a component might be situated within numerous different containers
+    in a UI, and so its layout states should be determined by the
+    aspect ratio of its parent. The conclusion is that layout states
+    should always follow the aspect ratio of the direct container (not
+    the "orientation" of the current device screen). The only
+    exception to this is of course the top level Window definition,
+    which is handled by the framework.
+
+    Within each layout State, you should define the relationships
+    between items using native QML layout definitions. See below for
+    more information. During transitions between the states (triggered
+    by the top level orientation change), in the case of anchor
+    layouts, AnchorAnimation elements can be used to control the
+    transitions. In some cases, you can also use a NumberAnimation on
+    e.g. the width of an item. Remember to avoid complex javascript
+    calculations during each frame of animation. Using simple anchor
+    definitions and anchor animations can help with this in the
+    majority of cases.
+
+    There are a few additional cases to consider:
+
+    \list
+    \o What if you have a single page that looks completely
+     different between landscape and portrait, i.e. all of the
+     child items are different? For each Page, have two child
+     components, with separate layout definitions, and make one
+     or other of the items have zero opacity in each state. You
+     can use a cross-fade animation by simply applying a
+     NumberAnimation transition to the opacity.
+    \o What if you have a single page that shares 30% or more of
+     the same layout contents between portrait and landscape? In
+     that case, consider having one component with landscape and
+     portrait states, and a collection of separate child items
+     whose opacity (or position) depends on the orientation
+     state. This will enable you to use layout animations for the
+     items that are shared between the orientations, whilst the
+     other items are either faded in/out, or animated on/off
+     screen.
+    \o What if you have two pages on a handheld device that need to
+     be on screen at the same time, for example on a larger form
+     factor device? In this case, notice that your view component
+     will no longer be occupying the full screen. Therefore it's
+     important to remember in all components (in particular, list
+     delegate items) should depend on the size of the containing
+     component width, not on the screen width. It may be
+     necessary to set the width in a Component.onCompleted()
+     handler in this case, to ensure that the list item delegate
+     has been constructed before the value is set.
+    \o What if the two orientations take up too much memory to have
+     them both in memory at once? Use a Loader if necessary, if
+     you cannot keep both versions of the view in memory at once,
+     but beware performance on the cross-fade animation during
+     layout switch. One solution could be to have two "splash
+     screen" items that are children of the Page, then you cross
+     fade between those during rotation. Then you can use a
+     Loader to load another child component that loads the actual
+     model data to another child Item, and cross-fade to that
+     when the Loader has completed. 
+    \endlist
+   */
+
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index f071845..283b403 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -91,7 +91,7 @@
         file reader providing the complete Qt documentation offline.
     \endlist
 
-    \section2 Cross-platform development using Qt Creator
+    \section2 Cross-Platform Development using Qt Creator
 
     \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
     a complete Cross-platform IDE included in the Qt SDK. The IDE allows
@@ -159,7 +159,7 @@
         and KDevelop IDEs are also available.
     \endlist
 
-    \section2 Cross-platform development using Qt Creator
+    \section2 Cross-Platform Development using Qt Creator
 
     \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
     a complete Cross-platform IDE included in the Qt SDK. The IDE allows
@@ -244,7 +244,7 @@
         file reader providing the complete Qt documentation offline.
     \endlist
 
-    \section2 Cross-platform development using Qt Creator
+    \section2 Cross-Platform Development using Qt Creator
 
     \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
     a complete Cross-platform IDE included in the Qt SDK. The IDE allows
@@ -303,7 +303,7 @@
     hardware dependencies, Qt is easy to build even for custom hardware
     configurations. Unused components and features can even be compiled out.
 
-     \section1 Getting Started on Windows CE/Mobile
+    \section1 Getting Started on Windows CE/Mobile
 
     \list
         \o \l{Supported Platforms}{Supported Windows CE/Mobile platforms}
@@ -495,15 +495,13 @@
     support for swiching between landscape and portrait mode, different
     screen resolutions as well as touch screen and key pad input.
 
-    \section2 Cross-platform development using Qt Creator
+    \section2 Cross-Platform Development using Qt Creator
 
     \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
     a complete Cross-platform IDE included in the Qt SDK. The IDE allows
     programmers to create, build, debug and run Qt applications accross all
     supported platforms.
 
-\omit
-
     \section3 Licensing
 
     Qt for Symbian is available under the Qt Commercial License, the LGPL
@@ -516,46 +514,44 @@
     communication and data exchange. Therefore, most Symbian developers
     can use Qt for Symbian under the LGPL.
 
-\endomit
-
     Additional \l{Cross-Platform and Platform-Specific Development}
     information.
 
 */
 /*!
-\omit
     \page maemo-support.html
-    \title Support for Maemo/MeeGo
-    \brief Platform support for Maemo/MeeGo.
+    \title Support for Maemo
+    \brief Platform support for Maemo.
     \ingroup platform-specific
     \ingroup platform-details
 
-    \section1 Qt on Maemo/MeeGo
+    \section2 Qt on Maemo
 
     Qt is a comprehensive application and UI framework for developing
-    Maemo and MeeGo applications that can also be deployed across major
+    Maemo applications that can also be deployed across major
     device and desktop operating systems without rewriting the source code.
-    If you are developing apps for the Symbian, Mameo or MeeGo platforms
+    If you are developing apps for the Symbian, Mameo platforms
     in most cases, you can use Qt under the free LGPL licensing option.
     Qt is cross-platform, and that means that you can use the code from
     one single code-base and rebuild for all \l{Supported Platforms}
-    {supported platforms}.
-
-     \section1 Getting Started on Maemo/MeeGo
+    {supported platforms}. Maemo 6 is now MeeGo.
 
+    \section1 Getting Started on Maemo
     \list
-        \o \l{Supported Platforms}{Supported Maemo/MeeGo platforms}
-        - Qt support for Maemo/MeeGo versions.
-        \o \l{Qt for Maemo Requirements}{Qt for Maemo/MeeGo
-        Requirements} - Software required to run Qt on Maemo/MeeGo.
+        \o \l{Supported Platforms}{Supported Maemo platforms}
+        - Qt support for Maemo versions.
+        \omit
+        \o \l{Qt for Maemo Requirements}{Qt for Maemo
+        Requirements} - Software required to run Qt on Maemo.
         \o \l{Installing Qt for Maemo}{Installing Qt for
-        Maemo/MeeGo} - Build Qt for Maemo/MeeGo    development.
+        Maemo} - Build Qt for Maemo	development.
         \o \l{Platform and Compiler Notes - Maemo}{Platform and
-        Compiler Notes - Maemo/MeeGo} - Platform specific notes.
+        Compiler Notes - Maemo} - Platform specific notes.
+        \endomit
         \o \l{Getting Started Guides}{Getting started}
     \endlist
 
-    \section1 Key Features for Maemo/MeeGo Development
+    \section1 Key Features for Maemo Development
 
     \section2 Native Look and Feel
 
@@ -565,16 +561,16 @@
 
     \section2 Graphics Features
 
-    Qt for Maemo/MeeGo provides a powerful paint engine that cotain
+    Qt for Maemo provides a powerful paint engine that cotain
     features such as anti aliasing, gradients, curves and transparency.
     It also has animation support with timelines and easing curves. Qt
-    for Maemo/MeeGo also supports hardware acceleration using ARM NEON
+    for Maemo also supports hardware acceleration using ARM NEON
     and OpenGL ES 2.0.
 
     \section2 Device Configurations
 
-    Applications developed with Qt for Maemo/MeeGo will across all
-    supported Maemo/MeeGo devices provide automatic support for switching
+    Applications developed with Qt for Maemo will across all
+    supported Maemo devices provide automatic support for switching
     between landscape and portrait mode. They will support input methods,
     including predictive text input and on-screen keyboard. The
     applications will also have support for one finger touch events and
@@ -586,7 +582,7 @@
     AIX, HP-UX, Maemo 5 and MeeGo. Qt for Maemo contains all Qt modules
     and features the same functionality as the Qt on X11 version.
 
-    \section2 Cross-platform development using Qt Creator
+    \section2 Cross-Platform Development using Qt Creator
 
     \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
     a complete Cross-platform IDE included in the Qt SDK. The IDE allows
@@ -595,8 +591,85 @@
 
     Additional \l{Cross-Platform and Platform-Specific Development}
     information.
+*/
+
+/*!
+
+    \page meego-support.html
+    \title Support for MeeGo
+    \brief Platform support for MeeGo.
+    \ingroup platform-specific
+    \ingroup platform-details
+
+    \section2 Qt on MeeGo
+
+    Qt is a comprehensive application and UI framework for developing
+    MeeGo applications that can also be deployed across major
+    device and desktop operating systems without rewriting the source code.
+    If you are developing apps for the Symbian, MeeGo platforms
+    in most cases, you can use Qt under the free LGPL licensing option.
+    Qt is cross-platform, and that means that you can use the code from
+    one single code-base and rebuild for all \l{Supported Platforms}
+    {supported platforms}.
+
+    \section1 Getting Started on MeeGo
+
+    \list
+        \o \l{Supported Platforms}{Supported MeeGo platforms}
+        - Qt support for MeeGo versions.
+        \omit
+        \o \l{Qt for MeeGo Requirements}{Qt for MeeGo
+        Requirements} - Software required to run Qt on MeeGo.
+        \o \l{Installing Qt for MeeGo}{Installing Qt for
+        MeeGo} - Build Qt for MeeGo	development.
+        \o \l{Platform and Compiler Notes - MeeGo}{Platform and
+        Compiler Notes - MeeGo} - Platform specific notes.
+        \endomit
+        \o \l{Getting Started Guides}{Getting started}
+    \endlist
+
+    \section1 Key Features for MeeGo Development
+
+    \section2 Native Look and Feel
+
+    Qt will detect which theme the device is running and applies the
+    style at runtime to your Qt application. Widgets are optimized
+    for touch screen usage.
+
+    \section2 Graphics Features
+
+    Qt for MeeGo provides a powerful paint engine that cotain
+    features such as anti aliasing, gradients, curves and transparency.
+    It also has animation support with timelines and easing curves. Qt
+    for MeeGo also supports hardware acceleration using ARM NEON, x86,
+    and OpenGL ES 2.0.
+
+    \section2 Device Configurations
+
+    Qt is the foundation of MeeGo UI and application development and
+    therefore Qt will be present in all upcoming MeeGo devices. Qt
+    can provide automatic support for:
+    \list
+    \o Switching between landscape and portrait mode
+    \o Input Methods, including predictive text input and on-screen
+    keyboard
+    \o Configurable kinetic scrolling
+
+    \section2 Maemo - Linux/X11
+
+    Qt supports a wide range of X11 platform variants, such as: Solaris,
+    AIX, HP-UX, Maemo 5 and MeeGo. Qt for MeeGo contains all Qt modules
+    and features the same functionality as the Qt on X11 version.
+
+    \section2 Cross-Platform Development using Qt Creator
+
+    \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is
+    a complete Cross-platform IDE included in the Qt SDK. The IDE allows
+    programmers to create, build, debug and run Qt applications accross all
+    supported platforms.
 
-    \endomit
+    Additional \l{Cross-Platform and Platform-Specific Development}
+    information.
 */
 
 /*!
@@ -614,25 +687,24 @@
     \section1 Qt is available for the following platforms:
 
     \table
-        \header
-        \o {2,1} Qt Cross Platform Support
-        \header
-        \o {1,1} Desktop
-        \o {1,1} Mobile/Embedded
-        \row
-        \o \l{Support for Windows}{Windows}
-        \o \l{Support for Windows CE and Windows Mobile.}{Windows CE and Windows Mobile.}
-        \row
-        \o \l{Support for Linux/X11}{Linux/X11}
-        \o \l{Support for Embedded Linux}{Embedded Linux}
-        \row
-        \o \l{Support for Mac}{Mac OS X}
-        \o \l{Support for Symbian}{Symbian}
-        \row
-        \o
-        \omit
-        \o\l{Support for Maemo/MeeGo}{Maemo/MeeGo}
-        \endomit
+    \header
+    \o {2,1} Qt Cross Platform Support
+    \header
+    \o {1,1} Desktop
+    \o {1,1} Mobile/Embedded
+    \row
+    \o \l{Support for Windows}{Windows}
+    \o \l{Support for Windows CE and Windows Mobile}{Windows CE and Windows Mobile}
+    \row
+    \o \l{Support for Linux/X11}{Linux/X11}
+    \o \l{Support for Embedded Linux}{Embedded Linux}
+    \row
+    \o \l{Support for Mac OS X}{Mac OS X}
+    \o \l{Support for Symbian}{Symbian}
+    \row
+    \o
+    \o\l{Support for MeeGo}{MeeGo}
+    \o\l{Support for Maemo}{Maemo}
     \endtable
 
     \section1 Supported platform details
@@ -684,6 +756,10 @@
                                      \o gcc (\l{http://www.codesourcery.com/}{Codesourcery version)}
     \row    \o Windows CE 5.0 (ARMv4i, x86, MIPS)
                                      \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii)
+    \row    \o Maemo 5(Linux, ARM, X11)
+                                     \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)}
+    \row    \o MeeGo (Linux, ARM, X11)
+                                     \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)}
     \row    \o Symbian (Symbian/S60 5.0)
                                      \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications)
     \endtable
@@ -722,8 +798,6 @@
                                      \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii)
     \row    \o Windows Embedded CE 6.0 (ARMv4i, x86, MIPS)
                                      \o MSVC 2008 WinCE Embedded 6.0 Professional
-    \row    \o Maemo 5(Linux, ARM, X11)
-                                     \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)}
     \row    \o Symbian (Symbian/S60 3.1, 3.2)
                                      \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications)
     \endtable