diff --git a/doc/src/qtquick/creator-projects-settings-run-qtquick.qdocinc b/doc/src/qtquick/creator-projects-settings-run-qtquick.qdocinc new file mode 100644 index 00000000000..309f3303fa8 --- /dev/null +++ b/doc/src/qtquick/creator-projects-settings-run-qtquick.qdocinc @@ -0,0 +1,28 @@ + \section1 Specifying Run Settings for Qt Quick UI Projects + + You can specify run settings for the \gui Desktop target: + + \list + + \o In the \gui {Qt version} field, select a Qt version that has support + for QML. + + \o In the \gui Arguments field, you can specify command line arguments + to be passed to the executable. + + \o In the \gui {Main QML file}, select the file that \QQV will be + started with. + + \o In the \gui Debugger group, select the languages to debug: + \gui{C++} and \gui QML. \gui {Debug port} is the port to access + \QQV. You can use any free port in the registered port range. + For more information, see \l{Debugging Qt Quick Projects}. + + \endlist + + \note Opening a socket at a well-known port presents a security risk. Anyone + on the Internet could connect to the application that you are debugging and + execute any JavaScript functions. Therefore, you must make sure that the + port is properly protected by a firewall. + + \image qmldesigner-run-settings.png "Run settings for Qt Quick UI projects" diff --git a/doc/src/qtquick/qtquick-app-development.qdoc b/doc/src/qtquick/qtquick-app-development.qdoc new file mode 100644 index 00000000000..17b23e66263 --- /dev/null +++ b/doc/src/qtquick/qtquick-app-development.qdoc @@ -0,0 +1,1067 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.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 info@qt.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. + + \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. + + 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 QML 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 + +*/ + + +/*! + \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 \QD. + + \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 + + \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. + + 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-snapshot/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{/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. + +*/ diff --git a/doc/src/qtquick/qtquick-app-tutorial.qdoc b/doc/src/qtquick/qtquick-app-tutorial.qdoc new file mode 100644 index 00000000000..16649347b6a --- /dev/null +++ b/doc/src/qtquick/qtquick-app-tutorial.qdoc @@ -0,0 +1,334 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.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 info@qt.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-build-example-application.html + \page creator-qml-application.html + \nextpage creator-qml-components-example.html + + \title Creating a Qt Quick Application + + \note To complete this tutorial, you must have Qt 4.7 or later installed. + + This tutorial uses basic elements and illustrates basic concepts of + \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}. + + This tutorial describes how to use the \QC to implement the + \l{http://doc.qt.nokia.com/4.7/declarative-animation-states.html} + {states and transitions example application}. The example application + displays a Qt logo that moves between three rectangles on the page when you + click them. + + \image qmldesigner-tutorial.png "States and transitions example" + + For more information about using \QMLD, see + \l{Developing Qt Quick Applications}. + + \section1 Creating the Project + + \list 1 + + \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick + Application > Choose}. + + \o Follow the instructions of the wizard to create a project called + Transitions. + + \o Press \key {Ctrl+R} to run the application. + + \endlist + + \QC generates a default QML file that you can modify to create the main view + of the application. + + \image qmldesigner-tutorial-project.png "Transitions project in Edit mode" + + \section1 Creating the Main View + + The main view of the application displays a Qt logo in the top left corner + of the screen and two empty rectangles. + + To use the states.png image in your application, you must copy it to the + project directory (same subdirectory as the QML file) from the examples + directory in the Qt installation directory. For example: + \c {C:\QtSDK\Examples\4.7\declarative\animation\states}. The image appears + in the \gui Resources pane. You can also use any other image or a QML + element, instead. + + \list 1 + + \o In the \gui Projects view, double-click the main.qml file + to open it in the code editor. + + \o Click \gui Design to open the file in \QMLD. + + \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode" + + \o In the \gui Navigator pane, select \gui Text and press \key Delete to + delete it. + + \o Select \gui Rectangle to edit its properties. + + \image qmldesigner-tutorial-page.png "Page properties" + + \list a + + \o In the \gui Id field, enter \e page, to be able to reference the + rectangle from other places. + + \o In the \gui Colors group, \gui Rectangle field, set the color to + #343434. + + \endlist + + \o In the \gui Library view, \gui Resources tab, select states.png and + drag and drop it to the canvas. + + \image qmldesigner-tutorial-user-icon.png "Image properties" + + \list a + + \o In the \gui Id field, enter \e icon. + + \o In the \gui Position field, set \gui X to 10 and \gui Y to 20. + + \endlist + + \o In the \gui Library view, \gui Items tab, select \gui Rectangle, + drag and drop it to the canvas, and edit its properties. + + \image qmldesigner-tutorial-topleftrect.png "Rectangle properties" + + \list a + + \o In the \gui Id field, enter \e topLeftRect. + + \o In the \gui Size field, set \gui W and \gui H to 64, for the + rectangle size to match the image size. + + \o In the \gui Colors group, \gui Rectangle field, click the + \inlineimage qmldesigner-transparent-button.png + button to make the rectangle transparent. + + \o In the \gui Border field, set the border color to #808080. + + \o In the \gui Rectangle group, \gui Border field, set the border + width to 1. + + \note If the \gui Border field does not appear after you set the + border color, try setting the border color to solid by clicking + the + \inlineimage qmldesigner-solid-color-button.png + button. + + \o In the \gui Radius field, select 6 to create rounded corners for + the rectangle. + + \o Click \gui {Layout}, and then click the top and left anchor + buttons to anchor the rectangle to the top left corner of the + page. + + \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab" + + \o In the \gui Margin field, select 20 for the top anchor and 10 + for the left anchor. + + \endlist + + \o In the \gui Navigator pane, drag and drop the \gui {Mouse Area} + element from \e page to \e topLeftRect to make it apply only to the + rectangle and not to the whole page. + + \o Edit \gui {Mouse Area} properties: + + \list a + + \o Click \gui {Layout}, and then click the + \inlineimage qmldesigner-anchor-fill-screen.png + button to anchor the mouse area to the rectangle. + + \o In the code editor, edit the pointer to the clicked expression + in the mouse area element, as illustrated by the following code + snippet: + + \qml + MouseArea { + anchors.fill: parent + onClicked: page.state = '' + } + \endqml + + The expression sets the state to the base state and returns the + image to its initial position. + + \endlist + + \o In the \gui Navigator pane, copy topLeftRect (by pressing + \key {Ctrl+C}) and paste it to the canvas twice (by pressing + \key {Ctrl+V}). \QC renames the new instances of the element + topLeftRect1 and topLeftRect2. + + \o Select topLeftRect1 and edit its properties: + + \list a + + \o In the \gui Id field, enter \e middleRightRect. + + \o In \gui {Layout}, select the vertical center anchor button and + then the right anchor button to + anchor the rectangle to the middle right margin of the screen. + + \o In the \gui Margin field, select 10 for the right anchor and 0 + for the vertical center anchor. + + \o In the code editor,add a pointer to a clicked expression to the + mouse area element. The following expression sets the state to + \e State1: + + \c {onClicked: page.state = 'State1'} + + You will create State1 later. + + \endlist + + \o Select topLeftRect2 and edit its properties: + + \list a + + \o In the \gui Id field, enter \e bottomLeftRect. + + \o In \gui {Layout}, select the bottom and left anchor buttons to + anchor the rectangle to the bottom left margin of the screen. + + \o In the \gui Margin field, select 20 for the bottom anchor and 10 + for the left anchor. + + \o In the code editor, add a pointer to a clicked expression to the + mouse area element. The following expression sets the state to + \e State2: + + \c {onClicked: page.state = 'State2'} + + You will create State2 later. + + \endlist + + \o Press \key {Ctrl+S} to save the changes. + + \o Press \key {Ctrl+R} to run the application. + + \endlist + + \image qmldesigner-tutorial.png "States and transitions example" + + You should see the Qt logo in the top left rectangle, and two additional + rectangles in the center right and bottom left of the screen. + + You can now create additional states to add views to the application. + + \section1 Adding Views + + In the .qml file, you already created pointers to two additional states: + State1 and State2. To create the states: + + \list 1 + + \o Click the empty slot in the \gui States pane to create State1. + + \o Click the empty slot in the \gui States pane to create State2. + + \o In the code editor, bind the position of the Qt logo to the + rectangle to make sure that the logo is displayed within the + rectangle when the view is scaled on different sizes of screens. Set + expressions for the x and y properties, as illustrated by the + following code snippet: + + \snippet snippets/qml/states-properties.qml states + + \image qmldesigner-tutorial-state1.png "States" + + \note When you set the expressions, drag and drop is disabled for + the icon in \QMLD. + + \o Press \key {Ctrl+R} to run the application. + + \endlist + + Click the rectangles to move the Qt logo from one rectangle to another. + + \section1 Adding Animation to the View + + Add transitions to define how the properties change when the Qt logo moves + between states. The transitions apply animations to the Qt logo. For example, + the Qt logo bounces back when it moves to the middleRightRect and eases into + bottomLeftRect. Add the transitions in the code editor. + + \list 1 + + \o In the code editor, add the following code to specify that when + moving to State1, the x and y coordinates of the Qt logo change + linearly over a duration of 1 second: + + \snippet snippets/qml/list-of-transitions.qml first transition + + \o You can use the Qt Quick toolbar for animation to change the easing + curve type from linear to OutBounce: + + \list a + + \o Click \gui NumberAnimation in the code editor to display the + \inlineimage qml-toolbar-indicator.png + icon, and then click the icon to open the toolbar: + + \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation" + + \o In the \gui Easing field, select \gui Bounce. + + \o In the \gui Subtype field, select \gui Out. + + \endlist + + \o Add the following code to specify that when moving to State2, the x + and y coordinates of the Qt logo change over a duration of 2 + seconds, and an InOutQuad easing function is used: + + \snippet snippets/qml/list-of-transitions.qml second transition + + \o Add the following code to specify that for any other state changes, + the x and y coordinates of the Qt logo change linearly over a + duration of 200 milliseconds: + + \snippet snippets/qml/list-of-transitions.qml default transition + + \o Press \key {Ctrl+R} to run the application. + + \endlist + + Click the rectangles to view the animated transitions. + +*/ diff --git a/doc/src/qtquick/qtquick-designer.qdoc b/doc/src/qtquick/qtquick-designer.qdoc new file mode 100644 index 00000000000..2a85d40d6a8 --- /dev/null +++ b/doc/src/qtquick/qtquick-designer.qdoc @@ -0,0 +1,529 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.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 info@qt.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 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. + + 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 + + \o \gui {Navigator} pane displays the QML elements in the current QML + file as tree structure. + + \o \gui {Library} pane displays the building blocks that you can use to + design applications: predefined QML elements, your own QML + components, Qt Quick components that you import to the project, and + other resources. + + \o \gui Canvas is the working area where you create QML components and + design applications. + + \o \gui {Properties} pane organizes the properties of the selected QML + element or QML component. You can change the properties also in the + code editor. + + \o \gui {State} pane displays the different states of the component. + QML states typically describe user interface configurations, such as + the UI elements, their properties and behavior and the available + actions. + + \endlist + + \section1 Managing Element Hierarchy + + The \gui Navigator pane displays the + \l{http://doc.qt.nokia.com/4.7/qdeclarativeelements.html}{QML elements} + in the current QML file and their relationships. Elements are listed in a + tree structure, below their parent. + + \image qmldesigner-navigator.png "Navigator pane" + + You can select elements in the \gui Navigator to edit their properties + in the \gui Properties pane. Elements can access the properties of their + parent element. To select elements on the canvas, right-click an element, + and select another element in the context menu. + + Typically, child elements are located within the parent element on the + canvas. However, they do not necessarily have to fit inside the parent + element. For example, you might want to make a mouse area larger than the + rectangle or image beneath it. + + \image qmldesigner-element-size.png "Mouse area for a button" + + When you copy an element, all its child elements are also copied. When + you remove an element, the child elements 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 element on the canvas. To change the + visibility of an element 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, elements are hidden, but you can still apply animation + to them. + + As all properties, visibility and opacity are inherited from the parent + element. To hide or show child elements, edit the properties of the + parent element. + + 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://doc.qt.nokia.com/4.7/qml-item.html#z-prop}{z property} of an + element determines its position in relation to its sibling elements in the + element hierarchy. By default, elements with a higher stacking value are + drawn on top of siblings with a lower stacking value. Elements 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. + + \section2 Switching Parent Elements + + When you drag and drop QML elements to the canvas, Qt Quick Designer + adds the new element as a child of the element beneath it. + When you move elements on the canvas, Qt Quick Designer cannot determine + whether you want to adjust their position or attach them to a new + parent element. Therefore, the parent element is not automatically + changed. To change the parent of the element, press down the \key Shift + key before you drag and drop the element into a new position. The topmost + element under the cursor becomes the new parent of the element. + + You can change the parent of an element also in the \gui Navigator pane. + Drag and drop the element to another position in the tree or use the arrow + buttons to move the element in the tree. + + \image qmldesigner-navigator-arrows.png "Navigator arrow buttons" + + \section1 Element Library + + The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}. + The \gui Items pane displays the QML elements grouped by type: your own QML + components, basic elements, positioner elements, and views. + + Sets of UI components with the look and feel of a particular mobile device + platform have been defined for Qt Quick. They are based on standard QML + elements. To view the UI components in the \gui {Library} pane, add import + statements to the .pro file of your project. For example: + + \list + + \if defined(qcmanual) + \o \c {import com.nokia.symbian 1.0} for Symbian + \endif + + \o \c {import com.nokia.meego 1.0} for MeeGo + + \endlist + + The Qt Quick Application wizard adds the import statements automatically + when you select the component set to use for your project. + + \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 Element Properties + + The \gui Properties pane displays all the properties of the selected QML + element. The properties are grouped by type. The top part of the pane + displays properties that are common to all elements, such as element type, + position, size, and visibility. + + The bottom part of the pane displays properties that are specific to each + element type. For example, the following image displays the properties you + can set for \gui Rectangle and \gui Text elements. + + \image qmldesigner-element-properties.png + + You can use a context-menu to reset some element properties. To reset the + position or size property of an element, right-click the element and select + \gui {Edit > Reset Position} or \gui {Reset Size} in the context menu. To + set the visibility of the component, select \gui {Edit > Visibility}. + + For more information on the properties available for an element, 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 an element 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 Position, + \gui Size, and \gui Colors values are explicitly set and highlighted. + + \image qmldesigner-properties-explicit-base.png "Explicitly set properties" + + In \gui State1, only the color 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 + \i \image qmldesigner-boolean-true.png + \i TRUE + \i The element is visible by default. The visibility might be + overridden by the visibility set in the base state. + \row + \i \image qmldesigner-boolean-true-blue.png + \i TRUE (highlighted) + \i The element is explicitly set to visible. + \row + \i \image qmldesigner-boolean-false.png + \i FALSE + \i The element is hidden by default. The visibility might be + overridden by the visibility set in the base state. + \row + \i \image qmldesigner-boolean-false-blue.png + \i FALSE (hightlighted) + \i The item is explicitly set to hidden. + \endtable + + \section2 Setting Expressions + + \l{http://doc.qt.nokia.com/4.7/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 "Element 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://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} + {Integrating JavaScript}. + + \section2 Marking Text Elements for Translation + + To support translators, mark each text element that should be translated. + In the \gui Properties pane, \gui Text field, select \gui tr. + + \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 element, the ListModel and the delegate + component 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 a component which 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: + + \snippet snippets/qml/dummydata.qml 0 + + 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: + + \snippet snippets/qml/datamodel.qml 0 + + \section3 Creating Dummy Context + + The following example presents a common pattern in QML: + + \code + Item { + width: parent.width + height: parent.height + } + \endcode + + 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: + + \snippet snippets/qml/dummydatacontext.qml 0 + + \section2 Setting Anchors and Margins + + In addition to arranging elements in a grid, row, or column, you can use + \l{http://doc.qt.nokia.com/4.7/qml-anchor-layout.html}{anchors} to lay out + screens. In an anchor-based layout, each item 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 elements. 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 objects in + the corners of the parent element or center them horizontally or vertically + within the parent element. + + \image qmldesigner-anchor-buttons.png "Anchor buttons" + + In version 2.1, 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 element to its siblings and + direct parent. By default, an element is anchored to its parent when you + use the anchor buttons. Select a sibling of the element 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 element are always + specified to the same side. However, anchors to sibling elements are specified + to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep + sibling elements together. + + In the following image, \gui{Rectangle 2} is anchored to its siblings on its + right and left and to the bottom of its parent. + + \image qmldesigner-anchors.png "Anchoring sibling elements" + + The anchors for \gui{Rectangle 2} are specified as follows in code: + + \qml + Rectangle { + id: rectangle2 + anchors.right: rectangle3.left + anchors.rightMargin: 15 + 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 elements, see + \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}. + + \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 interface elements 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 object 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 + + \o Show some UI elements and hide others. + + \o Present different available actions to the user. + + \o Start, stop or pause animations. + + \o Execute some script required in the new state. + + \o Change a property value for a particular item. + + \o Show a different view or screen. + + \endlist + + The \gui State pane displays the different + \l{http://doc.qt.nokia.com/4.7/qdeclarativestates.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 Elements + + The position of an element on the canvas can be either absolute or relative + to other elements. In the element properties, you can set the x and y + coordinates of an element, or \l{Setting Anchors and Margins}{anchor} it to + its parent and sibling elements. + + \section2 Snap to Margins + + When you are working on a design, you can use snap and guides to align + elements on the canvas. Click the + \inlineimage qmldesigner-snap-to-guides-button.png + button to have the elements snap to the guides. + + Choose \gui {Tools > Options > Qt Quick} to specify settings for snap to + margins. In the \gui {Snap margin} field, specify the position of the guides + as pixels from the edge of the canvas. In the \gui {Item spacing} field, + specify the space in pixels to leave between elements on the screen. + + The following image shows the position of the guides when \gui {Snap margin} + is set to 5 pixels. + + \image qmldesigner-snap-margins.png "Snap margins on canvas" + + \section2 Hiding Element Boundaries + + Qt Quick Designer displays the boundaries of elements on the canvas. To hide + the element boundaries, click the + \inlineimage qmldesigner-show-bounding-rectangles-button.png + button. + + \section2 Selecting Elements + + When you point the mouse to overlapping elements, the frontmost element is + selected by default. However, elements that do not have any content, such as + the mouse area, are typically located in front of elements that do have + content, such as rectangles or border images. To select elements with content + by default, click the + \inlineimage qmldesigner-only-select-items-with-content.png + button. + + \section2 Previewing Element Size + + The width and height of the root item in a QML file determine the size of + the QML element. You can reuse elements, 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 element sizes, enter values in the + \gui Height and \gui Width fields on the canvas toolbar. The changes are + displayed in the \gui States pane and on the canvas, but the property + values are not changed permanently in the QML file. You can permanently + change the property values in the \gui Properties pane. + + \image qmldesigner-preview-size.png "Canvas width and height" + + \section1 Specifying Canvas Size + + To change the canvas size, select \gui {Tools > Options > Qt Quick} and + specify the canvas width and height in the \gui Canvas group. + + \section1 Refreshing the Canvas + + When you open QML files in \QMLD, the QML elements in the file are drawn on + the canvas. When you edit the element 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. + +*/ diff --git a/doc/src/qtquick/qtquick-toolbars.qdoc b/doc/src/qtquick/qtquick-toolbars.qdoc new file mode 100644 index 00000000000..1849a49687b --- /dev/null +++ b/doc/src/qtquick/qtquick-toolbars.qdoc @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.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 info@qt.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-editor-refactoring.html + \page qt-quick-toolbars.html + \nextpage creator-editor-locator.html + + \title Using Qt Quick Toolbars + + When you edit QML code in the code editor, you specify the properties + of QML components. For some properties, such as colors and font names, + this is not a trivial task. For example, few people can visualize the + color #18793f. + + To easily edit these properties, you can use the Qt Quick Toolbars. + When you select a component in the code and a toolbar is available, + a light bulb icon appears: + \inlineimage qml-toolbar-indicator.png + . Select the icon to open the toolbar. + + To open toolbars immediately when you select a component, select + \gui{Tools > Options > Qt Quick > Qt Quick Toolbar > Always show Quick + Toolbar}. + + Drag the toolbar to pin it to another location. Select + \inlineimage qml-toolbar-pin.png + to unpin the toolbar and move it to its default location. To pin toolbars + by default, select \gui{Tools > Options > Qt Quick > Qt Quick Toolbar + > Pin Quick Toolbar}. + + \section1 Previewing Images + + The Qt Quick Toolbar for images allows you to edit the properties of + \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image} + and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components. + You can scale and tile the images, replace them with other images, + preview them, and change the image margins. + + \image qml-toolbar-image.png "Qt Quick Toolbar for images" + + To preview an image, double-click it on the toolbar. In the preview + dialog, you can zoom the image. Drag the image margins to change them. + + \image qml-toolbar-image-preview.png "Image preview dialog" + + \section1 Formatting Text + + The Qt Quick Toolbar for text allows you to edit the properties of + \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components. + You can change the font family and size as well as text formatting, style, + alignment, and color. + + If a property is assigned an expression instead of a value, you + cannot use the toolbar to edit it. The button for editing the property + is disabled. + + \image qml-toolbar-text.png "Qt Quick Toolbar for text" + + By default, font size is specified as pixels. To use points, instead, + change \gui px to \gui pt in the size field. + + \section1 Previewing Animation + + The Qt Quick Toolbar for animation allows you to edit the properties of + \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html} + {PropertyAnimation} components and the components that inherit it. You can + change the easing curve type and duration. For some curves, you can also + specify amplitude, period, and overshoot values. + + \image qml-toolbar-animation.png "Qt Quick Toolbar for animation" + + Select the play button to preview your changes. + + \section1 Editing Rectangles + + The Qt Quick Toolbar for rectangles allows you to edit the properties of + \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle} + components. You can change the fill and border colors and add + gradients. + + \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles" + + To add gradient stop points, click above the gradient bar. To remove + stop points, drag them upwards. + +*/