path: root/doc/src/qtquick/qtquick-app-development.qdoc

/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/

// **********************************************************************
// 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 creator-design-mode.html
    \page creator-visual-editor.html
    \nextpage quick-projects.html

    \title Developing Qt Quick Applications

    You can either create Qt Quick projects from scratch or import existing
    projects to \QC.

    You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual
    editor (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick
    applications.

    \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"

    The following sections describe typical tasks you can do with \QC.

    \list

        \o \l {Creating Qt Quick Projects}
        \o \l {Using Qt Quick Designer}
        \o \l {Creating Components}
        \o \l {Creating Buttons}
        \o \l {Creating Scalable Buttons and Borders}
        \o \l {Creating Screens}
        \o \l {Animating Screens}
        \o \l {Adding User Interaction Methods}
        \o \l {Exporting Designs from Graphics Software}
        \o \l {Implementing Application Logic}
        \o \l {Using QML Modules with Plugins}

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage creator-visual-editor.html
    \page quick-projects.html
    \nextpage creator-using-qt-quick-designer.html

    \title Creating Qt Quick Projects

    \image qmldesigner-new-project.png "New File or Project dialog"

    When you create a new Qt Quick project from scratch, you have the following
    options:

    \list

        \o  \gui {Qt Quick Application} creates a Qt Quick application project
            that can contain both QML and C++ code. The project includes a
            QDeclarativeView. You can build the application and deploy it on
            desktop and mobile target platforms. For example, you
            can create signed Symbian Installation System (SIS) packages for
            this type of projects.

        \o  \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML
            file that contains the main view. You can review Qt Quick UI
            projects in the QML Viewer and you need not build them. You do not
            need to have the development environment installed on your
            computer to create and run this type of projects.

        \o  \gui {Custom QML Extension Plugin} creates a C++ plugin that makes
            it possible to offer extensions that can be loaded dynamically into
            applications by using the QDeclarativeEngine class.

    \endlist

    If you have existing QML applications that you want to run in \QC or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard to convert
    them to Qt Quick applications.

    \note Qt 4.7.3 supports Qt Quick 1.0 and Qt 4.7.4 supports Qt Quick 1.1. The
    application wizards import Qt Quick 1.1, and therefore, you can use them
    without changes if you target only platforms that run Qt 4.7.4 (such as
    MeeGo or the desktop). If you also target platforms that run Qt 4.7.3
    (such as Maemo and S60 5th Edition), you must change the import statement to
    import Qt Quick 1.0.

    \section1 Creating Qt Quick UI Projects

    \list 1

        \o  Select \gui {File > New File or Project > Qt Quick Project >
            Qt Quick UI > Choose}.

            The \gui{Introduction and Project Location} dialog opens.

            \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"

        \o  In the \gui Name field, give a name to the project.

            Do not use spaces and special characters in the project name and
            path.

        \o  In the \gui {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}. To select the path from a
            directory tree, click \gui Browse.

        \o  Click \gui{Next}.

            \image qmldesigner-new-ui-project-summary.png "Project Management dialog"

        \o  Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    \QC creates the following files:

    \list

        \o  .qmlproject project file defines that all QML, JavaScript, and image
            files in the project folder belong to the project. Therefore, you do
            not need to individually list all the files in the project.

        \o  .qml file defines an element, such as a component, screen, or the
            whole application UI.

    \endlist

    The \c import statement in the beginning of the .qml file specifies the
    \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
    to import. Each Qt module contains a set of default elements.
    Specify a version to get the features you want.

    To use JavaScript and image files in the application, copy them to the
    project folder.

    \section1 Creating Qt Quick Applications

    \list 1

        \o  Select \gui {File > New File or Project > Qt Quick Project >
            Qt Quick Application > Choose}.

            The \gui{Introduction and Project Location} dialog opens.

            \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"

        \o  In the \gui Name field, give a name to the project.

            Do not use spaces and special characters in the project name and path.

        \o  In the \gui {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}. To select the path from a
            directory tree, click \gui Browse.

        \o  Click \gui{Next}.

            The \gui {Application Type} dialog opens.

            \image qmldesigner-new-project-qml-sources.png "Application Type dialog"

        \o  Select the Qt Quick Component Set to use in your application. The
            built-in elements allow you to write cross-platform applications
            with custom look and feel. The components for a mobile platform
            allow you to create applications with a native look and feel for
            that platform.

            \note We recommend that you use \gui {Qt Quick Components for
            MeeGo Harmattan} when you develop for MeeGo Harmattan devices.

            You can also import an existing QML file in this dialog.

        \o  Click \gui{Next}.

            The \gui {Target Setup} dialog opens.

            \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"

        \o  Select the Qt versions to use as build targets for your project,
            and then click \gui{Next}.

            \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7
            and later versions are displayed. Further, if you have only one
            supported Qt version installed, this dialog is skipped.

            The \gui {Mobile Options} dialog opens.

            \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"

        \o  In the \gui {Orientation behavior} field, determine how the application
            behaves when the orientation of the device display rotates between portrait
            and landscape, and then click \gui Next.

            \note This dialog opens only if you select \gui Maemo5 or
            \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
            Harmattan, the Qt Quick Components for MeeGo provide native-looking
            rotation.

            The \gui {Symbian Specific} dialog opens.

            \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"

        \o In the \gui {Application icon (.svg)} field, select an application
        icon for the \gui {Symbian Device} target, or use the default icon.

        \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
        use the default UID.

        \note \QC generates a UID for testing the application on a device.
        You need to change the UID when you deliver the application for public
        use.

        \o Click \gui Next.

        The \gui {Maemo Specific} dialog opens.

        \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"

        \o In the \gui {Application icon} field, select the application
         icon to use on Maemo or Harmattan targets, or use the default icon.

        The \gui {Project Management} dialog opens.

        \image qmldesigner-new-project-summary.png "Project Management" dialog

        \o In the \gui {Add to project} field, you can add this project to another
        project as a subproject.

        \o In the \gui {Add to version control} field, you can add the project to
        a version control system.

        \o Click \gui Finish to create the project.

    \endlist

    \QC creates the necessary boilerplate files. Some of the files are
    specific to the Symbian, Maemo, or MeeGo Harmattan platform.

    \section1 Importing QML Applications

    If you have existing QML applications that you want to run in \QC or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
    .qml file in your project. All the other files in the project are automatically added
    to the application project.

    To import QML applications:

    \list 1

        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
        > Choose}.

        \o Name the project and set its path, and then click \gui Next.

        \o In the \gui {Application Type} dialog, select the \gui {Use an
        existing .qml file}
        option and specify the main .qml file of the project you want to import.

        \image qmldesigner-import-project.png "Application Type dialog"

        \o Click \gui Next.

        \o Select the Qt versions to use as build targets for your project, and click
        \gui{Next}.

        \o Specify options for deploying the application to mobile device targets, and
        click \gui{Next}.

        \o Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    \QC adds references to the QML files to a project and creates the additional files
    necessary for deploying applications to mobile devices.

*/


/*!

    \contentspage index.html
    \previouspage creator-using-qt-quick-designer.html
    \page quick-components.html
    \nextpage quick-buttons.html

    \title Creating Components

    A \l{glossary-component}{component} provides a way of defining a new type
    that you can re-use in other QML
    files. A component is like a black box; it interacts with the outside world
    through properties, signals, and slots, and is generally defined in its own QML file.
    You can import components to screens and applications.

    You can use the following QML elements to create components:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
        uses an image as a border or background.
        \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
        adds a bitmap to the scene. You can stretch and tile images.
        \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
        is the most basic of all visual items in QML. Even though it has no visual appearance,
        it defines all the properties that are common across visual items, such as the x and
        y position, width and height, anchoring, and key handling.
        \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
        adds a rectangle that is painted with a solid fill color and an optional border.
        You can also use the radius property to create rounded rectangles.
        \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
        adds formatted read-only text.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
        adds a single line of editable formatted text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
        adds a single line of editable plain text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
        adds web content to a canvas.

    \endlist

    QML elements allow you to write cross-platform applications with custom look
    and feel. You can also use ready-made Qt Quick Components for Symbian and
    MeeGo Harmattan that allow you to create applications with a native look and
    feel for the selected mobile platform. You can install the components as
    part of \QSDK.

    When you use the \QC project wizard to create Qt Quick applications,
    you can select which component set to use in your application.

    Even if you use the Qt Quick Components, you can still write cross-platform
    applications, by using different sets of QML files for each platform.

    You can dowload a set of commonly used UI-components for generic use in
    Qt Quick projects from
    \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
    open and edit the templates in \QD.

    \section1 Creating Components in Qt Quick Designer

    \list 1

        \o Select \gui {File > New File or Project > Files and Classes > QML
        > Choose} to create a new .qml file.

        \note Components are listed in the \gui {QML Components} section of the
        \gui Library pane only if the filename begins with a capital letter.

        \o Click \gui Design to open the .qml file in \QMLD.

        \o Drag and drop an item from the \gui Library pane to the editor.

        \o Edit item properties in the \gui Properties pane.

        The available properties depend on the item.

    \endlist

    The following sections contain examples of how to create some common components:

    \list

        \o \l{Creating Buttons}

        \o \l{Creating Scalable Buttons and Borders}

    \endlist

    \section1 Moving Within Components

    Components can consist of several other components. To view the component
    hierarchy as a bread crumb path when you edit a component on the canvas,
    select \gui {Go into Component} or press \key F2. Click the component
    names in the path to navigate to them. You can easily navigate back to the
    top level when you are done editing the component.

    \image qmldesigner-breadcrumbs.png "Go into Component command"

*/


/*!
    \contentspage index.html
    \previouspage quick-components.html
    \page quick-buttons.html
    \nextpage quick-scalable-image.html

    \title Creating Buttons

    To create a button component:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose} to
         create a QML file called Button.qml (for example).

        \note Components are listed in the \gui Library pane only if the filename
        begins with a capital letter.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o In the \gui Navigator pane, click \gui Rectangle to set properties
        for it.

        \o In the \gui Properties pane, modify the appearance of the button.

        \list a

            \o In the \gui Size field, set the width (\gui W) and height (\gui H)
            of the button.

            \o In the \gui Color field, select the button color.

            \o In the \gui Radius field, use the slider to set the radius of the
            rectangle and produce rounded corners for the button.

        \endlist

        \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
        creates a nested element where \gui Rectangle is the parent element of
        \gui Text. Elements are positioned relative to their parents.

        \o In the \gui Properties pane, edit the properties of the \gui Text item.

        \list a

            \o In the \gui Text field, type \bold Button.

            You can select the text color, font, size, and style in the \gui Font
            section.

            \o In the \gui Alignment field, select the center buttons to align
            the text to the center of the button.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the text to the whole button area.

        \endlist

        \o Press \key {Ctrl+S} to save the button.

        \image qmldesigner-button.png "Button component"

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
    project.

    To create a graphical button that scales beautifully without using vector graphics,
    use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element. For more information, see \l{Creating Scalable Buttons and Borders}.

    */


/*!

    \contentspage index.html
    \previouspage quick-buttons.html
    \page quick-scalable-image.html
    \nextpage quick-screens.html

    \title Creating Scalable Buttons and Borders

    You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element to display an image, such as a PNG file, as a border and a background.

    Use two Border Image elements and suitable graphics to make it look like the button
    is pushed down when it is clicked. One of the Border Image elements is visible by default.
    You can specify that it is hidden and the other one becomes visible when the mouse
    is clicked.

    Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
    when it detects a mouse click.

    You can add text to the button and set it up as a property. The text can then be initialized
    from the outside, making the button a reusable UI component. The font size is also available
    in case the default size is too big. You can scale down the button text and use smooth text
    rendering for some extra quality.

    \image qmldesigner-borderimage.png "Graphical button"

    To create a graphical button:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose} to create
        a QML file called Button.qml (for example).

        \o Double-click the file to open it in the code editor.

        \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
        following code snippet:

        \qml
        Item {

        }
        \endqml

        \o Specify properties and set expressions for the \gui Item, as
        illustrated by the following code snippet:

        \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions

        You will point to the properties and expression later.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o Drag and drop two \gui BorderImage items from the \gui Library pane to
        the scene.

        \o Drag and drop a \gui Text item to the scene.

        \o Drag and drop a \gui MouseArea to the screen.

        \o In the \gui Navigator pane, select \gui border_image1 to specify
        settings for it in the \gui Properties pane:

        \list a

            \o Select \gui {Set Expression} in the menu next to the \gui Visibility
            check box.

            \o Enter the following expression to specify that the image is visible
            when the mouse is not pressed down: \c {!mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button, for example button_up.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui border_image2 to specify similar settings for it:

        \list a

            \o Set the following epression for \gui Visibility, to specify that
            the image is visible when the mouse is pressed down:
            \c {mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button when it is clicked, for example button_down.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui text1 to specify font size and color, and text
        scaling and rendering:

        \list a

            \o In the \gui Color field, use the color picker to select
            the font color, or enter a value in the field.

            \o In the \gui Text field, select \gui {Set Expression} and
            enter a pointer to the \c {text} property that you specified
            earlier: \c {parent.txt}.

            \o Select the \gui Aliasing check box to enable smooth text
            rendering.

            \o In the \gui Size field, select \gui {Pixels} to specify
            the font size in pixels. By default, the size is specified in
            points.

            \o In the \gui Size field, select \gui {Set Expression} and
            enter a pointer to the \c {fontSize} property that you specified
            earlier.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-center-in.png "Anchor buttons"
            buttons to inherit the vertical and horizontal centering from
            the parent.

            \o Click \gui Advanced to specify scaling for the text in the
            \gui Scale field.

            \o Select \gui {Set Expression} and enter the following expression:
            \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.

            \note You can enter long and complicated expressions also in the
            code editor.

        \endlist

        \o In the code editor, add to the \c MouseArea item
        a pointer to the \c clicked expression that you added earlier:
        \c {onClicked: parent.clicked()}.

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt
    Quick UI project.

*/


/*!

    \contentspage index.html
    \previouspage quick-scalable-image.html
    \page quick-screens.html
    \nextpage quick-animations.html

    \title Creating Screens

    You can use predefined QML elements and your own components to create screens.
    Typically, the main qml file in a Qt Quick project specifies the main window of an
    application.

    The QML files in the project folder are displayed in \gui {QML Components} in the
    \gui Library pane.

    You can also use ready-made Qt Quick Components for Symbian and
    MeeGo Harmattan that allow you to create screens with a native look and
    feel for the selected mobile platform. You can install the components as
    part of \QSDK.

    You can dowload QML templates that specify different types of screens from
    \l{https://projects.developer.nokia.com/QMLTemplates}{QML Templates} for use in
    your Qt Quick projects. You can open and edit the templates in \QMLD.

    \section1 Adding Components to Screens

    \list 1

        \o Drag and drop components from the \gui Library pane to the editor.

        \o Select components in the \gui Navigator pane to edit their properties
        in the \gui Properties pane.

        For example, you can anchor components to a position on the screen.

    \endlist

    \section1 Using Data Models

    You can create the following types of views to organize items provided by
    \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
        provides a grid vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
        provides a list vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
        visualizes the contents of a model along a path.

    \endlist

    When you add a Grid View, List View, or Path View element, the
    \l{http://doc.qt.nokia.com/4.7/qml-listmodel.html}{ListModel} and the
    delegate component that creates an instance for each item in the model are
    added automatically. You can edit element properties in the \gui Properties
    pane or in the code editor. You can also replace the default model and
    delegate with other, more complex models and delegates in the code editor.

    \section1 Positioning Items on Screens

    You can use the following items to arrange items on screens:

    \list

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
            arranges its child items vertically.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
            arranges its child items horizontally.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
            arranges its child items so that they are aligned in a grid and
            are not overlapping.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
            arranges its child items side by side, wrapping as necessary.

    \endlist

    To lay out several items in a Column, Row, Grid, or Flow element, select
    the elements on the canvas, and then select \gui Layout in the context
    menu.

    \section1 Using States

    Use states and transitions
    to navigate between screens.

    QML states typically describe user interface configurations, such as the UI elements,
    their properties and behavior and the available actions. For example, you can use
    states to create two screens.

    To add states, click the empty slot in the \gui States pane. Then modify the new state
    in the visual editor.

    \image qmldesigner-states.png "States pane"

    The properties that you change in a state are highlighted with blue color.
    In the code editor, you can see the changes recorded as changes to the base state.

    To keep the QML code clean, you should create a base state that contains all the
    elements you will need in the application. You can then create states, in
    which you hide and show a set of items and modify their properties.
    This allows you to:

    \list

        \o Align items on different screens with each other.

        \o Avoid excessive property changes. If an item is invisible in the base
        state, you must define all changes to its child elements as property changes,
        which leads to complicated QML code.

        \o Minimize the differences between the base state and the other states
        to keep the QML code short and readable and to improve performance.

        \o Avoid problems when using transitions and animation when changing
        states.

    \endlist

    To create screens for an application by using states:

    \list 1

        \o In the base state, add all elements you will need in the application.
        While you work on one screen, you can click the
        \inlineimage qmldesigner-show-hide-icon.png
        icon to hide elements on the canvas that are not part of a screen.

        \o In the \gui States pane, click the empty slot to create a new state
        and give it a name. For example, \c Normal.

        \o In the \gui Properties pane, deselect the \gui Visibility check box
        or set \gui Opacity to 0 for each element that is not needed in this view.
        If you specify the setting for the parent element, all child elements
        inherit it and are also hidden.

        \image qmldesigner-screen-design.png "Designing screens"

        \o Create additional states for each screen and set the visibility or
        opacity of the elements in the screen.

        \o To determine which view opens when the application starts, use the code
        editor to set the state of the root item of the .qml file, as specified by the
        following code snippet:

        \qml
        Item {
            state: "Normal"
        }
        \endqml

    \endlist


*/


/*!

    \contentspage index.html
    \previouspage quick-screens.html
    \page quick-animations.html
    \nextpage quick-user-interaction.html

    \title Animating Screens

    To make movement between states smooth, you can specify transitions.
    You can use different types of animated transitions. For example, you can animate changes
    to property values and colors. You can use rotation animation to control the direction of
    rotation. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.

    You can use the \c ParallelAnimation element to start several animations at the same time.
    Or use the \c SequentialAnimation element to run them one after another.

    You can use the code editor to specify transitions. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.

*/


/*!

    \contentspage index.html
    \previouspage quick-animations.html
    \page quick-user-interaction.html
    \nextpage quick-export-to-qml.html

    \title Adding User Interaction Methods

    You can add the following basic interaction methods to scenes:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
        items can be flicked horizontally or vertically.
        \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
        items can be flipped between their front and back sides by using rotation,
        state, and transition.
        \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
        assists in keyboard focus handling when building reusable QML components.
        \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
        enables simple mouse handling.

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage quick-user-interaction.html
    \page quick-export-to-qml.html
    \nextpage quick-application-logic.html

    \title Exporting Designs from Graphics Software

    You can export designs from graphics software, such as Adobe Photoshop and GIMP,
    to QML files. Each scene is converted into a single QML file with an Image or a
    Text element for each layer and saved on the development PC. Top-level layer
    groups are converted into merged QML Image elements.

    Note: GIMP does not support grouping, and therefore, each layer is exported as
    an item in GIMP.

    You can open the QML file in \QC for editing. If you edit the file in Adobe
    Photoshop and export it to the same directory again, any changes you made in
    \QC are overwritten. However, you can re-export graphical assets without
    recreating the QML code.

    If you create vector graphics with other tools that have an Adobe Photoshop export
    option, such as Adobe Illustrator, you can export them first to Photoshop
    and then
    to QML.

    \section1 Conversion Rules

    The following rules apply to the conversions:

    \list

        \o Layer names are used as element names. Spaces and hash marks (#) are
         replaced with underscore characters to create valid ids for the elements.

        \o Layer styles, such as drop shadows, are converted to images.

        \o Offset, size, ordering and opacity are preserved.

        \o Text layers are converted to Text elements, unless you specify that they
        be converted to Image elements.

        \o Hidden layers can be exported, and their visibility is set to hidden.

        \o PNG images are copied to the images subirectory.

    \endlist

    \section1 Preparing Files for Conversion

    To create QML files that are easy to use, prepare the Adobe Photoshop or
    GIMP designs for exporting, as follows:

    \list

        \o  To minimize the number of elements, minimize the number of layers or
            use top-level layer groups, because each layer or layer group is
            exported as a Text or Image element.

        \o  To make sure that all related elements are exported to the same
            element, use top-level layer groups.

        \o  To determine that some layers are not exported, hide them, and
            deselect the \gui {Export hidden} check box during exporting.

        \o  To make it easier to find the layers and layer groups after
            exporting them, use descriptive names for them.

        \o  To make sure that image dimensions are preserved during export,
            create at least one fully filled layer (which can be hidden), such
            as a background layer. If the export script does not find a fully
            filled layer, it resizes all images to the size of the canvas.

        \o  To prevent errors during export, make sure that the layers are not
            locked. Locked layers cannot be exported.

        \o  To avoid unexpected results, do not use Blending Mode effects. They
            are not exported.

    \endlist

    \section1 Exporting from Adobe Photoshop to QML

    \image qml-export-photoshop.png

    The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
    work on other versions.

    \list 1

        \o Download the export script, \e{Export QML.jx}, from
        \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.

        \note Read the README.txt file in the repository for latest information about
        the script.

        \o Double-click the export script to add the export command to the \gui Scripts
        menu. You can also copy the script file to the Adobe Photoshop scripts directory
        (typically, \c{\Presets\Scripts} in the Photoshop installation directory).

        \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
        scene to a QML file.

        \o In the \gui {Export Document to QML} dialog, enter a name and location for the
        QML file.

        \o Select the \gui {Rasterize text} check box to export text layers as images,
        not as Text elements.

        \o Select the \gui {Group layers} check box to export each top-level group as a
        merged QML Image element.

        \o Select the \gui {Export hidden} check box to export hidden layers and to set
        their visibility property to hidden.

        \o Deselect the \gui {Export QML} check box if you have modified the QML document
        in \QC, but still want to re-export graphical assets.

        \o Click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In \QC, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

    \section1 Exporting from GIMP to QML

    \image qml-export-gimp.png

    The script has been tested to work on GIMP 2. You can download GIMP 2 from
    \l{http://www.gimp.org/downloads/}{GIMP Downloads}.

    To use the export script on Microsoft Windows, you also need to install the
    GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
    not officially supported on Windows, so we cannot guarantee that this will
    work.

    \list 1

        \o On Microsoft Windows, you must first add Python support to your GIMP
        installation, as instructed in
        \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.

        \o Download the export script, \e qmlexporter.py, from
        \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.

        \note Read the INSTALL.txt in the repository for latest information about the
        script.

        \o Copy the export script to the plug-ins directory in the GIMP installation
        directory.

        \o Check the properties of the file to make sure that it is executable.

        On Linux, run the following command: \c {chmod u+rx}

        \o Restart GIMP to have the export command added to the \gui File menu.

        \o Choose \gui {File > Export to QML} to export the design to a QML file.

        \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
        location for the QML file, and click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In \QC, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

*/


/*!

    \contentspage index.html
    \previouspage quick-export-to-qml.html
    \page quick-application-logic.html
    \nextpage creator-qml-modules-with-plugins.html

    \title Implementing Application Logic

    A user interface is only a part of an application, and not really useful by itself.
    You can use Qt or JavaScript to implement the application logic. For more information on
    using JavaScript, see
    \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.

    For an example of how to use JavaScript to develop a game, see the
    \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.

 */


/*!
    \contentspage index.html
    \previouspage quick-application-logic.html
    \page creator-qml-modules-with-plugins.html
    \nextpage creator-using-qt-designer.html

    \title Using QML Modules with Plugins

    QML modules may use plugins to expose components defined in C++ to
    QML applications. Since \QC cannot load the plugins to determine
    the details of the contained components, these modules need to provide
    extra type information for code completion and the semantic checks to work
    correctly.

    When you write a QML module or use QML from a C++ application you typically
    register new types with
    \l{http://doc.qt.nokia.com/4.8/qdeclarativeengine.html#qmlRegisterType}
    {qmlRegisterType} or expose some class instances with
    \l{http://doc.qt.nokia.com/4.8/qdeclarativecontext.html#setContextProperty}
    {setContextProperty}. The \QC C++ code model now scans for these calls and
    tells the QML code model about them. This means that properties are
    displayed during code completion and the JavaScript code checker does not
    complain about unknown types. However, this works only when the source code
    is available, and therefore, you must explicitly generate type information
    for QML modules with plugins before distributing them.

    Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
    as the \c qmldir file. The \c qmltypes file contains a description of the
    components exported by the module's plugins and is loaded by \QC
    when the module is imported.

    For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
    \c qmldir file under the \c typeinfo header. These files will be read in addition
    to \c{plugins.qmltypes}. For more information, see
    \l{http://doc.qt.nokia.com/4.8/qdeclarativemodules.html#writing-a-qmldir-file}{Writing a qmldir File}.

    \section1 Generating qmltypes Files

    You can create and edit \c qmltypes files manually, but you are recommended
    to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
    them automatically. For earlier versions of Qt, you can compile a version
    of the tool called \c qmldump from the sources in
    \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains private headers.

    Once you have obtained qmlplugindump for the Qt version the QML module's
    plugins were compiled with, run the following command to load My.Module
    version 1.0 from \c{/import/path/my/module} including all its plugins and
    output a description of the plugins' types to
    \c{/import/path/my/module/plugins.qmltypes}:

    \code
    qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
    \endcode

    You can safely ignore the debug output.

    \section1 Dumping Plugins Automatically

    If a module with plugins lacks the \c qmltypes file, \QC tries to
    generate a temporary file itself by running the \c qmldump program in the
    background. However, this automatic dumping is a fallback mechanism with
    many points of failure and cannot be relied upon.

*/