/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \title Scalability
    \page scalability.html
    \brief How to develop applications that scale well on devices with different
    screen configurations and UI conventions.

    \ingroup best-practices

    When you develop applications for several different mobile device platforms,
    you face the following challenges:

    \list
        \li Mobile device platforms support devices with varying screen
            configurations: size, aspect ratio, orientation, and density.
        \li Different platforms have different UI conventions and you need to
            meet the users' expectations on each platform.
    \endlist

    Qt Quick enables you to develop applications that can run on different types
    of devices, such as tablets and handsets. In particular, they can cope
    with different screen configurations. However, there is always a certain
    amount of fixing and polishing needed to create an optimal user experience
    for each target platform.

    You need to consider scalability when:

    \list
        \li You want to deploy your application to more than one device
            platform, such as Android and iOS, or more than one
            device screen configuration.
        \li Your want to be prepared for new devices that might appear on the
            market after your initial deployment.
    \endlist

    To implement scalable applications using \l{Qt Quick}:

    \list
        \li Design UIs using \e {Qt Quick Controls} that provide sets of UI controls.
        \li Define layouts using \e {Qt Quick Layouts}, which can resize their
            items.
        \li Use \e {property binding} to implement use cases
            not covered by the layouts. For example, to display alternative
            versions of images on screens with low and high pixel density or
            automatically adapt view contents according to the current screen
            orientation.
        \li Select a reference device and calculate a \e {scaling ratio} for
            adjusting image and font sizes and margins to the actual screen
            size.
        \li Load platform-specific assets using \e {file selectors}.
        \li Load components on demand by using a \e {Loader}.
    \endlist

    Consider the following patterns when designing your application:

    \list
    \li The contents of a view might be quite similar on all
        screen sizes, but with an expanded content area. If you use the
        ApplicationWindow QML type from Qt Quick Controls, it will
        automatically calculate the window size based on the sizes of its
        content items. If you use Qt Quick Layouts to position the content
        items, they will automatically resize the items pushed to them.
    \li The contents of an entire page in a smaller
        device could form a component element of a layout in a
        larger device. Therefore, consider making that a separate
        component (that is, defined in a separate QML file), and in the
        smaller device, the view will simply contain an instance of
        that component. On the larger device, there may be enough
        space to use loaders to show additional 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.
    \li For games, you would typically want to create a game board that does not
        scale, so as not to provide an unfair advantage to players on larger
        screens. One solution is to define a \e {safe zone} that fits the screen
        with the smallest supported aspect ratio (usually, 3:2), and add
        decorative-only content in the space that will be hidden on a 4:3 or
        16:9 screen.
    \endlist

    \section1 Resizing Application Windows Dynamically

    \l{Qt Quick Controls} provide a set of UI controls to create user interfaces
    in Qt Quick. Typically, you declare an ApplicationWindow control as the root
    item of your application. The ApplicationWindow adds convenience for
    positioning other controls, such as MenuBar, ToolBar, and StatusBar in a
    platform independent manner. The ApplicationWindow uses the size constraints
    of the content items as input when calculating the effective size
    constraints of the actual window.

    In addition to controls that define standard parts of application windows,
    controls are provided for creating views and menus, as well as presenting or
    receiving input from users. You can use \l{Qt Quick Controls 1 Styles} to
    apply custom styling to the predefined controls. For examples of using the
    styles, see \l{Qt Quick Controls 1 - Touch Gallery}.

    Qt Quick Controls, such as the ToolBar, do not provide a layout
    of their own, but require you to position their contents. For this, you can
    use Qt Quick Layouts.

    \section1 Laying Out Screen Controls Dynamically

    \l{Qt Quick Layouts} provide ways of laying out screen controls in a row,
    column, or grid, using the RowLayout, ColumnLayout, and GridLayout QML
    types. The properties for these QML types hold their layout direction and
    spacing between the cells.

    You can use the \l{Layout} QML type to attach additional properties to the
    items pushed to the layouts. For example, you can specify mininum, maximum,
    and preferred values for item height, width, and size.

    The layouts ensure that your UIs are scaled properly when windows and
    screens are resized and always use the maximum amount of space available.

    A specific use case for the GridLayout type is to use it as a row or a
    column depending on the screen orientation.

    \image scalability-gridlayout.png

    The following code snippet uses
    the \c flow property to set the flow of the grid from left to right (as a
    row) when the screen width is greater than the screen height and from top to
    bottom (as a column) otherwise:

    \code
    ApplicationWindow {
        id: root
        visible: true
        width: 480
        height: 620

        GridLayout {
            anchors.fill: parent
            anchors.margins: 20
            rowSpacing: 20
            columnSpacing: 20
            flow:  width > height ? GridLayout.LeftToRight : GridLayout.TopToBottom
            Rectangle {
                Layout.fillWidth: true
                Layout.fillHeight: true
                color: "#5d5b59"
                Label {
                    anchors.centerIn: parent
                    text: "Top or left"
                    color: "white"
                }
            }
            Rectangle {
                Layout.fillWidth: true
                Layout.fillHeight: true
                color: "#1e1b18"
                Label {
                    anchors.centerIn: parent
                    text: "Bottom or right"
                    color: "white"
                }
            }
        }
    }
    \endcode

    Constantly resizing and recalculating screens comes with a performance cost.
    Mobile and embedded devices might not have the power required to recalculate
    the size and position of animated objects for every frame, for example. If
    you run into performance problems when using layouts, consider using some
    other methods, such as bindings, instead.

    Here are some things not to do with layouts:

    \list

    \li Do not have bindings to the x, y, width, or height properties of items
        in a Layout, since this would conflict with the goal of the Layout, and
        also cause binding loops.
    \li Do not define complex JavaScript functions that are regularly
        evaluated. This will cause poor performance, particularly
        during animated transitions.
    \li Do not 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.
    \li Do not use layouts if you want the design to be pixel perfect. Content
        items will be automatically resized and positioned depending on the
        space available.
    \endlist

    \section1 Using Bindings

    If Qt Quick Layouts do not fit your needs, you can fall back to using
    \l{Property Binding}{property binding}. Binding enables objects to
    automatically update their properties in response to changing attributes in
    other objects or the occurrence of some external event.

    When an object's property is assigned a value, it can either be assigned a
    static value, or bound to a JavaScript expression. In the former case, the
    property's value will not change unless a new value is assigned to the
    property. In the latter case, a property binding is created and the
    property's value is automatically updated by the QML engine whenever the
    value of the evaluated expression changes.

    This type of positioning is the most highly dynamic. However, constantly
    evaluating JavaScript expressions comes with a performance cost.

    You can use bindings to handle low and high pixel density on platforms that
    do not have automatic support for it (like \macos and iOS do).
    The following code snippet uses the \l{Screen}{Screen.PixelDensity}
    attached property to specify different images to display on screens with
    low, high, or normal pixel density:

    \code
    Image {
        source: {
            if (Screen.PixelDensity < 40)
            "image_low_dpi.png"
            else if (Screen.PixelDensity > 300)
            "image_high_dpi.png"
            else
            "image.png"
            }
        }
    \endcode

    On \macos and iOS, you can provide alternative resources with double the size
    and the \e @2x identifier for icons and images and place them in the
    resource file. On Retina displays, the @2x versions are used automatically.

    For example, the following code snippet will try to load \e artwork@2x.png
    on Retina displays:

    \code
    Image {
        source: "artwork.png"
    }
    \endcode

    \section1 Handling Pixel Density

    Some QML types, such as \l Image, BorderImage, and \l Text, are
    automatically scaled according to the properties specified for them.
    If the width and height of an Image are not specified, it automatically uses
    the size of the source image, specified using the \c source property. By
    default, specifying the width and height causes the image to be scaled to
    that size. This behavior can be changed by setting the \c fillMode property,
    allowing the image to be stretched and tiled instead. However, the original
    image size might appear too small on high DPI displays.

    A BorderImage is used to create borders out of images by scaling or tiling
    parts of each image. It breaks a source image into 9 regions that are scaled
    or tiled according to property values. However, the corners are not scaled
    at all, which can make the results less than optimal on high DPI displays.

    A \l Text QML type attempts to determine how much room is needed and set the
    \c width and \c height properties accordingly, unless they are explicitly
    set. The \c fontPointSize property sets the point size in a
    device-independent manner. However, specifying fonts in points and other
    sizes in pixels causes problems, because points are independent of the
    display density. A frame around a string that looks correct on low DPI
    displays is likely to become too small on high DPI displays, causing the
    text to be clipped.

    The level of high DPI support and the techniques used by the supported
    platforms varies from platform to platform. The following sections describe
    different approaches to scaling screen contents on high DPI displays.

    For more information about high DPI support in Qt and the supported
    platforms, see \l{High DPI Displays}.

    \section2 High DPI Scaling on \macos and iOS

    On \macos and iOS, applications use high DPI scaling that is an alternative to
    the traditional DPI scaling. In the traditional approach, the application is
    presented with an DPI value used to multiply font sizes, layouts, and so on.
    In the new approach, the operating system provides Qt with a scaling ratio
    that is used to scale graphics output: allocate larger buffers and set a
    scaling transform.

    The advantage of this approach is that that vector graphics and fonts scale
    automatically and existing applications tend to work unmodified. For raster
    content, high-resolution alternative resources are needed, however.

    Scaling is implemented for the QtQuick and QtWidgets stacks, as well as
    general support in QtGui and the Cocoa platform plugin.

    The OS scales window, event, and desktop geometry. The Cocoa platform plugin
    sets the scaling ratio as QWindow::devicePixelRatio() or
    QScreen::devicePixelRatio(), as well as on the backing store.

    For QtWidgets, QPainter picks up \c devicePixelRatio() from the backing
    store and interprets it as a scaling ratio.

    However, in OpenGL pixels are always device pixels. For example, geometry
    passed to glViewport() needs to be scaled by devicePixelRatio().

    The specified font sizes (in points or pixels) do not change and strings
    retain their relative size compared to the rest of the UI. Fonts are
    scaled as a part of painting, so that a size 12 font effectively becomes a
    size 24 font with 2x scaling, regardless of whether it is specified in
    points or in pixels. The \e px unit is interpreted as device independent
    pixels to ensure that fonts do not appear smaller on a high DPI display.

    \section2 Calculating Scaling Ratio

    You can select one high DPI device as a reference device and calculate
    a scaling ratio for adjusting image and font sizes and margins to the actual
    screen size.

    The following code snippet uses reference values for DPI, height, and
    width from the Nexus 5 Android device, the actual screen size returned by
    the QRect class, and the logical DPI value of the screen returned by the
    \c qApp global pointer to calculate a scaling ratio for image sizes and
    margins (\c m_ratio) and another for font sizes (\c m_ratioFont):

    \code
    qreal refDpi = 216.;
    qreal refHeight = 1776.;
    qreal refWidth = 1080.;
    QRect rect = QGuiApplication::primaryScreen()->geometry();
    qreal height = qMax(rect.width(), rect.height());
    qreal width = qMin(rect.width(), rect.height());
    qreal dpi = QGuiApplication::primaryScreen()->logicalDotsPerInch();
    m_ratio = qMin(height/refHeight, width/refWidth);
    m_ratioFont = qMin(height*refDpi/(dpi*refHeight), width*refDpi/(dpi*refWidth));
    \endcode

    For a reasonable scaling ratio, the height and width values must be set
    according to the default orientation of the reference device, which in this
    case is the portrait orientation.

    The following code snippet sets the font scaling ratio to \c 1 if it would
    be less than one and thus cause the font sizes to become too small:

    \code
    int tempTimeColumnWidth = 600;
    int tempTrackHeaderWidth = 270;
    if (m_ratioFont < 1.) {
        m_ratioFont = 1;
    \endcode

    You should experiment with the target devices to find edge cases that
    require additional calculations. Some screens might just be too short or
    narrow to fit all the planned content and thus require their own layout. For
    example, you might need to hide or replace some content on screens with
    atypical aspect ratios, such as 1:1.

    The scaling ratio can be applied to all sizes in a QQmlPropertyMap to
    scale images, fonts, and margins:

    \code
    m_sizes = new QQmlPropertyMap(this);
    m_sizes->insert(QLatin1String("trackHeaderHeight"), QVariant(applyRatio(270)));
    m_sizes->insert(QLatin1String("trackHeaderWidth"), QVariant(applyRatio(tempTrackHeaderWidth)));
    m_sizes->insert(QLatin1String("timeColumnWidth"), QVariant(applyRatio(tempTimeColumnWidth)));
    m_sizes->insert(QLatin1String("conferenceHeaderHeight"), QVariant(applyRatio(158)));
    m_sizes->insert(QLatin1String("dayWidth"), QVariant(applyRatio(150)));
    m_sizes->insert(QLatin1String("favoriteImageHeight"), QVariant(applyRatio(76)));
    m_sizes->insert(QLatin1String("favoriteImageWidth"), QVariant(applyRatio(80)));
    m_sizes->insert(QLatin1String("titleHeight"), QVariant(applyRatio(60)));
    m_sizes->insert(QLatin1String("backHeight"), QVariant(applyRatio(74)));
    m_sizes->insert(QLatin1String("backWidth"), QVariant(applyRatio(42)));
    m_sizes->insert(QLatin1String("logoHeight"), QVariant(applyRatio(100)));
    m_sizes->insert(QLatin1String("logoWidth"), QVariant(applyRatio(286)));

    m_fonts = new QQmlPropertyMap(this);
    m_fonts->insert(QLatin1String("six_pt"), QVariant(applyFontRatio(9)));
    m_fonts->insert(QLatin1String("seven_pt"), QVariant(applyFontRatio(10)));
    m_fonts->insert(QLatin1String("eight_pt"), QVariant(applyFontRatio(12)));
    m_fonts->insert(QLatin1String("ten_pt"), QVariant(applyFontRatio(14)));
    m_fonts->insert(QLatin1String("twelve_pt"), QVariant(applyFontRatio(16)));

    m_margins = new QQmlPropertyMap(this);
    m_margins->insert(QLatin1String("five"), QVariant(applyRatio(5)));
    m_margins->insert(QLatin1String("seven"), QVariant(applyRatio(7)));
    m_margins->insert(QLatin1String("ten"), QVariant(applyRatio(10)));
    m_margins->insert(QLatin1String("fifteen"), QVariant(applyRatio(15)));
    m_margins->insert(QLatin1String("twenty"), QVariant(applyRatio(20)));
    m_margins->insert(QLatin1String("thirty"), QVariant(applyRatio(30)));
    \endcode

    The functions in the following code snippet apply the scaling ratio to
    fonts, images, and margins:

    \code
    int Theme::applyFontRatio(const int value)
    {
        return int(value * m_ratioFont);
    }

    int Theme::applyRatio(const int value)
    {
        return qMax(2, int(value * m_ratio));
    }
    \endcode

    This technique gives you reasonable results when the screen sizes of the
    target devices do not differ too much. If the differences are huge, consider
    creating several different layouts with different reference values.

    \section1 Loading Files Depending on Platform

    You can use the QQmlFileSelector to apply a QFileSelector to QML file
    loading. This enables you to load altenative resources depending on the
    platform on which the application is run. For example, you can use the
    \c +android file selector to load different image files
    when run on Android devices.

    You can use file selectors together with singleton objects to access a
    single instance of an object on a particular platform.

    File selectors are static and enforce a file structure where
    platform-specific files are stored in subfolders named after the platform.
    If you need a more dynamic solution for loading parts of your UI on demand,
    you can use a Loader.

    The target platforms might automate the loading of alternative resources for
    different display densities in various ways. On iOS, the \e @2x filename
    suffix is used to indicate high DPI versions of images. The \l Image QML
    type and the QIcon class automatically load @2x versions of images and icons
    if they are provided. The QImage and QPixmap classes automatically set the
    \c devicePixelRatio of @2x versions of images to \c 2, but you need to add
    code to actually use the @2x versions:

    \code
    if ( QGuiApplication::primaryScreen()->devicePixelRatio() >= 2 ) {
        imageVariant = "@2x";
    } else {
        imageVariant = "";
    }
    \endcode

    Android defines generalized screen sizes (small, normal, large, xlarge) and
    densities (ldpi, mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi) for
    which you can create alternative resources. Android detects the current
    device configuration at runtime and loads the appropriate resources for your
    application. However, beginning with Android 3.2 (API level 13), these size
    groups are deprecated in favor of a new technique for managing screen sizes
    based on the available screen width.

    \section1 Loading Components on Demand

    A \l{Loader} can load a QML file (using the \c source property) or a Component
    object (using the \c sourceComponent property). It is useful for delaying the
    creation of a component until it is required. For example, when a component
    should be created on demand, or when a component should not be created
    unnecessarily for performance reasons.

    You can also use loaders to react to situations where parts of your UI are
    not needed on a particular platform, because the platform does not support
    some functionality. Instead of displaying a view that is not needed
    on the device the application is running on, you can determine that the
    view is hidden and use loaders to display something else in its place.

    \section1 Switching Orientation

    The \l{Screen}{Screen.orientation} attached property contains the current
    orientation of the screen, from the accelerometer (if available). On a
    desktop computer, this value typically does not change.

    If \c primaryOrientation follows \c orientation, it means that the screen
    automatically rotates all content that is displayed, depending on how you
    hold the device. If orientation changes even though \c primaryOrientation
    does not change, the device might not rotate its own display. In that case,
    you may need to use \l{QtQuick::Item::rotation}{Item.rotation} or
    \l{QtQuick::Item::transform}{Item.transform} to rotate your content.

    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 \l{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 a 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.

    If a component contained within a page 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).

    Within each layout \l{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
    \li What if you have a single page that looks completely
     different between landscape and portrait, that is, 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.
    \li 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.
    \li 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.
    \li What if the two orientations take up too much memory to have
     them both in memory at once? Use a \l{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
     \l{Loader} to load another child component that loads the actual
     model data to another child Item, and cross-fade to that
     when the \l{Loader} has completed.
    \endlist
   */