/**************************************************************************** ** ** This file is part of Qt Creator ** ** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies). ** ** Contact: http://www.qt-project.org/ ** ** ** GNU Free Documentation License ** ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of this ** file. ** ** ****************************************************************************/ // ********************************************************************** // NOTE: the sections are not ordered by their logical order to avoid // reshuffling the file each time the index order changes (i.e., often). // Run the fixnavi.pl script to adjust the links to the index order. // ********************************************************************** /*! \contentspage index.html \previouspage quick-projects.html \page creator-using-qt-quick-designer.html \nextpage quick-components.html \title Using Qt Quick Designer You can edit .qml files in the \QMLD visual editor or in the code editor. 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 (1) displays the QML elements in the current QML file as tree structure. \o \gui {Library} pane (2) 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 (3) is the working area where you create QML components and design applications. \o \gui {Properties} pane (4) 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 (5) 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 (1) are listed in a tree structure, below their parent (2). \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 (1). \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 z Property}. \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 (1) 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 (Qt 4.7) \o \c {import com.nokia.symbian 1.1} for Symbian (Qt 4.8) \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 (1) and \gui Text (2) 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 Size (1) and \gui Colors (2) values are explicitly set and highlighted. \image qmldesigner-properties-explicit-base.png "Explicitly set properties" In \gui State1, only the color (1) is explicitly set and highlighted. \image qmldesigner-properties-explicit-state1.png "Explicitly set properties" Resetting a property sets it back to the default value and removes the value from the .qml file. \note As a result, all boolean values can be visualized in four different ways. For example, visibility can be visualized as follows: \table \row \o \image qmldesigner-boolean-true.png \o TRUE \o The element is visible by default. The visibility might be overridden by the visibility set in the base state. \row \o \image qmldesigner-boolean-true-blue.png \o TRUE (highlighted) \o The element is explicitly set to visible. \row \o \image qmldesigner-boolean-false.png \o FALSE \o The element is hidden by default. The visibility might be overridden by the visibility set in the base state. \row \o \image qmldesigner-boolean-false-blue.png \o FALSE (hightlighted) \o 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 (1). \image qmldesigner-text-property-tr.png "Text properties" The text string is enclosed in a \c qsTr call. \image qml-translate.png "Text marked for translation" \section2 Loading Placeholder Data \QMLD supports views, models, and delegates, so that when you add a Grid View, List View, or Path View 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 \gui{Rectangle 1} on its 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.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 > Qt Quick Designer} 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 (1) on the canvas toolbar. The changes are displayed in the \gui States pane (2) and on the canvas (3), but the property values are not changed permanently in the QML file. You can permanently change the property values in the \gui Properties pane (4). \image qmldesigner-preview-size.png "Canvas width and height" \section1 Specifying Canvas Size To change the canvas size, select \gui {Tools > Options > Qt Quick > Qt Quick Designer} and specify the canvas width and height in the \gui Canvas group. \section1 Refreshing the Canvas When you open QML files in \QMLD, the 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. */