/****************************************************************************
**
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage quick-projects.html
    \page creator-using-qt-quick-designer.html
    \nextpage quick-components.html

    \title Using Qt Quick Designer

    You can edit .qml files in the \QMLD visual editor or in the code editor.

    \note In \QC 2.7, \QMLD supports both Qt Quick 1 and Qt Quick 2. However,
    the \QC packages that are not delivered with Qt 5 are still built with
    Qt 4.8, and therefore do not contain qml2puppet, which is the external
    process that is responsible for rendering Qt Quick 2. To develop Qt Quick 2
    applications using \QMLD, download the Qt 5.0.1 packages and build
    qml2puppet yourself. The sources for qml2puppet are located in
    \c{qt-creator\share\qtcreator\qml\qmlpuppet\qml2puppet}. The qml2puppet is
    installed to \c{qtbase\bin}. If you then configure Qt 5.0.1 for your
    project, \QMLD picks up the qml2puppet and supports Qt Quick 2.0.

    In \gui Projects, double-click a .qml file to open it in the code editor.
    Then select the \gui {Design} mode to edit the file in the visual editor.

    \image qmldesigner-visual-editor.png "Visual editor"

    Use the visual editor panes to manage your project:

    \list

        \li \gui {Navigator} pane (1) displays the items in the current QML
            file as tree structure.

        \li \gui {Library} pane (2) displays the building blocks that you can use to
            design applications: predefined QML types, your own QML
            components, Qt Quick components or Qt Quick Controls that you import
            to the project, and
            other resources.

        \li \gui Canvas (3) is the working area where you create QML components and
            design applications.

        \li \gui {Properties} pane (4) organizes the properties of the selected item.
            You can change the properties also in the code editor.

        \li \gui {State} pane (5) displays the different states of the item.
            QML states typically describe user interface configurations, such as
            the UI controls, their properties and behavior and the available
            actions.

    \endlist

    \section1 Managing Item Hierarchy

    The \gui Navigator pane displays the items in the current QML file and their relationships.
    Items (1) are listed in a tree structure, below their parent (2).

    \image qmldesigner-navigator.png "Navigator pane"

    You can select items in the \gui Navigator to edit their properties
    in the \gui Properties pane. Items can access the properties of their
    parent item. To select items on the canvas, right-click an item,
    and select another type in the context menu.

    Typically, child items are located within the parent item on the
    canvas. However, they do not necessarily have to fit inside the parent
    item. For example, you might want to make a mouse area larger than the
    rectangle or image beneath it (1).

    \image qmldesigner-element-size.png "Mouse area for a button"

    When you copy an item, all its child items are also copied. When
    you remove an item, the child items are also removed.

    You can show and hide items to focus on specific parts of the application.
    Click the
    \inlineimage qmldesigner-show-hide-icon.png
    icon to change the visibility of an item on the canvas. To change the
    visibility of an item in the application, use the \gui Visibility
    check box or the \gui Opacity field in the \gui Properties pane. If you set
    \gui Opacity to 0, items are hidden, but you can still apply animation
    to them.

    As all properties, visibility and opacity are inherited from the parent
    item. To hide or show child items, edit the properties of the parent item.

    To view lists of files or projects, instead, select \gui {File System},
    \gui {Open Documents}, or \gui Projects in the menu.
    To view several types of content at a time, split the sidebar by clicking
    \inlineimage qtcreator-splitbar.png
    .

    \section2 Setting the Stacking Order

    The \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-item.html#z-prop}{z property} of an
    item determines its position in relation to its sibling items in the
    type hierarchy. By default, items with a higher stacking value are
    drawn on top of siblings with a lower stacking value. Items with the same
    stacking value are drawn in the order they are listed, from the last item
    up.

    To change the stacking order of an item, right-click it on the canvas and
    select \gui {Stack (z)}. You can raise or lower the stack value of an item
    or move the item to the front or back of all its siblings. To remove the
    \c z property, select \gui {Reset z Property}.

    \section2 Switching Parent Items

    When you drag and drop instances of QML types to the canvas, Qt Quick Designer
    adds the new item as a child of the item beneath it.
    When you move items on the canvas, Qt Quick Designer cannot determine
    whether you want to adjust their position or attach them to a new
    parent item. Therefore, the parent item is not automatically
    changed. To change the parent of the item, press down the \key Shift
    key before you drag and drop the item into a new position. The topmost
    item under the cursor becomes the new parent of the item.

    You can change the parent of an item also in the \gui Navigator pane.
    Drag and drop the item to another position in the tree or use the arrow
    buttons (1) to move the item in the tree.

    \image qmldesigner-navigator-arrows.png "Navigator arrow buttons"

    \section1 QML Type Library

    The \gui {Library} pane contains two tabs: \gui {QML Types} and \gui {Resources}.
    The \gui {QML Types} pane displays the QML types grouped by category: your own QML
    components, basic types, positioner types, and views.

    Sets of UI components with the look and feel of a particular mobile device
    platform have been defined for Qt Quick 1. Since Qt 5.1, a set of Qt Quick
    Controls is available for creating classic desktop-style user interfaces
    using Qt Quick 2.1. The Qt Quick Components and Controls are based on
    standard QML types. To view the components and controls in the
    \gui {Library} pane, add import
    statements to the .pro file of your project. For example:

    \list

        \li \c {import com.nokia.meego 1.0} for MeeGo
        \li \c {import QtQuick.Controls 1.0} for Qt Quick Controls

    \endlist

    The \gui {Qt Quick Application} wizards for a particular platform, such as
    MeeGo Harmattan, and the \gui {Qt Quick 2 UI with Controls} wizard add the
    import statements automatically.

    \image qmldesigner-qml-components.png "QML Components pane"

    The \gui {Resources} pane displays the images and other files that you copy
    to the project folder (to the same subfolder as the QML files).

    \section1 Specifying Item Properties

    The \gui Properties pane displays all the properties of the selected item.
    The properties are grouped by type. The top part of the pane
    displays properties that are common to all QML types, such as
    position, size, and visibility.

    The bottom part of the pane displays properties that are specific to each
    QML type. For example, the following image displays the properties you
    can set for \gui Rectangle (1) and \gui Text (2) items.

    \image qmldesigner-element-properties.png

    You can use a context-menu to reset some item properties. To reset the
    position or size property of an item, right-click the item and select
    \gui {Edit > Reset Position} or \gui {Reset Size} in the context menu. To
    set the visibility of the item, select \gui {Edit > Visibility}.

    For more information on the properties available for an item, press
    \key {F1}.

    \section2 Viewing Changes in Properties

    The default values of properties are displayed in white color, while the
    values that you specify explicitly are highlighted with blue color. In
    addition, property changes in states are highlighted with blue.

    This allows you to easily see which values are set in the .qml file and
    which values are default characteristics of a QML type or a component.

    When editing states, you can easily see which values are explicitly set in
    the current state and which values are derived from the base state.

    The following images illustrate this. In the base state, the \gui Size (1)
    and \gui Colors (2) values are explicitly set and highlighted.

    \image qmldesigner-properties-explicit-base.png "Explicitly set properties"

    In \gui State1, only the color (1) is explicitly set and highlighted.

    \image qmldesigner-properties-explicit-state1.png "Explicitly set properties"

    Resetting a property sets it back to the default value and removes the value
    from the .qml file.

    \note As a result, all boolean values can be visualized in four different
    ways.

    For example, visibility can be visualized as follows:

    \table
        \row
            \li \image qmldesigner-boolean-true.png
            \li TRUE
            \li The QML type is visible by default. The visibility might be
                overridden by the visibility set in the base state.
        \row
            \li \image qmldesigner-boolean-true-blue.png
            \li TRUE (highlighted)
            \li The QML type is explicitly set to visible.
        \row
            \li \image qmldesigner-boolean-false.png
            \li FALSE
            \li The QML type is hidden by default. The visibility might be
                overridden by the visibility set in the base state.
        \row
            \li \image qmldesigner-boolean-false-blue.png
            \li FALSE (hightlighted)
            \li The type is explicitly set to hidden.
    \endtable

    \section2 Setting Expressions

    \l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-syntax-propertybinding.html}
    {Property binding} is a
    declarative way of specifying the value of a property.
    Binding allows a property value to be expressed as an JavaScript expression
    that defines the value relative to other property values or data accessible
    in the application. The property value is automatically kept up to date if
    the other properties or data values change.

    Property bindings are created implicitly in QML whenever a property is
    assigned a JavaScript expression. To set JavaScript expressions as values of
    properties in \QMLD, click the circle icon next to a property to open a
    context menu, and select \gui {Set Expression}.

    \image qmldesigner-set-expression.png "Type properties context menu"

    To remove expressions, select \gui Reset in the context menu.

    For more information on the JavaScript environment provided by QML, see
    \l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-javascript-topic.html}
    {Integrating QML and JavaScript}.

    \section2 Marking Text Items for Translation

    To support translators, mark each text item that should be translated.
    In the \gui Properties pane, \gui Text field, select \gui tr (1).

    \image qmldesigner-text-property-tr.png "Text properties"

    The text string is enclosed in a \c qsTr call.

    \image qml-translate.png "Text marked for translation"

    \section2 Loading Placeholder Data

    \QMLD supports views, models, and delegates, so that when you add a Grid
    View, List View, or Path View item, the ListModel and the delegate
    item are added automatically.

    However, the missing context of the application presents a challenge for
    \QMLD. Specific models defined in C++ are the most obvious case. Often,
    the context is missing simple properties, which are either defined in C++,
    or in other QML files. A typical example is an item that uses the
    properties of its parent, such as \c parent.width.

    \section3 Using Dummy Models

    If you open a file in \QMLD that references a C++ model, you see nothing on
    the canvas. If the data in the model is fetched from the internet, you have
    no control over it. To get reliable data, \e {dummy data} was introduced.

    For example, the following code snippet describes the file example.qml that
    contains a ListView that in turn specifies a C++ model:

    \qml
        ListView {
            model: dataModel
            delegate: ContactDelegate {
                name: name
            }
        }
    \endqml

    Create a directory named \e dummydata in the root directory of the project,
    so that it is not deployed to the device. In the \c dummydata directory,
    create a QML file that has the same name as the value of \c model:

    \code
        qml/exampleapp/example.qml
        dummydata/dataModel.qml
    \endcode

    Then create the dataModel.qml file that contains the dummy data:

    \qml
        import QtQuick 1.0

        ListModel {
             ListElement {
                 name: "Ariane"
             }
             ListElement {
                 name: "Bella"
             }
             ListElement {
                 name: "Corinna"
             }
        }
    \endqml

    \section3 Creating Dummy Context

    The following example presents a common pattern in QML:

    \qml
        Item {
            width: parent.width
            height: parent.height
        }
    \endqml

    This works nicely for applications but \QMLD displays a zero-sized item.
    A parent for the opened file does not exist, because the context is
    missing. To get around the missing context, the idea of a \e {dummy
    context} is introduced. If you place a file with the same name as the
    application (here, example.qml) in the \c {dummydata/context} directory,
    you can fake a parent context:

    \qml
        import QtQuick 1.0
        import QmlDesigner 1.0

        DummyContextObject {
            parent: Item {
                width: 640
                height: 300
            }
        }
    \endqml

    \section2 Setting Anchors and Margins

    In addition to arranging QML types in a grid, row, or column, you can use
    \l{http://qt-project.org/doc/qt-5.0/qtquick/qtquick-positioning-anchors.html}{anchors}
    to lay out screens. In an anchor-based layout, each QML type can be thought of as having a
    set of invisible \e anchor lines: top, bottom, left, right, fill, horizontal
    center, vertical center, and baseline.

    In the \gui Layout pane you can set anchors and margins for items. To set
    the anchors of an item, click the anchor buttons. You can combine the
    top/bottom, left/right, and horizontal/vertical anchors to anchor items in
    the corners of the parent item or center them horizontally or vertically
    within the parent item.

    \image qmldesigner-anchor-buttons.png "Anchor buttons"

    Specifying the baseline anchor in Qt Quick Designer is
    not supported. You can specify it using the code editor.

    For performance reasons, you can only anchor an item to its siblings and
    direct parent. By default, an item is anchored to its parent when you
    use the anchor buttons. Select a sibling of the item in the \gui Target
    field to anchor to it, instead.

    Arbitrary anchoring is not supported. For example, you cannot specify:
    \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
    When you use the anchor buttons, anchors to the parent item are always
    specified to the same side. However, anchors to sibling items are specified
    to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
    sibling items together.

    In the following image, \gui{Rectangle 2} is anchored to \gui{Rectangle 1}
    on its left and to the bottom of its parent.

    \image qmldesigner-anchors.png "Anchoring sibling items"

    The anchors for \gui{Rectangle 2} are specified as follows in code:

    \qml
    Rectangle {
        id: rectangle2
        anchors.left: rectangle1.right
        anchors.leftMargin: 15
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 15
        //
    }
    \endqml

    Margins specify the amount of empty space to leave to the outside of an item.
    Margins only have meaning for anchors. They do not take any effect when using
    other layouts or absolute positioning.

    \section2 Building Transformations on Items

    The \gui Advanced pane allows you to configure advanced transformations,
    such as rotation, scale, and translation. You can assign any number of
    transformations to an item. Each transformation is applied in order, one at
    a time.

    For more information on Transform types, see
    \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-transform.html}{Transform}.

    \section1 Adding States

    User interfaces are designed to present different interface configurations
    in different scenarios, or to modify their appearances in response to user
    interaction. Often, there are a set of changes that are made concurrently,
    such that the interface could be seen to be internally changing from one
    \e state to another.

    This applies generally to interfaces regardless of their complexity.
    A photo viewer may initially present images in a grid, and when an image is
    clicked, change to a detailed state where the individual image is expanded
    and the interface is changed to present new options for image editing.
    On the other end of the scale, when a simple button is pressed, it may change
    to a \e pressed state in which its color and position is modified to give a
    pressed appearance.

    In QML, any item can change between different states to apply sets of
    changes that modify the properties of relevant items. Each state can present
    a different configuration that can, for example:

    \list

        \li Show some UI items and hide others.

        \li Present different available actions to the user.

        \li Start, stop or pause animations.

        \li Execute some script required in the new state.

        \li Change a property value for a particular item.

        \li Show a different view or screen.

    \endlist

    The \gui State pane displays the different
    \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-state.html}{states}
    of the component in the Qt Quick Designer.

    \image qmldesigner-transitions.png "State pane"

    To add states, click the empty slot. Then modify the new state in the editor.
    For example, to change the appearance of a button, you can hide the button
    image and show another image in its place. Or, to add movement to the screen,
    you can change the position of an object on the canvas and then add animation
    to the change between the states.

    You can preview the states in the \gui State pane and click them to switch
    between states on the canvas.

    For more information on using states, see \l{Creating Screens}.

    If you add animation to the states, you can run the application to test the
    animation.

    For more information on adding animation, see \l{Animating Screens}.

    \section1 Aligning and Positioning QML Types

    The position of an item on the canvas can be either absolute or relative
    to other items. In the item properties, you can set the x and y
    coordinates of an item, or \l{Setting Anchors and Margins}{anchor} it to
    its parent and sibling items.

    \section2 Snapping to Parent and Sibling Items

    When you are working on a design, you can use snapping to align
    items on the canvas. Click the
    \inlineimage qmldesigner-snap-to-guides-button.png
    button to have the items snap to their parent or sibling items. Snapping
    lines automatically appear to help you position the items.
    Click the \inlineimage qmldesigner-snap-to-anchors-button.png
    button to anchor the item to the items that you snap to.

    Choose \gui {Tools > Options > Qt Quick > Qt Quick Designer} to specify
    settings for snapping. In the \gui {Parent item padding} field, specify the
    distance in pixels between the parent item and the snapping lines. In the
    \gui {Sibling item spacing} field, specify the distance in pixels between
    sibling items and the snapping lines.

    The following image shows the snapping lines when \gui {Parent item padding}
    is set to 5 pixels.

    \image qmldesigner-snap-margins.png "Snapping lines on canvas"

    \section2 Hiding Item Boundaries

    Qt Quick Designer displays the boundaries of items on the canvas. To hide
    the boundaries, click the
    \inlineimage qmldesigner-show-bounding-rectangles-button.png
    button.

    \section2 Selecting Items

    When you point the mouse to overlapping items, the frontmost item is
    selected by default. However, items that do not have any content, such as
    the mouse area, are typically located in front of items that do have
    content, such as rectangles or border images. To select items with content
    by default, click the
    \inlineimage qmldesigner-only-select-items-with-content.png
    button.

    \section2 Previewing Component Size

    The width and height of the root item in a QML file determine the size of
    the component. You can reuse component, such as buttons, in different
    sizes in other QML files and design screens for use with different device
    profiles, screen resolution, or screen orientation. The component size
    might also be zero (0,0) if its final size is determined by property
    bindings.

    To experiment with different component sizes, enter values in the
    \gui Height and \gui Width fields (1) on the canvas toolbar. The changes are
    displayed in the \gui States pane (2) and on the canvas (3), but the property
    values are not changed permanently in the QML file. You can permanently
    change the property values in the \gui Properties pane (4).

    \image qmldesigner-preview-size.png "Canvas width and height"

    \section1 Specifying Canvas Size

    To change the canvas size, select \gui {Tools > Options > Qt Quick
    > Qt Quick Designer} and
    specify the canvas width and height in the \gui Canvas group.

    \section1 Refreshing the Canvas

    When you open QML files in \QMLD, the items in the file are drawn on
    the canvas. When you edit the item properties in \QMLD, the QML file and
    the image on the canvas might get out of sync. For example, when you change
    the position of an item within a column or a row, the new position might
    not be displayed correctly on the canvas.

    To refresh the image on the canvas, press \key R or select the \gui {Reset
    View} button on the canvas toolbar.

*/
