diff options
Diffstat (limited to 'doc/qtdesignstudio/src')
53 files changed, 9524 insertions, 2 deletions
diff --git a/doc/qtdesignstudio/src/components/qtquick-animation-types.qdoc b/doc/qtdesignstudio/src/components/qtquick-animation-types.qdoc new file mode 100644 index 0000000000..f8ffb2918d --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-animation-types.qdoc @@ -0,0 +1,245 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-animations.html + \if defined(qtdesignstudio) + \previouspage quick-logic-helpers.html + \else + \previouspage quick-data-models.html + \endif + \nextpage studio-3d-view.html + + \title Animations + + To create an animation, use the appropriate animation type for the property + that is to be animated, and apply the animation depending on the type of + behavior that is required. + + You can drag-and-drop animation components from \l Library > + \uicontrol Components > \uicontrol {Default Components} > + \uicontrol Animation to \l Navigator or \l {Form Editor} to + create instances of them. + + You can achieve similar results by using different animation techniques. + For more information, see \l{Introduction to Animation Techniques}. + + \section1 Applying Animation + + A property animation is applied when the value of a property changes. + Color and number animations are property animation types for specific + purposes. Specify settings for animations in \l Properties > + \uicontrol {Animation Targets}. + + \section2 Animating Color Changes + + For example, you can apply animation to the value of the \uicontrol Color + property of an instance of a \l Rectangle component to change its value + from its current color to another color over a period of time specified in + milliseconds. + + \image qtquick-color-animation.gif "Color animation" + + First create an instance of the \uicontrol {Color Animation} component. + Select the component to animate in the \uicontrol Target field, and enter + the property to animate in the \uicontrol Property field. To animate several + properties, enter them into the \uicontrol Properties field separated by + commas. + + \image qtquick-properties-coloranimation.png "Color Animation properties" + + Select the original color in the \uicontrol {From color} field and the new + color in the \uicontrol {To color} field. Specify the duration of the + animation in the \uicontrol Duration field. + + \section2 Animating Changes in Numerical Values + + Similarly, to apply animation when a numerical value of a property changes, + create an instance of the \uicontrol {Number Animation} component. + + \image qtquick-properties-numberanimation.png "Number Animation properties" + + Select the original value in the \uicontrol From field and the new value in + the \uicontrol To field. Then specify the duration of the animation in the + \uicontrol Duration field. + + For example, you can apply animation to the value of the \uicontrol X + property of a \l Rectangle instance to make it appear to move from its + current position on the x axis to another position over a period of time + specified in milliseconds. To make the component appear to move both on + the x and y axis, enter x and y into the \uicontrol Properties field + separated by a comma. + + \image qtquick-number-animation.gif "Number animation" + + \if defined(qtdesignstudio) + For an example of using property animation to animate the scale and opacity + of components, see the \l{Coffee Machine} example. + \endif + + \section2 Setting Non-Animated Properties + + To immediately change a property value during an animation + without animating the property change, create an instance + of the \uicontrol {Property Action} component instead, and + set the value in the \uicontrol Value field. This is useful + for setting non-animated property values during an animation. + + \image qtquick-properties-propertyaction.png "Property Action properties" + + For example, you can create an instance of the + \uicontrol {Sequential Animation} component that contains two instances + of the \uicontrol {Property Action} component around an instance of the + \uicontrol {Number Animation} component. The first property action sets + the \uicontrol Opacity property of a \l{Rectangle} to \c 0.5, the number + animation changes the width of the image, and the second property action + sets the opacity back to \c 1. + + \image qtquick-property-action.gif "Sequential property actions and number animation" + + \section1 Playing Animations + + Specify settings for playing animations in the \uicontrol Animation group. + + \image qtquick-properties-animation.png "Animation properties" + + To run animations automatically, select the \uicontrol Running + check box. Animations are run for the time you specify in the + \uicontrol Duration field. + + You can connect the running property of an animation to a signal emitted + by a component to play the animation when users click a button, for + example. For more information, see \l{Connecting Components to Signals}. + + To run animations several times in a loop, set the number of times they + should play in the \uicontrol Loops field. Set the value to -1 to have + the animation continuously repeat until it is explicitly stopped. + + To specify that animations should run to completion when they are stopped, + select the \uicontrol {Run to end} check box. This behavior is most useful + when the \uicontrol Loops property is set, as the animation will finish + playing normally but not restart. + + All animations defined for a component are run in parallel, + unless you include them in a \uicontrol {Parallel Animation} or + \uicontrol {Sequential Animation} component for managing them as a + group. + + To pause animations, select the \inlineimage icons/pause-icon.png + (\uicontrol Paused) check box. + + To attach an \l{Editing Easing Curves}{easing curve} to + the animation, select the \inlineimage curve_editor.png + (\uicontrol {Easing Curve Editor}) button in the + \uicontrol {Easing Curve} field. + + \section2 Playing Groups of Animations + + You can create several animations that can run in parallel or in sequence. + To manage a group of animations that will play at the same time, create an + instance of a \uicontrol {Parallel Animation} component and drag-and-drop + the other animations to it. To play the animations in the specified order, + one after the other, create an instance of a + \uicontrol {Sequential Animation} instead. + + For example, a banner component may have several icons or slogans to + display, one after the other. The value of the \uicontrol Opacity property + could change to \c 1.0 denoting an opaque object. Using a sequential + animation, each opacity animation will play after the preceding animation + finishes, whereas using a parallel animation will play the animations at + the same time. + + Once individual animations are placed into a group of parallel or sequential + animations, they can no longer be started and stopped independently. The + sequential or parallel animations must be started and stopped as a group. + + When used in a \uicontrol {Sequential Animation}, a + \uicontrol {Pause Animation} is a step when nothing + happens, for a specified duration. To specify a pause + between two animations, select the \uicontrol Paused + check box and specify the duration of the pause in the + \uicontrol Duration field. + + \section1 Performance Considerations + + \QDS enables you to use fluidity and dynamic transitions as well as visual + effects to great effect in a UI. However, you need to take some care when + using some of the supported features because they can affect the + performance of the UI. + + In general, animating a property will cause any bindings which reference + that property to be re-evaluated. Usually, this is what is desired, but in + some cases it may be better to disable the binding prior to performing + the animation and then reassign the binding once the animation has + completed. + + Avoid running JavaScript during animation. For example, running a complex + JavaScript expression for each frame of an x property animation should be + avoided. + + Take special care when creating instances of the \uicontrol {Script Action} + component because script animations are run in the main thread and can + therefore cause frames to be skipped if they take too long to complete. + + \section1 Summary of Animation Components + + The following table lists the components that you can use to animate + component properties programmatically. They are available in \l Library + > \uicontrol Components > \uicontrol {Default Components} > + \uicontrol Animation + + \table + \header + \li Component + \li Use Case + \row + \li \uicontrol {Property Animation} + \li Applying animation when the value of a property changes. Color + and number animations are property animation types for specific + purposes. + \row + \li \uicontrol {Property Action} + \li Setting non-animated property values during an animation. + \row + \li \uicontrol {Color Animation} + \li Applying animation when a color value changes. + \row + \li \uicontrol {Number Animation} + \li Applying animation when a numerical value changes. + \row + \li \uicontrol {Parallel Animation} + \li Running animations in parallel. + \row + \li \uicontrol {Sequential Animation} + \li Running animations sequentially. + \row + \li \uicontrol {Pause Animation} + \li Creating a step in a sequential animation where nothing happens for + a specified duration. + \row + \li \uicontrol {Script Action} + \li Executing JavaScript during an animation. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-buttons.qdoc b/doc/qtdesignstudio/src/components/qtquick-buttons.qdoc new file mode 100644 index 0000000000..a92328e038 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-buttons.qdoc @@ -0,0 +1,285 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +// ********************************************************************** +// 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. +// ********************************************************************** + +/*! + \page quick-buttons.html + \previouspage quick-components-creating.html + \nextpage quick-scalable-image.html + + \title Creating Buttons + + To create a button component: + + \list 1 + + \li Select \uicontrol File > \uicontrol {New File or Project} > + \if defined(qtcreator) + \uicontrol Qt > \uicontrol {Qt Quick UI File} > + \else + \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} > + \endif + \uicontrol Choose to create a \l{UI Files}{UI file} called + Button.ui.qml (for example). + + \note Components are listed in \l Library > \uicontrol Components > + \uicontrol {My Components} only if the filename begins with a + capital letter. + + \li Click \uicontrol {Design} to edit the file in \l {Form Editor}. + + \li In \l Navigator, select \uicontrol Item and set the width + (\uicontrol W) and height (\uicontrol H) of the button in + \l Properties. + + \li Drag-and-drop a \uicontrol Rectangle from \l Library > + \uicontrol Components > \uicontrol {Default Components} > + \uicontrol Basic to the component in \uicontrol Navigator. This + creates a nested component where the Item is the parent of the + Rectangle. Components are positioned relative to their parents. + + \li In the \uicontrol Properties view, modify the appearance of the + rectangle: + + \list a + + \li In the \uicontrol Color field, select the button color. + + \li In the \uicontrol Radius field, set the radius of + the rectangle to produce rounded corners for the button. + + \li Select \uicontrol {Layout}, and then select the + \inlineimage icons/anchor-fill.png + (\uicontrol {Fill to Parent}) button to anchor the Rectangle to + the Item. + + + \endlist + + \li Drag-and-drop a \uicontrol {Text} component to the Item in + \uicontrol Navigator. + + \li In the \uicontrol Properties view, edit the properties of the + \uicontrol Text component + + \list a + + \li In the \uicontrol Text field, enter \e Button. + + You can select the text color in the \uicontrol {Text color} field and the + font, size, and style in the + \uicontrol Font section. + + \li In the \uicontrol Alignment field, select the center buttons to align + the text to the center of the button. + + \li Select \uicontrol Layout > \uicontrol {Fill to Parent} + to anchor the text to the whole button area. + + \endlist + + \li Press \key {Ctrl+S} to save the button. + + \image qmldesigner-button.png "Button component" + + \endlist + + To be useful, the button component has to be created in a project. + When you work on other files in the project to create screens + or other components for the UI, the button component appears in + \uicontrol Library > \uicontrol Components > \uicontrol {My Components}. + You can use it to create button instances and modify their properties + to assign them useful IDs, change their appearance, and set the button + text for each button instance, for example. + + To create a graphical button that scales beautifully without using + vector graphics, use the \l {Border Image} component. For more + information, see \l{Creating Scalable Buttons and Borders}. + */ + + +/*! + \previouspage quick-buttons.html + \page quick-scalable-image.html + \if defined(qtdesignstudio) + \nextpage qtquick-properties.html + \else + \nextpage studio-optimized-3d-scenes.html + \endif + + \title Creating Scalable Buttons and Borders + + You can use the \l {Border Image} component to display an image, such as a + PNG file, as a border and a background. + + Use two border images and suitable graphics to change the appearance of + a button when it is clicked. You can use use \l{Adding States}{states} + to determine which image is visible depending on whether the mouse + button is pressed down. You could add more images and states to + change the appearance of the button depending on other mouse events, + such as hovered. + + Use a \l Text component to add button text. + You can use states also to change the button text color and font size. For + example, you can scale the button text up or down. + + Add a \l {Mouse Area} component that covers the whole area and + reacts to mouse events. + + \image qmldesigner-borderimage-type.png "Button component in Form Editor and States" + + \section1 Creating the Button Component + + To create a button component, select \uicontrol File > + \uicontrol {New File or Project} > + \if defined(qtcreator) + \uicontrol Qt > \uicontrol {Qt Quick UI File} > + \else + \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} > + \endif + \uicontrol Choose to create a \l{UI Files}{UI file} called Button.ui.qml + (for example). + + \note Components are listed in \l Library > \uicontrol Components > + \uicontrol {My Components} only if the filename begins with a + capital letter. + + \section1 Constructing the Button Component + + To construct the button component: + + \list 1 + \li Click \uicontrol {Design} to edit the UI file in \l {Form Editor}. + \li Select \l Library > \uicontrol Assets > \inlineimage plus.png + to copy the image files you want to use to the project folder. + \li In \l Navigator, select the root component and set the + width (\uicontrol W) and height (\uicontrol H) of the button in the + \l Properties view to match the size of the images + you plan to use. This specifies the initial size of the button + component. + \li Drag-and-drop two \uicontrol {Border Image} components from + \uicontrol Library > \uicontrol Components > + \uicontrol {Default Components} > \uicontrol Basic to the root + component in \uicontrol Navigator. + \li Drag-and-drop a \uicontrol Text component to the root component. + \li Drag-and-drop a \uicontrol {Mouse Area} to the root component. + \li Select a border image to edit the values of its properties: + \list a + \li In the \uicontrol Id field, enter an ID for the border + image. In this example, we use the ID \e inactiveButton. + \li In the \uicontrol Source field, select the image file for + the border image. For example, inactive_button.png. + \li In the \uicontrol {Layout} tab, select the + \inlineimage icons/anchor-fill.png + (\uicontrol {Fill to Parent}) button to always make the + image the same size as its parent. This makes the button + component scalable, because the image size is bound to the + component size. + \endlist + \li Select the other border image to edit the values of its properties + similarly: + \list a + \li In the \uicontrol Id field, enter \e activeButton. + \li In the \uicontrol Source field, select the image file + for the button when it is clicked. For example, + active_button.png. + \li In the \uicontrol {Layout} tab, select the + \inlineimage icons/anchor-fill.png + (\uicontrol {Fill to Parent}) button. + \endlist + \li Select the text component to specify font size and color in + \uicontrol Properties: + \list a + \li In the \uicontrol Color field, use the \l{Picking Colors} + {color picker} to select the font color, or enter a value + in the field. + \li In \uicontrol Font group, \uicontrol Size field, enter the + font size. + \li In the \uicontrol {Layout} tab, select + \inlineimage icons/anchor-center-vertical.png + (\uicontrol {Vertical Center}) and + \inlineimage icons/anchor-center-horizontal.png + (\uicontrol {Horizontal Center}) buttons to inherit the + vertical and horizontal centering from the parent. + This ensures that the button label is centered when the + component is resized. + \endlist + \endlist + + \section1 Using States to Change Component Property Values + + \list 1 + \li In the \l States view, select \uicontrol {Create New State} + twice to create two new states. + \image qmldesigner-borderimage-states.png "Active and inactive states" + \li Select \uicontrol State1. + \li Change the state name to \e active. + \li Select \inlineimage icons/action-icon.png + , and then select \uicontrol {Set when Condition} to determine + when the state should be applied. + \li In the \uicontrol {Binding Editor}, select the \c mouseArea + component and the \c pressed signal to specify that the state is + applied when the mouse button is pressed down. + \image qmldesigner-borderimage-bindings.png "Active state when condition" + \li Select the text component in \uicontrol Navigator to specify that the + text size is scaled up when the button is pressed down. + \li In \uicontrol Properties, select the \uicontrol Advanced section, and + increase the value of the \uicontrol Scale property. + \li Select \e inactiveButton in \uicontrol Navigator to hide + it in the \e active state by changing the value of its + \uicontrol Visibility property in \uicontrol Properties. + \li Select \uicontrol State2. + \li Change the state name to \e inactive. + \li Set the when condition for the state to \c !mouseArea.pressed to + specify that the state is applied when the mouse button is not + pressed down. + \image qmldesigner-borderimage-bindings1.png "Inactive state when condition" + \li Press \key {Ctrl+S} to save the button. + \li Select the \inlineimage live_preview.png + (\uicontrol {Show Live Preview}) button to check how the + button behaves when you click it. You can drag the preview + window borders to see what happens when you resize the + component. + \endlist + + To be useful, the button component has to be created in a project. + When you work on other files in the project to create screens + or other components for the UI, the button component appears in + \l Library > \uicontrol Components > \uicontrol {My Components}. + You can drag-and-drop it to \uicontrol {Form Editor} or + \uicontrol Navigator to create button instances and modify the values + of their properties to assign them useful IDs, change their appearance, + and set the button text for each button instance, for example. + + For more information about positioning buttons on screens, see + \l{Scalable Layouts}. + + \image qmldesigner-borderimage.png "Button preview as part of a screen" +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc b/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc new file mode 100644 index 0000000000..af83a8e918 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-component-context-menu.qdocinc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! +//! [context-menu] + \section1 Context Menu + + The following table summarizes the \uicontrol Navigator and + \uicontrol {Form Editor} context menu items and provides links + to more information about them. + + \table + \header + \li To Learn About + \li Go To + \row + \li Arrange + \li \l{Arranging Components} + \row + \li Edit + \li \l{Showing and Hiding Components} + \row + \li Anchors + \li \l{Setting Anchors and Margins} + \if defined(qtdesignstudio) + \row + \li Group + \li \l{Organizing Components} + \endif + \row + \li Position + \li \l{Using Positioners} + \row + \li Layout + \li \l{Using Layouts} + \row + \li Stacked Container + \li \l{Lists and Other Data Models} + \row + \li Timeline + \li \l{Creating Timelines} + \if defined(qtdesignstudio) + \row + \li Event List + \li \l{Simulating Events} + \endif + \row + \li Edit Color + \li \l{Editing Properties Inline} + \row + \li Edit Annotation + \li \l{Annotating Designs} + \row + \li Merge File with Template + \li \l{Merging Files with Templates} + \row + \li Move Component Instances into Separate Files + \li \l{Turning Component Instances into Custom Components} + \row + \li Add New Signal Handler + \li \l{Adding Signal Handlers} + \row + \li Go to Implementation + \li \l{Using UI Files} + \row + \li Go into Component + \li \l{Moving Within Components} + \endtable +//! [context-menu] +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-component-instances.qdoc b/doc/qtdesignstudio/src/components/qtquick-component-instances.qdoc new file mode 100644 index 0000000000..eb2e12f8f9 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-component-instances.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-component-instances.html + \previouspage studio-3d-loader-3d.html + \nextpage quick-components-creating.html + + \title Creating Component Instances + + \QDS comes with \e {preset components} that you can use in your UI by + creating instances of them. + + \image qmldesigner-editing-components.png "Creating Component Instances" + + To create component instances and edit their properties: + + \list 1 + \li Drag-and-drop components from \uicontrol Library (1) to + \l Navigator (2), \l {Form Editor} (3), or \l {3D Editor} (4). + This creates instances of the components in the current + component file. + \li Select component instances in \uicontrol Navigator to edit the + values of their properties in \uicontrol Properties. + \image qmldesigner-properties-view.png "Properties view" + For more information, see \l {Specifying Component Properties}. + \li To change the appearance and behavior of the component instances + in ways that are not supported in \QDS by default, you can define + custom properties in \l {Connection View} > \uicontrol {Properties}. + \image qmldesigner-dynamicprops.png "Connection View Properties tab" + For more information, see \l{Specifying Dynamic Properties}. + \li To enable users to interact with the component instances, connect + the instances to signals in \uicontrol {Connection View} > + \uicontrol Connections. For example, you can specify what happens + when a component instance is clicked. For more information, see + \l{Connecting Components to Signals}. + \image qmldesigner-connections.png "Connection View Connections tab" + \li To dynamically change the behavior of a component instance when + another component instance changes, create bindings between them in + \uicontrol {Connection View} > \uicontrol Bindings. + For more information, see \l{Adding Bindings Between Properties}. + \image qmldesigner-bindings.png "Connection View Bindings tab" + \li Add states to apply sets of changes to the property values of one + or several component instances in the \uicontrol States view. + For more information, see \l{Adding States}. + \li Animate the properties of component instances in the + \uicontrol Timeline view. For more information, see + \l{Creating Timeline Animations}. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-components-custom.qdoc b/doc/qtdesignstudio/src/components/qtquick-components-custom.qdoc new file mode 100644 index 0000000000..dc7ba75268 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-components-custom.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-components-creating.html + \previouspage quick-component-instances.html + \nextpage quick-buttons.html + + \title Creating Custom Components + + You can either use project wizard templates to create custom components and + controls or move component instances into separate files to turn them into + new components that you can create instances of. You can then use the + instances of the new components in other components. + + \image qtquick-components-custom.png "Custom components in My Components" + + Custom components are stored in \l Library > \uicontrol Components > + \uicontrol {My Components}. You can create instances of custom components + by dragging-and-dropping them from \uicontrol Library to \l {Form Editor}, + \l {3D Editor}, or \l Navigator. + + \section1 Creating Components from Scratch + + To use wizard templates to create custom components: + + \list 1 + \li Select \uicontrol File > \uicontrol {New File or Project} > + \if defined(qtcreator) + \uicontrol Qt > \uicontrol {Qt Quick UI File} > + \else + \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} > + \endif + \uicontrol Choose to create a new \c .ui.qml file. + \note Components are listed in \uicontrol Library > + \uicontrol Components > \uicontrol {My Components} only + if the filename begins with a capital letter. + \li Click \uicontrol Design to open the file in + \uicontrol {Form Editor}. + \li Drag-and-drop a component from \uicontrol Library to + \uicontrol Navigator or \uicontrol {Form Editor}. + \li Edit component properties in the \uicontrol Properties view. + The available properties depend on the component type. You can + \l{Specifying Dynamic Properties}{add properties for + components} in \uicontrol {Connection View} > \uicontrol Properties. + \li To change the appearance and behavior of the component instances + in ways that are not supported in \QDS by default, you can define + custom properties in \uicontrol {Connection View} > + \uicontrol {Properties}. + + \endlist + + The following sections contain more information about how to use + \uicontrol {Form Editor} to edit 2D content and \uicontrol {3D Editor} + to edit 3D scenes, as well as examples of how to create UI controls + using instances of basic components: + + \list + \li \l{Form Editor} + \li \l{3D Editor} + \li \l{Creating Buttons} + \li \l{Creating Scalable Buttons and Borders} + \endlist + + \section1 Naming Conventions + + Establish naming conventions to keep the components in your UI organized. + Name your components accurately and give them suitable IDs. Particularly, + check and modify the default names of the components you export from design + tools to create reliable and self-explanatory names that follow the naming + conventions you have established. + + For example, a button symbol might have the ID \e myButton_symbol and the + different layers might have it as a prefix with the states appended, thus + producing IDs such as \e myButton_symbol_default. To prepare for additional + mouse areas later in the project, you could use similar IDs for them, such + as \e myButton_symbol_hotspot. When you use the button as instances in a + screen, you would give each of these instances a unique ID that relates to + that screen. For example, \e myButton_myMenu_home, \e myButton_myMenu_profile, + and \e myButton_myMenu_settings + + \if defined(qtdesignstudio) + \include qtdesignstudio-components.qdocinc creating studio components + \endif + + \section1 Turning Component Instances into Custom Components + + An alternative way of creating reusable components is to turn + component instances into custom components by moving them into + separate component files (.ui.qml). Right-click a component instance + in \uicontrol Navigator or \uicontrol {Form Editor}, and select + \uicontrol {Move Component into Separate File} in the context menu. + + \image qtcreator-move-component-into-separate-file.png + + Give the new component a name, and select whether properties are set for + the new component or for the original one. + + When you select \uicontrol OK, a new component file is created and an + instance of the component is added to the code in the current component + file. The look of your UI in \uicontrol {Form Editor} does not change. + + To open the new component file for editing the properties that you want + to change for all instances of the component, right-click the component, + and then select \uicontrol {Go into Component} in the context menu. For + additional ways of opening base components, see \l{Moving Within Components}. + + For an example of creating a reusable custom component, see + \if defined(qtcreator) + \l{Creating a Mobile Application}. + \else + \l{Progress Bar}. + \endif + + Custom components are listed in \uicontrol Library > \uicontrol Components + > \uicontrol {My Components}, and you can use instances of them to build + more components. + + \include qtquick-mcu-support.qdocinc mcu qtquick components + + \section1 Merging Files with Templates + + You can merge the current component file against an existing second + component file using the second file in a way similar to using a CSS + stylesheet. + + To use this experimental feature, right-click a component in the + \uicontrol Navigator or \uicontrol {Form Editor} view and select + \uicontrol {Merge File with Template} in the context menu. + + \image qmldesigner-merge-with-template.png "Merge with Template dialog" + + In the \uicontrol Template field, select the file to use as a template. +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-components.qdoc b/doc/qtdesignstudio/src/components/qtquick-components.qdoc new file mode 100644 index 0000000000..d41d4d0bd3 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-components.qdoc @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-components.html + \if defined(qtdesignstudio) + \previouspage studio-flow-external-events.html + \else + \previouspage creator-using-qt-quick-designer.html + \endif + \nextpage quick-preset-components.html + + \title Components + + A \e component is a reusable building block for a UI. + + \QDS comes with \e {preset components} that you can use in your UI by + creating instances of them. + The preset components are similar to \e Symbols in Sketch or \e Prefab in + Unity. + + Some of the preset components represent simple shapes, text, or images, + while others represent complex UI controls with full functionality, such + as spin boxes or sliders. You can also add instances of preset + \l {3D Components}{3D components} to your UIs. + + To build your own components, you can modify the \e properties of the + component instances and combine them. + + A component is specified within one file (with the file extension + \e ui.qml or \e .qml). For example, a Button component may be defined + in \e Button.ui.qml. Typically, the visual appearance of a component + is defined in a \e {UI file} (ui.qml). To create component files, + you can use \l{Creating Components from Scratch}{wizard templates}, or + \l{Turning Component Instances into Custom Components} + {move component instances into separate component files}. + + Select \l Library > \uicontrol Components to view the preset components that + have been added to your project. If you cannot find the components you need, + add the relevant modules to your project, as described in + \l {Adding and Removing Modules}. + + \image qtquick-components-tab.png "Components in Library" + + Read more about components: + + \list + \li \l {Preset Components} + \li \l {Creating Component Instances} + \li \l {Creating Custom Components} + \endlist + + \section1 Using Components Economically + + It is important to understand the performance costs associated with using + components. + + To use components efficiently and economically: + + \list + \li Componentize your design by packaging your resources into reusable + components that can be conveniently recombined to suit the needs of + your UI. + \li Use as few components as necessary. To minimize the number of + components, use \l{Adding Property Aliases}{alias properties} and + \l{Adding States}{states} to create the differences in your + component instances. We recommend reusing components + instead of duplicating them, so the components do not need to be + processed as completely new component types. This reduces loading + and compilation time as well as the size of the binary. + \li Any content that is data-driven should be exported as a public + property (alias property) of the relevant component. For example, + a speedometer should have an \c int or \c real property for speed + to which the UI is bound. + \li Separate UI from the application logic. Designers should work with + the \l{UI Files}{UI files} (.ui.qml), while developers should work + on the corresponding implementation files (.qml) to define their + programmatic behaviors or JavaScript. This enables iteration from + both the design and development side of the process without the the + risk of overwriting each other's work. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-controls.qdoc b/doc/qtdesignstudio/src/components/qtquick-controls.qdoc new file mode 100644 index 0000000000..a9153f6bcf --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-controls.qdoc @@ -0,0 +1,855 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-controls.html + \previouspage quick-user-interaction-methods.html + \nextpage quick-data-models.html + + \title UI Controls + + You can create instances of preset UI controls to inform users about + the progress of the application or to gather input from users. They are + available in \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls. + + \image qtquick-designer-qtquickcontrols-types.png "Qt Quick Controls components in Library" + + The following types of controls are available for user interaction: + + \list + \li \l {Button Controls} + \li \l {Indicators} + \li \l {Selectors} + \li \l {Tab Bar} + \li \l {Tool Bar} + \li \l {Summary of UI Controls} + \endlist + + You can specify values for the properties of component instances in the + \l Properties view. Some properties are common to all components, + whereas some are common to particular types of controls. Some properties + are only available for a particular control. The following sections + describe the preset UI controls and their properties. + + \section1 General Control Properties + + You can set control properties in the \l Properties view. + + \image qtquick-designer-control-properties.png "Control section in Properties" + + The \uicontrol Enable check box indicates whether the control is enabled. + + The value of the \uicontrol {Focus policy} field determines whether the + control accepts focus by tabbing, clicking, and using the mouse wheel. + + Select the \uicontrol Hover and \uicontrol Wheel check boxes to enable the + control to accept mouse events. The hover value is propagated to all child + components, unless it has been explicitly set for them. + + \note Take care when enabling wheel events for controls within scrollable + components, such as \l Flickable, because the control will consume the + events, and therefore interrupt scrolling of the flickable. + + \uicontrol Spacing is useful for controls that have multiple or repetitive + building blocks. For example, some \l{Styling Controls}{styles} use spacing + to determine the distance between the text and indicator of a + \l {Check Box}. Spacing is not enforced by the controls, so each style may + interpret it differently, and some may ignore it altogether. + + \section1 Button Controls + + Qt Quick Controls offer a selection of button-like controls for specific + use cases. The following sections contain guidelines for choosing the button + most suitable for a use case and discuss the values you can set for button + properties in the \uicontrol Properties view. + + \image qtquick-designer-button-types.png "Button controls in Form Editor" + + Recommendations for buttons that contain text: + + \list + \li Keep labels short and concise. + \li Use the default font unless you have UI guidelines specifying + otherwise. + \li If the text is localized, consider how a longer text affects the + layout. + \endlist + + For more information about setting text properties, see + \l {Character Properties} and \l Padding. + + The properties that are shared by all button controls are described in: + + \list + \li \l {Displaying Text and Icons} + \li \l {Checking Buttons} + \li \l {Button Signals} + \endlist + + \section2 Button + + You can create an instance of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > \uicontrol Button: + + \image qtquickcontrols2-button.gif "Qt Quick Controls - Button" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create a \l{Creating Custom Controls} + {custom button}: + + \image studio-custom-button.gif "Custom button" + \endif + + A button can be pushed or clicked by users. Typically, buttons + are used to perform an action or to answer a question. For example, \e OK, + \e Apply, \e Cancel, \e Close, \e Yes, \e No, and \e Help. + + The button text should be a verb describing the action, or a noun matching + the title of the popup that will be opened. + + Don't use a button to set state, because a \l Switch is more suitable for + that purpose. + + \section3 Highlighted Buttons + + Select the \uicontrol Highlight check box in the \uicontrol Button section + to draw the users' attention towards a button. Highlighting a button has no + effect on keyboard interaction. + + \image qtquick-designer-button-properties.png "Button properties" + + The following image shows an example of a highlighted button: + + \image qtquickcontrols2-button-highlighted.gif "Highlighted button" + + \section3 Flat Buttons + + A flat button typically does not draw a background unless it is pressed or + checked. To create a flat button, select the \uicontrol Flat check box in + the \uicontrol Button section. + + The following image shows an example of a flat button: + + \image qtquickcontrols2-button-flat.gif "Flat button" + + \if defined(qtdesignstudio) + \section3 Icon Buttons + + To create a button that contains an icon, use the wizard template to + \l{Creating Custom Controls}{create a custom button} and drag-and-drop + the icon to the button background component. For an example of using the + wizard template, see \l{Creating a Push Button}. + \endif + + \section2 Delay Button + + \image qtquickcontrols2-delaybutton.gif "Delay button" + + The \uicontrol {Delay Button} control incorporates a delay before + triggering an action. This delay prevents accidental presses. + + Use delay buttons in touch UIs and for actions that must be + triggered with care. + + You can set the delay in milliseconds in the \uicontrol Delay field. + + \section2 Check Box + + You can create instances of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > + \uicontrol {Check Box}: + + \image qtquickcontrols2-checkbox.gif "Check boxes" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create \l{Creating Custom Controls} + {custom check boxes}: + + \image studio-custom-check-box.gif "Custom check boxes" + \endif + + A check box presents an option button that can be toggled on + (checked) or off (unchecked). Check boxes are typically used to select + one or more options from a set of options. For larger sets of options, + such as those in a list, consider creating an instance of the + \uicontrol {Check Delegate} control instead. + + \image qtquickcontrols2-checkdelegate.gif "Check delegate" + + A delegate can be highlighted in order to draw the user's attention towards + it. Highlighting has no effect on keyboard interaction. Select the + \uicontrol Highlight check box in the \uicontrol {Item Delegate} section to + highlight the delegate. + + Use check boxes to build multi-selection option lists where any number + of options can be selected, including none, but the options are not + mutually exclusive. + + Use a single check box for a yes/no choice, such as when users have to + accept the terms of service agreement in a dialog. For a single yes/no + choice, you can also use a \l Switch. If users are choosing between options, + use a check box. If they are choosing between actions to be taken, a switch + is recommended. + + The value of the \uicontrol Checked check box in the + \uicontrol {Button Content} section determines the state of the + check box. However, in addition to the checked and unchecked states, a + check box has a third state: \e {partially checked}. + + \image qtquick-properties-check-box.png "Check Box properties" + + Select the \uicontrol Tri-state check box in the \uicontrol {Check Box} + section to enable the check box to cycle between checked, partially + checked, and unchecked states when users toggle it by using touch, mouse, + or keyboard. + + \image qtquickcontrols2-checkbox-tristate.gif "Tri-state check box" + + When options can be grouped, you can use a partially checked check box to + represent the whole group. Select \uicontrol PartiallyChecked in the + \uicontrol {Check state} field to indicate that users selected some + sub-components in the group but not all of them. + + The checkable options are often listed vertically. + + The check box label should be a statement that the check mark makes true + and that the absence of a check mark makes false. Therefore, the check box + label should not contain a negative statement. + + \section2 Radio Button + + \image qtquickcontrols2-radiobutton.gif "Radio button" + + \uicontrol {Radio Button} is an option button that can be toggled on + (checked) or off (unchecked). Radio buttons are typically used to select + one option from a set of options. Selecting an option automatically clears + the previous selection. + + If there are only two mutually exclusive options, combine them into a single + \l {Check Box} or a \l Switch. + + \uicontrol {Radio Delegate} is similar to radio button, except that it is + typically used in views. + + \image qtquickcontrols2-radiodelegate.gif "Radio delegate" + + Select the \uicontrol Highlight check box in the \uicontrol {Radio Delegate} + section to highlight the delegate. + + Recommendations for radio buttons: + + \list + \li Limit the label text to one line. + \li Ensure that a sensible default option is checked. + \li List radio button options vertically. + \li Keep the list short. + \li In order to avoid confusion, do not put two groups of radio buttons + next to each other. + \endlist + + \section2 Switch + + You can create an instance of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > \uicontrol Switch: + + \image qtquickcontrols2-switch.gif "Switch" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create a \l{Creating Custom Controls} + {custom switch}: + + \image studio-custom-switch.gif "Custom switch" + \endif + + A switch is an option button that can be dragged or toggled on + (checked) or off (unchecked). Switches are typically used to select between + two states: \e on or \e off. For larger sets of options, such as those in a + list, consider using \uicontrol {Switch Delegate} instead. + + \image qtquickcontrols2-switchdelegate.gif "Switch delegate" + + Select the \uicontrol Highlight check box in the \uicontrol {Item Delegate} + section to highlight the delegate. + + Use a switch for binary operations that take effect immediately after the + switch is toggled. For example, use a switch to turn WiFi on or off. + + \section2 Round Button + + \uicontrol {Round Button} is a clickable control that starts an action, + or opens or closes a popup. A round button with a square image icon or + one-letter font icon is circular. A circular round button takes less space + than a normal button, and can also be used as a floating action button. + + In addition to common \l Button properties, a round button has the + \uicontrol Radius property, which holds the radius of the button. + + \image qtquick-designer-round-button-properties.png "Round Button properties" + + To create a relatively square button that has slightly rounded corners, use + a small value, such as 3. + + To create a completely circular button, use a value that is equal to half + of the width or height of the button, and make the button's width and height + identical. + + \section2 Displaying Text and Icons + + A button can contain text, an icon, or both. Specify the button text in + the \uicontrol Text field in the \uicontrol {Button Content} section. The + value of the \uicontrol Display field determines whether only text or an + icon is displayed, or when both are visible, whether the text is placed + beside the icon or under it. + + \image qtquick-designer-abstract-button-properties.png "Button Content properties" + + \section2 Checking Buttons + + A \e checkable button toggles between checked (on) and unchecked (off) when + users click on it or press the space bar while the button has active + focus. Select the \uicontrol Checkable check box to make a button checkable. + To make the button checked, select the \uicontrol Checked check box. + + Buttons that belong to the same parent component can be mutually exclusive. + Users can click a button to check it, and the previous selection is + cleared. Users cannot uncheck the currently checked button by clicking + it. Instead, they must click another button in the group to set the new + checked button for that group. + + Radio buttons and tab buttons are mutually exclusive by default. To make + other types of buttons mutually exclusive, select the \uicontrol Exclusive + check box. + + If the buttons don't belong to the same parent, checking and unchecking + buttons does not affect the other buttons in the group. + + \section2 Button Signals + + A button emits the \c clicked() signal when it is activated by users. + \l{Connecting Components to Signals}{Connect to this signal} to perform + the button's action. Buttons provide the following additional signals: + \c canceled(), \c doubleClicked(), \c pressed(), \c released(), and + \c pressAndHold() for long presses. + + Select the \uicontrol Auto-repeat check box to repeat the \c pressed(), + \c released(), and \c clicked() signals while the button is pressed and + held down. The \c pressAndHold() signal will not be emitted. + + \section1 Indicators + + Qt Quick Controls offer a selection of indicator-like controls, such as + busy indicator, page indicator, and progress bar, for specific use cases. + The following sections contain guidelines for choosing the indicator most + suitable for a use case. + + \image qtquick-designer-indicator-types.png "Indicator types" + + \section2 Busy Indicator + + \image qtquickcontrols2-busyindicator.gif "Busy indicator" + + \uicontrol {Busy Indicator} indicates that an operation is in progress, and + that the UI has to wait for the operation to complete. + + A busy indicator is similar to an indeterminate \l {Progress Bar}. Both can + be used to indicate background activity. The main difference is visual and + that a progress bar can also present a concrete amount of progress (when it + can be determined). Due to the visual difference, busy indicators and + indeterminate progress bars fit in different places in UIs. + + Select the \uicontrol Running check box to make the busy indicator visible. + + \image qtquick-properties-busy-indicator.png "Busy Indicator properties" + + Select the \uicontrol Live check box to provide live updates of the + progress. + + Typical places for a busy indicator are: + + \list + \li In the corner of a \uicontrol {Tool Bar} + \li As an overlay on top of a \uicontrol Page + \li On the side of an \uicontrol {Item Delegate} + \endlist + + \section2 Page Indicator + + \uicontrol {Page Indicator} is used to indicate the currently active page + in a container of multiple pages. Specify the number of pages in the + \uicontrol Count field. Select the current page in the \uicontrol Current + field. + + \image qtquick-properties-page-indicator.png "Page Indicator properties" + + Select the \uicontrol Interactive check box to determine that the page + indicator reacts to presses and automatically changes the value of the + \uicontrol Current field accordingly. + + Page indicators are typically quite small in order to avoid distracting the + user from the actual content of the UI. Therefore, they can be hard to + click, and might not be easily recognized as interactive by users. For these + reasons, they are best used to complement primary methods of navigation, + such as a \uicontrol {Swipe View}, not replace them. + + \target progress-bar-control + \section2 Progress Bar + + \image qtquickcontrols2-progressbar.gif "Progress bar" + + \uicontrol {Progress Bar} indicates the progress of an operation. You + can specify the initial value in the \uicontrol Value field, but it + should be updated regularly. Specify the range in the \uicontrol From + and \uicontrol To fields, which can both contain any value. + + \image qtquick-designer-progressbar-properties.png "Progress Bar properties" + + Select the \uicontrol Indeterminate check box when unable to determine the + size of the item being downloaded, or if the download progress might get + interrupted due to a network failure. + + \image qtquickcontrols2-progressbar-indeterminate.gif + + The indeterminate mode is similar to a \l {Busy Indicator} in that both can + be used to indicate background activity. Due to their visual differences, + indeterminate progress bars and busy indicators fit in different places in + UIs. + + Typical places for an indeterminate progress bar are: + + \list + \li At the bottom of a \uicontrol {Tool Bar} + \li Inline within the content of a \uicontrol Page + \li In an \uicontrol {Item Delegate} to show the progress + of a particular item + \endlist + + \section1 Selectors + + Qt Quick Controls offer a set of selector-like controls, such as sliders, + dial, spin box, combo box, and tumbler, for specific use cases. The + following sections contain guidelines for choosing the selector most + suitable for a use case. + + \image qtquick-designer-selector-types.png "Selector types" + + \target slider-control + \section2 Slider and Dial + + You can create an instance of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > \uicontrol Slider: + + \image qtquickcontrols2-slider.gif "Slider" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create a \l{Creating Custom Controls} + {custom slider}: + + \image studio-custom-slider.gif "Custom slider" + \endif + + A slider is used to select a value by sliding a handle along a + track, whereas \uicontrol {Range Slider} is used to select a range + specified by two values, by sliding each handle along a track. + + \image qtquickcontrols2-rangeslider.gif "Range slider" + + \uicontrol Dial is similar to a traditional dial knob that is found on + devices such as stereos or industrial equipment. It allows users to + specify a value within a range. + + You can create an instance of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > \uicontrol Dial: + + \image qtquickcontrols2-dial-no-wrap.gif "Dial" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create a \l{Creating Custom Controls} + {custom dial}: + + \image studio-custom-dial.gif "Custom dial" + \endif + + In the \uicontrol From and \uicontrol To fields, set the range of the + slider or dial. Set the value of the slide handle or dial in the + \uicontrol Value field. For a range slider, set the initial positions + of the first and second handles in the \uicontrol {Value 1} and + \uicontrol {Value 2} fields. Select the \uicontrol Live check box to + provide live updates of the value properties. + + \image qtquick-designer-range-slider-properties.png "Range slider properties" + + In the \uicontrol {Snap mode} field, set how the slider handles or dial + behave with regards to the value of the \uicontrol {Step size} field. By + default, they do not snap to step size, but you can set them to snap to it + either while being dragged or after being released. + + You can set slider orientation to horizontal or vertical in the + \uicontrol Orientation field. + + Modify the \uicontrol {Drag threshold} to determine the threshold at + which a touch drag event will be initiated. + + For more information, watch the following video: + + \youtube Ed8WS03C-Vk + + A dial supports circular, horizontal, and vertical input modes. For + applications where fast input is important, the circular input mode is + useful, as clicking the dial will move it directly to that position. + For applications where precise input is important, the horizontal and + vertical input modes are recommended, as these allow small adjustments to + be made relative to where the dial is clicked. These modes are also better + for dials where large jumps in values could be unsafe, such as a dial that + controls audio volume. Set the input mode in the \uicontrol {Input mode} + field. + + \image qtquick-designer-dial-properties.png "Dial properties" + + \section2 Spin Box + + You can create an instance of \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls} > \uicontrol Controls > + \uicontrol {Spin Box}: + + \image qtquickcontrols2-spinbox.png "Spin Box" + + \if defined(qtdesignstudio) + Alternatively, you can use a wizard to create a \l{Creating Custom Controls} + {custom spin box}: + + \image studio-custom-spinbox.gif "Custom spin box" + \endif + + A spin box enables users to choose an integer value by clicking + the up or down indicator buttons, or by pressing up or down on the keyboard. + Select the \uicontrol Editable check box to enable users to enter a text + value in the input field. + + The other spin box properties are similar to those of a \uicontrol {Dial}. + + \section2 Combo Box + + \image qtquickcontrols2-combobox.gif "Combo box" + + \uicontrol {Combo Box} is a combined button and popup list. It provides a + means of presenting a list of options to users in a way that takes up the + minimum amount of screen space. + + A combo box is used to select a value from a static multiple-line drop-down + list. Users cannot add new values, and only one option can be selected. + + Combo box values are provided by a \l{Lists and Other Data Models} + {data model}. The data model is usually a JavaScript array, a \l ListModel, + or an integer, but other types of data models are also supported. + + Select the \uicontrol Editable check box to auto-complete combo box text + based on what is available in the model. + + \image qtquick-designer-combobox-properties.png "Combo box properties" + + When using models that have multiple named roles, specify the role of + the \uicontrol {Display text} property in the \uicontrol {Text role} field. + To use a role of the model item that corresponds to the text role, enter + \c valueRole in the field. + + The \uicontrol {Current index} field contains the index of the item that + is displayed in the combo box. The default value is \c -1 when the combo + box is empty and \c 0 otherwise. + + A flat combo box does not draw a background unless it is + interacted with, which makes it blend into the UI. Use flat combo + boxes on a toolbar, for example, to match the flat look of tool + buttons. To create a flat combo box, select the \uicontrol Flat + check box. + + Recommendations for combo boxes: + + \list + \li If the number of values is very large, consider applying a filter. + \li If the number of values is small, consider using \l {Radio Button}, + so that users can see all options at the same time. + \li Set a default value, which should be the value that you expect + to be chosen most often. + \endlist + + \section2 Tumbler + + \image qtquickcontrols2-tumbler-wrap.gif + + \uicontrol Tumbler allows users to select an option from a spinnable + \e wheel of items. It is useful when there are too many options to use, for + example, a \l {Radio Button}, and too few options to require the use of an + editable \l {Spin Box}. It is convenient in that it requires no keyboard + usage and wraps around at each end when there are a large number of items. + + Specify the number of visible options in the \uicontrol {Visible count} + field. Select the index of the current option in the + \uicontrol {Current index} field. + + \image qtquick-designer-tumbler-properties.png "Tumbler properties" + + To enable wrapping, select the \uicontrol Wrap check box. + + \section1 Tab Bar + + \image qtquickcontrols2-tabbar.gif "Tab Bar" + + \uicontrol {Tab Bar} provides a tab-based navigation model, where users + can switch between different views or subtasks. A tab bar is commonly + used as a header or footer of an \l ApplicationWindow. Select the toolbar + position in the \uicontrol Position field. + + Typically, a tab bar contains a static set of \uicontrol {Tab Button} + controls that are defined as its children. The \uicontrol {Current index} + field in the \uicontrol Container section shows the index of the current + tab button. The default value is \c -1 when the tab bar is empty and + \c 0 otherwise. + + \image qtquick-designer-tabbar-properties.png "Tab Bar properties" + + You can specify content width (\uicontrol W) and height (\uicontrol H) + in the \uicontrol {Content size} field. + + If the total width of the buttons exceeds the available width of the tab + bar, it automatically becomes \l{Flickable}{flickable}. + + \image qtquickcontrols2-tabbar-flickable.png + + \section1 Tool Bar + + \image qtquickcontrols2-toolbar.png + + \uicontrol {Tool Bar} contains application-wide and context-sensitive + actions and controls, such as navigation buttons and search fields. A + toolbar is commonly used as a header or footer of an \l ApplicationWindow. + Select the toolbar position in the \uicontrol Position field. + + \image qtquick-designer-toolbar-properties.png "Tool Bar properties" + + \uicontrol {Tool Button} is nearly identical to \l Button, but it has a + graphical appearance that makes it more suitable for insertion into a + toolbar. + + A toolbar does not provide a layout of its own, but requires you to + position its contents, for instance by creating a \l RowLayout. If the + toolbar contains only one item, it will resize to fit the implicit item + size. This makes a toolbar particularly suitable for use together with + \l{Using Layouts}{layouts}. However, you can specify content width + (\uicontrol W) and height (\uicontrol H) in the \uicontrol {Content size} + field in the \uicontrol Pane section. + + \uicontrol {Tool Separator} is used to visually distinguish between + groups of items on a toolbar by separating them with a line. It can + be used in horizontal or vertical toolbars by setting the value of + the \uicontrol Orientation field. + + \section1 Styling Controls + + The preset UI controls can be \l {Styling Qt Quick Controls}{styled}. + \uicontrol {Form Editor} reads the preferred style from a + configuration file (\c qtquickcontrols2.conf). To change the + style, select another style from the list on the main toolbar. This + enables you to check how your UI looks when using the available + styles. + + \image qtquick-designer-style-list.png "Style menu on the toolbar" + + For an example of defining your own style and using it in the Design mode, + see \l {Qt Quick Controls 2 - Flat Style}. + + For more information about how to customize a particular control, see + \l{Customization Reference}. + + \if defined(qtcreator) + \section1 History of Qt Quick Controls + + In Qt 4, ready-made Qt Quick 1 Components were provided for creating + UIs with a native look and feel for a particular target platform. + In Qt 5.1, Qt Quick Controls, Dialogs, and Layouts were added for + creating classic desktop-style user interfaces using Qt Quick 2.1. The + Qt Quick Controls Styles could be used to customize Qt Quick Controls. + + Since Qt 5.7, \l {Qt Quick Controls 2} replace Qt Quick Controls 1 and + Qt Labs Controls. They provide lightweight components for creating performant + user interfaces for \l{glossary-device}{devices}. + + Qt Quick Controls 2 work in conjunction with Qt Quick and Qt Quick Layouts. + + The \QC project wizards create Qt Quick applications that use Qt Quick + 2 types or Qt Quick Controls 2 types. + + Even if you use Qt Quick Controls 2, you can still write cross-platform + applications, by using different sets of QML files for each platform. + + Some ready-made controls, such as a gauge, dial, status indicator, and + tumbler, are provided by the \l {Qt Quick Extras} module. + \endif + + \section1 Summary of UI Controls + + The following table lists preset UI controls with links to their developer + documentation. They are available in \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls}. The \e MCU column indicates which controls + are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li MCU + \li Purpose + \row + \li \inlineimage icons/busyindicator-icon16.png + \li \l [QtQuickControls]{BusyIndicator}{Busy Indicator} + \li + \li Indicates activity while content is being loaded. + \row + \li \inlineimage icons/button-icon16.png + \li \l [QtQuickControls]{Button} + \li \inlineimage ok + \li A push button that you can associate with an action. + \row + \li \inlineimage icons/checkbox-icon16.png + \li \l [QtQuickControls]{CheckBox}{Check Box} + \li \inlineimage ok + \li An option button that can be toggled on (checked) or off + (unchecked). + \row + \li \inlineimage icons/checkbox-icon16.png + \li \l [QtQuickControls]{CheckDelegate}{Check Delegate} + \li + \li An item delegate that can be toggled on (checked) or off + (unchecked). + \row + \li \inlineimage icons/combobox-icon16.png + \li \l [QtQuickControls]{ComboBox}{Combo Box} + \li + \li A combined button and popup list that is populated by using a data + model. + \row + \li \inlineimage icons/delaybutton-icon16.png + \li \l [QtQuickControls]{DelayButton}{Delay Button} + \li + \li An option button that is triggered when held down long enough. + \row + \li \inlineimage icons/dial-icon16.png + \li \l [QtQuickControls]{Dial} + \li \inlineimage ok + \li A circular dial that is rotated to set a value. + \row + \li \inlineimage icons/pageindicator-icon16.png + \li \l [QtQuickControls]{PageIndicator}{Page Indicator} + \li + \li Indicates the indicate the currently active page in a container of + multiple pages. + \row + \li \inlineimage icons/progressbar-icon16.png + \li \l [QtQuickControls]{ProgressBar}{Progress Bar} + \li \inlineimage ok + \li Indicates the progress of an operation. + \row + \li \inlineimage icons/radiobutton-icon16.png + \li \l [QtQuickControls]{RadioButton}{Radio Button} + \li \inlineimage ok + \li An option button that can be switched on (checked) or off + (unchecked). + \row + \li \inlineimage icons/radiobutton-icon16.png + \li \l [QtQuickControls]{RadioDelegate}{Radio Delegate} + \li + \li An item delegate that can be toggled on (checked) or off + (unchecked). + \row + \li \inlineimage icons/rangeslider-icon16.png + \li \l [QtQuickControls]{RangeSlider}{Range Slider} + \li + \li Enables users to select a range of values by sliding two handles + along a track. + \row + \li \inlineimage icons/roundbutton-icon16.png + \li \l [QtQuickControls]{RoundButton}{Round Button} + \li + \li A push button with rounded corners that you can associate with an + action. + \row + \li \inlineimage icons/slider-icon16.png + \li \l [QtQuickControls]{Slider} + \li \inlineimage ok + \li Enables users to select a value by sliding a handle along a track. + \row + \li \inlineimage icons/spinbox-icon16.png + \li \l [QtQuickControls]{SpinBox}{Spin Box} + \li + \li Enables users to specify a value by clicking the up or down buttons, + by pressing up or down on the keyboard, or by entering a value in + the box. + \row + \li \inlineimage icons/switch-icon16.png + \li \l [QtQuickControls]{Switch} + \li \inlineimage ok + \li An option button that can be toggled on or off. + \row + \li \inlineimage icons/switch-icon16.png + \li \l [QtQuickControls]{SwitchDelegate}{Switch Delegate} + \li + \li An item delegate with a switch indicator that can be toggled on or + off. + \row + \li \inlineimage icons/toolbar-icon16.png + \li \l [QtQuickControls] {TabBar}{Tab Bar} + \li + \li Enables users to switch between different views or subtasks. + \row + \li \inlineimage icons/toolbutton-icon16.png + \li \l [QtQuickControls]{TabButton}{Tab Button} + \li + \li A button that is functionally similar to \uicontrol Button, but + provides a look that is more suitable for a \uicontrol {Tab Bar}. + \row + \li \inlineimage icons/toolbar-icon16.png + \li \l [QtQuickControls]{ToolBar}{Tool Bar} + \li + \li A container of application-wide and context sensitive actions and + controls, such as navigation buttons and search fields. + \row + \li \inlineimage icons/toolbutton-icon16.png + \li \l [QtQuickControls]{ToolButton}{Tool Button} + \li + \li A button that is functionally similar to \uicontrol Button, but + provides a look that is more suitable for a \uicontrol {Tool Bar}. + \row + \li \inlineimage icons/toolseparator-icon16.png + \li \l [QtQuickControls]{ToolSeparator}{Tool Separator} + \li + \li Separates a group of items from adjacent items on a + \uicontrol {Tool Bar}. + \row + \li \inlineimage icons/tumbler-icon16.png + \li \l [QtQuickControls]{Tumbler} + \li + \li A spinnable wheel of items that can be selected. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc b/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc new file mode 100644 index 0000000000..2f07c78861 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-data-models.qdoc @@ -0,0 +1,271 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-data-models.html + \previouspage quick-controls.html + \if defined(qtdesignstudio) + \nextpage quick-2d-effects.html + \else + \nextpage quick-animations.html + \endif + + \title Lists and Other Data Models + + Applications typically need to handle and display data that is organized + into list or grid views. Models, views, and delegates are used for + this purpose. They modularize the visualization of data in order to give + you control over the different aspects of the data. For example, you can + swap a list view with a grid view with little changes to the data. + Similarly, encapsulating an instance of the data in a delegate allows + developers to dictate how to present or handle the data. + + A \e model contains the data and its structure. There are several + components for creating different types of models. A \e view is a container + that displays the data in a list or a grid, or along a path. A \e delegate + dictates how the data should appear in the view. The delegate takes each + piece of data in the model and encapsulates it. The data is then accessible + through the delegate. + + To visualize data, the view's model property is bound to a model and the + delegate property to a component. + + For more information, see \l{Models and Views in Qt Quick}. + + \section1 List and Grid Views + + Create instances of \uicontrol {List View} and \uicontrol {Grid View} + components to organize other component instances in list or grid format. + They are available in \l Library > \uicontrol Components > + \uicontrol {Default Components} > \uicontrol Views. + + A \uicontrol {List View} organizes other components as a list, whereas a + \uicontrol {Grid View} organizes them as a grid. By default, components + in list and grid views flow vertically from left to right. They are laid + out from left to right horizontally, and from top to bottom vertically. + + You can change the list view orientation in the \uicontrol Orientation + field and the grid view flow in the \uicontrol Flow field. You can change + the layout direction in the \uicontrol {Layout direction} field. By setting + values for these properties, you can produce a variety of layouts. + + \image qtquick-designer-listview-properties.png "List View properties" + + For a list view, you can specify space between list items in the + \uicontrol Spacing field. For a grid view, you can specify the width + and height of each cell in the \uicontrol W and \uicontrol H fields. + + \image qtquick-designer-gridview-properties.png "Grid View properties" + + Select the \uicontrol {Navigation wraps} check box to specify that key + navigation wraps around and moves the selection to the next line or cell + in the other end of the view when it reaches the end of the view. + + Both list and grid views are inherently \l {Flickable}{flickable}. + + The value of the \uicontrol {Snap mode} field determines how the view + scrolling will settle following a drag or flick. By default, the view + stops anywhere within the visible area. If you select \uicontrol SnapToRow, + the view settles with a row (or column for a grid view top-to-bottom flow) + aligned with the start of the view. If you select \uicontrol SnapOneRow, + the view will settle no more than one row or column away from the first + visible row at the time the mouse button is released. This option is + particularly useful for moving one page at a time. + + \section1 Delegate Cache + + The value of the \uicontrol Cache field determines whether delegates are + retained outside the visible area of the view. + + If this value is greater than zero, the view may keep as many delegates + instantiated as will fit within the cache specified. For example, if in + a vertical view the delegate is 20 pixels high, there are three columns + and the cache is set to 40, then up to six delegates above and below the + visible area may be created or retained. The cached delegates are created + asynchronously, allowing creation to occur across multiple frames and + reducing the likelihood of skipping frames. To improve painting performance, + delegates outside the visible area are not painted. + + The default value of this property is platform dependent, but will usually + be a value greater than zero. Negative values are ignored. + + The cache is not a pixel buffer. It only maintains additional instantiated + delegates. + + \note Setting the \uicontrol Cache property is not a replacement for + creating efficient delegates. It can improve the smoothness of scrolling + behavior at the expense of additional memory usage. The fewer items and + bindings in a delegate, the faster a view can be scrolled. It is important + to realize that setting a cache will only postpone issues caused by + slow-loading delegates, it is not a solution to this problem. + + \section1 View Highlight + + In the \uicontrol {List View Highlight} and \uicontrol {Grid View Highlight} + sections, you can specify properties for highlighting items in views. + + \image qtquick-designer-listview-highlight-properties.png "List View Highlight properties" + + The current item in a list or grid view is higlighted if you set + the value of the \uicontrol Range field to \uicontrol ApplyRange + or \uicontrol StrictlyEnforceRange. When you select to apply the + range, the view attempts to maintain the highlight within the range. + However, the highlight can move outside of the range at the ends of + the view or due to mouse interaction. When you select to enforce the + range, the highlight never moves outside of the range. The current + item changes if a keyboard or mouse action would cause the highlight + to move outside of the range. + + The values of the \uicontrol {Preferred begin} and \uicontrol {Preferred end} + fields affect the position of the current item when the view is scrolled. + For example, if the currently selected item should stay in the middle of the + view when it is scrolled, set the begin and end values to the top and bottom + coordinates of where the middle item would be. If the current item is + changed programmatically, the view will automatically scroll so that the + current item is in the middle of the view. The begin value must be less than + the end value. + + Select the \uicontrol {Follows current} check box to enable the view to + manage the highlight. The highlight is moved smoothly to follow the current + item. Otherwise, the highlight is not moved by the view, and any movement + must be implemented by the highlight. + + The values of the \uicontrol {Move duration}, \uicontrol {Move velocity}, + \uicontrol {Resize duration}, and \uicontrol {Resize velocity} fields + control the speed of the move and resize animations for the highlight. + + \section1 Editing List Models + + When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or + \l{PathView}{Path View}, the ListModel and the delegate component that + creates an instance for each item in the model are added automatically. + For grid and list views, you can edit the list model in \QC. + + \image qtquick-designer-listview-preview.png "Preview of a list view" + + To edit list models: + + \list 1 + \li Drag-and-drop a \uicontrol {Grid View} or \uicontrol {List View} + from \uicontrol Library > \uicontrol Components > + \uicontrol {Default Components} > \uicontrol Views to + \uicontrol Navigator or \uicontrol {Form Editor}. + \li Right-click the view in \uicontrol Navigator, and select + \uicontrol {Edit List Model} in the context-menu to open + the list model editor: + \image qtquick-designer-edit-list-model.png "List view in model editor" + \li Double-click the column headings and cells to change their values. + \li Use the toolbar buttons to add, remove, or move rows and columns. + In a list, each column represents a property and each row adds a + list item. + \endlist + + You can replace the default model and delegate with other, + more complex models and delegates in \l {Text Editor}. + \l{ItemDelegate}{Item Delegate} and \l{SwipeDelegate}{Swipe Delegate} + components are also available in \uicontrol Library > \uicontrol Components + > \uicontrol {Qt Quick Controls}. + + \include qtquick-pathview-editor.qdocinc pathview + \if defined(qtdesignstudio) + \include qtquick-pathview-editor.qdocinc svgpath + \endif + + \section1 Summary of Model Components + + The following table lists the components that you can use to add data models + to UIs. The \e Location column indicates the location of the component in + \l Library > \uicontrol Components. The \e MCU column indicates which + components are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li Location + \li MCU + \li Purpose + \row + \li \inlineimage gridview-icon16.png + \li \l{GridView}{Grid View} + \li Default Components - Views + \li + \li A grid vizualization of a model. + \row + \li \inlineimage icons/itemdelegate-icon16.png + \li \l{ItemDelegate}{Item Delegate} + \li Qt Quick Controls + \li + \li A standard view item that can be used as a delegate in various + views and controls, such as \l ListView and \l ComboBox. + \row + \li \inlineimage listview-icon16.png + \li \l{ListView}{List View} + \li Default Components - Views + \li \inlineimage ok + \li A list vizualization of a model. + \row + \li \inlineimage pathview-icon16.png + \li \l{Path View} + \li Default Components - Views + \li + \li Vizualizes the contents of a model along a path. + \row + \li \inlineimage icons/scrollview-icon16.png + \li \l [QtQuickControls] {ScrollView}{Scroll View} + \li Qt Quick Controls + \li + \li Provides scrolling for user-defined content. It can be used instead + of a \l Flickable component. + \row + \li \inlineimage icons/stackview-icon16.png + \li \l [QtQuickControls] {StackView}{Stack View} + \li Qt Quick Controls + \li + \li A stack-based navigation model. + \if defined(qtdesignstudio) + \row + \li \inlineimage icons/item-svg-16px.png + \li \l{SVG Path Item} + \li Qt Quick Studio Components + \li + \li An SVG path data string that is used to draw a path as a line. + \endif + \row + \li \inlineimage icons/itemdelegate-icon16.png + \li \l{SwipeDelegate}{Swipe Delegate} + \li Qt Quick Controls + \li + \li A view item that can be swiped left or right to expose more + options or information. It is used as a delegate in views such + as \l ListView. + \row + \li \inlineimage icons/swipeview-icon16.png + \li \l[QtQuickControls] {SwipeView}{Swipe View} + \li Qt Quick Controls + \li \inlineimage ok + \li Enables users to navigate pages by swiping sideways. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-images.qdoc b/doc/qtdesignstudio/src/components/qtquick-images.qdoc new file mode 100644 index 0000000000..407c2715b5 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-images.qdoc @@ -0,0 +1,280 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-images.html + \previouspage quick-text.html + \nextpage quick-user-interaction-methods.html + + \title Images + \target basic-image + + The Image component is used for adding images to the UI in several supported + formats, including bitmap formats, such as PNG and JPEG, and vector graphics + formats, such as SVG. To use any image files in your designs, you need to + first add them to \l Library: + \list 1 + \li Select \uicontrol Library > \uicontrol Assets + > \inlineimage plus.png + . + \li Select the image file, and then select \uicontrol Open. + \li Select the location where the image will be saved in the + \uicontrol {Add Resources} dialog. + \li Select \uicontrol OK. + \endlist + + Your image is now available in \uicontrol Library > \uicontrol Assets. + + \image qtquick-designer-image-type.png "Image component in different views" + + When you drag-and-drop an image file from \uicontrol Library > + \uicontrol Assets to \l Navigator or \l {Form Editor}, \QC automatically + creates an instance of the Image component for you with the path to the + image file set as the value of the \uicontrol Source field in + \uicontrol Properties. + + To load images from a URL using a supported URL scheme, specify the URL + in the \uicontrol Source field. + + You can use the \l {Border Image} component to display an image, + such as a PNG file, as a border and a background. For more + information about using border images to create buttons, see + \l {Creating Scalable Buttons and Borders}. + + If you need to display animated images, such as GIFs, use the + \l {Animated Image} component. + + \section1 Image Size + + \image qtquick-designer-image-properties.png "Image properties" + + If the image \uicontrol Size is not specified, the size of the source + image is used automatically. + + By default, explicitly setting the width and height of the component causes + the image to be scaled to that size. To change this behavior, set the + value of the \uicontrol {Fill mode} field. Images can be stretched, tiled, + or scaled uniformly to the specified size with or without cropping. The + \uicontrol Pad option means that the image is not transformed. + + \note If the \uicontrol Clip check box is not selected, the component might + paint outside its bounding rectangle even if the \uicontrol {Fill mode} + is set to \uicontrol PreserveAspectCrop. + + Select the \uicontrol Smooth check box to smoothly filter images when scaled + or transformed. Smooth filtering gives better visual quality, but it may be + slower on some hardware. If the image is displayed at its natural size, + this property has no visual or performance effect. + + Select the \uicontrol Mipmap check box to use mipmap filtering when scaling + or transforming images. Mipmap filtering gives better visual quality when + scaling down compared with smooth filtering, but it may come at a + performance cost both when initializing the image and during rendering. + + Select the \uicontrol {Auto transform} check box if the image should + automatically apply image transformation metadata, such as EXIF orientation. + + \section1 Source Size + + The \uicontrol {Source size} property specifies the scaled width and height + of the full-frame image. Unlike the value of the \uicontrol Size property, + which scales the painting of the image, this property sets the maximum + number of pixels stored for the loaded image so that large images do not + use more memory than necessary. This ensures the image in memory is no + larger than the set source size, regardless of its set size. + + If the image's actual size is larger than the source size, the image is + scaled down. If only one dimension of the size is set to greater than 0, + the other dimension is set in proportion to preserve the source image's + aspect ratio. The \uicontrol {Fill mode} is independent of this. + + If both the source size width and height are set, the image is scaled + down to fit within the specified size maintaining the image's aspect ratio. + However, if \uicontrol PreserveAspectCrop or \uicontrol PreserveAspectFit + are used, the image is scaled to match the optimal size for cropping or + fitting. + + If the source is an intrinsically scalable image (such as SVG), source size + determines the size of the loaded image regardless of intrinsic size. + Avoid changing the source size property dynamically, because rendering an + SVG is slow compared with rendering other image formats. + + If the source is a non-scalable image (such as JPEG), the loaded image will + be no greater than the source size specifies. For some formats, the whole + image will never actually be loaded into memory. + + \note Changing this property dynamically causes the image source to be + reloaded, potentially even from the network, if it is not in the disk cache. + Select the \uicontrol Cache check box to cache the image. + + \section1 Image Alignment + + You can align images horizontally and vertically in the + \uicontrol {Alignment H} and \uicontrol {Alignment V} + fields. By default, images are centered. + + Select the \uicontrol Mirror check box to horizontally invert the image, + effectively displaying a mirrored image. + + \section1 Performance + + By default, locally available images are loaded immediately, and the UI + is blocked until loading is complete. If a large image is to be loaded, + it may be preferable to load the image in a low priority thread, by + selecting the \uicontrol Asynchronous check box. If the image is obtained + from a network rather than a local resource, it is automatically loaded + asynchronously. + + Images are cached and shared internally, so if several images have the same + \uicontrol Source, only one copy of the image will be loaded. + + \note Images are often the greatest user of memory in UIs. We recommended + that you set the \uicontrol {Source size} of images that do not form a part + of the UI. This is especially important for content that is loaded from + external sources or provided by the user. + + \section1 Border Image + + The Border Image component extends the features of the Image component. + It is used to create borders out of images by scaling or tiling parts + of each image. A source image is broken into 9 regions that are scaled or + tiled individually. The corner regions are not scaled at all, while the + horizontal and vertical regions are scaled according to the values of the + \uicontrol {Tile mode H} and \uicontrol {Tile mode V} field, or both. + + The \uicontrol Stretch option scales the image to fit the available area. + The \uicontrol Repeat option tiles the image until there is no more space. + To ensure that the last image is not cropped, select the \uicontrol Round + option that scales the images down when necessary. + + Specify the regions of the image in the \uicontrol {Border left}, + \uicontrol {Border right}, \uicontrol {Border top}, and + \uicontrol {Border bottom} fields. The regions describe + the distance from each edge of the source image to use as a border. + + \image qtquick-designer-border-image-properties.png "Border Image properties" + + \note You cannot change the \uicontrol {Source size} of a border image. + + For examples of using border images, see the documentation of the + \l [QtQuick]{BorderImage} component. + + \section1 Animated Image + + The Animated Image component extends the features of the Image component, + providing a way to play animations stored as images containing a series of + frames, such as those stored in GIF files. + + Set the speed of the animation in the \uicontrol Speed field. The speed is + measured in percentage of the original animated image speed. The default + speed is 1.0, which means the original speed. + + \image qtquick-designer-animated-image-properties.png "Animated Image properties" + + To play the animation, select the \uicontrol Playing check box. + + To pause the animation, select the \inlineimage icons/pause-icon.png + (\uicontrol Paused) check box. + + When the \uicontrol Cache check box is selected, every frame of the + animation is cached. Deselect the check box if you are playing a long + or large animation and you want to conserve memory. + + If the image data comes from a sequential device (such as a socket), + Animated Image can only loop if caching is enabled. + + For more information, watch the following video: + + \youtube DVWd_xMMgvg + + \if defined(qtdesignstudio) + \section1 Iso Icon + + \note The Iso Icon component is not available if you selected + \uicontrol {Qt 6} when \l{Creating Projects}{creating the project}. + + The Iso Icon component specifies an icon from an ISO 7000 icon library as a + \l [QtQuickExtras] {Picture} component. The icon to use for the type and + its color can be specified. + + To select an icon in the \uicontrol {ISO Icon Browser} in \QDS, select + the ISO icon in \l Navigator or \l {Form Editor}, and then select + \uicontrol {Choose Icon} in the context menu. + + \image studio-iso-icon.png + + You can use the \l{Picking Colors}{color picker} in \l Properties to + set the value of \uicontrol {Icon color}. + + \image iso-icon-browser.png + \endif + + \section1 Summary of Images + + The following table lists the components that you can use to add images. + The \e Location column contains the tab name where you can find the + component in \l Library > \uicontrol Components. The \e MCU column + indicates which components are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li Location + \li MCU + \li Purpose + \row + \li \inlineimage animated-image-icon16.png + \li \l [QtQuick]{AnimatedImage}{Animated Image} + \li Default Components - Basic + \li + \li An images that stores animations containing a series of frames, + such as those stored in GIF files. + \row + \li \inlineimage border-image-icon16.png + \li \l [QtQuick]{BorderImage}{Border Image} + \li Default Components - Basic + \li \inlineimage ok + \li An image that is used as a border or background. + \row + \li \inlineimage image-icon16.png + \li \l [QtQuick]{Image} + \li Default Components - Basic + \li \inlineimage ok + \li An image in one of the supported formats, including bitmap formats + such as PNG and JPEG and vector graphics formats such as SVG. + \if defined(qtdesignstudio) + \row + \li \inlineimage icons/iso-icons-16px.png + \li \l{Iso Icon} + \li Qt Quick Studio Components + \li + \li An icon from an ISO 7000 icon library specified as a \l Picture + component. You can select the icon to use and its color. + + \note This component is not supported on Qt 6. + \endif + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-pathview-editor.qdocinc b/doc/qtdesignstudio/src/components/qtquick-pathview-editor.qdocinc new file mode 100644 index 0000000000..83bd827f39 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-pathview-editor.qdocinc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! +//! [pathview] + + \section1 Path View + + A \uicontrol {Path View} component lays out data provided by data models + on a \l{Path}. + + A graphical spline editor enables you to specify path view paths, which + is a non-trivial task to do in \uicontrol {Text Editor}. + + \image qmldesigner-pathview-editor.png "Path View editor" + + To start editing the path, double-click the path view in + \l {Form Editor}. The editor composes the path of PathCubic path + objects. They are cubic Bezier curves to a given position with two control + points. Drag and drop the control points in \uicontrol {Form Editor} to + construct the curve. + + In addition, PathLine and PathQuad path objects are supported indirectly. + To make a curve segment linear, select \uicontrol {Make Curve Segment Straight} in + the context menu. + + By default, the path is closed, which means that its start and end points + are identical. To create separate start and end points for it, right-click + an edit point to open a context menu, and deselect \uicontrol {Closed Path}. + + To add intermediary points to a curve segment, select \uicontrol {Split Segment} + in the context menu. + + In the \uicontrol {Path View} section, you can specify other properties for + the path view. The value of the \uicontrol {Drag margin} field specifies + the maximum distance from the path that initiates mouse dragging. + + \image qtquick-designer-pathview-properties.png "Path View properties" + + Select the \uicontrol Interactive check box to make an item flickable. + The value of the \uicontrol {Flick deceleration} field specifies the + rate at which a flick will decelerate. + + In the \uicontrol Offset field, specify how far along the path the items + are from their initial positions. This is a real number that ranges from + 0 to the value of the \uicontrol {Item count} field, which displays the + number of items in the model. + + In the \uicontrol {Path View Highlight} section, you can specify properties + for \l{View Highlight}{highlighting} path objects. + + \if defined(qtdesignstudio) + \note You can also use the \l {SVG Path Item} Studio Component to specify an + SVG path data string that draws a path. + \endif + +//! [pathview] + +//! [svgpath] + + \section1 SVG Path Item + + The \uicontrol {SVG Path Item} component uses an SVG path data string to + draw a path as a line. + + Setting path colors is described in \l {Picking Colors}. + + The stroke property values that specify the appearance of the path are + described in \l{Strokes}. + + \image studio-svgpath-properties.png "SVG Path Item properties" + + The \uicontrol {Path data} field in the \uicontrol {Path Info} section + contains the SVG path data string that specifies the path. For more + information, see \l{https://www.w3.org/TR/SVG/paths.html#PathData} + {W3C SVG Path Data}. + +//! [svgpath] +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-positioning.qdoc b/doc/qtdesignstudio/src/components/qtquick-positioning.qdoc new file mode 100644 index 0000000000..1076e7a374 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-positioning.qdoc @@ -0,0 +1,579 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-positioning.html + \previouspage qtquick-properties.html + \if defined(qtdesignstudio) + \nextpage qtquick-annotations.html + \else + \nextpage qtquick-fonts.html + \endif + + \title Scalable Layouts + + The position of a \l{glossary-component}{component} in a UI can be either + absolute or relative to other components. The visual components exist at a + particular location in the screen coordinate system at any instant in time. + The x and y coordinates of a visual component are relative to those of its + visual parent, with the top-left corner having the coordinate (0, 0). + + If you are designing a static UI, + \l{Important Concepts In Qt Quick - Positioning#manual-positioning} + {manual positioning} provides the most efficient form of positioning + components. For a dynamic UI, you can employ the following positioning + methods: + + \list + \li \l{Setting Bindings} + \li \l{Setting Anchors and Margins} + \li \l{Aligning and Distributing Components} + \li \l{Using Positioners} + \li \l{Using Layouts} + \li \l{Organizing Components} + \endlist + + \section2 Setting Bindings + + \l{Positioning with Bindings}{Property binding} is a declarative way of + specifying the value of a property. Binding allows a property value to be + expressed as a 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 whenever a property is assigned a + JavaScript expression. To set JavaScript expressions as values of properties + in the \l Properties view, select the \inlineimage icons/action-icon.png + (\uicontrol Actions) menu next to a property, and then select + \uicontrol {Set Binding}. + + \image qmldesigner-set-expression.png "Actions menu" + + In \uicontrol {Binding Editor}, select a component and a property from + lists of available components and their properties. + + \image qmldesigner-binding-editor.png "Binding Editor" + + Alternatively, start typing a + string and press \key Ctrl+Space to display a list of properties, IDs, and + code snippets. When you enter a period (.) after a property name, a list of + available values is displayed. Press \key Enter to accept the first + suggestion in the list and to complete the code. For more information, see + \l{Completing Code}. + + When a binding is set, the \uicontrol Actions menu icon changes to + \inlineimage icons/action-icon-binding + . To remove bindings, select \uicontrol Actions > \uicontrol Reset. + + You can set bindings also in \l {Connection View} > \uicontrol Bindings. + For more information, see \l {Adding Bindings Between Properties}. + + For more information on the JavaScript environment provided, see + \l{Integrating QML and JavaScript}. + + Bindings are a black box for \QC and using them might have a + negative impact on performance, so consider setting anchors and margins for + components, instead. For example, instead of setting \c {parent.width} for a + component, you could anchor the component to its sibling components on the + left and the right. + + \section2 Setting Anchors and Margins + + In an \l{Important Concepts In Qt Quick - Positioning#anchors} + {anchor-based} layout, each component 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 \l Properties > \uicontrol Layout, you can set anchors and margins for + components. To set the anchors of a component, click the anchor buttons. + You can combine the top/bottom, left/right, and horizontal/vertical anchors + to anchor components in the corners of the parent component or center them + horizontally or vertically within the parent component. + + \image qmldesigner-anchor-buttons.png "Anchor buttons" + + For convenience, you can click the \inlineimage icons/anchor-fill.png + (\uicontrol {Fill to Parent}) toolbar button to apply fill anchors to a + component and the \inlineimage qtcreator-anchors-reset-icon.png + (\uicontrol {Reset Anchors}) button to reset the anchors to their saved + state. + + You can specify the baseline anchor in \l{Text Editor}. + + For performance reasons, you can only anchor a component to its siblings + and direct parent. By default, a component is anchored to its parent when + you use the anchor buttons. Select a sibling of the component in the + \uicontrol 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 component are always specified to the same side. However, anchors + to sibling components are specified to the opposite side: + \c {anchor.left: sibling.right}. This allows you to keep sibling components + together. + + In the following image, the left edge of \e rectangle1 is anchored to the + right edge of the sibling on its left side, \e rectangle, while its top + edge is anchored to the top of its parent. + + \image qmldesigner-anchors.png "Anchoring sibling components" + + The anchors are specified as follows in code: + + \qml + Rectangle { + id: rectangle1 + anchors.left: rectangle.right + anchors.top: parent.top + anchors.leftMargin: 5 + anchors.topMargin: 30 + } + \endqml + + Margins specify the amount of empty space to leave to the outside of a + component. Margins only have meaning for anchors. They do not take any + effect when using layouts or absolute positioning. + + \section2 Aligning and Distributing Components + + When you're working with a group of components, you can select them to align + and distribute them evenly. As the positions of the components are fixed, + you cannot apply these functions to anchored components. For scalability, + you can anchor the aligned and distributed components when your design is + ready. + + \image qmldesigner-alignment.png "Aligning sibling components" + + Select the buttons in the \uicontrol Alignment field to align the top/bottom + or left/right edges of a group of components to the one farthest away + from the center of the group. For example, when left-aligning, the + components are aligned to the leftmost component. You can also align the + horizontal/vertical centers of components, or both. + + In the \uicontrol {Align to} field, select whether to align the components + in respect to the selection, the root component, or a \e {key component} + that you select in the \uicontrol {Key object} field. The key component must + be a part of the selection. + + You can distribute either \e components or the \e spacing between them. + If the components or spacing cannot be distributed to equal pixel values + without ending up with half pixels, you receive a notification. You can + either allow \QDS to distribute components or spacing using the closest + values possible or tweak your design so that the components and spacing + can be distributed perfectly. + + When distributing components, select the buttons in the + \uicontrol {Distribute objects} field to determine whether the + distance between components is calculated from their top/bottom + or left/right edges or their horizontal/vertical center. + + When distributing spacing, select the buttons in the + \uicontrol {Distribute spacing} field to determine whether + it is distributed evenly within a target area or at + specified distances, calculated from a starting point. + You can select the orientation in which the components are distributed + evenly within the target area: horizontally along the x axis or vertically + along the y axis. + + Alternatively, you can distribute spacing in pixels by selecting one of the + starting point buttons: top/left or bottom/right edge of the target area or + item, or its center. The edge to use depends on whether the items are + distributed horizontally or vertically: + + \list + \li Select \inlineimage icons/distribute-origin-top-left.png + and \inlineimage icons/distribute-spacing-horizontal.png + to use the left edge of the target area or item as the starting + point. + \li Select \inlineimage icons/distribute-origin-top-left.png + and \inlineimage icons/distribute-spacing-vertical.png + to use the top edge. + \li Select \inlineimage icons/distribute-origin-bottom-right.png + and \inlineimage icons/distribute-spacing-horizontal.png + to use the right edge. + \li Select \inlineimage icons/distribute-origin-bottom-right.png + and \inlineimage icons/distribute-spacing-vertical.png + to use the bottom edge. + \endlist + + \note Some components might end up outside the target area. + + In the \uicontrol {Pixel spacing} field, you can set the space between + components in pixels. You can disable the distribution of spacing in + pixels by clicking the \inlineimage icons/distribute-origin-none.png + button. + + \section3 Summary of Aligment Buttons + + The following table summarizes the buttons available in the + \uicontrol Alignment section. + + \table + \header + \li Icon + \li Purpose + \row + \li \inlineimage icons/align-left.png + \li Aligns the left edges of the selected components to the one + farthest away from the center of the group. + \row + \li \inlineimage icons/align-center-horizontal.png + \li Aligns the horizontal centers of the selected components. + \row + \li \inlineimage icons/align-right.png + \li Aligns the right edges of the selected components. + \row + \li \inlineimage icons/align-top.png + \li Aligns the top edges of the selected components. + \row + \li \inlineimage icons/align-center-vertical.png + \li Aligns the verical centers of the selected components. + \row + \li \inlineimage icons/align-bottom.png + \li Aligns the bottom edges of the selected components. + \row + \li \inlineimage icons/distribute-left.png + \li Distributes the selected components and calculates the distance + between them from their left edges. + \row + \li \inlineimage icons/distribute-center-horizontal.png + \li Distributes the selected components and calculates the distance + between them from their horizontal centers. + \row + \li \inlineimage icons/distribute-right.png + \li Distributes the selected components and calculates the distance + between them from their right edges. + \row + \li \inlineimage icons/distribute-top.png + \li Distributes the selected components and calculates the distance + between them from their top edges. + \row + \li \inlineimage icons/distribute-center-vertical.png + \li Distributes the selected components and calculates the distance + between them from their vertical centers. + \row + \li \inlineimage icons/distribute-bottom.png + \li Distributes the selected components and calculates the distance + between them from their bottom edges. + \row + \li \inlineimage icons/distribute-spacing-horizontal.png + \li Distributes spacing between the selected components horizontally. + \row + \li \inlineimage icons/distribute-spacing-vertical.png + \li Distributes spacing between the selected components vertically. + \row + \li \inlineimage icons/distribute-origin-none.png + \li Disables the distribution of spacing in pixels. + \row + \li \inlineimage icons/distribute-origin-top-left.png + \li Sets the top or left edge of the target area or item as the + starting point for distributing spacing in pixels depending on + the distribution orientation. + \row + \li \inlineimage icons/distribute-origin-center.png + \li Sets the center of the target area as the starting point + for distributing spacing in pixels. + \row + \li \inlineimage icons/distribute-origin-bottom-right.png + \li Sets the bottom or right edge of the target area or item as the + starting point for distributing spacing in pixels, depending on + the distribution orientation. + \endtable + + \section2 Using Positioners + + Positioner components are containers that manage the positions of their + child components. For many use cases, the best positioner to use is a simple + column, row, flow, or grid. You can use the components available in + \l Library > \uicontrol Components > \uicontrol {Default Components} > + \uicontrol Positioner to position the children of a component in these + formations in the most efficient manner possible. + + To position several components in a \uicontrol Column, \uicontrol Row, + \uicontrol Flow, or \uicontrol Grid, select the components in + \l {Form Editor}, and then select \uicontrol Position in + the context menu. + + \section3 Column Positioner + + A \uicontrol Column positions its child components along a single column. + It can be used as a convenient way to vertically position a series of + components without using anchors. + + \image qtquick-positioner-column-properties.png "Column properties" + + For all positioners, you can specify the spacing between the child + components that they contain in the \uicontrol Spacing field. + + In addition, you can specify the vertical and horizontal padding between + content and the left, right, top, and bottom edges of components as values + of the fields in the \l Padding section. + + \section3 Row and Flow Positioners + + A \uicontrol Row positions its child components along a single row. It can + be used as a convenient way to horizontally position a series of components + without using anchors. + + The \uicontrol Flow component positions its child components like words on a + page, wrapping them to create rows or columns of components. + + \image qtquick-positioner-flow-properties.png "Flow properties" + + For flow and row positioners, you can also set the direction of a flow to + either left-to-right or top-to-bottom in the \uicontrol Flow field. + Components are positioned next to to each other according to the value you + set in the \uicontrol {Layout direction} field until the width or height of + the \uicontrol Flow component is exceeded, then wrapped to the next row or + column. + + You can set the layout direction to either \uicontrol LeftToRight or + \uicontrol RightToLeft in the \uicontrol {Layout direction} field. If + the width of the row is explicitly set, the left anchor remains to the + left of the row and the right anchor remains to the right of it. + + \section3 Grid Positioner + + A \uicontrol Grid creates a grid of cells that is large enough to hold all + of its child components, and places these components in the cells from left + to right and top to bottom. Each component is positioned at the top-left + corner of its cell with position (0, 0). + + \QC generates the grid based on the positions of the child components in + \l {Form Editor}. You can modify the number of rows and columns in the + \uicontrol Rows and \uicontrol Columns fields. + + \image qtquick-positioner-grid-properties.png "Grid properties" + + In addition to the flow and layout direction, you can set the horizontal + and vertical alignment of grid components. By default, grid components are + vertically aligned to the top. Horizontal alignment follows the value of the + \uicontrol {Layout direction} field. For example, when layout direction is + set to \uicontrol LeftToRight, the components are aligned on the left. + + To mirror the layout, set the layout direction to \uicontrol RightToLeft. + To also mirror the horizontal alignment of components, select + \uicontrol AlignRight in the \uicontrol {Alignment H} field. + + \section3 Summary of Positioners + + The following table lists the positioners that you can use to arrange + components in UIs. They are available in \l Library > \uicontrol Components + > \uicontrol {Default Components} > \uicontrol Positioner. + + \table + \header + \li Icon + \li Name + \li Purpose + \row + \li \inlineimage column-positioner-icon-16px.png + \li \l[QtQuick] {Column} + \li Arranges its child components vertically. + \row + \li \inlineimage row-positioner-icon-16px.png + \li \l[QtQuick] {Row} + \li Arranges its child components horizontally. + \row + \li \inlineimage grid-positioner-icon-16px.png + \li \l[QtQuick] {Grid} + \li Arranges its child components so that they are aligned in a grid and + are not overlapping. + \row + \li \inlineimage flow-positioner-icon-16px.png + \li \l[QtQuick] {Flow} + \li Arranges its child components side by side, wrapping as necessary. + \endtable + + \section2 Using Layouts + + \if defined(qtcreator) + Since Qt 5.1, you can use QML types in the \l{qtquicklayouts-index.html} + {Qt Quick Layouts} module to arrange components in UIs. + \else + You can use the components available in \l Library > \uicontrol Components + > \uicontrol {Qt Quick Layouts} to arrange components in UIs. + \endif + Unlike positioners, layouts manage both the positions and sizes of their + child components, and are therefore well suited for dynamic and resizable + UIs. However, this means that you should not specify fixed positions and + sizes for the child components in the \l{2D Geometry}{Geometry - 2D} section + in \l Properties, unless their implicit sizes are not satisfactory. + + You can use anchors or the width and height properties of the layout itself + to specify its size in respect to its non-layout parent component. However, + do not anchor the child components within layouts. + + To arrange several components in a column, row, grid, or + \uicontrol {Stack Layout}, select the components in \l {Form Editor}, + and then select \uicontrol Layout in the context menu. + + You can also click the \inlineimage column.png + (\uicontrol {Column Layout}), \inlineimage row.png + (\uicontrol {Row Layout}), and \inlineimage grid.png + (\uicontrol {Grid Layout}) toolbar buttons to apply + layouts to the selected components. + + To make a component within a layout as wide as possible while respecting the + given constraints, select the component in \uicontrol {Form Editor}, and + then select \uicontrol Layout > \uicontrol {Fill Width} in the context menu. + To make the component as high as possible, select \uicontrol {Fill Height}. + + \section3 Layout Properties + + A \uicontrol {Grid Layout} component provides a way of dynamically + arranging components in a grid. If the grid layout is resized, all + its child components are rearranged. If you want a layout with just + one row or one column, use the \uicontrol {Row Layout} or + \uicontrol {Column Layout} component. + + The child components of row and column layout components are automatically + positioned either horizontally from left to right as rows or vertically from + top to bottom as columns. The number of the child components determines the + width of the row or the height of the column. You can specify the spacing + between the child components in the \uicontrol Spacing field. + + The child components of grid layout components are arranged according to the + \uicontrol Flow property. When the direction of a flow is set to + \uicontrol LeftToRight, child components are positioned next to to each + other until the the number of columns specified in the + \uicontrol {Columns & Rows} field is reached. Then, + the auto-positioning wraps back to the beginning of the next row. + + \image qtquick-layout-grid-properties.png "Grid Layout properties" + + If you set the direction of the flow to \uicontrol TopToBottom, child + components are auto-positioned vertically using the number of rows set + in the \uicontrol {Columns & Rows} field to determine the maximum number + of rows. + + You can set the layout direction to either \uicontrol LeftToRight or + \uicontrol RightToLeft in the \uicontrol {Layout direction} field. + When you select \uicontrol RightToLeft, the alignment of the components + will be mirrored. + + You can specify the spacing between rows and columns in the + \uicontrol Spacing field. + + \section3 Stack Layout + + \image qtquick-designer-stacked-view.png + + To add components to a \uicontrol {Stack Layout}, select the + \inlineimage plus.png + button next to the component name in \l {Form Editor}. + To move between components, select the \inlineimage prev.png + (\uicontrol Previous) and \inlineimage next.png + (\uicontrol Next) buttons. + + To add a tab bar to a stack layout, right-click on the + \uicontrol {Stack Layout} in \l Navigator to access the context menu, and + select \uicontrol {Stacked Container} > \uicontrol {Add Tab Bar}. + + To raise or lower the stacking order of a component, select + \uicontrol {Stacked Container} > \uicontrol {Increase Index} or + \uicontrol {Decrease Index}. + + \section3 Summary of Layouts + + The following table lists the layout components that you can use to arrange + components in UIs. They are available in \l Library > \uicontrol Components + > \uicontrol {Qt Quick Layouts}. + + \table + \header + \li Icon + \li Name + \li Purpose + \row + \li \inlineimage column-layouts-icon-16px.png + \li \l{ColumnLayout}{Column Layout} + \li Provides a grid layout with only one column. + \row + \li\inlineimage row-layouts-icon-16px.png + \li \l{RowLayout}{Row Layout} + \li Provides a grid layout with only one row. + \row + \li \inlineimage grid-layouts-icon-16px.png + \li \l{GridLayout}{Grid Layout} + \li Provides a way of dynamically arranging components in a grid. + \row + \li \inlineimage stack-layouts-icon-16px.png + \li \l{StackLayout}{Stack Layout} + \li Provides a stack of components where only one component is + visible at a time. + \endtable + + + \section2 Organizing Components + + You can use the \uicontrol Frame and \uicontrol {Group Box} controls to + draw frames around groups of controls. + \if defined(qtdesignstudio) + If you don't want a frame, use the \uicontrol Group component instead. + \endif + + + The following table lists the UI controls that you can use to organize + components in UIs (since Qt 5.7). The \e Location column indicates the + location of the component in \l Library > \uicontrol Components. + + \table + \header + \li Icon + \li Name + \li Location + \li Purpose + \row + \li \inlineimage icons/frame-icon16.png + \li \l [QtQuickControls]{Frame} + \li Qt Quick Controls + \li A visual frame around a group of controls. + \if defined(qtdesignstudio) + \row + \li \inlineimage icons/group-16px.png + \li Group + \li Qt Quick Studio Components + \li Enables handling the selected components as a group. + \endif + \row + \li \inlineimage icons/groupbox-icon16.png + \li \l [QtQuickControls]{GroupBox}{Group Box} + \li Qt Quick Controls + \li A titled visual frame around a group of controls. + \row + \li \inlineimage icons/page-icon16.png + \li \l [QtQuickControls]{Page} + \li Qt Quick Controls + \li A styled page control with support for a header and footer. + \row + \li \inlineimage icons/pane-icon16.png + \li \l [QtQuickControls]{Pane} + \li Qt Quick Controls + \li A background that matches the application style and theme. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc b/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc new file mode 100644 index 0000000000..488dbbdfe0 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-preset-components.qdoc @@ -0,0 +1,116 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-preset-components.html + \previouspage quick-components.html + \nextpage quick-shapes.html + + \title Preset Components + + To use preset components, add the modules that contain them to your project + by selecting \l Library > \uicontrol Components > \inlineimage plus.png + . For more information, see \l{Adding and Removing Modules}. You can then + create instances of the components by dragging-and-dropping them from + \uicontrol Library to \l {Form Editor}, \l {3D Editor}, or \l Navigator. + + To edit the appearance of a component instance, select it in + \uicontrol {Form Editor}, \uicontrol {3D Editor}, or \uicontrol Navigator + and set its properties in the \l Properties view. + + For more information about creating your own components, see + \l{Creating Custom Components}. + + \section1 2D Components + + \list + \li \l Shapes + \li \l Text + \li \l Images + \li \l {User Interaction Methods} + \li \l {UI Controls} + \li \l {Lists and Other Data Models} + \if defined(qtdesignstudio) + \li \l {2D Effects} + \li \l {Logic Helpers} + \endif + \li \l Animations + \endlist + + \section1 3D Components + + You can use \l{3D Editor} in the \uicontrol Design mode to edit files you + created using 3D graphics applications and stored in one of the supported + formats. You cannot create 3D models or other assets in the editor, but you + can \l{Importing 3D Assets}{import} the assets you need and work with them + to create scenes and states, as well as the transitions between them. + + \list + \li \l {3D Views} + \li \l {Node} + \li \l {Group} + \li \l {Instanced Rendering} + \li \l {Skeletal Animation} + \li \l {3D Models} + \li \l {Materials and Shaders} + \li \l {Textures} + \li \l {3D Materials} + \li \l {3D Effects} + \li \l {Custom Shaders} + \li \l {Custom Effects and Materials} + \li \l {Lights} + \li \l {Cameras} + \li \l {Scene Environment} + \li \l {Morph Target} + \li \l {Repeater3D} + \li \l {Loader3D} + \li \l {Particles} + \endlist + + When you import 3D scenes from files that you exported from 3D graphics + tools, you also import the camera, light, model, and materials as 3D + components. If your scene did not contain them, you can add predefined + 3D components to it and edit their properties to fit your needs. + + \note Using 3D components will affect the performance of your UI. Do not + use 3D components if the same results can be achieved using 2D components. + + \section2 Videos About 3D Components + + The following video shows you how to add the components included in the + \uicontrol {Qt Quick 3D} module, such as 3D models, cameras, and lights, + to your scene: + + \youtube u3kZJjlk3CY + + The following video shows you how to use the custom shader utilities, 3D + effects, and materials: + + \youtube bMXeeQw6BYs + + The following video shows you how to combine 2D and 3D components: + + \youtube w1yhDl93YI0 +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-shapes.qdoc b/doc/qtdesignstudio/src/components/qtquick-shapes.qdoc new file mode 100644 index 0000000000..a174a52ab1 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-shapes.qdoc @@ -0,0 +1,310 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-shapes.html + \previouspage quick-preset-components.html + \nextpage quick-text.html + + \title Shapes + + \if defined(qtdesignstudio) + \QDS is a UI design tool rather than a generic drawing tool, and therefore, + the focus is on providing ready-made UI controls that you can modify + according to your needs. The values of some properties of the controls are + specified by using styling, and therefore you cannot change them. + + However, you can use some of the components in \l Library to draw + basic shapes, such as rectangles. In addition, \QDS comes with a set of + more powerful and flexible graphical primitives, that allow creating more + complex shapes, such as borders, triangles, arcs, and pies in + \uicontrol {Form Editor}. + + \image studio-shapes.png "Shapes in Form Editor" + + \else + You can use the Rectangle component to draw basic shapes in + \l {Form Editor}. + \image qml-shapes.png "Shapes in Form Editor" + \endif + + Most visual components in \uicontrol Library are based on the \l [QtQuick] + {Item} component. Even though it has no visual appearance itself (similarly + to a mouse area, for example), it defines all the properties that are + common across visual components, such as position, size, and visibility. For + more information, see \l{Basic Component Properties}. + + In addition, each component has a set of properties that specify its visual + appearance and behavior. You can modify the property values to set fill + and border colors, stroke width, and other characteristics of the shapes. + + The following sections describe the available shapes and their properties + in more detail. You can modify the values of the properties in the + \uicontrol Properties view. + + \target basic-rectangle + \section1 Rectangle + + The basic \l [QtQuick] {Rectangle} component is used for drawing shapes + with four sides and corners, as well as a solid border. + + \if defined(qtdesignstudio) + \image qml-shapes-rectangle.png "A rectangle and its properties" + \endif + + Rectangles can be filled either with a solid fill color or a linear + gradient that you set in the \uicontrol {Fill color} field. You can + also use a \l{Picking Colors}{color picker} to select colors and a + \l{Picking Gradients}{gradient picker} to select gradients from a + predefined set of \l{https://webgradients.com/}{WebGradients}. + + An optional solid border can be added to a rectangle with its own color + and thickness by setting the values of the \uicontrol {Border color} and + \uicontrol {Border width} fields. To create a border without a fill color, + select the \inlineimage icons/transparent-icon.png + button that sets the color to \e transparent. + + By setting the value of the \uicontrol Radius field, you can create shapes + with rounded corners. With the right combination of the values of the + rectangle width, height, and radius properties, you can create oval and + circular shapes. For example, to draw a full circle, first draw a rectangle + with all four sides equal, and then set its radius to half the side length. + + When drawing curved edges, consider enabling the \uicontrol Antialiasing + check box in the \uicontrol Advanced section to improve the appearance of + your shape. + + \if defined(qtdesignstudio) + \target studio-rectangle + \section2 Studio Rectangle + + If you want to modify each corner of the rectangle independently + or use a dashed border, create an instance of the \uicontrol Rectangle + component available in \uicontrol Library > \uicontrol Components > + \uicontrol {Qt Quick Studio Components} instead of the basic + \uicontrol Rectangle component available in \uicontrol {Default Components} + > \uicontrol Basic. + + By setting the values of properties in the \uicontrol {Corner Radiuses} + section, you can draw each corner independently. By using radius values + in combination with the values in the \uicontrol {Corner Bevel} section, + you can create shapes with cut corners. + + \image studio-shapes-rectangle.png "A studio rectangle with cut corners" + + In addition to linear gradients, you can specify conical and radial + gradients in the \uicontrol {Fill color} field. + + In the \uicontrol {Stroke Details} section, you can specify the border + mode, line style, and dash pattern for dashed and dotted lines. + For more information, see \l{Strokes}. + + \section1 Border + + The Border component is used to create borders out of four segments: + left, top, right, and bottom. By selecting the check boxes in the + \uicontrol {Draw Edges} section, you can determine whether each + of the segments is visible. This enables you to draw solid or dashed + lines with specified dash patterns and joint and cap styles. + + \image studio-shapes-border.png "Border properties" + + Set the color of the border in the \uicontrol {Stroke color} field and its + thickness in the \uicontrol {Stroke width} field. Then specify additional + properties for borders in the \uicontrol {Stroke Details} section. + + \section2 Strokes + + In the \uicontrol {Stroke Details} section, you can specify the border mode, + line style, and dash pattern for dashed and dotted lines. + + \image studio-shapes-stroke-properties.png "Stroke properties" + + In the \uicontrol {Border mode} field, you can specify whether the border + is drawn along the inside or outside edge of the component, or on top of the + edge. + + If you select a dashed or dotted pattern in the \uicontrol {Stroke style} + field, you can specify the dash pattern as the dashes and the gaps between + them in the \uicontrol {Dash pattern} field. The dash pattern is specified + in units of the stroke width. That is, a dash with the length 5 and width + 10 is 50 pixels long. + + The value of the \uicontrol {Dash offset} field specifies the starting point + of the dash pattern for a line. It is measured in terms of the units used to + specify the dash pattern. For example, a pattern where each stroke is four + units long, followed by a gap of two units, will begin with the stroke when + drawn as a line. However, if the dash offset is set to 4.0, any line drawn + will begin with the gap. Values of the offset up to 4.0 will cause part of + the stroke to be drawn first, and values of the offset between 4.0 and 6.0 + will cause the line to begin with part of the gap. + + In the \uicontrol {Join style} field, select \uicontrol {Miter Join} to + extend the outer edges of the lines to meet at an angle and to fill the + area between them. Select \uicontrol {Bevel Join} to fill the triangular + notch between the two lines. Select \uicontrol {Round Join} to fill a + circular arc between the two lines. + + The value of the \uicontrol {Cap style} property specifies whether line + ends are square or rounded. + + \section1 Triangle + + The Triangle component can be used to draw triangles with different dimensions + and shapes. The component is enclosed in an invisible rectangle that determines + its size. The dimensions of the triangle can be changed to make it elongated + or squatter with space around it by setting the top, bottom, left, and right + margins in the \uicontrol Margin section. The margins are set between the + triangle and the edges of the parent rectangle. + + \image studio-shapes-triangle.png "Triangle properties" + + The fill and stroke color property values are set in the same way as for a + rectangle. The border property values are described in \l{Strokes}. + + \section1 Arc + + An arc is specified by setting values in degrees in the + \uicontrol {Arc start} and \uicontrol {Arc end} fields. + The arc can be just a line or a filled outline. The + properties of the line or outline are described in \l{Strokes}. + + \image studio-shapes-arc.png "Arc properties" + + The area between the arc's start and end points or the area inside the + outline are painted using either a solid fill color or a gradient. + + \image studio-shapes-arc-outline-properties.png "Arc Outline Properties" + + To create an arc with an outline, select the \uicontrol {Full outline} + check box. The \uicontrol {Outline width} field sets the width of + the arc outline, including the stroke. The \uicontrol {Outline start} + and \uicontrol {Outline end} fields set the width of the start and + end points of the outline separately. The width of the outline between + them is calculated automatically. You can adjust the inner and outer + curves of the outline in the \uicontrol {Inner radius} and + \uicontrol {Outer radius} fields. + + The \uicontrol {Round outline}, \uicontrol {Round start}, and + \uicontrol {Round end} properties specify whether the end points of the + arc outline have rounded caps. For an arc that does not have an outline, + the \uicontrol {Cap style} field in the \uicontrol {Stroke Details} + section specifies whether the line ends are square or rounded. + + \section1 Pie + + The Pie component is used to create a pie slice, a pie that is missing slices, + or just the pie rind (similar to an arc), depending on the values of the + \uicontrol {Pie start} and \uicontrol {Pie end} fields and the + \uicontrol Hide check box. + + \image studio-shapes-pie.png "Pie properties" + + The filling of the pie is painted using either a solid fill color or a + gradient. The fill and stroke color property values are set in the same + way as for a rectangle. The border property values are described in + \l{Strokes}. + + \section1 Flipable + + A Flipable component can be visibly \e flipped between its front and back + sides, like a card. The front and back sides are specified by using any + two components inside the Flipable component. The component with the + higher z-order is the front side. The \uicontrol Front and \uicontrol Back + fields in the \uicontrol Opacity section are used to hide and show either + the front or back side of the item at a time. + + \image studio-flipable.png + + The \uicontrol {Flip angle} property is used to animate the angle + of the component to produce the flipping effect. The value of the + \uicontrol {Rotational axis} property determine whether the component + is rotated around the x-axis or the y-axis. + + \section1 Summary of Shapes + + The following table lists the components that you can use to draw shapes. + The \e Location column indicates the location of the component in + \l Library > \uicontrol Components. The \e MCU column indicates which + components are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li Location + \li MCU + \li Purpose + \row + \li \inlineimage icons/item-arc-16px.png + \li \l Arc + \li Qt Quick Studio Components + \li + \li An arc that begins and ends at given positions. + \row + \li \inlineimage icons/custom-border-16px.png + \li \l Border + \li Qt Quick Studio Components + \li + \li A line with four segments that you can show and shape individually. + \row + \li \inlineimage icons/item-pie-16px.png + \li \l Pie + \li Qt Quick Studio Components + \li + \li A pie slice or a pie with a slice missing from it. + \row + \li \inlineimage icons/item-flippable-16px.png + \li \l Flipable + \li Qt Quick Studio Components + \li + \li A component that can be visibly \e flipped between its front and + back sides, like a card. + \row + \li \inlineimage rect-icon16.png + \li \l Rectangle + \li Default Components - Basic + \li \inlineimage ok + \li A rectangle that is painted with a solid fill color or linear + gradient and an optional border. You can use the radius property + to draw circles. + \row + \li \inlineimage icons/custom-rectangle-16px.png + \li \l{Studio Rectangle}{Rectangle} + \li Qt Quick Studio Components + \li + \li An extended rectangle that is painted with a solid fill color or + linear, conical, or radial gradients, and corners that you can + shape independently of each other. + \row + \li \inlineimage icons/item-triangle-16px.png + \li \l Triangle + \li Qt Quick Studio Components + \li + \li A triangle with different dimensions and shapes that is + enclosed in an invisible rectangle. + \endtable + \endif +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-text.qdoc b/doc/qtdesignstudio/src/components/qtquick-text.qdoc new file mode 100644 index 0000000000..8202082341 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-text.qdoc @@ -0,0 +1,472 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-text.html + \previouspage quick-shapes.html + \nextpage quick-images.html + + \title Text + + You can use several different text components to add read-only or editable + text to a UI, such as titles or labels and text input fields with + placeholder text. The \uicontrol Text component adds formatted text, the + \uicontrol {Text Edit} component adds a multiline line edit, and the + \uicontrol {Text Input} component adds a single editable line field. + + You can select the font to use and specify extensive properties for each + text string, such as size in points or pixels, style name, emphasis, + alignment, and spacing. + + For more information, watch the following video: + + \youtube yOUdg1o2KJM + + To create a label with a background, use the \uicontrol Label + component available in \l Library > \uicontrol Components > + \uicontrol {Qt Quick Controls}. The module also contains components + for creating \uicontrol {Text Field} and \uicontrol {Text Area} controls. + They differ from the basic components in that a common style is applied + to them and that you can specify placeholder text for them. + + \section1 Using Rich Text + + You can use rich text in the \uicontrol Text and \uicontrol {Text Input} + components. To open the rich text editor, select the \inlineimage icons/edit.png + (\uicontrol Edit) button in \uicontrol Properties > \uicontrol Character + > \uicontrol Text. + + \image qtquick-text-rtf.gif "Editing text in the rich text editor" + + In the rich text editor, you can: + + \list + \li Emphasize text + \li Create hyperlinks + \li Align text + \li Create bulleted and numbered lists + \li Specify text color + \li Select text font + \li Set font size + \li Create tables + \endlist + + \image qtquick-rtf-editor.png "Text formatted as rich text in the editor" + + \section1 Marking Strings for Translation + + To support translators, mark the strings that should be translated. + In \uicontrol Properties > \uicontrol Character > \uicontrol Text, select + \uicontrol tr. + + \image qmldesigner-text-property-tr.png "tr button in Character section" + + By default, the text string is enclosed in a \c qsTr() call. + + \image qml-translate.png "Text marked for translation" + + If you use text IDs instead of plain text, change the default call to + \c qsTrId(). Select \uicontrol Tools > \uicontrol Options > + \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer}, and then select the + \uicontrol {qsTrId()} radio button in the \uicontrol Internationalization + group. For more information about text ID based translations, see + \l {Qt Linguist Manual: Text ID Based Translations}. + + To preserve the context when editing the text or to change the context + by setting a binding on the text property, change the default call to + \c qsTranslate() by selecting the \uicontrol {qsTranslate()} radio button. + + For more information, see + \l {Internationalization and Localization with Qt Quick}. + + \if defined(qtcreator) + When you \l{Creating Qt Quick Projects}{create a new project}, you can + automatically generate a translation source file (TS) for one language. + You can add other languages later by editing the project file. + \endif + + \section1 Character Properties + + You can set font properties in the \uicontrol Character section + in \uicontrol Properties. For each string that you enter in the + \uicontrol Text field, you can select the font to use in the + \uicontrol Font field and specify the size, emphasis, aligment, + and spacing of the text. Specify the font size in either points + or pixels in the \uicontrol Size field. + + \image qtquick-designer-text-properties.png "Character properties" + + To display custom fonts in the list of available fonts in the + \uicontrol Font field, you need to first add them to \l Library: + + \list 1 + \li Select \uicontrol Library > \l Assets + > \inlineimage plus.png + . + \li Select the font file, and then select \uicontrol Open. + \li Select the location where the file will be saved in the + \uicontrol {Add Resources} dialog. + \li Select \uicontrol OK. + \endlist + + In the \uicontrol Weight field, you can select the font weight from a + list of predefined values that range between extra-light and extra-bold. + You can also use the buttons in the \uicontrol Emphasis group to format + text by making it bold, italic, underlined, or strikethrough. + + If you set a style name in the \uicontrol {Style name} field, the font is + matched against the style name instead of the values set in the + \uicontrol Weight and \uicontrol Emphasis fields. + + The value of the \uicontrol {Word spacing} field changes the default + spacing between individual words, whereas the value of the + \uicontrol {Letter spacing} field changes the spacing between individual + letters in a word. A positive value increases the spacing by a + corresponding amount of pixels, while a negative value decreases it. + + The value of the \uicontrol {Line height} field sets the line height + for the text. In the \uicontrol {Line height mode} field in the + \uicontrol {Text Extras} section, select \uicontrol FixedHeight to set + the line height in pixels or \uicontrol ProportionalHeight (default) + to set the spacing proportionally to the line (as a multiplier). + For example, set to 2 for double spacing. + + \section1 Text Alignment + + You can align text components horizontally and vertically. By default, text + is vertically aligned to the top. Horizontal alignment follows the natural + alignment of the text. By default, left-to-right text like English is + aligned to the left side of the text area, whereas right-to-left text + like Arabic is aligned to the right side of the text area. + + You can align text to the left, right, top, or bottom, and center it + horizontally or vertically. You can justify horizontal text. + + For a single line of text, the size of the text is the area of the text. + In this common case, all alignments are equivalent. To center a text in + its parent, use \l{Setting Anchors and Margins}{anchoring} or bind the + width of the text component to that of the parent. For more information, see + \l{Setting Bindings}. + + \section1 Text and Style Colors + + You can set the color of the text itself and a secondary color used by + text styles. + + For the \uicontrol {Text Edit} and \uicontrol {Text Input} components, you + can also set the color of selected text and the text highlight color + that is used behind selections in the \uicontrol {Selected text color} + and \uicontrol {Selection color} fields. + + For the \uicontrol {Text Field} and \uicontrol {Text Area} controls, you + can also set the color of the \l{Placeholder Text}{placeholder text}. + + For more information about selecting colors, see \l{Picking Colors}. You + can only set solid colors for text components. + + \section1 Advanced Text Properties + + The height and width of a text component are determined automatically depending + on the values of the properties you set, to accommodate the length of the + string that you specify in the \uicontrol Text field and the font size, for + example. You can specify additional properties for formatting text in the + \uicontrol {Text Extras} section. + + \image qtquick-properties-text-extras.png "Text Extras section" + + The value of the \uicontrol {Size mode} field specifies how the font + size of the displayed text is determined. Select \uicontrol FixedSize + to use the size specified in the \uicontrol Size field in the + \uicontrol Character section in pixels or points. + + Select \uicontrol HorizontalFit or \uicontrol VerticalFit to use the largest + size up to the size specified that fits the width or height of the component. + Select \uicontrol Fit to use the largest size up to the size specified that + fits within the width and height of the component. The font size of fitted text + has a minimum bound specified by the \uicontrol {Min size} field and + maximum bound specified by the \uicontrol Size field. + + \section3 Wrapping and Eliding Text + + In the \uicontrol {Wrap mode} field, you can wrap the text to the text + component's width. The text will only wrap if you set an explicit width for + the text component. By default, text is not wrapped. Select \uicontrol WordWrap + to restrict wrapping to word boundaries only. Select \uicontrol WrapAnywhere + to enable wrapping at any point on a line, even if it occurs in the middle + of a word. Select \uicontrol Wrap to wrap at a word boundary, if possible, + or at the appropriate point on the line, even in the middle of a word. + + You can use the \uicontrol Elide property with the \uicontrol Wrap + option to fit a single line of plain text to a set width. Select + \uicontrol ElideRight, and set the \uicontrol {Max line count} + or the text component height (in the \uicontrol H field). If you set both, + the maximum line count will apply unless the lines do not fit in the + height allowed. + + If the text is a multi-length string, and you set the \uicontrol Elide + property value to something else than \uicontrol ElideNone, the first + string that fits will be used, otherwise the last will be elided. + + Multi-length strings are ordered from longest to shortest, separated by the + Unicode \e {String Terminator} character \c U009C. + + \section3 Formatting Text + + Text can be either in plain text or rich text format, depending on the + value you set in the \uicontrol Format field. If you select + \uicontrol AutoText and the the first line of text contains an HTML tag, + the text is treated as rich text. Rich text supports a subset of HTML 4 + described on the \l {Supported HTML Subset}. Note that plain text offers + better performance than rich text. + + \section3 Rendering Text + + In the \uicontrol {Render type} field, you can override the default + rendering type for a text component. Select \uicontrol NativeRendering if + you prefer text to look native on the target platform and do not + require advanced features such as \l {Managing 2D Transformations} + {transformation} of the text. Using rotation or scaling in combination + with native rendering leads to poor and sometimes pixelated results. + + If you select \uicontrol NativeRendering, you can set the hinting preference + in the \uicontrol Hinting field in the \uicontrol {Font Extras} section: + + \list + \li \uicontrol PreferDefaultHinting uses the default hinting level for + the target platform. + \li \uicontrol PreferNoHinting renders text without hinting the outlines + of the glyphs, if possible. + \li \uicontrol PreferVerticalHinting renders text with no horizontal + hinting, but aligns glyphs to the pixel grid in the vertical + direction, if possible. + \li \uicontrol PreferFullHinting renders text with hinting in both + horizontal and vertical directions. + \endlist + + \note This property only describes a preference, as the full range of + hinting levels are not supported on all of Qt's supported platforms. + + \section1 Advanced Font Properties + + You can specify additional properties for fonts in the + \uicontrol {Font Extras} section. + + \image qtquick-properties-font-extras.png "Font Extras section" + + In the \uicontrol Capitalization field, select \uicontrol MixedCase + for normal text rendering where no capitalization changes are applied. You + can also set the text in all upper or lower case, or use small caps. The + \uicontrol Capitalize option renders the first character of each word as an + uppercase character. + + You can set the font style in the \uicontrol Style field to + \uicontrol Outline, \uicontrol Raised, or \uicontrol Sunken. + The color that you pick in the \uicontrol {Style color} + field is used as the outline color for outlined text, and as + the shadow color for raised or sunken text. + + To use kerning when drawing text with the selected font, select the + \uicontrol {Auto kerning} check box. + + Sometimes, a font will apply complex rules to a set of characters in order + to display them correctly. In some writing systems, such as Brahmic scripts, + this is required in order for the text to be legible but in others, such + as Latin script, it is merely a cosmetic feature. Such features are disabled + by default to improve performance. If they are required, select the + \uicontrol {Prefer shaping} check box. + + \target text-edit + \section1 Text Input + + You can use the \uicontrol {Text Edit} and \uicontrol {Text Input} + components to add text fields where users can enter text. + + The \uicontrol {Text Input} component displays a single line of editable + plain text, whereas the \uicontrol {Text Edit} component displays a block + of editable, formatted text. Both components are used to accept text input. + + \image qtquick-designer-text-input-properties.png "Text input field properties" + + \section2 Entering Passwords + + You can set properties for \uicontrol {Text Input} components that make + them suitable for entering passwords. + + In the \uicontrol {Input mask} field, you can create an input mask that + contains mask and meta characters and separators between them. When created + or cleared, the text edit or input is filled with a copy of the input mask + string, where the meta characters have been removed, and the mask characters + have been replaced with the blank character. For example, in an input field + for an IP address, you could use the following mask (with the underscore as + the blank character): \c {000.000.000.000;_}. For more information about + creating input masks, see the documentation for \l QLineEdit::inputMask. + + In the \uicontrol {Echo mode} field, select \uicontrol Password to display + platform-dependent password mask characters instead of the actual characters + that users enter. Select \uicontrol PasswordEchoOnEdit to display characters + as users enter them. The mask character is displayed in the + \uicontrol {Password character} field. + + \section2 Entering Text + + You can specify how users can enter text into text edit or input fields. + + In the \uicontrol {Maximum length} field, set the maximum number of + characters that users can enter. + + The value of the \uicontrol {Auto scroll} check box determines whether the + text edit or input should scroll when the text is longer than the width of + the field. + + If the \uicontrol {Overwrite mode} check box is selected, existing text is + overwritten, character-for-character by new text. Otherwise, new text is + inserted at the cursor position, displacing existing text. By default, new + text does not overwrite existing text. + + To prevent users from changing the text, select the \uicontrol {Read only} + check box. + + \section2 Selecting Text + + In the \uicontrol {Selection mode} field, you can specify whether + individual characters or whole words are selected when selecting text + with a pointer device. + + Select the \uicontrol {Select by mouse} check box to enable users to + use the mouse to select text in some platform-specific way. For some + platforms this may not be an appropriate interaction because it may + conflict with how the text needs to behave inside a \uicontrol Flickable + component, for example. + + For a \uicontrol {Text Edit} component, you can select the + \uicontrol {Select by keyboard} check box to enable users to + use the keyboard to select text even if the edit field is + read-only. If this property is set to \c false, users cannot + use the keyboard to select text even if it is editable. + + \section2 Focus + + The value of the \uicontrol {Focus on press} check box determines + whether the text edit or input should gain active focus on a mouse press. + + By default, the cursor becomes visible when the text edit or input gains + active focus, so that other properties can be bound to whether the cursor + is currently shown. Because the value of the \uicontrol {Cursor visible} + property gets set and unset automatically, any value you set yourself may + be overwritten. + + If the \uicontrol {Persistent selection} check box is selected, a text edit + or input keeps its selection when active focus moves to another component. + + \section2 Tabs and Margins + + You can specify additional properties for formatting a block of text in + a \uicontrol {Text Edit} component. + + \image qtquick-designer-text-edit-properties.png "Text edit properties" + + In the \uicontrol {Tab stop distance} field, set the default distance, in + device units, between tab stops. + + In the \uicontrol {Text margin} field, set the margin around the text in + pixels. + + \section1 Padding + + The values of the properties in the \uicontrol Padding section specify the + padding around the content. The individual padding properties adopt the + value of the \uicontrol Global field, unless you set them explicitly. + + \image qtquick-properties-text-padding.png "Padding section" + + \note If you explicitly set the width or height of a text edit or input, + ensure that it is large enough to accommodate the padding values. If the + text does not have enough vertical or horizontal space in which to be + rendered, it will appear clipped. + + \section1 Placeholder Text + + For \uicontrol {Text Field} and \uicontrol {Text Area} controls, you can + specify text to display in a field before users enter text into it. + Specify the text in the \uicontrol {Placeholder text} field and its color + in the \uicontrol {Placeholder color} field. + + \image qtquick-properties-text-field.png "Placeholder text settings" + + Select the \uicontrol Hover check box to enable the text field to accept + hover events. + + \section1 Summary of Text Components + + The following table lists the components that you can use to add text to + UIs. The \e Location column contains the tab name where you can find the + component in \l Library > \uicontrol Components. The \e MCU column + indicates which components are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li Location + \li MCU + \li Purpose + \row + \li \inlineimage icons/label-icon16.png + \li \l [QtQuickControls]{Label} + \li Qt Quick Controls + \li + \li A text label with inherited styling and font. + \row + \li \inlineimage text-icon16.png + \li \l [QtQuick]{Text} + \li Default Components - Basic + \li \inlineimage ok + \li Formatted read-only text. + \row + \li \inlineimage icons/textarea-icon16.png + \li \l [QtQuickControls]{TextArea}{Text Area} + \li Qt Quick Controls + \li + \li Multiple lines of editable formatted text. + \row + \li \inlineimage text-edit-icon16.png + \li \l [QtQuick]{TextEdit}{Text Edit} + \li Default Components - Basic + \li + \li A single line of editable formatted text that can be validated. + \row + \li \inlineimage icons/textfield-icon16.png + \li \l [QtQuickControls]{TextField}{Text Field} + \li Qt Quick Controls + \li + \li A single line of editable plain text. + \row + \li \inlineimage text-input-icon16.png + \li \l [QtQuick]{TextInput}{Text Input} + \li Default Components - Basic + \li + \li A single line of editable plain text that can be validated. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/components/qtquick-user-interaction-methods.qdoc b/doc/qtdesignstudio/src/components/qtquick-user-interaction-methods.qdoc new file mode 100644 index 0000000000..408a5b6a84 --- /dev/null +++ b/doc/qtdesignstudio/src/components/qtquick-user-interaction-methods.qdoc @@ -0,0 +1,348 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-user-interaction-methods.html + \previouspage quick-images.html + \nextpage quick-controls.html + + \title User Interaction Methods + + You can create instances of preset basic components to add interaction + methods to UIs, such as performing actions by using a pointing device or + the keyboard, or flicking the visible area of the screen horizontally or + vertically. They are availabe in \l Library > \uicontrol Components > + \uicontrol {Default Components} > \uicontrol Basic. + + In addition, you can create instances of preset \l{UI Controls} to inform + users about the progress of the application or to gather input from users. + + The following basic components are available for user interaction: + + \list + \li \l {Mouse Area} + \li \l {Focus Scope} + \li \l {Flickable} + \li \l {Summary of Basic Interaction Methods} + \endlist + + You can specify values for the properties of component instances in the + \l Properties view. + + \section1 Mouse Area + + Signals and handlers are used to deliver mouse interactions. Specifically, + you can use a \uicontrol {Mouse Area} component to define JavaScript + callbacks (also called signal handlers), which accept mouse events within + a defined area. + + A mouse area receives events within a defined area. One quick way to define + this area is to \l{Setting Anchors and Margins}{anchor} the mouse area to + its parent's area. If the parent is a \l {basic-rectangle}{Rectangle} (or + any component that is derived from an \l {basic-item}{Item}), the mouse area + will fill the area defined by the parent's dimensions. Alternatively, you + can define an area smaller or larger than the parent. Several controls, such + as \l {Button}{buttons}, contain a mouse area. + + A mouse area emits \l{Connecting Components to Signals}{signals} in response + to different mouse events: + + \list + \li \c canceled() + \li \c clicked() + \li \c doubleClicked() + \li \c entered() + \li \c exited() + \li \c positionChanged() + \li \c pressAndHold() + \li \c pressed() + \li \c released() + \endlist + + \if defined(qtcreator) + A more modern way of handling events from all pointing devices, including + mouse and touchscreen, is via \l {Qt Quick Input Handlers}. + \endif + + \section2 Mouse Area Properties + + A \uicontrol {Mouse Area} is an invisible component that is typically used + in conjunction with a visible component in order to provide mouse handling + for that component. By effectively acting as a proxy, the logic for mouse + handling can be contained within a \uicontrol {Mouse Area} component. + + Select the \uicontrol Enable check box to enable mouse handling for the + proxied component. When disabled, the mouse area becomes transparent to + mouse events. + + \image qtquick-properties-mouse-area.png "Mouse Area properties" + + By default, \uicontrol {Mouse Area} components only report mouse clicks and + not changes to the position of the mouse cursor. Select the \uicontrol Hover + check box to ensure that the appropriate handlers are used and the values of + other properties are updated as necessary even when no mouse buttons are + pressed. + + Even though \uicontrol {Mouse Area} is an invisible component, it has a + \uicontrol Visible property. Deselect the \uicontrol Visible check box in + the \uicontrol Visibility section to make the mouse area transparent to + mouse events. + + In the \uicontrol {Accepted buttons} field, select the mouse button that + the mouse area reacts to. Select \uicontrol AllButtons to have the mouse + area react to all mouse buttons. You can add support for several buttons + in \l {Text Editor} or \uicontrol {Binding Editor} by combining the + values with the OR operator (|). For more information about the available + values, see the developer documentation for \l {MouseArea::acceptedButtons} + {acceptedButtons}. + + \image qtquick-properties-mouse-area-accepted-buttons.png "Adding accepted buttons in Binding Editor" + + In the \uicontrol {Cursor shape} field, select the cursor shape for this + mouse area. On platforms that do not display a mouse cursor, this value + may have no effect. + + In the \uicontrol {Hold interval} field, specify a value to override the + elapsed time in milliseconds before the \c pressAndHold() signal is emitted. + If you do not explicitly set the value or it is reset, it follows the + globally set application style hint. Set this value if you need particular + intervals for particular \uicontrol {Mouse Area} instances. + + Select the \uicontrol {Scroll gesture} check box to respond to scroll + gestures from non-mouse devices, such as the 2-finger flick gesture on + a trackpad. If the check box is not selected, the wheel signal is emitted + only when the wheel event comes from an actual mouse with a wheel, while + scroll gesture events will pass through to any other component that will + handle them. For example, the user might perform a flick gesture while the + cursor is over a component containing a \uicontrol {Mouse Area} instance, + intending to interact with a \uicontrol Flickable component which is + underneath. Setting this property to \c false will allow the \l PinchArea + component to handle the mouse wheel or the pinch gesture, while the + \uicontrol Flickable handles the flick gesture. + + Information about the mouse position and button clicks are provided via + signals for which event handler properties are defined. If a mouse area + overlaps with the area of other instances of the \uicontrol {Mouse Area} + components, you can propagate \c clicked(), \c doubleClicked(), and + \c pressAndHold() events to these other components by selecting the + \uicontrol {Propagate events} check box. Each event is propagated to the + next enabled \uicontrol {Mouse Area} beneath it in the stacking order, + propagating down this visual hierarchy until a \uicontrol {Mouse Area} + accepts the event. + + \section2 Advanced Mouse Area Properties + + You can place a \uicontrol {Mouse Area} instance within a component that + filters child mouse events, such as \uicontrol Flickable. However, the + mouse events might get stolen from the \uicontrol {Mouse Area} if a gesture, + such as a flick, is recognized by the parent component. + + Select the \uicontrol {Prevent stealing} check box to stop mouse events from + being stolen from the \uicontrol {Mouse Area} instance. This value will take + no effect until the next \c press() event if it is set once a component has + started stealing events. + + For more information, see the developer documentation for the \l {MouseArea} + {Mouse Area} component. + + \section2 Drag Properties + + You can specify properties for dragging components in the \uicontrol Drag + section. Select the component to drag in the \uicontrol Target field. + Keep in mind that anchored components cannot be dragged. + + \image qtquick-properties-mouse-area-drag.png "Drag properties" + + In the \uicontrol Axis field, specify whether dragging can be done + horizontally, vertically, or both. + + In the \uicontrol Threshold field, set the threshold in pixels of when the + drag operation should start. By default, this value is bound to a platform + dependent value. + + Select the \uicontrol {Filter children} check box to enable dragging to + override descendant \uicontrol {Mouse Area} instances. This enables a + parent \uicontrol {Mouse Area} instance to handle drags, for example, while + the descendant areas handle clicks. + + Select the \uicontrol Smoothed check box to move the target component only + after the drag operation has started. If this check box is not selected, the + target component is moved straight to the current mouse position. + + \section1 Focus Scope + + When a key is pressed or released, a key event is generated and delivered + to the focused component. If no component has active focus, the key event + is ignored. If the component with active focus accepts the key event, + propagation stops. Otherwise the event is sent to the component's parent + until the event is accepted, or the root component is reached and the event + is ignored. + + A component has focus when the \uicontrol Focus property in the + \uicontrol Advanced section is set to \c true. However, for reusable + or imported components, this is not sufficient, and you should use + a \uicontrol {Focus Scope} component. + + Within each focus scope, one object may have focus enabled. If more + than one component have it enabled, the last component to enable it + will have the focus and the others are unset, similarly to when there + are no focus scopes. + + When a focus scope receives active focus, the contained component with + focus set (if any) also gets the active focus. If this component is + also a focus scope, both the focus scope and the sub-focused component + will have active focus. + + The \uicontrol {Focus Scope} component is not a visual component and + therefore the properties of its children need to be exposed to the parent + component of the focus scope. \l{Using Layouts}{Layouts} and + \l{Using Positioners}{positioners} will use these visual and styling + properties to create the layout. + + For more information, see \l {Keyboard Focus in Qt Quick}. + + \section1 Flickable + + \uicontrol Flickable places its children on a surface that can be dragged + and flicked, causing the view onto the child components to scroll. This + behavior forms the basis of components that are designed to show large + numbers of child components, such as \uicontrol {List View} and + \uicontrol {Grid View}. For more information, see \l{List and Grid Views}. + + In traditional user interfaces, views can be scrolled using standard + controls, such as scroll bars and arrow buttons. In some situations, it + is also possible to drag the view directly by pressing and holding a + mouse button while moving the cursor. In touch-based user interfaces, + this dragging action is often complemented with a flicking action, where + scrolling continues after the user has stopped touching the view. + + The contents of a \uicontrol Flickable component are not automatically + clipped. If the component is not used as a full-screen component, consider + selecting the \uicontrol Clip check box in the \uicontrol Visibility + section. + + \image qtquick-designer-flickable-properties.png "Flickable properties" + + Users can interact with a flickable component if the \uicontrol Interactive + check box is set to \c true. Set it to \c false to temporarily disable + flicking. This enables special interaction with the component's children. + For example, you might want to freeze a flickable map while scrolling + through a pop-up that is a child of the \uicontrol Flickable component. + + The \uicontrol {Flick direction} field determines whether the view can be + flicked horizontally or vertically. Select \uicontrol AutoFlickDirection + to enable flicking vertically if the content height is not equal to height + of the flickable and horizontally if the content width is not equal + to the width of the flickable. Select \uicontrol AutoFlickIfNeeded if + the content height or width is greater than that of the flickable. + + Specify the maximum velocity for flicking the view in pixels per second in + the \uicontrol {Max. velocity} field. Specify the rate at which a flick + will decelerate in the \uicontrol Deceleration field. + + The value of the \uicontrol Movement field determines whether the flickable + will give a feeling that the edges of the view are soft, rather than a hard + physical boundary. Select \uicontrol StopAtBounds for custom edge effects + where the contents do not follow drags or flicks beyond the bounds of the + flickable. Select \uicontrol FollowBoundsBehavior to have the contents + follow drags or flicks beyond the bounds of the flickable depending on the + value of the \uicontrol Behavior field. + + In the \uicontrol {Press delay} field, specify the time in milliseconds + to delay delivering a press to children of a flickable. This can be useful + when reacting to a press before a flicking action has undesirable effects. + If the flickable is dragged or flicked before the delay times out, + the press event will not be delivered. If the button is released + within the timeout, both the press and release will be delivered. + + \note For nested flickables with press delay set, the press delay of + outer flickables is overridden by the innermost flickable. If the drag + exceeds the platform drag threshold, the press event will be delivered + regardless of this property. + + The \uicontrol {Pixel aligned} check box sets the unit of alignment set in + the \uicontrol Content \uicontrol X and \uicontrol Y fields to pixels + (\c true) or subpixels (\c false). Set it to \c true to optimize for still + content or moving content with high constrast edges, such as one-pixel-wide + lines, text, or vector graphics. Set it to \c false when optimizing for + animation quality. + + If \uicontrol {Synchronous drag} is set to \c true, then when the mouse or + touchpoint moves far enough to begin dragging the content, the content will + jump, so that the content pixel which was under the cursor or touchpoint + when pressed remains under that point. The default is \c false, which + provides a smoother experience (no jump) at the cost of losing some of the + drag distance at the beginning. + + \section2 Flickable Geometry + + The \uicontrol {Content size} field specifies the dimensions of the + surface controlled by a flickable. Typically, set the values of the + \uicontrol W and \uicontrol H fields to the combined size of the components + placed in the flickable. You can set additional margins around the + content in the \uicontrol {Left margin}, \uicontrol {Right margin}, + \uicontrol {Top margin}, and \uicontrol {Bottom margin} fields. + + \image qtquick-designer-flickable-geometry.png "Flickable geometry properties" + + The \uicontrol Origin field specifies the origin of the content. It + refers to the top-left position of the content regardless of layout + direction. Usually, the \uicontrol X and \uicontrol Y values are set to 0. + However, a \l{ListView}{List View} and \l {GridView}{Grid View} + may have an arbitrary origin due to delegate size variation, or component + insertion or removal outside the visible region. + + \section1 Summary of Basic Interaction Methods + + The following table lists the components that you can use to add basic + interaction methods to UIs with links to their developer documentation. + They are availabe in \l Library > \uicontrol Components > + \uicontrol {Default Components} > \uicontrol Basic. The \e MCU column + indicates which components are supported on MCUs. + + \table + \header + \li Icon + \li Name + \li MCU + \li Purpose + \row + \li \inlineimage flickable-icon16.png + \li \l [QML]{Flickable} + \li \inlineimage ok + \li Enables flicking components horizontally or vertically. + \row + \li \inlineimage focusscope-icon16.png + \li \l{FocusScope}{Focus Scope} + \li + \li Assists in keyboard focus handling when building reusable + components. + \row + \li \inlineimage mouse-area-icon16.png + \li \l [QtQuick]{MouseArea}{Mouse Area} + \li \inlineimage ok + \li Enables simple mouse handling. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtdesignstudio-simulation-overview.qdoc b/doc/qtdesignstudio/src/overviews/qtdesignstudio-simulation-overview.qdoc new file mode 100644 index 0000000000..b62198deb8 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtdesignstudio-simulation-overview.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page studio-simulation-overview.html + \previouspage qtquick-creating-ui-logic.html + \nextpage qtquick-placeholder-data.html + + \title Simulating Complex Experiences + + \QDS enables you to connect UIs to different forms of data from various + sources, such as QML-based data models, JavaScript files, and backend + services. You can also connect your UI to Simulink to load live data from a + Simulink simulation. + + + \list + \li \l{Loading Placeholder Data} + + You can create QML files that contain placeholder data, so that + you can test grid, list, or path views, even though you don't + have access to real data. + + \li \l{Simulating Application Logic} + + You can use JavaScript to generate mock data for your UI. + + \li \l{Simulating Dynamic Systems} + + Use the Simulink connector to connect a Simulink Simulation Model to + your UI. Simulink is a MATLAB-based graphical programming environment + for modeling, simulating, and analyzing multi-domain dynamic systems. + + \li \l{Using QML Modules with Plugins} + + You can load C++ plugins for QML to simulate data. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-animation-overview.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-animation-overview.qdoc new file mode 100644 index 0000000000..672e62c8ae --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-animation-overview.qdoc @@ -0,0 +1,263 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-animation-overview.html + \previouspage qtquick-motion-design.html + \nextpage studio-timeline.html + + \title Introduction to Animation Techniques + + \image timeline-rotation-animation.gif "Timeline animation of rotation and opacity" + + \QDS supports the following types of animation techniques that are suitable + for different purposes: + + \list + \li Common motion design techniques for 2D and 3D + \li Screen-to-screen or state-to-state animations + \li Data-driven UI logic animations + \endlist + + \section1 Common Motion Design Techniques + + The following table summarizes common motion design techniques for 2D and + 3D and their typical use cases. + + \table + \header + \li Technique + \li Use Case + \row + \li \l{Timeline}{Timeline animation} + \li Linear interpolation through intermediate values at specified + keyframes instead of immediately changing to the target value. + \row + \li \l{Editing Easing Curves}{Easing curves} attached to keyframes + \li Nonlinear interpolation between keyframes to make components + appear to pick up speed, slow down, or bounce back at the end + of the animation. + \row + \li \l{Curve Editor}{Animation curves} attached to keyframes + \li Complex 3D animations that require several keyframes so it becomes + necessary to visualize the value and the interpolation of a keyframe + simultaneously. + \endtable + + \section2 Timeline and Keyframe Based Animation + + Timeline animation is based on \e keyframes. In \QC, keyframes determine the + value of the property of a \l{glossary_component}{component} at a certain + time. Animating properties enables their values to move through intermediate + values instead of immediately changing to the target value. + + For example, you can set the y position property of a rectangle to 0 at the + start of your animation and to 100 at the end of the animation. When the + animation is run, the rectangle moves from position 0 to 100 on the y axis. + In the middle of the animation, the y property has the value of 50 since + keyframes are interpolated linearly by default. + + \section2 Easing Curves + + Sometimes you don't want linear movement but would rather like the rectangle + to move faster at the beginning and slower at the end of the animation. To + achieve this effect, you could insert a large number of keyframes between + the start frame and the end frame. To avoid this effort, you can specify + \e {easing curves} for nonlinear interpolation between keyframes. The + easing curves can make components appear to pick up speed, slow down, or + bounce back at the end of the animation. + + \section2 Animation Curves + + While easing curves work well for most simple UI animations, more complex + 3D animations require several keyframes so it becomes necessary to visualize + the value and the interpolation of a keyframe simultaneously. The + \l {Curve Editor} visualizes the whole animation of a property at once and + shows the effective values of a keyframe together with the interpolation + between keyframes. It can also show animations of different properties + simultaneously so that you can see the animation for the x position + and the animation for the y position side-by-side. + + \section1 Screen-to-Screen or State-to-State Animations + + The following table summarizes techniques used for navigating between + screens and UI states. + + \table + \header + \li Technique + \li Use Case + \if defined(qtdesignstudio) + \row + \li \l{Designing Application Flows}{Application flows} + \li An interactive prototype that can be clicked through to simulate + the user experience of the application. + \endif + \row + \li \l{Transition Editor}{Transitions between states} + \li Transitions between different states of the UI using a transition + timeline that is based on keyframes. You can apply easing curves + to the keyframes. + \endtable + + \if defined(qtdesignstudio) + \section2 Application Flows + + You can design an application in the form of a \e {schematic diagram} + that shows all the significant components of the application UI and their + interconnections by means of symbols. This results in an interactive + prototype that can be clicked through to simulate the user experience of + the application. Code is created in the background and can be used + as the base of the production version of the application. + + For more information, see \l{Designing Application Flows}. + \endif + + \section2 Transitions Between States + + UIs are designed to present different UI configurations in different + scenarios, or to modify their appearances in response to user + interaction. Often, several changes are made concurrently so that the + UI can be seen to be internally changing from one \e state to another. + + This applies generally to UIs 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. At the other + end of the scale, when a button is pressed, it may change to a + \e pressed state in which its color and position are modified so that it + appears to be pressed down. + + Any component can change between different states to apply sets of + changes that modify the properties of relevant components. Each state can + present a different configuration that can, for example: + + \list + \li Show some UI components and hide others. + \li Present different available actions to the user. + \li Start, stop, or pause animations. + \li Execute some script required in the new state. + \li Change a property value for a particular component. + \li Show a different view. + \endlist + + State changes introduce abrupt motion that you can make visually appealing + by using \e transitions. Transitions are animation types that interpolate + property changes caused by state changes. + + In \l {Transition Editor}, you can set the start frame, end frame, + and duration for the transition of each property. You can also set + an \l{Editing Easing Curves}{easing curve} for each animation and + the maximum duration of the whole transition. + + \section1 Data-Driven UI Logic Animations + + The following table summarizes techniques used for animating the UI logic + by using real or mock data from a backend. + + \table + \header + \li Technique + \li Use Case + \row + \li Data-driven timeline animation + \li Using real or mock data from a backend to control motion. + \row + \li Programmatic property animation + \li Interpolating property values programmatically to create smooth + transitions. + \endtable + + \section2 Data-Driven Timeline Animation + + You can connect property values to data backends to drive timeline + animation. You can fetch data from various sources, such as data models, + JavaScript files, and backend services. You can also connect your UI to + Simulink to load live data from a Simulink simulation. + + You can connect these data sources to the current frame of a timeline, + creating animation when the backend changes the current frame property. + + For example, you could connect the speed value from a backend to a + tachometer dial in a cluster. As the speed value is increased or + decreased from the backend, it moves the needle animation from one + end of the timeline to the other. + + For more information, see \l{Simulating Complex Experiences}. + + \section2 Programmatic Animation + + You can control property animation programmatically. Property animations + are created by binding \uicontrol Animation components to property + values of component instances to gradually change the property values + over time. The property animations apply smooth movement by interpolating + values between property value changes. They provide timing controls and + enable different interpolations through easing curves. + + Developers can control the execution of property animations by using the + \c start(), \c stop(), \c resume(), \c pause(), \c restart(), and + \c complete() functions. + + You can create instances of preset animation components available in + \l Library > \uicontrol Components > \uicontrol {Default Components} > + \uicontrol Animation to create animations depending on the type of the + property and the behavior that you want. + + For more information about \uicontrol Animation components and their + properties, see \l{Animations}. + + \table + \header + \li Component + \li Use Case + \row + \li \uicontrol {Property Animation} + \li Applying animation when the value of a property changes. Color + and number animations are property animation types for specific + purposes. + \row + \li \uicontrol {Property Action} + \li Setting non-animated property values during an animation. + \row + \li \uicontrol {Color Animation} + \li Applying animation when a color value changes. + \row + \li \uicontrol {Number Animation} + \li Applying animation when a numerical value changes. + \row + \li \uicontrol {Parallel Animation} + \li Running animations in parallel. + \row + \li \uicontrol {Sequential Animation} + \li Running animations sequentially. + \row + \li \uicontrol {Pause Animation} + \li Creating a step in a sequential animation where nothing happens for + a specified duration. + \row + \li \uicontrol {Script Action} + \li Executing JavaScript during an animation. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-annotations.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-annotations.qdoc new file mode 100644 index 0000000000..8c493319b9 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-annotations.qdoc @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-annotations.html + \if defined(qtdesignstudio) + \previouspage qtquick-positioning.html + \nextpage qtquick-prototyping.html + \else + \previouspage qtquick-fonts.html + \nextpage creator-quick-ui-forms.html + \endif + + \title Annotating Designs + + You can submit your designs to review or further development as QML files. + You can annotate your designs to provide reviewers or developers with + additional information about them. You can add \e {global annotations} + that apply to the whole file or annotate individual components. + + An annotation consist of an annotation name and one or several comments. + The comments have a title, author, and comment text. + + To add or edit global annotations, select \inlineimage icons/annotation.png + on the top menu bar in the Design mode. + + Global annotations have an additional status property, which enables you + to indicate whether you are still working on the design, you have submitted + it to review, or it can be considered done. To set the status, select + \uicontrol {Add Status}. + + \image qtquick-annotations.png "Annotation Editor" + + Annotations are saved in the end of QML files when you save the file. They + do not affect the QML performance in any way. + + \section1 Annotating Components + + To add annotations to components: + + \list 1 + \li Select the component to annotate in \uicontrol Navigator or in + \uicontrol {Form Editor}. + \li In \uicontrol Properties, select \uicontrol {Add Annotation} to + open \uicontrol {Annotation Editor}. + \image qtquick-annotation-editor.png "Annotation Editor" + \li The \uicontrol {Selected Item} field displays the ID of the + component. + \li In the the \uicontrol Name field, enter a free-form text that + describes the component. + \li In the \uicontrol Title field, enter the text to display in + the tab for this comment. + \li In the \uicontrol Author field, enter the author's name. + \li In the \uicontrol Text field, enter the comment text. + \li Select \uicontrol OK. + \endlist + + To add more comments about the component, select the \inlineimage plus.png + (\uicontrol {Add Comment}) button. + + To remove the active comment, select the \inlineimage minus.png + (\uicontrol {Remove Comment}) button. To remove the annotation, right-click + the annotation icon, and then select \uicontrol {Remove Annotation}. + + To view the annotations in table format, select \uicontrol {Table view}. + + To edit annotations, select \uicontrol {Edit Annotation} in the context + menu of the component. +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc new file mode 100644 index 0000000000..1b7be83102 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-creating-ui-logic.qdoc @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-creating-ui-logic.html + \previouspage qtquick-prototyping.html + \nextpage studio-simulation-overview.html + + \title Creating UI Logic + + Turn your wireframe into an interactive prototype by adding UI logic that + enables your components to apply actions or react to mock data from backend + systems to simulate complex experiences. + + Create connections between the UI components to enable them to communicate + with each other. For example, how should the appearance of a button change + on a mouse click and which action should the UI perform in response to the + \e signal that is emitted upon the mouse click. + + You can create connections between UI components by binding their + properties together. This way, when the value of a property changes in a + parent component, it can be automatically changed in all the child + components by emitting a signal that indicates a change in the value. + + To reference a property of a component from another component, you can + create \l{Adding Property Aliases}{property aliases} that hold a reference + to another property. Unlike an ordinary property definition, which + allocates a new, unique storage space for the property, a property + alias connects the newly declared property (called the + \e {aliasing property}) as a direct reference to an existing property + (the \e {aliased property}). Any content that is data-driven should be + exported as a public property of the relevant component. For example, + a speedometer should have a property for speed to which the UI is bound. + + You can declare various \l{Adding States}{UI states} that describe how + property values change from a base state. States can be a useful way of + organizing your UI logic. You can associate transitions with components + to define how their properties will animate when they change due to a + state change. + + \if defined(qtdesignstudio) + The \l{Log In UI - States} example illustrates using states to create + two UI screens and signals emitted by buttons to apply the states. + The button components also switch states when they are pressed down. + + \image loginui3.gif "Clicking buttons to switch between screens" + \endif + + Using property aliases and states to create the differences in your + component instances enables you to reuse components instead of duplicating + them. Thus, the components do not need to be processed as completely new + component types. This reduces the loading and compilation time as well as + the package size of the final application. + + The preset \l{UI Controls}{UI controls} have default properties and states + that you can modify. If you need additional properties, you can turn + instances of the controls into custom components and specify new properties + for them. + + \if defined(qtdesignstudio) + To have your UI perform certain operations, you might need to write + JavaScript expressions for conditions or convert numbers to strings. + To make this easier, \QDS provides preset components called + \l{Logic Helpers}{logic helpers}. They are invisible components that + you can use in connection with controls, such as a \l {slider-control} + {Slider} or \l {Check Box}. + + Logic helpers are available for binding property values using the boolean + AND, NOT, and OR operators, as well as for mapping numbers and numerical + ranges. In addition, you can synchronize the property values of two + components bi-directionally. + + The logic helper example uses property binding, states, and logic helpers + to implement the UI logic. + + \image studio-logic-helper-combining-example.gif "Logic helper example application" + \endif + + The following table summarizes some typical use cases with links to more + information. + + \table + \header + \li To Learn About + \li Go To + \row + \li Responding to application events + \li \l{Connecting Components to Signals} + \row + \li Formatting connections + \li \l{Adding Actions and Assignments} + \row + \li Dynamically changing the behavior of a component + \li \l{Adding Bindings Between Properties} + \row + \li Formatting property bindings + \li \l{Setting Bindings} + \row + \li Referencing a property of a component from another component + \li \l{Adding Property Aliases} + \row + \li Referencing a state from within a specific component + \li \l{Adding States} + \row + \li Switching to a state when a particular property changes + \li \l{Applying States} + \row + \li Using preset UI controls that have default properties and states + \li \l{UI Controls} + \if defined(qtdesignstudio) + \row + \li Creating conditional conditions + \li \l{Logic Helpers} + \endif + \row + \li Adding custom properties for a particular component type + \li \l{Specifying Dynamic Properties} + \omit + \row + \li Adding properties for controlling states + \li TODO + \endomit + \endtable +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc new file mode 100644 index 0000000000..2aed8fea62 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-export.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page creator-exporting-qml.html + \previouspage studio-importing-3d.html + \nextpage qtquick-motion-design.html + + \title Exporting Components + + \l{glossary-component}{Components} contained in \l{UI Files} + {UI files} (.ui.qml) can be exported to JSON metadata format and PNG assets. + + To export the UI files from the current project, select \uicontrol Build > + \uicontrol {Export Components}. + + The primary use of exported metadata and assets is to generate native file + formats in content creation tools, such as Adobe Photoshop, using \QB. \QBPS + can generate PSD files by importing the metadata and assets. + + Components are exported as follows: + + \list + \li Components (QML types) inherited from \l [QML]{Item}{Item} are + exported, other components are ignored. + \li \l [QML]{Text}{Text} components are exported as metadata only + and no assets are generated. + \li \l [QML]{Rectangle}{Rectangle} and \l [QML]{Image}{Image} + components generate assets as PNG files. + \endlist + + \section1 Configuring QML Export + + You can configure the export in the \uicontrol {Export Components} dialog, + which lists the UI files (.ui.qml) of the current project. + + \image qtquick-qml-export-dialog.png "Export Components dialog" + + \list 1 + \li In the \uicontrol {Export path} field, specify the path where + the metadata file and assets are exported. + \li Deselect the \uicontrol {Export assets} check box to disable + exporting assets and only generate the metadata file. + \li Select the \uicontrol {Export components separately} check box to + generate separate metadata files for each component. + \li In the file list, select the .ui.qml files to be exported. + \li Select \uicontrol {Export} export to start the export process. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-fonts.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-fonts.qdoc new file mode 100644 index 0000000000..bf79ffa20b --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-fonts.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-fonts.html + \if defined(qtdesignstudio) + \previouspage studio-importing-2d.html + \nextpage studio-importing-3d.html + \else + \previouspage qtquick-positioning.html + \nextpage qtquick-annotations.html + \endif + + \title Using Custom Fonts + + For your UI to use custom fonts when you preview it on a device, + you have to import the fonts to the project folder. \QDS deploys them to + the device along with your UI. + + \note Use fixed-width fonts if you plan to animate running numbers, so that + they do not appear to jump around the screen when they change. + + To add fonts: + + \list 1 + \li Select \uicontrol Library > \l Assets + > \inlineimage plus.png + . + \li Browse to the folder that contains the font files and select them, + and then select \uicontrol Open. + \li Select the location where the file will be saved in the + \uicontrol {Add Resources} dialog. + \li Select \uicontrol OK to save the fonts. + \endlist + + The fonts are added to the list of fonts for the \uicontrol Font property + in \l Properties. +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-motion-design.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-motion-design.qdoc new file mode 100644 index 0000000000..91f842e08e --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-motion-design.qdoc @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-motion-design.html + \previouspage creator-exporting-qml.html + \nextpage quick-animation-overview.html + + \title Motion Design + + \table + \row + \li \image studio-animation.png + \li You can use different animation techniques for different + purposes. \QDS supports common motion design techniques, + such as timeline and keyframe based animation and easing + curves, as well as screen-to-screen or state-to-state + application flows and data-driven UI logic animation. + \endtable + + \list + \li \l {Introduction to Animation Techniques} + + Learn more about which animation techniques are supported by \QDS + and the use cases they are most suitable for. + + \li \l {Creating Timeline Animations} + + You can use a timeline and keyframe based editor in the + \l Timeline view to animate the properties of UI + components. Animating properties enables their values to + move through intermediate values at specified keyframes + instead of immediately changing to the target value. + \li \l{Editing Easing Curves} + + Specify easing curves for nonlinear interpolation between + keyframes in timeline animations, as well as between original + and new property values in property animations and between + transitions. + \li \l {Production Quality} + + After the wireframing and prototyping phases, you can use previewing + and profiling tools to fine-tune your UI for production. + \li \l{Optimizing Designs} + + You can test your UIs on the target devices to make sure you get + the best performance out of your animations. To solve performance + problems, you typically need to optimize the graphical assets used + in the UI, such as images, effects, or 3D scenes. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc new file mode 100644 index 0000000000..0f6c31fe84 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-optimizing-designs.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-optimizing-designs.html + \previouspage qtquick-production-quality-animation.html + \nextpage studio-optimized-3d-scenes.html + + \title Optimizing Designs + + You can test your UIs on the target devices to make sure you get the best + performance out of your animations. To solve performance problems, you + typically need to optimize the graphical assets used in the UI, such as + images, effects, or 3D scenes. + + How to optimize UIs for different target devices: + + \list + \li Minimize image size + \li Use transparency sparingly + \endlist + + For more useful information for application developers, see + \l {Performance Considerations And Suggestions}. + + For more information about optimizing 3D scenes, see + \l{Creating Optimized 3D Scenes}. + + \section1 Minimizing Image Size + + Images are a vital part of any user interface. Unfortunately, they are also + a big source of problems due to the time it takes to load them, the amount + of memory they consume, and the way in which they are used. + + We recommend that you make image size as small as possible without + negatively affecting image quality. + + For more information about how to use images efficiently in your UI, see + \l{Images}. + + \section1 Avoid Transparency + + Opaque content is generally a lot faster to draw than transparent because + the latter needs blending and the renderer can potentially optimize opaque + content better. + + An image with one transparent pixel is treated as fully transparent, even + though it is mostly opaque. The same is true for a \l {Border Image} with + transparent edges. +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-placeholder-data.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-placeholder-data.qdoc new file mode 100644 index 0000000000..237cfc67ef --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-placeholder-data.qdoc @@ -0,0 +1,118 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-placeholder-data.html + \previouspage studio-simulation-overview.html + \nextpage studio-javascript.html + + \title Loading Placeholder Data + + \QDS supports views, models, and delegates, so that when you add + a Grid View, List View, or Path View component, the ListModel and + the delegate component are added automatically. + + However, the missing context of the application presents a challenge. + 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 component files. A typical example is a component that uses the + properties of its parent, such as \c parent.width. + + \section1 Using Dummy Models + + If you open a file in \l {Form Editor} that references a C++ model, you see + nothing in it. If the data in the model is fetched from the + internet, you have no control over it. To get reliable data, \e {dummy data} + was introduced. + + For example, the following code snippet describes the file example.qml that + contains a ListView that in turn specifies a C++ model: + + \qml + ListView { + model: dataModel + delegate: ContactDelegate { + name: name + } + } + \endqml + + Create a directory named \e dummydata in the root directory of the project, + so that it is not deployed to the device. In the \c dummydata directory, + create a file (.qml) that has the same name as the value of \c model: + + \code + qml/exampleapp/example.qml + dummydata/dataModel.qml + \endcode + + Then create the dataModel.qml file that contains the dummy data: + + \qml + import QtQuick 2.0 + + ListModel { + ListElement { + name: "Ariane" + } + ListElement { + name: "Bella" + } + ListElement { + name: "Corinna" + } + } + \endqml + + \section1 Creating Dummy Context + + The following example presents a common pattern: + + \qml + Item { + width: parent.width + height: parent.height + } + \endqml + + This works nicely for applications but \uicontrol {Form Editor} displays a + zero-sized component. A parent for the opened file does not exist, because + the context is missing. To get around the missing context, the idea of a + \e {dummy context} is introduced. If you place a file with the same name as + the application (here, example.qml) in the \c {dummydata/context} directory, + you can fake a parent context: + + \qml + import QtQuick 2.0 + import QmlDesigner 1.0 + + DummyContextObject { + parent: Item { + width: 640 + height: 300 + } + } + \endqml +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc new file mode 100644 index 0000000000..bfdf435cf6 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-production-quality-animation.qdoc @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-production-quality-animation.html + \previouspage qtquick-editing-easing-curves.html + \nextpage qtquick-optimizing-designs.html + + \title Production Quality + + After the wireframing and prototyping phases, you can use previewing and + profiling tools to fine-tune your UI for production. + + How to achieve production quality motion in UIs: + + \list + \li Preview the UI to check the FPS refresh rate. + \li Profile the UI code to find causes for slowness, unresponsiveness, + and stuttering. + \endlist + + \section1 FPS Refresh Rate + + As a general rule, animators strive to allow the rendering engine to + achieve a consistent 60 frames-per-second (FPS) refresh rate. 60 FPS + means that there is approximately 16 milliseconds between each frame + in which processing can be done, which includes the processing required + to upload the draw primitives to the graphics hardware. + + The frames-per-second (FPS) refresh rate of animations is displayed in the + \uicontrol FPS field on the \l{Summary of Main Toolbar Actions}{toolbar} + in the \uicontrol Design mode. + + To improve the FPS rate, application developers should: + + \list + \li Use asynchronous, event-driven programming wherever possible. + \li Use worker threads to do significant processing. + \li Never manually spin the event loop. + \li Never spend more than a couple of milliseconds per frame within + blocking functions to avoid skipped frames, which negatively + affect the user experience. + \endlist + + For more information about previewing UIs on devices, see + \l{Validating with Target Hardware}. + + \section1 Profiling UI Code + + You can use \l{Profiling QML Applications}{QML Profiler} that is integrated + into \QC to find causes for typical performance problems in your UI. For + example, your UI might be slow, unresponsive, or stuttering. Typically, such + problems are caused by executing too much JavaScript in too few frames. All + JavaScript must return before the GUI thread can proceed, and frames are + delayed or dropped if the GUI thread is not ready. + + In general, knowing where time is spent in a UI enables you to focus on + problem areas that actually exist, rather than problem areas that + potentially exist. + + Determining which bindings are being run the most often or which functions + your application is spending the most time on enables you to decide whether + you need to optimize the problem areas, or redesign some implementation + details of your application so that the performance is improved. Attempting + to optimize code without profiling is likely to result in very minor rather + than significant performance improvements. + + For more information, see \l{Profiling QML Applications}. +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-prototyping.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-prototyping.qdoc new file mode 100644 index 0000000000..1e9c784000 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-prototyping.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-prototyping.html + \if defined(qtdesignstudio) + \previouspage qtquick-annotations.html + \else + \previouspage creator-quick-ui-forms.html + \endif + \nextpage qtquick-creating-ui-logic.html + + \title Prototyping + + \table + \row + \li \image studio-3d-scenes.png + \li After your UI wireframe has been approved, you can turn it + into an interactive prototype to ensure that you and the + developers share a common vision about the UI appearance + and functionality. You can create the UI logic to simulate + complex experiences and add dynamic behavior. You can then + validate your design on desktop, embedded, and mobile device + platforms. In the prototyping phase, you can also import + assets from 2D and 3D content creation tools to bring your + prototype closer to the final UI. + \endtable + + \list + + \li \l {Creating UI Logic} + + You can turn your wireframe into an interactive prototype by + adding the logic that enables your components to apply actions + or react to mock data from backend systems to simulate complex + experiences. + \li \l{Simulating Complex Experiences} + + You can connect UIs to different forms of data from various + sources, such as QML-based data models, JavaScript files, and + backend services. + \if defined(qtdesignstudio) + You can also connect your UI to Simulink to load live data from + a Simulink simulation. + \endif + + \li \l {Dynamic Behaviors} + + You can create connections between components to enable them to + communicate with each other. The connections can be triggered by + changes in component property values or in UI states. + + \if defined(qtdesignstudio) + \li \l {Validating with Target Hardware} + + You can use the live preview feature to preview a UI file or the + entire UI on the desktop, as well as on Android and embedded Linux + devices. The changes you make to the UI are instantly visible + to you in the preview. + + \li \l {Asset Creation with Other Tools} + + Describes how to export designs containing 2D and 3D assets into + files that you can import to projects in \QDS, how to import them, + and how to export them from \QDS back to the metadata format. + + \else + \li \l {Exporting 3D Assets} + + You can export assets from 3D graphics applications into several + widely-used formats, such as .blend, .dae, .fbx, .glb, .gltf, .obj, + .uia, or .uip. + + \li \l {Importing 3D Assets} + + You can import exported assets into \QC. For a list of formats + supported by each \l{Qt Quick 3D} version, see the module + documentation. + + \li \l {Exporting Components} + + You can export components contained in \l{UI Files}{UI files} + (.ui.qml) to JSON metadata format and PNG assets. + \endif + + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/qtquick-uis.qdoc b/doc/qtdesignstudio/src/overviews/qtquick-uis.qdoc new file mode 100644 index 0000000000..3cb66337fc --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/qtquick-uis.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-uis.html + \if defined(qtdesignstudio) + \previouspage {Examples and Tutorials} + \nextpage studio-app-flows.html + \else + \previouspage qtquick-text-editor.html + \nextpage quick-components.html + \endif + + \title Wireframing + + \table + \row + \li \image front-ui.png + \li Plan your UI properly. Know what elements, such as screens, + components, and states, you need. Create a descriptive wireframe + and acquire a detailed UI specification before you start to make + the process of creating the UI more efficient. + \QC enables you to turn your UI concept into a wireframe with + a scalable layout where all your screens and controls are in + place. You can present your wireframe to developers and other + stakeholders for discussion, review, and approval before + continuing into the prototyping phase. + \endtable + + In \QC, you build UIs around the behavior of \l{glossary-component} + {components} and how they connect with one another. You can use preset + components available in the \l Library view or combine them to create + your own components. You can specify values for the \e properties of a + component to change its appearance and behavior. All components have a + set of predefined properties, some of which control things that are + visible to users, while others are used behind the scene. + + You drag-and-drop the preset components from the \uicontrol Library view + to the \l {Form Editor}, \l{3D Editor}, or \l Navigator view to create + instances of them. You then change the instances to your liking by modifying + their properties in the \l Properties view. The application code is + generated for you accordingly. For more information about the code, open + the developer documentation by pressing \key F1. + + \list + + \if defined(qtdesignstudio) + \li \l {Designing Application Flows} + + You can design an application in the form of a \e {schematic diagram} + that shows all significant components of an application UI and their + interconnections by means of symbols. This results in an + interactive prototype that can be clicked through to simulate + the user experience of the application. + \endif + + \li \l {Components} + + \QDS comes with \e {preset components} that you can use in + wireframes and prototypes by creating instances of them. + To build your own components, you can modify the \e properties + of the component instances and combine them. You can import + designs and assets from other tools as components. + + \li \l {Specifying Component Properties} + + You can specify values for the properties of a component to change + its appearance and behavior. All components have a set of predefined + properties. Some properties, such as position, size, and visibility, + are common to all components, whereas others are specific to the + component. You can specify values for properties of component + instances in the \l Properties view. + + \li \l {Scalable Layouts} + + The position of a component in a UI can be either absolute + or relative to other components. While manual positioning + is efficient for a static UI, consider the other available + methods, such as anchors, layouts, positioners, and property + bindings, for dynamic UIs. + + \if defined(qtcreator) + \li \l {Using Custom Fonts} + + You can load custom fonts to \QC and use them in your designs. + \endif + + \li \l {Annotating Designs} + + You can annotate your designs to provide reviewers or developers + with additional information about them. + + \if defined(qtcreator) + \li \l {Loading Placeholder Data} + + You can create QML files that contain placeholder data, so that + you can test grid, list, or path views, even though you don't + have access to real data. + + \li \l{UI Files} + + Some of the wizards create projects that contain UI files + (.ui.qml). You should always edit UI files in \l{Form Editor} + and \l Properties, to avoid breaking the code. + + \endif + + \endlist +*/ diff --git a/doc/qtdesignstudio/src/overviews/studio-crashpad.qdoc b/doc/qtdesignstudio/src/overviews/studio-crashpad.qdoc new file mode 100644 index 0000000000..e195977f8b --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/studio-crashpad.qdoc @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page studio-crashpad.html + \previouspage studio-user-feedback.html + \nextpage studio-packaging.html + + \title Reporting Crashes + + You can enable \QDS to report crashes automatically. \QDS uses Google + Crashpad to collect crashes and report them to the Sentry backend storage + for processing. The purpose of Crashpad is to capture application state in + sufficient detail to allow developers to diagnose and, where possible, fix + the issue causing the crash. Crashpad may capture arbitrary contents from + the memory of a crashed process, including user sensitive information, URLs, + and other content provided by the users. The collected reports are used for + the sole purpose of fixing bugs. For more information on Crashpad, see the + \l {https://chromium.googlesource.com/crashpad/crashpad/+/master/doc/overview_design.md} + {documentation} by Google. For more information on processing and storing + of the collected data, see \l {https://sentry.io/security/} + {Security & Compliance} by Sentry. + + To enable sending crash reports, select \uicontrol Tools > \uicontrol + Options > \uicontrol Environment > \uicontrol System + (\uicontrol {Qt Design Studio} > \uicontrol Preferences > \uicontrol + Environment > \uicontrol System on \macos), and then select + \uicontrol {Enable crash reporting}. + + Since crash reports take up disk space, you may wish to remove them when + they are no longer needed. Select \uicontrol {Clear local crash reports} to + remove the crash report data. + + \image studio-crashpad-checkbox.png "Checkbox for enabling crash reporting" + + \note Crashpad is currently only supported on Windows and \macos. +*/ diff --git a/doc/qtdesignstudio/src/overviews/studio-user-feedback.qdoc b/doc/qtdesignstudio/src/overviews/studio-user-feedback.qdoc new file mode 100644 index 0000000000..463148a1c4 --- /dev/null +++ b/doc/qtdesignstudio/src/overviews/studio-user-feedback.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page studio-user-feedback.html + \previouspage collecting-usage-statistics.html + \nextpage studio-crashpad.html + + \title Collecting User Feedback + + A pop-up survey asking for your feedback will appear for some of the features + after you have been using them for some time. You will be asked to to rate + the usefulness of the feature on a scale of one to five stars. You must rate + the feature with at least one star if you wish to submit your rating. You + are also encouraged to give additional written feedback. After you select + \uicontrol Skip or \uicontrol Submit, the pop-up survey will not appear for + the same feature again. + + \image studio-feedback-popup.png "User feedback pop-up survey for Flow Editor" + + For the pop-up survey to appear, you must enable collecting statistics, and + also allow collecting \uicontrol {4 - Detailed usage statistics} in + \uicontrol Tools > \uicontrol Options > \uicontrol Telemetry > + \uicontrol {Usage Statistics} > \uicontrol {Telemetry mode}. + You can review the submitted user feedback in + \uicontrol Tools > \uicontrol Options > \uicontrol Telemetry > + \uicontrol {Usage Statistics} > \uicontrol {Collected Data} by selecting + \uicontrol {Qt Quick Designer Usage of views and actions} in + \uicontrol {Data sources}. +*/ diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc index 87a9904cc8..4b45b87670 100644 --- a/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc +++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc @@ -127,7 +127,7 @@ \li Second level group layers are merged to their parent. \li Asset layers are exported as merged. \li Text layers are always exported as child items. - \li Images are exported in JPG, PNG, or SVG format, depending on your + \li Images are exported in PNG or JPG format, depending on your selection. \endlist diff --git a/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc index d789677057..8f43fca390 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-packaging.qdoc @@ -25,7 +25,7 @@ /*! \page studio-packaging.html - \previouspage creator-crashpad.html + \previouspage studio-crashpad.html \nextpage studio-developer-topics.html \title Packaging Applications diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-optimized-3d-scenes.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-optimized-3d-scenes.qdoc new file mode 100644 index 0000000000..43379fdc35 --- /dev/null +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-optimized-3d-scenes.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page studio-optimized-3d-scenes.html + \previouspage qtquick-optimizing-designs.html + \if defined(qtdesignstudio) + \nextpage studio-implementing-applications.html + \else + \nextpage qtquick-iso-icon-browser.html + \endif + + \title Creating Optimized 3D Scenes + + In \QC, you can use various means to create a 3D scene. Your choice of + strategy should always depend on the target platform of your scene. + The way the content of your scene is authored can have dramatic effects on + the runtime performance of your UI. The Optimal 3D Scene described + below illustrates four different ways to create a scene. Also see guidelines + for \l{Optimizing your 3D Scene}{optimizing the graphics performance of your 3D scene} + and \l{Best Practices for 3D Scenes Based on Use Cases}. + + \section1 The Optimal 3D Scene Example + + \if defined(qtdesignstudio) + The \l {Optimal 3D Scene} + \else + The Optimal 3D Scene + \endif + example features four versions of the same kitchen + scene that have been created using different strategies: High, Low, Combined, + and Vertex Color. The High Scene includes a significantly higher number of + objects compared to the other versions of the scene. The Low, Combined and + Vertex scenes include less objects since they have been optimized by, for + example, combining geometry and baking materials into textures. The + following image displays the components in each scene in \l Navigator to + illustrate the structural differences between the scenes. + + \image studio-kitchen-navigators.png "Navigators for the four scenes in the Optimal 3D Scene." + + \section2 The High Scene + + \image studio-kitchen-high.png "The High Scene in the Optimal 3D Scene" + + The High scene (1) includes a total of 27 objects. The scene is otherwise + similar to the Low scene, but has more details and animated components, such + as cabinet doors that can be opened and a latch for the oven. + + \section2 The Low Scene + + \image studio-kitchen-low.png "The Low Scene in the Optimal 3D Scene" + + The Low scene (2) includes a total of 12 objects. Each model, for example + cabinets, lamps, plates, and the sink, are separate meshes. + + \section2 The Combined Scene + + \image studio-kitchen-combined.png "The Combined Scene in the Optimal 3D Scene" + + The Combined scene (3) has all the meshes combined into a single object. All + materials are baked into one single texture. + + \section2 The Vertex Color Scene + + \image studio-kitchen-vertex.png "The Vertex Color Scene in the Optimal 3D Scene" + + The Vertex Color scene (4) has all the meshes combined into a single object, + and colors for the mesh are provided from .mesh file's vertex data, which + includes one material and no textures. + + \section1 Optimizing Your 3D Scene + + To optimize the graphics performance of your 3D scene, you should first + consider whether you need to animate the 3D objects, lights, camera, or + other components in your scene. If not, simplify the scene structure by, for + example, combining geometries and baking materials into textures. Ideally, + pre-render your 3D image into a 2D image. You should not waste resources + by rendering static 3D objects. You should also check if your scene has + multiple instances of the same mesh. If so, import only one instance of the + mesh, duplicate it in the scene, and use the same material for each + duplicate. + + See also the following guidelines related to scene graph, asset complexity, + CPU specific optimization, and model geometry. + + \section2 Scene Graph + + The scene graph is the hierarchy of nodes that describe the scene to be + rendered. + + In \QC, the scene graph is represented by the tree-like view in + \uicontrol Navigator. You can also view the hierarchy of nodes in the + \l {Text Editor} view. By minimizing the size of the scene graph, + you can minimize the effort needed when running the scene. In terms of + optimization, you should avoid unnecessary groups and complex hierarchy when + possible. Deep hierarchies with complex parenting increase the performance + cost. + + \section2 Asset Complexity + + The performance of your UI or scene may sometimes be bottlenecked at render + time. Avoid this by simplifying your assets. + + For 3D models, you should try to use the minimum number of triangles or + vertices to achieve the desired result. Also note that smaller images + require less memory and render faster. + + \section2 Optimizing CPU Performance + + Rendering objects requires plenty of processing work from the CPU. + Processing each component consumes resources, so reducing the visible object + count reduces the amount of work required from the CPU. + + To reduce the visible object count: + \list + \li Combine objects that are positioned closely and share a texture. + \note Combining objects that do not share a texture does not increase + the CPU performance while running the scene. + \li Use fewer materials by combining separate textures into a single + texture atlas (like in the Merged scene in the + Kitchen Scene Example). + \li Minimize the number of factors that cause objects to be rendered + multiple times, for example reflections and shadows. + \endlist + + \section2 Optimizing Model Geometry + + To optimize the geometry of a model: + + \list + \li Minimize the number of triangles used in the model. + \li Minimize the number of UV mapping seams and hard edges created with + doubled-up vertices. + \endlist + + \section1 Best Practices for 3D Scenes Based on Use Cases + + The following table summarizes best practices related to optimizing 3D + scenes in the form of use cases. + + \table + \header + \li How to... + \li Solution + \row + \li Get best performance from the 3D scene. + \li If no animation is required, pre-render your 3D scene into a 2D + image. + + \row + \li Include animation for some of the objects in the scene + (for example, to open doors). + \li Merge all objects that are static, and export only one of + each animated component (for example, each door type). + + \row + \li Get best performance with animated camera. + \li While using a 2D image is not an option in this case, you should + combine all geometry and bake lighting and materials into a single + material. + + \row + \li Get best performance with animated light. + \li While using a 2D image is not an option in this case, you should + combine all geometry and bake all materials into a single + material. + + \row + \li Get best performance in a 3D scene where all meshes are + separated. + \li Use the same material for each instance of the same mesh. + + \row + \li Disable rendering for one of the meshes during runtime. + \li Keep that particular mesh separate but merge the rest of the + components. + + \row + \li Use baked textures with low memory. + \li Bake mesh colors into vertex colors (see the Vertex Color Scene + in the example project). + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/creator-logical-operators.qdocinc b/doc/qtdesignstudio/src/views/creator-logical-operators.qdocinc new file mode 100644 index 0000000000..79284654a4 --- /dev/null +++ b/doc/qtdesignstudio/src/views/creator-logical-operators.qdocinc @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! +//! [logical operators] + \section2 Summary of Logical Operators + + You can use the following + \l{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators} + {logical operators} in the expressions to combine several conditions in one + expression: + + \table + \header + \li Operator + \li Meaning + \li Evaluates to \c true if + \row + \li ! + \li NOT + \li The condition is not met. + \row + \li && + \li AND + \li Both conditions are met. + \row + \li || + \li OR + \li Either of the conditions is met. + \row + \li < + \li Less than + \li The left operand is less than the right operand. + \row + \li > + \li Greater than + \li The left operand is greater than the right operand. + \row + \li >= + \li Greater than or equal + \li The left operand is greater than or equal to the right operand. + \row + \li <= + \li Less than or equal + \li The left operand is less than or equal to the right operand. + \row + \li == + \li Equal + \li The operands are equal. + \row + \li === + \li Strict equal + \li The operands are equal and of the same type. + \row + \li != + \li Not equal + \li The operands are not equal. + \row + \li !== + \li Strict not equal + \li The operands are of the same type but not equal, or are of + different type. + \endtable + + \if defined(qtdesignstudio) + Alternatively, you can use \uicontrol {And Operator}, + \uicontrol {Or Operator}, and \uicontrol {Not Operator} + components to bind property values using the boolean AND, + OR, and NOT operator. For more information, see \l{Logic Helpers}. + \endif + + + In addition, you can use arithmetic operators to compare numbers before + checks. However, we recommend that you create separate properties for this + purpose whenever possible. +//! [logical operators] +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-adding-dynamics.qdoc b/doc/qtdesignstudio/src/views/qtquick-adding-dynamics.qdoc new file mode 100644 index 0000000000..274c205c60 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-adding-dynamics.qdoc @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-adding-dynamics.html + \previouspage creator-qml-modules-with-plugins.html + \nextpage qmldesigner-connections.html + + \title Dynamic Behaviors + + Create connections between components to enable them to communicate with + each other. The connections can be triggered by signals that are emitted + when the values of other components or the UI state change. + + \list + \li \l {Adding Connections} + + You can create connections between the UI components and + the application to enable them to communicate with each other. For + example, how does the appearance of a button change on a mouse click + and which action does the application need to perform in response to + it. + + You can also create connections between UI components by + binding their properties together. This way, when the value of a + property changes in a parent component, it can be automatically + changed in all the child components, for example. + \li \l {Adding States} + + You can declare various UI states that describe how component + properties change from a base state. Therefore, states can be + a useful way of organizing your UI logic. You can associate + transitions with components to define how their properties will + animate when they change due to a state change. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-editor-bindings.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-editor-bindings.qdoc new file mode 100644 index 0000000000..82107b7507 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-connection-editor-bindings.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-property-bindings.html + \previouspage quick-signals.html + \nextpage quick-dynamic-properties.html + + \title Adding Bindings Between Properties + + To dynamically change the behavior of a component, you can create a + \e binding between the properties of two components. To create a property + binding, a property is assigned a JavaScript expression that evaluates to + the desired value. Behind the scenes, the variables in the binding + expression are monitored. When a change is detected, the binding + expression is re-evaluated and the new result is applied to the property. + + At its simplest, a binding may be a reference to another property. + For example, the height of a component can be bound to the height of its + parent, so that when the parent height changes, the component height is + adjusted automatically. + + For more information about the use of property bindings, see + \l{Property Binding}. + + You can create bindings between components in \uicontrol Bindings. + + \image qmldesigner-bindings.png + + To bind a property of a component to the property of another component: + + \list 1 + \li Select \uicontrol View > \uicontrol Views > + \l {Connection View} > \uicontrol {Bindings}. + \li Select the \inlineimage plus.png + (\uicontrol Add) button to add a binding for the currently selected + component. The component ID is displayed in the \uicontrol Item + column. + \li Double-click the value in the \uicontrol Property column to select + the property to bind to a source property. + \li Double-click the value in the \uicontrol {Source Item} column to + select the component whose property you want to use to determine the + behavior of the target component. + \li Double-click the value in the \uicontrol {Source Property} column + to select the property to bind the target property to. + \endlist + + Right-click a binding and select \uicontrol {Open Binding Editor} in + the context menu to specify the binding as a JavaScript expression in + \uicontrol {Binding Editor}. For more information, see \l{Setting Bindings}. + + \image qmldesigner-binding-editor.png "Binding Editor" + + For examples of creating property bindings, see: + + \list + \li \l{Using States to Change Component Property Values} + \if defined(qtdesignstudio) + \li \l{Exporting Properties} + \else + \li \l{Moving the Bubble} in \l{Creating a Mobile Application} + \endif + \endlist + + For more information, watch the following video: + + \youtube UfvA04CIXv0 + + \include creator-logical-operators.qdocinc logical operators + +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-editor-properties.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-editor-properties.qdoc new file mode 100644 index 0000000000..c0db8d22e7 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-connection-editor-properties.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-dynamic-properties.html + \previouspage quick-property-bindings.html + \if defined(qtdesignstudio) + \nextpage quick-states.html + \else + \nextpage quick-connections-backend.html + \endif + + \title Specifying Dynamic Properties + + Each preset \l{glossary-component}{component} has a set of preset properties + that you can specify values for. You can add custom properties that would + not otherwise exist for a particular \l{Component Types}{component type}. + You bind the properties to dynamic expressions to define global properties + for a component that can be read by other components. For example, you can + specify global properties for the root component that you can use in the + child components. + + For example, to specify spacing between UI elements, you could define a + margin for a component that does not have a margin property, and then use + \l{Adding Bindings Between Properties}{bindings} to refer to the value of + the margin property from other components. + + Similarly, you can add custom properties for your own components that are + based on preset components. + + Any content that is data-driven should be exported as a public property + (alias property) of the relevant component. For example, a speedometer + should have an \e int or \e real property for speed to which the UI is + bound. + + You can add properties for components in \l {Connection View} > + \uicontrol Properties. + + \image qmldesigner-dynamicprops.png "Custom properties in Connection View Custom Properties tab" + + To add properties for a component: + + \list 1 + \li Select \uicontrol View > \uicontrol Views > + \uicontrol {Connection View} > \uicontrol {Properties}. + \li Select the \inlineimage plus.png + (\uicontrol Add) button to add a dynamic property for the currently + selected component. The component ID is displayed in the \uicontrol Item + column. + \li Double-click the value in the \uicontrol Property column to give a + name to the property. Property names must begin with a lower case + letter and can only contain letters, numbers, and underscores. + JavaScript \e {reserved words} are not valid property names. + \li Double-click the value in the \uicontrol {Property Type} column to + specify the \l{Supported Property Types}{type of the property}. + \li Double-click the value in the \uicontrol {Property Value} column + to specify the value of the property. + \endlist + + Right-click a property and select \uicontrol {Open Binding Editor} in + the context menu to bind the value of the property to that of another one + or to data accessible in the application in \uicontrol {Binding Editor}. + For more information, see \l{Setting Bindings}. + + \image qmldesigner-binding-editor.png "Binding Editor" + + The properties you add for a component are displayed in the \l Properties + view when you select a component of that type in \l Navigator or + \l {Form Editor}. + + \image qtquick-custom-properties.png "Custom properties in Properties view" + + For more information about setting property values in the + \l Properties view, see \l{Specifying Component Properties}. + + \if defined(qtcreator) + For an example of using custom properties in an application, see + \l{Creating a Mobile Application}. + \endif + + \section1 Supported Property Types + + The following table describes the supported property types: + + \table + \header + \li Type + \li Description + \row + \li alias + \li \l{Property Aliases}{Property alias} that holds a reference to + another property + \row + \li bool + \li Binary \c true or \c false value + \row + \li color + \li Color value that can be specified by using an SVG color name, such + as "red", "green", or "lightsteelblue", or a hexadecimal triplet or + quad in the form "#RRGGBB" and "#AARRGGBB", respectively. For + example, the color red corresponds to a triplet of "#FF0000" and + a slightly transparent blue to a quad of "#800000FF". + In addition, you can use the following Qt functions: \l{Qt::rgba()} + {Qt.rgba()}, \l{Qt::hsva()}{Qt.hsva()}, \l{Qt::hsla()}{Qt.hsla()}, + \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()}, and + \l{Qt::tint()}{Qt.tint()}. + \row + \li int + \li Whole integer number, such as 0, 10, or -20 + \row + \li real + \li Number with a decimal point + \row + \li string + \li Free form text string + \row + \li url + \li Resource locator, such as a file name. It can be either absolute, + (\c http://qt-project.org), or relative (\c pics/logo.png). A + relative URL is resolved relative to the URL of the parent + component. + \row + \li variant + \li Generic property type. For example, variant properties can store + numbers, strings, objects, arrays, and functions. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-editor-signals.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-editor-signals.qdoc new file mode 100644 index 0000000000..754066a93c --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-connection-editor-signals.qdoc @@ -0,0 +1,153 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \previouspage qmldesigner-connections.html + \page quick-signals.html + \nextpage quick-property-bindings.html + + \title Connecting Components to Signals + + A signal and handler mechanism enables components to respond to application + events, which are represented by \e signals. When a signal is emitted, the + corresponding \e {signal handler} is invoked to respond to the event by + using scripts or other operations placed in the handler. + + To receive a notification when a particular signal is emitted for a + particular component, the component definition should declare a signal handler + named \e {on<Signal>} where \e {<Signal>} is the name of the signal, with + the first letter capitalized. The signal handler should contain the + JavaScript code to be executed when the signal handler is invoked. + + Components have predefined signals that are emitted when users interact with + the application. For example, the \l {Mouse Area} component has a \c clicked + signal that is emitted whenever the mouse is clicked within the area. Since + the signal name is \c clicked, the signal handler for receiving this signal + is named \c onClicked. + + A signal is automatically emitted when the value of a property changes. + This type of signal is a \e{property change signal} and signal handlers + for these signals are written in the form \c on<Property>Changed, where + \e <Property> is the name of the property, with the first letter + capitalized. + + For example, the Mouse Area component has a \c pressed property. To receive + a notification whenever this property changes, you would use a signal handler + called \c onPressedChanged. + + For more information about signals and signal handlers, see + \l{Signal and Handler Event System}. + + You can connect components to signals that are available to them in + \uicontrol Connections. + + \image qmldesigner-connections.png + + To connect components to signals: + + \list 1 + \li Select \uicontrol View > \uicontrol Views > + \l {Connection View} > \uicontrol {Connections}. + \li Select the \inlineimage plus.png + (\uicontrol Add) button to add a connection. + \li Double-click the value in the \uicontrol Target column to add the + component to connect to a signal. + \li Double-click the value in the \uicontrol {Signal Handler} column to + select the signal that the connection will listen to from a list of + all signals available for the component. + \li Double-click the value in the \uicontrol Actions column to specify + the action to perform when the signal is emitted. You use JavaScript + to specify the actions. + \endlist + + Right-click a connection and select \uicontrol {Open Connection Editor} + in the context menu to specify the connection in + \uicontrol {Connection Editor}. + + \if defined(qtcreator) + For an example of using the \uicontrol {Connections} view, see + \l{Connecting Mouse Clicks to State Changes}. + \else + For examples of using the \uicontrol {Connections} view, see: + + \list + \li \l{Connecting Buttons to States} in \l{Log In UI - States} + \li \l{Connecting Buttons to State Changes} in \l{Washing Machine UI} + \endlist + \endif + + \section1 Adding Signal Handlers + + If a signal handler that you need is not listed in the + \uicontrol {Signal Handler} column, you can add it: + + \list 1 + \li Right-click a component in the \l Navigator or \l {Form Editor} view + and select \uicontrol {Add New Signal Handler} in the context menu. + \li In the \uicontrol Signal field, select the signal to handle. + \image qmldesigner-implement-signal-handler.png "Implement Signal Handler dialog" + \li Select the radio buttons to filter the list to only display + frequently used signals or property changes. + \li Select \uicontrol OK. + \endlist + + The added signal handler is automatically \l{Adding Property Aliases} + {exported as a property}. + + \section1 Adding Actions and Assignments + + You use the \uicontrol {Connection Editor} to create the JavaScript + expressions for \e actions and \e assignments. An \e action connects + an component to a signal, whereas an \e assignment fetches property values + from another component. + + For more information about the logical operators that you can use to + construct conditional expressions, see \l {Summary of Logical Operators}. + + To create JavaScript expressions for actions: + + \list 1 + \li Select \uicontrol {Open Connection Editor} in the context menu + in \uicontrol {Connections}. + \image qtquick-connection-editor-action.png + \li Select \uicontrol Action as the type of the connections component. + \li Select the component to connect to a signal. + \li Select the action to perform when the signal is emitted. + \endlist + + To create JavaScript expressions for assignments: + + \list 1 + \li Select \uicontrol {Open Connection Editor} in the context menu + in \uicontrol {Connections}. + \image qtquick-connection-editor-assignment.png + \li Select \uicontrol Assignment as the type of the connections + component. + \li Select the target component for the property assignment. + \li Select the property of the target component to assign a value to. + \li Select the source component for the property assignment. + \li Select the property of the source component to fetch the value from. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-editor.qdoc new file mode 100644 index 0000000000..62c9bdb543 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-connection-editor.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qmldesigner-connections.html + \previouspage qtquick-adding-dynamics.html + \nextpage quick-signals.html + + \title Adding Connections + + \list + \li \l{Connecting Components to Signals} + + A signal and handler mechanism enables components to respond to + application events, which are represented by \e signals. When a + signal is emitted, the corresponding \e {signal handler} is + invoked to respond to the event by applying an action, for + example. + + \li \l{Adding Bindings Between Properties} + + A component's property can be assigned a static value that stays + constant until it is explicitly changed. To make the UI more + dynamic, you can use \e {property bindings}. This means that you + can specify relationships between component properties so that when + the value of a property changes, the values of any properties that + are bound to it are automatically updated accordingly. + + \li \l{Specifying Dynamic Properties} + + Each preset component has a set of preset properties that you + can specify values for. You can add custom properties that would + not otherwise exist for a particular \l{Component Types} + {component type} or your custom components. + + \if defined(qtcreator) + \li \l{Managing C++ Backend Objects} + + Application developers can access QObject objects implemented in C++ + from QML files. + \endif + \endlist + + For an example of using properties, bindings, and connections to create a + scalable push button, see \l{Creating Scalable Buttons and Borders}. +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc new file mode 100644 index 0000000000..42a74339fb --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-connection-view.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-connection-view.html + \previouspage qtquick-properties-view.html + \nextpage qtquick-states-view.html + + \title Connection View + + \uicontrol {Connection View} is a collection of views that enable you + to create connections between components and the application, to bind + component properties together, and to add custom properties for components. + + \image qmldesigner-connections.png "Connection View" + + The \l{glossary-component}{components} of the application UI and the + application logic need to communicate with each other. For example, a + button needs to know that the user has clicked it. The button may then + change color to indicate its state or perform an action. Further, the + application needs to know whether the user clicked the button because + it may need to relay this clicking event to other applications. For + this purpose, a button typically contains a \l{Mouse Area} component, + which can receive different pointer events and emit \e signals in + response to them. + + Another way to connect components is to bind their \l{Properties} + {properties} together. A component's property can be assigned a static + value which stays constant until it is explicitly changed. To make the + UI more dynamic, you can use \e {property bindings}. This means that + you can specify relationships between component properties so that when + the value of a property changes, the values of any properties that are + bound to it are updated accordingly. + + Each preset component has a set of \l{Specifying Component Properties} + {preset properties} that you can specify values for. You can add + custom properties that would not otherwise exist for a particular + \l{Component Types}{component type}. + + \if defined(qtcreator) + In addition, application developers can use the \uicontrol Backends view + to access QObject objects implemented in C++ from QML files. + \endif + + \section1 Summary of Connection Views + + \table + \header + \li View + \li Purpose + \li Read More + \row + \li \uicontrol Connections + \li Create connections between components and the application logic + by accessing signals outside of the components that emit them. + \li \l{Connecting Components to Signals} + \row + \li \uicontrol Bindings + \li Dynamically change the behavior of a component by creating a + binding between the properties of two components. + \li \l{Adding Bindings Between Properties} + \row + \li \uicontrol Properties + \li Add custom properties that would not otherwise exist for a + particular preset component or your own custom component. + \li \l{Specifying Dynamic Properties} + \if defined(qtcreator) + \row + \li \uicontrol Backends + \li Access QObject objects implemented in C++ from QML files. + \li \l{Managing C++ Backend Objects} + \endif + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc new file mode 100644 index 0000000000..7b34c33436 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-curve-editor.qdoc @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-curve-editor.html + \previouspage qtquick-timeline-view.html + \nextpage qtquick-text-editor.html + + \title Curve Editor + + \uicontrol {Curve Editor} shows the interpolated values of an animated + property over the animation range. + + \image studio-curve-editor.png "Curve Editor" + + When you edit an animation curve, you implicitly edit the + \l{Editing Easing Curves}{easing curves} that the underlying system uses + to define an animation. The animation curve is an extension to visualize + both the value of a keyframe and the interpolation between keyframes + simultaneously. + + You can use the toolbar buttons to add \uicontrol Linear, \uicontrol Step, + or \uicontrol Spline interpolation between two keyframes. + + When you set interpolation to \uicontrol Spline, handles appear in + \uicontrol {Curve Editor} that you can use to modify the curve. Select + \uicontrol Unify to lock the handle on the left of a keyframe to the one + on the right of it so that moving the left handle also moves the right + handle. + + If the component that contains the animated property has been locked + in \l Navigator, you can select \inlineimage icons/lockon.png + to unlock it. You can also lock individual easing curves for editing. + + To lock an animation curve, hover the mouse over the keyframe in the list, + and then select \inlineimage icons/lockoff.png + . + + To pin an animation curve, hover the mouse over the keyframe in the list, + and then select \inlineimage icons/pin.png + . + + \section1 Curve Editor Toolbar + + The \uicontrol {Curve Editor} toolbar contains the following buttons and + fields. + + \table + \header + \li Button/Field + \li Action + \row + \li \inlineimage icons/easing-curve-linear-icon.png + \li \uicontrol Linear specifies that the interpolation between + keyframes is linear. + \row + \li \inlineimage icons/easing-curve-step-icon.png + \li \uicontrol Step uses steps for interpolation between keyframes. + \row + \li \inlineimage icons/easing-curve-spline-icon.png + \li \uicontrol Spline uses bezier spline curves for interpolation + between keyframes and displays handles for managing them. + \row + \li \uicontrol {Set Default} + \li Currently not used. + \row + \li \uicontrol Unify + \li For \uicontrol Spline curves, locks the handle on the left of a + keyframe to the one on the right. + \row + \li Start Frame + \li Specifies the first frame of the curve. + \row + \li End Frame + \li Specifies the last frame of the curve. + \row + \li Current Frame + \li Displays the frame that the playhead is currently on. Enter a + number in the field to move the playhead to the respective frame. + \endtable + + \section1 Editing Animation Curves + + To edit animation curves: + + \list 1 + \li In the \l Timeline view, animate at least one property value by + \l{Managing Keyframes}{inserting keyframes} for it. + \li Select \uicontrol View > \uicontrol Views > + \uicontrol {Curve Editor} to open the animation curve editor. + \li Right-click in \uicontrol {Curve Editor}, and select + \uicontrol {Insert Keyframe} to add a keyframe. + \li Select keyframes to display the easing curves attached to them. + To select multiple keyframes, press and hold \key Ctrl. + \endlist + + Your changes are automatically saved when you close the view. + + \section1 Deleting Keyframes in Curve Editor + + To delete the selected keyframe, select \uicontrol {Delete All Keyframes} + in the context menu. +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-designer.qdoc b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc new file mode 100644 index 0000000000..7536e8c757 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc @@ -0,0 +1,299 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +// ********************************************************************** +// 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. +// ********************************************************************** + +/*! + \page creator-using-qt-quick-designer.html + \if defined(qtdesignstudio) + \previouspage creator-modes.html + \nextpage qtquick-form-editor.html + \else + \previouspage quick-projects.html + \nextpage quick-uis.html + \endif + + \title Design Views + + \QDS contains views for designing UIs. To open them, select + \uicontrol View > \uicontrol Views. The following images present the + views that you are likely to use most often while designing UIs. + + \image studio-design-mode.png "Design views" + \image studio-design-mode-states-timeline.png "The States and Timeline views" + + You can move the views anywhere on the screen and save them as + \e workspaces, as instructed in \l {Managing Workspaces}. + + To learn more about using the design views, see the following video: + + \youtube RfEYO-5Mw6s + + \section1 Summary of Design Views + + \table + \header + \li View + \li Purpose + \li Read More + \row + \li \l{Form Editor} + \li Provides a working area for designing 2D UIs. + When you are editing 3D scenes, \uicontrol {Form Editor} is + used as a canvas for the 3D scene projected by the camera. + \li \l{Form Editor} + \row + \li \l{3D Editor} + \li Provides an editor for files you created using 3D graphics + applications and stored in one of the supported formats. + \li \l{3D Editor} + \row + \li \l Library + \li Contains the building blocks that you can use to design + applications: preset components, your own components, and + assets. + \li \l{Components} + \row + \li \l Navigator + \li Displays the composition of the current component file as + a tree structure. A component file can contain references + to other components and assets. + \li \l Navigator + \row + \li \l Properties + \li Enables you to modify the properties of the selected component. + \li \l {Specifying Component Properties} + \row + \li \l{Connection View} + \li Enables you to add functionality to the UI by creating + connections between components, signals, and component properties. + \li \l{Adding Connections} + \row + \li \l States + \li Displays the different states that can be applied to a component. + Typically, states describe UI configurations, such as the + visibility and behavior of components and the available user + actions. + \li \l{Adding States} + \row + \li \l{Transition Editor} + \li Enables you to make movement between states smooth by animating + the changes between states. + \li \l{Animating Transitions Between States} + \row + \li \l Timeline + \li Provides a timeline and keyframe based editor for animating + the properties of components. + \li \l{Creating Timeline Animations} + \row + \li \l{Curve Editor} + \li Enables you to view and modify the whole animation curve by + inserting keyframes to the curve and dragging them and the point + handlers to modify the curve. + \li \l {Editing Animation Curves} + \row + \li \l{Text Editor} + \li Provides a code editor for viewing and modifying the code + generated by the visual editors. + \li \l {Working in Edit Mode} + \row + \li \l Projects + \li Shows a list of open projects and the files they contain. + \li \l Projects + \row + \li \l{File System} + \li Shows all files in the currently selected directory. + \li \l{File System} + \row + \li \l{Open Documents} + \li Shows currently open files. + \li \l{Open Documents} + \endtable + + \section1 Summary of Main Toolbar Actions + + The top level toolbar in the \uicontrol Design mode contains shortcuts to + widely used actions. + + \table + \header + \li Button/Field + \li Action + \li Keyboard Shortcut + \li Read More + \row + \li \inlineimage prev.png + \li \uicontrol {Go Back}: moves a step backwards in your location history. + That is, returns the focus to the last location in the last file it + was on. + \li \key Alt+< (\key Opt+Cmd+< on \macos) + \li \l{Navigating Between Open Files and Symbols} + \row + \li \inlineimage next.png + \li \uicontrol {Go Forward}: moves a step forward in your location history. + \li \key Alt+> (\key Opt+Cmd+> on \macos) + \li \l{Navigating Between Open Files and Symbols} + \row + \li \inlineimage unlocked.png + \li File is writable: the currently open file can be modified and saved. + \li + \li \l{Open Documents} + \row + \li File type icon + \li Indicates the type of the currently open file. Design views cannot + be split, so the icon cannot be dragged, contrary to the tooltip. + \li + \li \l{Open Documents} + \row + \li Currently open file + \li Displays the location and filename of the currently open file. You + can select another file in the list of open files to view it in + \uicontrol {Form Editor} and \uicontrol Navigator. + \li + \li \l{Open Documents} + \row + \li \inlineimage close.png + \li \uicontrol {Close Document}: closes the current file. + \li \key Ctrl+W (\key Cmd+W on \macos) + \li + \row + \li \inlineimage live_preview.png + \li \uicontrol {Show Live Preview} shows a preview of the current file + or the entire UI. The changes you make to the UI are instantly + visible to you in the preview. + \li \key Alt+P (\key Opt+P on \macos) + \li \l{Validating with Target Hardware} + \row + \li Preview size + \li Displays the size of the preview dialog as a percentage. You can + select another percentage in the list to view the UI in different + sizes. + \li + \li \l{Previewing on Desktop} + \row + \li FPS + \li Displays the frames-per-second (FPS) refresh rate of previewed + animations. + \li + \li \l{Previewing on Desktop} + \row + \li Preview language + \li Displays the language used for a localized application during + preview. You can select another language in the list of languages + that the application has been localized to. + \li + \li + \row + \li \inlineimage qtcreator-reset-position-icon.png + \li Returns a component to its \e {implicit position} after + being moved. + \li \key Ctrl+D (\key Cmd+D on \macos) + \li \l{Resetting Component Position and Size} + \row + \li \inlineimage qtcreator-reset-size-icon.png + \li Returns a component to its implicit size after it was scaled. + \li \key Shift+S + \li \l{Resetting Component Position and Size} + \row + \li \inlineimage icons/anchor-fill.png + \li Fills the selected component to its parent component. + \li \key Shift+F + \li \l{Setting Anchors and Margins} + \row + \li \inlineimage qtcreator-anchors-reset-icon.png + \li Resets anchors to their saved state for the selected component. + \li \key Ctrl+Shift+R (\key Shift+Cmd+R on \macos) + \li \l{Setting Anchors and Margins} + \row + \li \inlineimage icons/copy-formatting.png + \li Copies property values from the selected component. + \li + \li \l{Copying and Pasting Formatting} + \row + \li \inlineimage icons/paste-formatting.png + \li Applies copied property values to one or several selected + components. + \li + \li \l{Copying and Pasting Formatting} + \row + \li \inlineimage row.png + \li Uses a \uicontrol Row component to lay out the selected components. + \li \key Ctrl+U (\key Cmd+U on \macos) + \li \l{Using Layouts} + \row + \li \inlineimage column.png + \li Uses a \uicontrol Column component to lay out the selected + components. + \li \key Ctrl+L (\key Cmd+L on \macos) + \li \l{Using Layouts} + \row + \li \inlineimage grid.png + \li Uses a \uicontrol Grid component to lay out the selected + components. + \li \key Shift+G + \li \l{Using Layouts} + \if defined(qtdesignstudio) + \row + \li \inlineimage icons/edit.png + \li \uicontrol {Show Event List}: opens a dialog for viewing and + creating an event list for an application flow. + \li \key Alt+E (\key Opt+E on \macos) + \li \l{Simulating Events} + \row + \li \inlineimage icons/assign.png + \li \uicontrol {Assign Events to Actions}: assigns events to actions in + an application flow. + \li \key Alt+A (\key Opt+A on \macos) + \li \l{Simulating Events} + \endif + \row + \li Styling + \li Displays the UI style used for UI controls. + \li + \li \l{Styling Controls} + \row + \li Subcomponents + \li Displays the components referred to in the current file. Select a + component in the list to open it in \uicontrol {Form Editor} and + \uicontrol Navigator. + \li + \li \l{Components} + \row + \li Workspace + \li Displays the currently selected workspace. To switch to another + workspace, select it in the list. + \li + \li \l{Managing Workspaces} + \row + \li \inlineimage icons/annotation.png + \li Enables you to add or edit global annotations. + \li + \li \l{Annotating Designs} + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc new file mode 100644 index 0000000000..5a6825ca6c --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-easing-curve-editor.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-editing-easing-curves.html + \previouspage studio-timeline.html + \nextpage qtquick-production-quality-animation.html + + \title Editing Easing Curves + + Easing curves define the progress of animation to make motion appear more + natural because real objects don't usually move at a constant speed nor + start and stop instantly. You can add and edit easing curves for nonlinear + interpolation to make components appear to pick up speed, slow down, or + bounce back at the end of an animation. + + You can attach easing curves to: + + \list + \li Keyframes in timeline animations + \li Transitions + \li Property animation component instances + \endlist + + You can use \uicontrol {Easing Curve Editor} to select and edit easing + curves. + + \section1 Selecting Easing Curves + + You can use the preset curves or modify them by dragging the curve handles + around. You can add points to the curve and drag them and the point handles + to modify the curve. When you are happy with the curve, you can save it as + a custom curve. For more information about easing curve types, see the + technical documentation for \l [QML] {PropertyAnimation}{easing curves}. + + \image studio-easing-curve-editor.png "Easing Curve Editor" + + To select an easing curve: + + \list 1 + \li Select an easing curve in the \uicontrol Presets tab. + \li In the \uicontrol {Duration (ms)} field, select the + duration of the easing function in milliseconds. + \li Select \uicontrol Preview to preview the curve. + \li Select \uicontrol OK to attach the easing curve and + return to the view where you are adding the curve. + \endlist + + To zoom into and out of the easing curve editor, use the mouse + roller. To reset the zoom factor, right-click in the picker and + select \uicontrol {Reset Zoom}. + + \section1 Easing Curves in Timeline Animations + + For timeline animations, you can also use the more advanced + \l {Curve Editor} that shows the interpolated values of an animated + property over the \l{Creating Timeline Animations}{animation} range. + + The animation curves present a more readable view of the animation by + showing the effective values of the animated properties over the animation + range. In order to do so, they need to be converted to and from easing + curves. This comes with the following side effects: + + \list + \li Interpolation between identical current and previous keyframe values + is meaningless regardless of what the easing curve looks like. + \li Some easing curves are not trivially mappable to animation curves + and are therefore painted in a different color and without handles. + \endlist + + \section2 Attaching Easing Curves to Keyframes + + To attach easing curves to keyframes: + + \list 1 + \li Right-click a keyframe in \l Timeline and select + \uicontrol {Easing Curve Editor} in the context menu. + \li Select an easing curve, as described in \l{Selecting Easing Curves}. + \endlist + + When you attach easing curves to keyframes, the shape of the + \l{keyframe_marker}{keyframe marker} on a keyframe track in + \l Timeline changes from \inlineimage keyframe_linear_inactive.png + to a marker that describes the type of the selected easing curve. + + \section1 Attaching Easing Curves to Transitions + + To attach easing curves to transitions: + + \list 1 + \li In \l{Transition Editor}, select the \inlineimage curve_editor.png + (\uicontrol {Easing Curve Editor}) button. + \li Select an easing curve, as described in \l{Selecting Easing Curves}. + \endlist + + \section1 Attaching Easing Curves to Property Animations + + To attach easing curves to property animations: + + \list 1 + \li In \l Navigator, select an \l{Animations}{Animation} component + instance. + \li In \l Properties, select the \inlineimage curve_editor.png + (\uicontrol {Easing Curve Editor}) button. + \li Select an easing curve, as described in \l{Selecting Easing Curves}. + \endlist + + \section1 Customizing Easing Curves + + To customize easing curves: + + \list 1 + \li In \uicontrol {Easing Curve Editor}, select an easing curve in + the \uicontrol Presets tab. + \li Drag the curve handles to modify the curve. + \li Right-click in the editor, and select \uicontrol {Add Point} to add + points to the curve. + \li Drag the points or the point handles to modify the curve. If the + curve becomes invalid, it turns red in the editor and the + \uicontrol Save button is disabled. + \li Select \uicontrol Save to save your changes to the curve. + \li In the \uicontrol Name field, enter a name for the custom curve, + and then select \uicontrol OK to save the curve in the + \uicontrol Custom tab. + \endlist + + To paste easing curve definitions to \uicontrol {Easing Curve Editor} as + text, select the \uicontrol Text tab. +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc new file mode 100644 index 0000000000..bcd9317615 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-form-editor.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-form-editor.html + \previouspage creator-using-qt-quick-designer.html + \nextpage studio-3d-editor.html + + \title Form Editor + + You design applications in the \uicontrol {Form Editor} view by opening + component files and placing instances of \l{Component Types}{2D components} + and \l{Assets}{assets} into them. + + \image qmldesigner-form-editor.png "Form Editor view" + + When you select component instances in \uicontrol {Form Editor}, markers + appear around their edges and in their corners. Depending on the shape of + the cursor, you can apply the following actions to the component instances + by dragging them: + + \list + \li \l{Moving Components}{Move} + \li \l{Resizing 2D Components}{Resize} + \li \l{Rotating 2D Components}{Rotate} + \endlist + + \section1 Summary of Form Editor Buttons + + The \uicontrol {Form Editor} toolbar contains the following buttons and + fields. + + \table + \header + \li Button/Field + \li Tooltip + \li Read More + \row + \li \inlineimage no_snapping.png + \li Disables snapping. + \li \l{Snapping to Parent and Sibling Components} + \row + \li \inlineimage snapping_and_anchoring.png + \li Anchors the component instance to the component instances that it + is snapped to. + \li \l{Snapping to Parent and Sibling Components} + \row + \li \inlineimage snapping.png + \li Snaps component instances to their parent or siblings when you + align them. + \li \l{Snapping to Parent and Sibling Components} + \row + \li \inlineimage boundingrect.png + \li Hides and shows component instance boundaries. + \li \l{Hiding Component Boundaries} + \row + \li \uicontrol {Override Width} + \li Shows a preview of the component using the specified width. + \li \l{Previewing Component Size} + \row + \li \uicontrol {Override Height} + \li Shows a preview of the component using the specified height. + \li \l{Previewing Component Size} + \row + \li \inlineimage icons/canvas-color.png + \li Sets the color of the \uicontrol {Form Editor} working area. + \li \l{Setting Canvas Color} + \row + \li \inlineimage icons/zoomIn.png + \li Zooms in. + \li \l{Zooming} + \row + \li \inlineimage icons/zoomOut.png + \li Zooms out. + \li \l{Zooming} + \row + \li Zoom level + \li Sets the zoom level that you select from the list. + \li \l{Zooming} + \row + \li \inlineimage icons/zoomAll.png + \li Zooms to fit all content. + \li \l{Zooming} + \row + \li \inlineimage icons/zoomSelection.png + \li Zooms to fit the current selection. + \li \l{Zooming} + \row + \li \inlineimage reset.png + \li Refreshes the contents of \uicontrol {Form Editor}. + \li \l{Refreshing Form Editor Contents} + \endtable + + \section1 Moving Components + + When the move cursor is displayed, you can move the selected component + instance to any position in \uicontrol {Form Editor}. + + \image qmldesigner-form-editor-move-cursor.png "Move cursor in Form Editor view" + + For more information about alternative ways of positioning component + instances in UIs, see \l{Scalable Layouts}. + + \section1 Resizing 2D Components + + When the resize cursor is displayed, you can drag the markers to resize + component instances. + + \image qtquick-designer-scaling-items.png "Form Editor view" + + To have the resizing done from the center of the selected component instance + rather than from its edges, press \key Alt (or \key Opt on \macos). + + To preserve the image aspect ratio while resizing when using the corner + markers, press \key Shift. This also works on component instances that + are anchored using left, right, top, or bottom anchors. + + To both resize from the center of the component instance and preserve the + aspect ratio, press \key Alt+Shift (or \key {Opt+Shift} on \macos). + + For more information about alternative ways to specify the size of a + component or component instance in a UI, see \l{2D Geometry}. + + \section1 Rotating 2D Components + + When the rotation cursor \inlineimage icons/rotation-cursor.png + is displayed in one of the corners of a component instance, you can drag + clockwise or counter-clockwise to freely rotate the component instance + around its origin. + + \image qtquick-designer-rotating-items.png "2D rotation tool" + + Additionally, press \key Shift or \key Alt (or \key Opt on \macos) + to rotate component instances in steps of 5 or 45 degrees, respectively. + + You can set the \l{Managing 2D Transformations}{origin} in \l Properties > + \uicontrol {Geometry - 2D} > \uicontrol Origin. There, you can also enter + the value of the \uicontrol Rotation property in degrees. + + \section1 Zooming + + You can use the zoom buttons on the toolbar to zoom into and out of + \uicontrol {Form Editor} or select the zoom level as a percentage + from a list. More buttons are availabe for zooming to fit all content + in the view or zooming to fit the currently selected component instances. + + \image qmldesigner-zooming.gif "Zooming in Form Editor" + + \section1 Snapping to Parent and Sibling Components + + You can use snapping to align component instances in + \uicontrol {Form Editor}. Select the \inlineimage snapping.png + button to have the component instances snap to their parent or siblings. + Snapping lines automatically appear to help you position the component + instances. Click the \inlineimage snapping_and_anchoring.png + button to anchor the selected component instance to those that you snap to. + Only one snapping button can be selected at the time. Selecting + one snapping button automatically deselects the others. + + Choose \uicontrol Tools > \uicontrol Options > \uicontrol {Qt Quick} > + \uicontrol {Qt Quick Designer} to specify settings for snapping. In the + \uicontrol {Parent component padding} field, specify the distance in + pixels between the parent and the snapping lines. In the + \uicontrol {Sibling component spacing} field, specify the + distance in pixels between siblings and the snapping lines. + + \image qtquick-designer-options.png "Qt Quick Designer options" + + The following image shows the snapping lines (1) when + \uicontrol {Parent component padding} is set to 5 pixels. + + \image qmldesigner-snap-margins.png "Snapping lines on canvas" + + For alternative ways of aligning and distributing component instances by + using the \l Properties view, see \l{Aligning and Distributing Components}. + + \section1 Hiding Component Boundaries + + \uicontrol {Form Editor} displays the boundaries of component instances. + To hide them, select the \inlineimage boundingrect.png + button. + + \section1 Previewing Component Size + + The width and height of the root component in a UI file determine the size + of the component. You can reuse components, such as buttons, in different + sizes in other UI files and design UIs 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 + \l{Setting Bindings}{property bindings}. + + To experiment with different component sizes, enter values in the + \uicontrol {Override Width} and \uicontrol {Override Height} fields (1) on + the toolbar. The changes are displayed in the \uicontrol {Form Editor} + view (2) and in the \uicontrol States view (3), but the property + values are not changed permanently in the UI file. You can permanently + change the property values in the \uicontrol Properties view (4). + + \image qmldesigner-preview-size.png "Component width and height" + + To set the initial size of the root component, select \uicontrol Tools > + \uicontrol Options > \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer} + and specify the component width and height in the + \uicontrol {Root Component Init Size} group. + + \section1 Specifying Canvas Size + + To change the canvas size, select \uicontrol Tools > \uicontrol Options > + \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer} and + specify the canvas width and height in the \uicontrol Canvas group. + + \section1 Setting Canvas Color + + If you set the background of the root component transparent, the color of + the working area can make it difficult to see the component instance you + are working on. To make component instances more visible, you can select + the canvas color in the \inlineimage icons/canvas-color.png + list. By default, the color is transparent. Setting the canvas color does + not affect the background color of your root component or component + instances in any way. + + \image qmldesigner-canvas-color.png "Transparent canvas color for a transparent component instance" + + \section1 Refreshing Form Editor Contents + + When you open a UI file, the component defined in the file and the component + instances it contains are drawn in \uicontrol {Form Editor}. When you + edit component instance properties in \l Properties, the code and its + representation in \uicontrol {Form Editor} might get out of sync. For + example, when you change the position of a component instance within a + column or a row, the new position might not be displayed correctly in + \uicontrol {Form Editor}. + + To refresh the contents of \uicontrol {Form Editor}, press \key R or + select the \inlineimage reset.png + (\uicontrol {Reset View}) button. + + \include qtquick-component-context-menu.qdocinc context-menu +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-library.qdoc b/doc/qtdesignstudio/src/views/qtquick-library.qdoc new file mode 100644 index 0000000000..b1d03a72e6 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-library.qdoc @@ -0,0 +1,159 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-library.html + \if defined(qtdesignstudio) + \previouspage studio-3d-editor.html + \else + \previouspage creator-using-qt-quick-designer.html + \endif + \nextpage qtquick-navigator.html + + \title Library + + The \uicontrol Library view lists the available components and assets. + + \section1 Components + + \image qtquick-components-tab.png "Library view Components tab" + + \uicontrol Library > \uicontrol Components displays modules that have been + added to your project. In many modules the components have been further + organized into different categories. The modules contain visual components, + such as basic shapes, UI controls, and 3D components, and add functionality + to the project. All components have a type. + + The UI controls can be styled to have the look and feel of a particular + operating system, such as \macOS, Windows, Android, or iOS. + + Some modules have no visible components. For example, the + \uicontrol {Qt.Multimedia} module adds support for audio and video + files to your UI. + + \section2 Component Types + + You can add the following types of components to your project: + + \list + \li \l Shapes + \li \l Text + \li \l Images + \li \l {UI Controls} + \li \l {User Interaction Methods} + \li \l {Lists and Other Data Models} + \if defined(qtdesignstudio) + \li \l {2D Effects} + \li \l {Logic Helpers} + \endif + \li \l Animations + \li \l{3D Views} + \li \l{Node} + \li \l{Group} + \li \l{Instanced Rendering} + \li \l{Skeletal Animation} + \li \l{3D Models} + \li \l{Materials and Shaders} + \li \l{Textures} + \li \l{3D Materials} + \li \l{3D Effects} + \li \l{Custom Shaders} + \li \l{Lights} + \li \l{Cameras} + \li \l{Scene Environment} + \li \l{Morph Target} + \li \l{Repeater3D} + \li \l{Particles} + \endlist + + For more information about creating your own components, see + \l{Creating Custom Components}. + + \section2 Adding and Removing Modules + + When you \l{Creating Projects}{create projects}, modules typically needed in + them are added by default. For example, an empty application project + contains basic components and UI controls, while a 3D application project + contains additional 3D components. + + To view the list of available modules, select \inlineimage plus.png + . Most commonly used modules are placed at the top of the list in + alphabetical order. You can search for components and modules by entering + search criteria in the \uicontrol Search field. + + Select the module to add it to \uicontrol Library > \uicontrol Components. + + \image qtquick-components-tab-add.png "Select Modules to Add" + + This adds an \e {import statement} to the component code that you + can see in \l {Text Editor}. For example, if you add the + \uicontrol QtQuick.Controls module, the following import statement + is added to the code: \c {import QtQuick.Controls}. + + Since the added components and modules are packaged with your UI into the + final application package, it is recommended that you select + \uicontrol {Remove Module} to remove the ones you don't use in the project. + + \section1 Assets + + \uicontrol Library > \uicontrol {Assets} displays the images and other files + that you add to the project folder by selecting \inlineimage plus.png + . To add assets to your UI, drag-and-drop them to \l Navigator or + \l {Form Editor}. + + To add multiple assets to your UI simultaneously, multiselect them first by + holding \key Ctrl and clicking the asset files you wish to select. + + \image qtquick-assets-tab.png "Library view Assets tab" + + When you drag-and-drop assets from \uicontrol Assets to \l Navigator + or \l {Form Editor}, component instances with a suitable type are + automatically created for you. For example, instances of the + \l{Images}{Image} component will be created for graphics files. + + \section1 Context Menu Commands + + \image qtquick-library-context-menu.png "Context menu commands in Library" + \image qtquick-library-context-menu-hide.png "Context menu command Hide Category" + + To use the context menu commands in \uicontrol Library, right-click the + name of a module or category and select one of the following commands: + + \list + \li \uicontrol {Remove Module}: removes the module and all of its + components from \uicontrol Library > \uicontrol Components. + \li \uicontrol {Expand All}: expands all the modules. + \li \uicontrol {Collapse All}: collapses all the modules. + \li \uicontrol {Hide Category}: hides the category from the module. + \li \uicontrol {Show Module Hidden Categories}: shows the hidden + categories of the module. + \li \uicontrol {Show All Hidden Categories}: shows the hidden + categories in all of the modules. + \endlist + + \note The context menu commands for the \uicontrol Library categories do not + function if you have entered something into the \uicontrol Search field. + Clear the \uicontrol Search field to resume using the context menu commands. +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc b/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc new file mode 100644 index 0000000000..3e50256a20 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-navigator.qdoc @@ -0,0 +1,262 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-navigator.html + \previouspage quick-library.html + \nextpage qtquick-properties-view.html + + \title Navigator + + The \uicontrol Navigator view displays the components in the current + component file and their relationships. \l{glossary-component}{Components} + (1) are listed in a tree structure, below their parent (2). You can preview + components by hovering the mouse over them (3). + + \image qmldesigner-navigator.png "Navigator with component preview" + + You can select components in the \uicontrol Navigator view to edit their + properties in the \l Properties view. Components can access the + properties of their parent component. To select components in the + \l {Form Editor} view, right-click a component, and select another + component in the \uicontrol Selection submenu. + + Typically, child components are located within the parent component in + \uicontrol {Form Editor}. However, they do not necessarily have to + fit inside the parent component. 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 a component, all its child components are also copied. When + you remove a component, the child components are also removed. + + Select context menu commands to apply commands to components. The + availability of the commands depends on the component type. For example, + you can change the source of an Image component by selecting + \uicontrol {Change Source URL} in the context menu. + + \section1 Summary of Navigator Buttons + + The following table lists the \uicontrol Navigator buttons: + + \table + \header + \li Icon + \li Tooltip + \li Read More + \row + \li \inlineimage arrowleft.png + \li Moves the component one level up in the component tree, so that + it becomes the last sibling of its current parent. + \li \l{Arranging Components} + \row + \li \inlineimage arrowright.png + \li Moves the component one level down in the component tree, so that it + becomes the child of its last sibling. + \li \l{Arranging Components} + \row + \li \inlineimage icons/navigator-arrowdown.png + \li Moves the component down within its parent. + \li \l{Arranging Components} + \row + \li \inlineimage icons/navigator-arrowup.png + \li Moves the component up within its parent. + \li \l{Arranging Components} + \row + \li \inlineimage filtericon.png + \li Shows and hides invisible components in \uicontrol Navigator. + \li \l{Showing and Hiding Components} + \row + \li \inlineimage icons/alias.png + \li Adds a property alias that you can use from outside of the + component. + \li \l{Adding Property Aliases} + \row + \li \inlineimage icons/visibilityon.png + \li Shows and hide components in \uicontrol {Form Editor}. + \li \l{Showing and Hiding Components} + \row + \li \inlineimage icons/lockon.png + \li Locks components in all views. + \li \l{Locking Components} + \endtable + + \section1 Showing and Hiding Components + + To show and hide components in \uicontrol {Form Editor} when focusing on + specific parts of the application, click \inlineimage icons/visibilityon.png + in \uicontrol Navigator. + + To change the visibility of a component in the application code, select the + \uicontrol Visibility check box in the \uicontrol Properties view or select + \uicontrol Edit > \uicontrol Visibility in the context menu. + + You can also set the \uicontrol Opacity field to 0 in \uicontrol Properties + to hide components in the UI that you want to apply animation to. + + As all properties, visibility and opacity are inherited from the parent + component. To hide or show child components, edit the properties of the + parent component. + + To hide invisible components in \uicontrol Navigator, click + \inlineimage filtericon.png + (\uicontrol {Filter Tree}) and select + \uicontrol {Show Only Visible Components}. + + \section1 Locking Components + + When designing complex applications, it is easy to accidentally modify + the properties of a component in one of the \QC views in ways that lead to + surprising results. For example, \uicontrol {Form Editor} can become + crowded and other components can get in the way when you are trying to + select or transform a particular component, so that you end up transforming + more components than you wanted to. + + To lock components that you are not currently editing and their children, + click \inlineimage icons/lockon.png + in \uicontrol Navigator. Locked components cannot be handled in any \QC + views. You can unlock the components when you want to edit them again. + + \image qtquick-designer-navigator-lock.gif "Locking components in Navigator" + + You cannot select locked components in \uicontrol {Form Editor} or + \l {3D Editor} nor access their properties in + \uicontrol Properties. + + If you attempt to \l{Adding States}{remove a state} that changes the + properties of a locked component, you are prompted to confirm the removal. + + If you have \l{Editing Animation Curves}{added easing curves} to keyframe + animations, you can lock and unlock them in the \l {Curve Editor} + view. If you lock the components that contain the easing curves, the lock + status is synchronized between \uicontrol Navigator and + \uicontrol {Curve Editor}. + + \section1 Arranging Components + + You can view the order of components in a component file in \uicontrol Navigator + and \l {Text Editor}. The order of components in the file also + determines the order in which they are drawn in \uicontrol {Form Editor}. + By default, components that are located at the top of the file are listed at + the bottom of the \uicontrol Navigator tree and behind overlapping + components in \uicontrol {Form Editor}. To list the components in the order + in which they appear in the file, as some other tools do, click + \inlineimage filtericon.png + (\uicontrol {Filter Tree}), and select \uicontrol {Reverse Component Order}. + + To move a component to the top or bottom of the tree within its parent, + right-click it in \uicontrol Navigator or \uicontrol {Form Editor} + and select \uicontrol Arrange > \uicontrol {Bring to Front} or + \uicontrol {Send to Back}. To move a component up or down, select + \uicontrol {Bring Forward} or \uicontrol {Send Backward}. + + To reverse the order of the selected components in \uicontrol Navigator and + \uicontrol {Text Editor}, select \uicontrol Arrange > \uicontrol Reverse. + + \image qtquick-designer-navigator-arrange.gif "Reversing component order" + + You can also drag-and-drop the component to another position in the tree or + use the arrow buttons to move the component in the tree. You can use the + left and right arrow buttons to change the parent of the component. + + \image qmldesigner-navigator-arrows.png "Navigator buttons" + + When you drag-and-drop instances of components to \uicontrol {Form Editor}, + the new component is added as a child of the component + beneath it. When you move the components, it is not possible to determine + whether you want to adjust their position or attach them to a new parent component. + Therefore, the parent component is not automatically changed. To change the + parent of the component, press down the \key Shift key before you drag-and-drop + the component into a new position. The topmost component under the cursor becomes the + new parent of the component. + + \section1 Adding Property Aliases + + A \e {property alias} is a property that you can use from outside the + component. When you view the code in \l {Text Editor}, a property alias + declaration looks like an ordinary property definition, except that it + requires the \e alias keyword instead of a \l{Supported Property Types} + {property type}, and the right-hand-side of the property declaration must + be a valid alias reference: + + \badcode + property alias <name>: <alias reference> + \endcode + + For example, the following alias refers to a button component instance + within an item component instance: + + \badcode + property alias button: item.button + \endcode + + A valid alias reference: + + \list + \li Can only point to a component instance or property within + the component where the property alias is declared. + \li Cannot contain arbitrary JavaScript expressions. + \li Cannot point to components of another type than the component + where the property alias is declared. + \li Must be defined when the alias is first declared. + \li Cannot point to attached properties. + \li Cannot point to properties of nested component instances + below the third level. + \endlist + + You can use the \inlineimage icons/alias.png + (\uicontrol Export) button in \uicontrol Navigator to export + a component as a property alias with a valid alias reference. + + \image qmldesigner-export-item.png + + You can then use the property alias in other components to + \l{Adding Connections}{create connections} to this component. + + \section1 Moving Within Components + + The files that specify components (\c ui.qml, \c .qml) can contain + instances of other components specified in separate files. You can + open the file that specifies a component in different ways from + different views: + + \list + \li In \uicontrol {Form Editor} or \uicontrol Navigator, + right-click an instance of a component and then select + \uicontrol {Go into Component} in the context menu or + press \key F2. + \li In \uicontrol Properties, select \uicontrol {Edit Base Component}. + \endlist + + The component hierarchy is displayed as a bread crumb path, where you can + click the component names to open the respective files. This enables you + to easily navigate back to the top level when you are done editing the + component. + + \image qmldesigner-breadcrumbs.png "Component hierarchy" + + \include qtquick-component-context-menu.qdocinc context-menu +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc new file mode 100644 index 0000000000..9f7fb15820 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-properties-view.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-properties-view.html + \previouspage qtquick-navigator.html + \nextpage qtquick-connection-view.html + + \title Properties + + The \uicontrol Properties view displays all the properties of the selected + \l{glossary-component}{component}. The properties are grouped by type. The + top part of the view displays properties that are common to all components, + such as component type, ID, name, geometry, and visibility. + + \image qtquick-item-properties-common.png "Basic component properties" + + The bottom part of the view displays properties that have been defined for + the component type. For example, the following image displays the predefined + properties you can set for \l{basic-rectangle}{Rectangle} and \l Text + components. + + \image qmldesigner-element-properties.png "Rectangle and Text properties" + + \section1 Summary of Properties View Buttons + + The following table lists the \uicontrol Properties view buttons: + + \table + \header + \li Icon + \li Tooltip + \li Read More + \row + \li \inlineimage icons/alias.png + \li Adds a property alias that you can use from outside of the + component for the root component. You can use a menu item + in the actions menu to add property aliases for property + values of child components. + \li \l{Adding Property Aliases} + \row + \li \inlineimage icons/action-icon.png + \li Opens a menu with actions for: + \list + \li Resetting property values to their default values + \li Setting property bindings + \li Creating property aliases + \li Inserting keyframes for timeline animations + \endlist + \li + \list + \li \l{Viewing Changes in Properties} + \li \l{Adding Bindings Between Properties} + \li \l{Adding Property Aliases} + \li \l{Setting Keyframe Values} + \endlist + \row + \li \inlineimage icons/action-icon-binding.png + \li Indicates that the value of the property is bound to the value + of another property. Opens the same menu as the action icon. + \li \l{Adding Bindings Between Properties} + + \endtable + + \section1 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 \l{Adding States}{states} are highlighted + with blue. + + This allows you to easily see which values are set in the component + file for this component instance and which values are default + characteristics of 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 + \uicontrol Position and \uicontrol Size values are explicitly set + and highlighted. + + \image qmldesigner-properties-explicit-base.png "Explicitly set properties" + + In \uicontrol State1, only \uicontrol Position 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 component file. + + \note As a result, all boolean values can be visualized in four different + ways. + + For example, visibility can be visualized as follows: + + \table + \row + \li \image qmldesigner-boolean-true.png + \li TRUE + \li The component is visible by default. The visibility might be + overridden by the visibility set in the base state. + \row + \li \image qmldesigner-boolean-true-blue.png + \li TRUE (highlighted) + \li The component is explicitly set to visible. + \row + \li \image qmldesigner-boolean-false.png + \li FALSE + \li The component is hidden by default. The visibility might be + overridden by the visibility set in the base state. + \row + \li \image qmldesigner-boolean-false-blue.png + \li FALSE (hightlighted) + \li The component is explicitly set to hidden. + \endtable + + \section1 Multiselection + + To modify the values of common properties of multiple components + simultaneously, select the components in \l Navigator, \l {Form Editor} + or \uicontrol {3D Editor}: + + \list + \li On Windows, press and hold \key Ctrl and \key Shift, and then click + the components to select them. + \li On \macos, press \key Shift to select a range of components or + \key Cmd to select multiple single components. + \endlist + + You can \l{Locking Components}{lock other components} in + \uicontrol Navigator to make multiselection easier. + + \section1 Getting Help for Properties + + \list + \li For information about setting common component properties, see + \l{Specifying Component Properties}. + \li For more information about the properties available for a + component, press \key {F1} or see \l{Component Types} + and \l{Scalable Layouts}. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-properties.qdoc b/doc/qtdesignstudio/src/views/qtquick-properties.qdoc new file mode 100644 index 0000000000..9b7989fb53 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-properties.qdoc @@ -0,0 +1,491 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-properties.html + \previouspage quick-scalable-image.html + \nextpage qtquick-positioning.html + + \title Specifying Component Properties + + The \l Properties view displays all the properties of the selected + \l{glossary-component}{component}. + + \target basic-item + \section1 Basic Component Properties + + All components share a set of properties that you can specify in the + \uicontrol Properties view. + + \image qtquick-item-properties-common.png "Basic component properties" + + \section2 Type + + When you create an instance of a \l{Component Types}{preset component}, + it has all the properties of the preset you used. If you realize later that + another preset component with another set of default properties would be + more suitable for your purposes, you can change the component type by + double-clicking the \uicontrol Type field and entering the name of + another preset component in the field. + + If you have specified values for properties that are not supported by the + new component type, \QC offers to remove them for you. If you'd rather do + this yourself, you can select the \inlineimage icons/action-icon.png + (\uicontrol Actions) menu next to the property name, and then select + \uicontrol Reset to remove the property values before trying again. + + \section2 ID + + Each component and each instance of a component has an \e ID that uniquely + identifies it and enables other components' properties to be bound to it. + You can specify IDs for components in the \uicontrol ID field. + + An ID must be unique, it must begin with a lower-case letter or an + underscore character, and it can contain only letters, numbers, and + underscore characters. + + For more technical information about IDs, see \l{The id Attribute}. + + To add a \l{Adding Property Aliases}{property alias} that you can use + from outside of the component, select \inlineimage icons/alias.png + . You can use a menu item in the \uicontrol Actions menu to add property + aliases for property values of child components. + + \section2 Name + + The value of the \uicontrol {Name} field specifies the component name + used in an \l{Annotating Designs}{annotation}. It is a free-form text + that descibes the component. + + \section1 2D Geometry + + Set the properties in the \uicontrol {Geometry - 2D} section to determine + the position and size of a component. + + \image qtquick-properties-2D-geometry.png "2D Geometry properties" + + In the \uicontrol Position group, you can set the position of a component on + the x and y axis. The position of a component in the UI can be either + absolute or relative to other components. For more information, see + \l{Scalable Layouts}. + + In the 2D space, the z position of a component determines its position in + relation to its sibling components in the component hierarchy. You can set + the z position in the \uicontrol {Z stack} field. + + In the \uicontrol Size group, you can set the width and height of a + component. You can also use the resize cursor to \l{Resizing 2D Components} + {resize 2D components} in \uicontrol {Form Editor} or the scaling gizmo + to \l{Scaling Components}{scale 3D components} in \uicontrol {3D Editor}. + The values in the \uicontrol X and \uicontrol Y fields change accordingly. + + The component size and position can also be managed automatically + when \l{Using Layouts}{using layouts}. + + The width and height of the root component in a component file determine + the size of a component. The component size might also be zero (0,0) + if its final size is determined by property bindings. For more + information, see \l {Previewing Component Size}. + + \section2 Resetting Component Position and Size + + To return a component to its default position after moving it, + select the \inlineimage qtcreator-reset-position-icon.png + (\uicontrol {Reset Position}) button on the \l{Design Views} + {Design mode toolbar}. To return it to its default size, select + \inlineimage qtcreator-reset-size-icon.png + (\uicontrol {Reset Size}) button. + + \section2 Managing 2D Transformations + + You can assign any number of transformations, such as rotation and scaling, + to a component. Each transformation is applied in order, one at a time. + + In the \uicontrol Origin field, select the origin point for scaling and + rotation. + + Set the scale factor in the \uicontrol Scale field. A value of less than + 1.0 makes the component smaller, whereas a value greater than 1.0 makes + it larger. A negative value causes the component to be mirrored in + \uicontrol {Form Editor}. + + In the \uicontrol Rotation field, specify the rotation of the component + in degrees clockwise around the origin point. + + Alternatively, you can move, resize, or rotate components by dragging them + in \l{Form Editor}. + + For more information about transforming 3D components, see + \l{Managing 3D Transformations} and \l{3D Editor}. + + \section1 Visibility + + Set the properties in the \uicontrol Visibility section to show and + hide components. + + \image qtquick-properties-visibility.png "Visibility properties" + + Deselect the \uicontrol Visible check box to hide a component and all + its child components, unless they have explicitly been set to be visible. + This might have surprise effects when using property bindings. In such + cases, it may be better to use the \uicontrol Opacity property instead. + + If this property is disabled, the component will no longer receive + \l{Mouse Area}{mouse events}. However, it will continue to receive key + events and will retain the keyboard focus events if the \uicontrol Enabled + check box in the \uicontrol Advanced section is selected. + + The visibility value is only affected by changes to this property or the + parent's visible property. It does not change, for example, if this + component moves off-screen, or if the opacity changes to 0. + + In the \uicontrol Opacity field, specify the opacity of a component as a + number between 0.0 (fully transparent) and 1.0 (fully opaque). The specified + opacity is also applied individually to child components, sometimes with + surprising effects. + + Changing a component's opacity does not affect whether the component + receives user input events. + + You can \l{Creating Timeline Animations}{animate} the opacity value to make a + component fade in and out. + + If the \uicontrol Clip check box is selected, the component and its children + are clipped to the bounding rectangle of the component. + + in the \uicontrol State field, select the \l{Adding States}{state} to + change the value of a property in that state. + + \section1 Picking Colors + + You can define color properties for some of the components in the + \uicontrol Properties view by using the color picker. Open the color picker + by clicking, for example, the color field of the \uicontrol {Fill color} or + \uicontrol {Border color} property. + + \image qtquick-designer-color-picker.png "Color Picker view" + + To select a new color, click the color of your choice in the color selector + (1), or click the \uicontrol {Eye Dropper} icon (2) to be able to select any + color visible in your screen to use further in your project. + + The \uicontrol Original field displays the original color of the component, + while the \uicontrol New field displays the current color. + + Make the color fully transparent by clicking the \uicontrol Transparent icon + (3). + + To use preset \l {Selecting Web Gradients}{web gradients}, click the + \uicontrol {Gradient Picker} icon (4). + + Use the dropdown menu (5) to determine the color fill type you wish to use. + You can choose a solid or a gradient color. Available gradient types vary + between components. The items listed in light grey are not available for the + selected component. + + The current color bar (6) shows gradient and gradient stops when a gradient + is selected. + + Use the hue slider (7) or the alpha slider (8) to further define a new + color. + + Click the \uicontrol X icon to close the color picker. + + \section2 Picking Gradients + + A gradient is defined by two or more colors which are blended + seamlessly. The colors are specified as a set of gradient stops, + each of which defines a position on the gradient bar from 0.0 to 1.0 + and a color. Drag the gradient stops along the gradient bar to set their + values. Select the arrow below a gradient stop to see its value as + a number. + + To add gradient stops, move the cursor over the gradient bar and point at + it with the finger-shaped cursor. To remove gradient stops, pull them away + from the gradient line. + + Set the direction of the gradient by selecting \uicontrol Horizontal + or \uicontrol Vertical in the \uicontrol {Gradient Controls} section of the + color picker. + + \image qtquick-designer-gradient-stops.gif + + Calculating gradients can be computationally expensive compared to the + use of solid color fills or images. Consider using gradients only for + static components in a UI. + + \if defined(qtdesignstudio) + \section2 Setting Gradient Properties + + \image qtquick-designer-gradient-types.png "Available gradient types" + + You can select \uicontrol Linear (1), \uicontrol Radial (2), or + \uicontrol Conical (3) as the color fill type. After selecting one of the + gradient types, you can define the gradient properties for + \l{Shapes}{Qt Quick Studio Components} in the \uicontrol {Gradient Controls} + section of the color picker. + + \section3 Linear Gradients + + A \e {linear gradient} interpolates colors between start and end points. + Outside these points, the gradient is either padded, reflected, or repeated + depending on the spread type. Set start and end points for horizontal and + vertical interpolation in the \uicontrol X1, \uicontrol X2, \uicontrol Y1, + and \uicontrol Y2 fields. + + \image qtquick-designer-gradient-properties-linear.png "Linear gradient controls" + + \section3 Radial Gradients + + A \e {radial gradient} interpolates colors between a focal circle and a + center circle. Points outside the cone defined by the two circles will + be transparent. Outside the end points, the gradient is either padded, + reflected, or repeated depending on the spread type. + + You can set the center and focal radius in the \uicontrol {Center radius} + and \uicontrol {Focal radius} fields. For simple radial gradients, set + \uicontrol {Focal radius} to 0. + + You can set the center and focal points in the \uicontrol CenterX, + \uicontrol CenterY, \uicontrol FocalX, and \uicontrol FocalY fields. + To specify a simple radial gradient, set the \uicontrol FocalX and + \uicontrol FocalY to the value of \uicontrol CenterX and \uicontrol CenterY, + respectively. + + \image qtquick-designer-gradient-properties-radial.png "Radial gradient properties" + + \section3 Conical Gradients + + A \e {conical gradient} interpolates colors counter-clockwise around a + center point. Set the horizontal and vertical center point of the gradient + in the \uicontrol CenterX and \uicontrol CenterY fields and the start angle + in the \uicontrol Angle field. + + \image qtquick-designer-gradient-properties-conical.png "Conical gradient properties" + \endif + + \section2 Selecting Web Gradients + + The \uicontrol {Gradient Picker} enables you to specify + \l{https://webgradients.com/}{WebGradients} for components + that support \l QGradient. + + To open the \uicontrol {Gradient Picker}, select the + \uicontrol {Gradient Picker Dialog} icon (4). + + \image qtquick-designer-gradient-picker.png "Gradient Picker dialog" + + To apply a gradient on the selected component, select \uicontrol Apply. + + To save a gradient in the \uicontrol {User Presets} tab, select + \uicontrol Save. + + By default, a linear gradient is used, but you can select another + supported gradient type in the dropdown menu (5) of the color picker. + + \section2 Color Details + + Further define the colors in your project by modifying the properties in the + \uicontrol {Color Details} section of the color picker. + + \image qtquick-designer-color-details.png "Color Details tab" + + Use the \uicontrol Hex property to enter the Hex value of a new color + manually. Define exact values for red, green, and blue using the + \uicontrol Hex property to create different shades for the colors used in + the project. + + The default color value mode is HSVA (hue-saturation-value-alpha). Use the + dropdown menu to change the color value mode to RGBA (red-green-blue-alpha) + or HSLA (hue-saturation-lightness-alpha). \e Hue is defined in degrees which + refer to different colors of the color wheel. \e Saturation modifies the + intensity of the color. \e Value determines the brightness of the color. In + HSLA \e Lightness signifies the amount of white or black blended with the + color. + + \section2 Palette + + \image qtquick-designer-color-palette.png "Color Palette tab" + + Use the dropdown menu in the \uicontrol Palette section of the + color picker to change the \uicontrol Palette type. \uicontrol Recent + displays the recent colors used in the project, while \uicontrol Favorites + shows the colors you have added to your collection of favorite colors. You + can add colors to \uicontrol Favorites by right-clicking the color thumbnail + for \uicontrol Original, \uicontrol New, or in \uicontrol Palette > + \uicontrol Recent colors and selecting \uicontrol {Add to Favorites}. + + Click one of the \uicontrol Palette color thumbnails to select it as + the new color. + + \section1 Specifying Developer Properties + + In the \uicontrol Advanced and \uicontrol Layer sections of the + \uicontrol Properties view, you can manage the more advanced + properties of components that are inherited from the \l Item + component and that are mostly used by application developers. + + \image qtquick-properties-advanced.png "Advanced section in Properties" + + Select the \uicontrol Smooth check box to activate smooth sampling. Smooth + sampling is performed using linear interpolation, while non-smooth sampling + is performed using the nearest neighbor. Because smooth sampling has minimal + impact on performance, it is activated by default. + + Antialiasing is used to make curved lines smoother on the screen. Select + the \uicontrol Antialising check box to turn on antialiasing. + + The value of the \uicontrol {Baseline offset} specifies the position of the + component's baseline in local coordinates. The baseline of a \l Text + component is the imaginary line on which the text sits. Controls containing + text usually set their baseline to the baseline of their text. For non-text + components, a default baseline offset of 0 is used. + + \section2 Managing Mouse and Keyboard Events + + Select the \uicontrol Enabled check box to allow the component to receive + mouse and keyboard events. The children of the component inherit this + behavior, unless you explicitly set this value for them. + + You can enable the \uicontrol Focus check box to specify that the component + has active focus and the \uicontrol {Focus on tab} check box to add + the component to the \e {tab focus chain}. The tab focus chain traverses + components by first visiting the parent, and then its children in the order + they are defined. Pressing \key Tab on a component in the tab focus chain + moves keyboard focus to the next component in the chain. Pressing back tab + (usually, \key {Shift+Tab}) moves focus to the previous component. + + \section2 Using Layers + + Qt Quick makes use of a dedicated scene graph that is then traversed and + rendered via a graphics API such as OpenGL ES, OpenGL, Vulkan, Metal, or + Direct 3D. Using a scene graph for graphics rather than the traditional + imperative painting systems, means that the scene to be rendered can be + retained between frames and the complete set of primitives to render is + known before rendering starts. This opens up for a number of optimizations, + such as \l{Batching}{batch rendering} to minimize state changes and + discarding obscured primitives. + + For example, a UI might contain a list of ten items where + each item has a background color, an icon and a text. Using traditional + drawing techniques, this would result in 30 draw calls and a similar + amount of state changes. A scene graph, on the other hand, could reorganize + the primitives to render such that all backgrounds are drawn in one call, + then all icons, then all the text, reducing the total amount of draw calls + to only 3. Batching and state change reduction like this can greatly + improve performance on some hardware. + + You need a basic understanding of how components are rendered + to be able to set layer properties. Rendering is described in + \l {Qt Quick Scene Graph Default Renderer}. + + \image qtquick-item-properties-layer.png "Layer properties" + + Components are normally rendered directly into the window they belong to. + However, by selecting the \uicontrol Enabled check box in the + \uicontrol Layer section, you can delegate the component and its entire subtree + into an offscreen surface. Only the offscreen surface, a texture, will + then be drawn into the window. For more information, see \l{Item Layers}. + + When layering is enabled, you can use the component directly as a texture, + in combination with the component you select in the \uicontrol Effect field. + Typically, this component should be a shader effect with a source texture + specified. You can use the effects in \l Library > \uicontrol Components > + \uicontrol {Qt Quick Studio Effects} that are based on the components in the + \l {Qt Graphical Effects} module. + + To enable the component to pass the layer's offscreen surface to the effect + correctly, the \uicontrol {Sampler name} field is set to the source + property of the texture. + + Note that when a component's layer is enabled, the scene graph will allocate + memory in the GPU equal to width x height x 4. In memory constrained + configurations, large layers should be used with care. Also, a component + using a layer cannot be batched during rendering. This means that a + scene with many layered components may have performance problems. + + By default, multisampling is enabled for the entire window if the scenegraph + renderer is in use and the underlying graphics API supports it. By setting + the value in the \uicontrol Samples field, you can request multisampling for + a part of the scene. This way, multisampling is applied only to a particular + subtree, which can lead to significant performance gain. Even then, enabling + multisampling can be potentially expensive regardless of the layer's size, + as it incurs a hardware and driver dependent performance and memory cost. If + support for multisample renderbuffers and framebuffer blits is not + available, the value is silently ignored. + + The value of the \uicontrol Format field specifies the internal OpenGL + format of the texture. Depending on the OpenGL implementation, it might + allow you to save some texture memory. However, use the \uicontrol RGB + and \uicontrol Alpha values with caution, because the underlying hardware + and driver might not support them. + + In the \uicontrol {Texture mirroring} field, specify whether the generated + OpenGL texture should be mirrored by flipping it along the x or y axis. + Custom mirroring can be useful if the generated texture is directly accessed + by custom shaders. If no effect is specified for the layered component, + mirroring has no effect on the UI representation of the component. + + The component will use linear interpolation for scaling if the + \uicontrol Smooth check box is selected. To use a mipmap for downsampling, + select the \uicontrol Mipmap check box. Mipmapping may improve the visual + quality of downscaled components. For mipmapping of single \uicontrol Image + components, select the \uicontrol Mipmap check box in the \l{Images} + {image properties}, instead. + + To use a texture with a size different from that of the component, specify + the width and height of the texture in the \uicontrol {Texture size} field. + + The \uicontrol {Wrap mode} defines the OpenGL wrap modes associated with + the texture. You can clamp the texture to edges or repeat it horizontally + and vertically. Note that some OpenGL ES 2 implementations do not support + the \uicontrol Repeat wrap mode with non-power-of-two textures. + + \section1 Copying and Pasting Formatting + + You can copy property values from a component and paste them to one or + several other components. The values are applied if the target components + have those particular properties. + + To copy property values from the selected component, select + \inlineimage icons/copy-formatting.png + on the \uicontrol Design mode \l{Summary of Main Toolbar Actions} + {main toolbar}. + + To apply the values to one or several other components, select + them in \l Navigator or \l{Form Editor}, and then select + \inlineimage icons/paste-formatting.png + . + + \section1 Editing Properties Inline + + You can double-click components in \l {Form Editor} to edit their + text, color, or source properties inline. Because you can specify several + of these properties for some components, such as \l {text-edit}{Text Edit}, + you can also right-click components to open the inline editors from the + context menu. + + \image qmldesigner-inline-editing.png +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc new file mode 100644 index 0000000000..66179af77a --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-states-view.html + \previouspage qtquick-connection-view.html + \nextpage qtquick-transition-editor.html + + \title States + + The \uicontrol States view displays the different \l{Adding States}{states} + of a UI. + + \image qmldesigner-transitions.png "States view" + + To open the \uicontrol States view, select \uicontrol View > + \uicontrol Views > \uicontrol States. + + To collapse or expand the \uicontrol States view, select: + + \list + \li Select \uicontrol View > \uicontrol Views > + \uicontrol {Toggle States}. + \li Press \key {Ctr+Alt+S} on Windows or \key {Cmd+Option+S} on \macOS. + \li Right-click the view and select \uicontrol Collapse or + \uicontrol Expand. + \endlist + + Initially, \uicontrol States displays a \e {base state} that shows the + selected \l{glossary-component}{component} in its initial state. To add + states, select \uicontrol {Create New State}. + + For more information, watch the following video: + + \youtube FzmLuRHQXaw + + \section1 Summary of States View Actions + + To open the \uicontrol Actions menu, select + \inlineimage icons/action-icon.png + . The actions available in the menu depend on the current context. For + example, the option for editing an annotation becomes available after + you add an annotation. + + \table + \header + \li Action + \li Purpose + \li Read More + \row + \li \uicontrol {Set when Condition} + \li Determines when a state should be applied. + \li \l{Applying States} + \row + \li \uicontrol {Reset when Condition} + \li Removes \c when condition for the state. + \li \l{Applying States} + \row + \li \uicontrol {Set as Default} + \li Sets the current state as the startup state of the application. + \li \l{Setting the Default State} + \row + \li\uicontrol {Reset Default} + \li Resets the current state as the default state. + \li \l{Setting the Default State} + \row + \li \uicontrol {Add Annotation} + \li Opens the \uicontrol {Annotation Editor} when you can add an + annotation for the states that you create. + \li \l{Annotating Designs} + \row + \li \uicontrol {Edit Annotation} + \li Opens the \uicontrol {Annotation Editor} where you can edit the + annotation for the state. + \li \l{Annotating Designs} + \row + \li \uicontrol {Add Annotation} + \li Removes the annotation for the state. + \li \l{Annotating Designs} + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-states.qdoc b/doc/qtdesignstudio/src/views/qtquick-states.qdoc new file mode 100644 index 0000000000..71d4eba388 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-states.qdoc @@ -0,0 +1,200 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-states.html + \if defined(qtdesignstudio) + \previouspage quick-dynamic-properties.html + \nextpage creator-live-preview.html + \else + \previouspage quick-connections-backend.html + \nextpage exporting-3d-assets.html + \endif + + \title Adding States + + You can define states for components and component instances in the + \l States view by selecting \uicontrol {Create New State}. + + \image qmldesigner-transitions.png "States view" + + Click the new state to switch to it in \l {Form Editor}, and then modify the + values of the properties of components or component instances in + \l Properties. + + For example, to change the appearance of a button, you can define states in + the button component to hide the button image and show another image in its + place or to change the button background or text color. When you use + instances of the button in other components, you can define states to + create different screens by hiding or showing button component instances. + The preset \l Button control in \l Library > \uicontrol Components + > \uicontrol {Qt Quick Controls} > \uicontrol Controls has predefined + \e normal and \e down states. + + \if defined(qtdesignstudio) + This also applies to the custom button component that you can create + by using a \l{Creating Custom Controls}{wizard template}. For more + information about editing the states within the button component and + hiding and showing buttons to create several screens, see + \l{Log In UI - Components} and \l{Log In UI - States}. + \endif + + To add motion to a screen, you can change the position of a component + instance in \uicontrol {Form Editor} and then add animation to the change + between the states. + + The properties that you change in a state are highlighted with blue color. + In \l{Text Editor}, you can see the changes recorded as changes + to the base state. + + \image qmldesigner-states.png "States and Properties views" + + \note If you have \l{Locking Components}{locked a component} in + \l Navigator, and you attempt to remove states where you change the + values of its properties, you are prompted to confirm the removal. + + For more information, watch the following video: + + \youtube FzmLuRHQXaw + + \section1 Setting the Default State + + To determine the startup state of the application, + select \inlineimage icons/action-icon.png + to open the \uicontrol Actions menu, and then select + \uicontrol {Set as Default}. + + To reset the state later, select \uicontrol Actions > + \uicontrol {Reset Default}. + + \section1 Applying States + + To determine when a state should be applied, select \uicontrol Actions > + \uicontrol {Set when Condition}. In \uicontrol {Binding Editor}, specify + a \l [QtQuick]{State::when}{when} property for the state. Set the value of + the property to a boolean expression that evaluates to \c true when you want + the state to be applied. + + This enables you to evaluate the truthfulness of several components' + properties and move the UI to the state in which these conditions apply. + You can evaluate whether something is true or false, greater than or equal + to something else, and so on. You can also use operators, such as AND or + OR, to evaluate the truthfulness of several components. + + The when conditions are evaluated from left to right and in order of + appearance in the code. Therefore, if you have two conditions for two + different states that both evaluate to \c true, the first state is applied. + + In \uicontrol {Binding Editor}, select the component and property to + create the expression. For example, to change the state when a button is + pressed, you could select a button component and its pressed property. + + \image qtquick-states-binding-editor.png "Binding Editor in States view" + + When you compose the expressions in \uicontrol {Binding Editor}, the + \l{Completing Code}{code completion} feature lists the components and + their properties you can use in the expressions. + + \include creator-logical-operators.qdocinc logical operators + + \section2 Examples of when Conditions + + To apply a state to a button when the button is pressed, you could simply + write: + + \badcode + when: control.pressed + \endcode + + To apply a state when the button is not pressed, select the \uicontrol NOT + check box. + + \image qtquick-states-binding-editor-not.png "NOT check box in Binding Editor" + + To apply a state when the button is not pressed, selected, nor hovered on, + you could combine conditions, as follows: + + \badcode + when: !control.pressed && !control.checked && !control.hovered + \endcode + + To apply a state when the button is pressed or selected, but not hovered on, + you could write: + + \badcode + when: control.pressed || control.checked && !control.hovered + \endcode + + \if defined(qtdesignstudio) + If you are not familiar with writing expressions, you can use preset + \l{Logic Helpers}{logic helpers} from \l Library > \uicontrol Components + > \uicontrol {Qt Quick Studio Logic Helper}. + \endif + + \section1 Using States + + To keep the code clean, you should create a base state that contains all + the components you will need in the application. You can then create states, + in which you hide and show a set of components and modify their properties. + This allows you to: + + \list + \li Align components on different views with each other. + \li Avoid excessive property changes. If a component is invisible in + the base state, you must define all changes to its child components + as property changes, which leads to complicated code. + \li Minimize the differences between the base state and the other states + to keep the code short and readable and to improve performance. + \li Avoid problems when using transitions and animation when changing + states. + \endlist + + To create views for an application by using states: + + \image qmldesigner-screen-design.png "Designing views" + + \list 1 + \li In the base state, add all components you will need in the + application (1). While you work on one view, you can click the + \inlineimage eye_open.png + icon in \l Navigator to hide components on the canvas that are + not part of a view. + \li In \uicontrol States, select \uicontrol {Create New State} to create + a new state and give it a name. For example, \c Normal. + \li In \l Properties (2), deselect the \uicontrol Visibility + check box or set \uicontrol Opacity to 0 for each component that + is not needed in this view. If you specify the setting for the + parent component, all child components inherit it and are also + hidden. + \li Create additional states for each view and set the visibility + or opacity of the components in the view. + \li To determine which state is applied when the application starts, + select \uicontrol Actions > \uicontrol {Set as Default}. + \endlist + + \if defined(qtcreator) + \include qtquick-states-scxml.qdocinc scxml state machines + \endif +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc new file mode 100644 index 0000000000..f60821ca9a --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-text-editor.html + \previouspage qtquick-curve-editor.html + \if defined(qtdesignstudio) + \nextpage creator-projects-view.html + \else + \nextpage quick-uis.html + \endif + + \title Text Editor + + In the \uicontrol {Text Editor} view, you can view and modify the code in a + \l{UI Files}{UI file} (.ui.qml) or component file (.qml) that is generated + when you create components in \l{Form Editor} or \l{3D Editor} and specify + their properties in \l Properties. + + \image qtquick-text-editor.png "Text Editor" + + You can also view and modify other types of text files. + + You can use a subset of the functions available in the + \l{Writing Code}{Edit mode}: + + \list + \li \l{Semantic Highlighting} + \li \l{Checking Code Syntax} + \li \l{Completing Code} + \li \l{Indenting Text or Code} + \li \l{Using Qt Quick Toolbars} + \endlist +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc new file mode 100644 index 0000000000..246442def9 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-timeline-view.qdoc @@ -0,0 +1,281 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-timeline-view.html + \previouspage qtquick-transition-editor.html + \nextpage qtquick-curve-editor.html + + \title Timeline + + You can use the timeline and keyframe based editor in the + \uicontrol Timeline view to animate the properties of + \l{glossary_component}{components}. The view is empty until + you create a timeline. + + \image studio-timeline-empty.png "Empty Timeline view" + + Select the \inlineimage plus.png + (\uicontrol {Add Timeline}) button to \l{Creating Timelines} + {create a timeline} and specify settings for it in the + \uicontrol {Timeline Settings} dialog. + + \image studio-timeline-settings.png "Timeline Settings dialog" + + When you select \uicontrol Close, the \uicontrol Timeline view appears. + It now displays a \l{Timeline Toolbar}{toolbar} and a ruler but no + keyframe tracks. + + \image studio-timeline-no-tracks.png "Timeline view without keyframe tracks" + + To animate component properties in the \uicontrol Timeline view, you + must \l{Setting Keyframe Values}{insert keyframes} for them. In the + \l Properties view, select \inlineimage icons/action-icon.png + (\uicontrol Actions) > \uicontrol {Insert Keyframe} for a property that you + want to animate. A keyframe track is generated for each component that you + insert keyframes for. + + \image studio-timeline-with-empty-tracks.png "Timeline view with a property" + + You can now select \inlineimage local_record_keyframes.png + to \l{Setting Keyframe Values}{record changes} in component properties + while you \l{Navigating in Timeline}{navigate the timeline}. + + The following video shows how to insert keyframes for component properties + and to animate them in \uicontrol Timeline: + + \youtube V3Po15bNErw + + \if defined(qtdesignstudio) + To try it yourself, follow the \l{Log In UI - Timeline} tutorial. + \endif + + + For more information about creating timeline animations, see + \l{Creating Timeline Animations}. + + \section1 Navigating in Timeline + + \image studio-timeline.png "Timeline view" + + You can navigate the timeline in the following ways: + + \list + \li Drag the playhead (1) to a frame. + \li Click on the ruler (2) to move to a frame. + \li Select the \uicontrol {To Start (Home)}, \uicontrol {Previous (,)}, + \uicontrol {Next (.)}, or \uicontrol {To End (End)} buttons (3), or + use the keyboard shortcuts to move to the first, previous, next, or + last frame on the timeline. + \li Enter the number of a frame in the current keyframe field (4) to + move to that frame. + \li Select the \uicontrol Previous and \uicontrol Next buttons next to + a property name on the timeline (5) to move to the previous or next + keyframe for that property. + \endlist + + \section1 Zooming in Timeline + + Use the slider on the toolbar to set the zooming level in the + \uicontrol Timeline view. Select the \inlineimage zoom_small.png + and \inlineimage zoom_big.png + buttons to zoom out of or into the view. + + \section1 Setting Keyframe Track Color + + To change the color of a keyframe track, select \uicontrol {Override Color} + in the context menu, and then select a color in the \l{Picking Colors} + {color picker}. To reset the color, select \uicontrol {Reset Color}. + + \image studio-timeline-keyframe-track-colors.png "Keyframe track colors in Timeline" + + \section1 Timeline Toolbar + + The \uicontrol Timeline toolbar contains the following buttons and fields. + + \table + \header + \li Button/Field + \li Action + \li Read More + \row + \li \inlineimage animation.png + \li Opens the \uicontrol {Timeline Settings} dialog for editing + timeline settings. + \li \l{Creating Timelines} + \row + \li Timeline ID + \li Displays the ID of the current timeline. + \li \l{Creating Timelines} + \row + \li \inlineimage to_first_frame.png + \li \uicontrol {To Start (Home)} moves to the first frame on the + timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage back_one_frame.png + \li \uicontrol {Previous (,)} moves to the previous frame on the + timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage start_playback.png + \li \uicontrol {Play (Space)} previews the animation. + \li \l{Viewing the Animation} + \row + \li \inlineimage forward_one_frame.png + \li \uicontrol {Next (.)} moves to the next frame on the timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage to_last_frame.png + \li \uicontrol {To End (End)} moves to the last frame on the timeline. + \li \l{Navigating in Timeline} + \row + \li Current Keyframe + \li Displays the frame that the playhead is currently on. Enter a + number in the field to move the playhead to the respective frame. + \li \l{Navigating in Timeline} + \row + \li \inlineimage global_record_keyframes.png + \li Records changes in keyframe values. + \li \l {Setting Keyframe Values} + \row + \li \inlineimage curve_editor.png + \li Opens \uicontrol {Easing Curve Editor} for attaching an easing + curve to the selected transition. + \li \l{Editing Easing Curves} + \row + \li Start Frame + \li Specifies the first frame of the timeline. Negative values are + allowed. The difference between the start frame and the end frame + determines the duration of the animation. + \li \l{Creating Timelines} + \row + \li \inlineimage zoom_small.png + \li \uicontrol {Zoom Out} (\key Ctrl+-) zooms out of the view. + \li \l{Zooming in Timeline} + \row + \li Slider + \li Sets the zooming level. + \li \l{Zooming in Timeline} + \row + \li \inlineimage zoom_big.png + \li \uicontrol {Zoom In} (\key Ctrl++) zooms into the view. + \li \l{Zooming in Timeline} + \row + \li End Frame + \li Specifies the last frame of the timeline. The difference between + the start frame and the end frame determines the duration of the + animation, so if the start frame is 0, the end frame equals the + duration. + \li \l{Creating Timelines} + \row + \li State Name + \li Displays the name of the current state. + \li \l{Binding Animations to States} + \endtable + + \section1 Keyframe Track Icons + + Each keyframe track can contain the following buttons and markers. + + \table + \header + \li Button/Icon + \li Action + \li Read More + \row + \li \inlineimage previous_keyframe.png + \li Jumps to the previous frame on the timeline. + \li \l{Setting Keyframe Values} + \row + \li \inlineimage next_keyframe.png + \li Jumps to the next frame on the timeline. + \li \l{Setting Keyframe Values} + \row + \li \inlineimage local_record_keyframes.png + \li Records changes in keyframe values for a particular property. + \li \l {Setting Keyframe Values} + \target keyframe_marker + \row + \li \inlineimage keyframe.png + \li Indicates the type of easing curve attached to the keyframe. + When a keyframe track is selected, the keyframe markers on it turn + gray, and when a keyframe itself is selected, its marker turns + brown: + \list + \li \inlineimage keyframe_linear_inactive.png + - linear easing curve + \li \inlineimage keyframe_manualbezier_inactive.png + - manually set Bezier curve + \li \inlineimage keyframe_autobezier_inactive.png + - automatically set Bezier curve + \li \inlineimage keyframe_lineartobezier_inactive.png + - linear-to-Bezier curve + \endlist + \li \l {Editing Easing Curves} + \endtable + + \section1 Timeline Context Menu + + The following table summarizes the context menu items available for each + keyframe track for a component, property, or keyframe marker and provides + links to more information about them. + + \table + \header + \li To Learn About + \li Go To + \row + \li Delete All Keyframes + \li \l{Deleting Keyframes} + \row + \li Add Keyframes at Current Frame + \li \l{Setting Keyframe Values} + \row + \li Copy All Keyframes + \li \l{Copying Keyframes} + \row + \li Paste Keyframes + \li \l{Copying Keyframes} + \row + \li Remove Property + \li \l{Setting Keyframe Values} + \row + \li Delete Keyframe + \li \l{Deleting Keyframes} + \row + \li Edit Easing Curve + \li \l{Editing Easing Curves} + \row + \li Edit Keyframe + \li \l{Editing Keyframe Values} + \row + \li Override Color + \li \l{Setting Keyframe Track Color} + \row + \li Reset Color + \li \l{Setting Keyframe Track Color} + \endtable +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc b/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc new file mode 100644 index 0000000000..ab3e376872 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-timeline.qdoc @@ -0,0 +1,222 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \previouspage quick-animation-overview.html + \page studio-timeline.html + \nextpage qtquick-editing-easing-curves.html + + \title Creating Timeline Animations + + You can create timeline and keyframe based animations for linear + interpolation through intermediate values at specified keyframes + instead of immediately changing to the target value. + + \section1 Creating Timelines + + You specify settings for the timeline and for running the animation in the + \uicontrol {Timeline Settings} dialog. The \uicontrol Animation radio button + is selected for a timeline animation and the \uicontrol {Expression binding} + radio button for a \l{Setting Bindings}{property animation}. + + \image studio-timeline-settings.png "Timeline Settings dialog" + + To create a timeline to animate a UI component: + + \list 1 + \li In the \l Timeline view, select the \inlineimage plus.png + (\uicontrol {Add Timeline}) button to specify settings + for the timeline and running the animation + in the \uicontrol {Timeline Settings} dialog. + \li In the \uicontrol {Timeline ID} field, enter an ID that describes + the animated component. + \li In the \uicontrol {Start frame} field, set the first frame of the + timeline. Negative values are allowed. + \li In the \uicontrol {End frame} field, set the last frame of the + timeline. + \li In the \uicontrol {Animation ID} field, enter an ID for the + animation. + \li Select the \uicontrol {Running in Base State} check box to run the + animation when the base state is applied. Deselect the check box + if you want to run the animation when some other state is applied. + For more information, see \l{Binding Animations to States}. + \li In the \uicontrol {Start frame} field, set the first frame of the + animation. + \li In the \uicontrol {End frame} field, set the last frame of the + animation. + \li In the \uicontrol {Duration} field, set the length of the + animation from the start frame to the end frame. If you set a + shorter duration than the number of frames, frames are left out + from the end of the animation when viewing it. + \li Select the \uicontrol Continuous check box to loop the animation + indefinitely. + \li In the \uicontrol Loops field, select the number of times to run + the animation as a loop. The default number of loops is one, which + means that you must restart the animation to see it again + \li Select the \uicontrol {Ping pong} check box to play the animation + backwards back to the beginning when it reaches the end. + \li In the \uicontrol Finished field, select the state + to apply when the animation finishes. + \li Select \uicontrol Close to close the dialog and save the settings. + \endlist + + To create additional timelines, select the \inlineimage plus.png + (\uicontrol {Add Timeline}) button next to the + \uicontrol {Timeline Settings} tab. + + To specify settings for running timeline animations, select the + \inlineimage plus.png + (\uicontrol {Add Animation}) button next to the + \uicontrol {Animation Settings} tab. For example, you could create + settings for running a part of the timeline animation between specified + frames or for running the animation backwards from the last frame to the + first. + + To modify the settings, select the \inlineimage animation.png + (\uicontrol {Timeline Settings (S)}) button on the \l{Timeline Toolbar} + {toolbar} (or press \key S) in the \l Timeline view. + + \section2 Binding Animations to States + + The table at the bottom of the \uicontrol {Timeline Settings} dialog lists + the available states. Double-click the values in the \uicontrol Timeline + and \uicontrol Animation column to bind the states to animations. In the + \uicontrol {Fixed Frame} column, you can bind the states that don't have + animations to fixed frames. + + \section1 Managing Keyframes + + To animate components in the \l Timeline view, move to a frame + on the timeline and specify changes in the values of a property. \QC + automatically adds keyframes between two keyframes and sets their values + evenly to create an appearance of movement or transformation. + + \image studio-timeline-with-tracks.png "Timeline view" + + \section2 Setting Keyframe Values + + You can insert keyframes for all the properties of all the components that + you want to animate first, and then record the changes in their values by + selecting the \inlineimage local_record_keyframes.png + (\uicontrol {Per Property Recording}) button for one property at a time. + For example, you can hide and show components by turning their visibility + off and on or by setting their opacity to 0 or 1. + + You can also select the \uicontrol {Auto Key (K)} button (or press \key K) + to record changes in property values, but you need to be more careful about + which property values you are changing to avoid surprises. + + To record the changes of property values: + + \list 1 + \li In the \l Navigator view, select the component to animate. + \li In the \l Properties view, select \inlineimage icons/action-icon.png + (\uicontrol Actions) > \uicontrol {Insert Keyframe} for the property + that you want to animate. + \li In the \l Timeline view, select the + \uicontrol {Per Property Recording} button + to start recording property changes. + \li Check that the playhead is in frame 0 and enter the value of the + property in the field next to the property name on the timeline. + Press \key Enter to save the value. + \li Move the playhead to another frame on the timeline and specify + the value at that frame. For more information, see + \l{Navigating in Timeline}. + \li When you have specified as many values as you need, select + \uicontrol {Per Property Recording} again to stop recording. + \endlist + + To remove all the changes you recorded for a property, right-click the + property name on the timeline and select \uicontrol {Remove Property}. + + To add keyframes to the keyframe track of a component at the current + position of the playhead, select \uicontrol {Add Keyframes at Current Frame}. + + Keyframes are marked on the timeline by using \l{keyframe_marker}{markers} + of different colors and shapes, depending on whether they are active or + inactive or whether you have applied \l{Editing Easing Curves} + {easing curves} to them. + + \section2 Editing Keyframe Values + + To fine-tune the value of a keyframe, double-click a keyframe marker or + select \uicontrol {Edit Keyframe} in the context menu. + + The \uicontrol {Edit Keyframe} dialog displays the name of the property + you are animating and its current value at the frame specified in the + \uicontrol Frame field. You can change both the keyframe and its value. + + \image studio-edit-keyframe.png "Edit Keyframe dialog" + + \section2 Copying Keyframes + + You can copy the keyframes from the keyframe track for a component and + paste them to the keyframe track of another component. To copy all + keyframes from one track to another one, first right-click the component ID + and select \uicontrol {Copy All Keyframes} in the context menu. + Then right-click the other component ID, and select + \uicontrol {Paste Keyframes} in the context menu. + + \section2 Deleting Keyframes + + To delete the selected keyframe, select \uicontrol {Delete Keyframe} in the + context menu. + + To delete all keyframes from the selected component, select + \uicontrol {Delete All Keyframes} in the context menu. + + \section1 Viewing the Animation + + You can view the animation on the canvas by moving the playhead along the + timeline. + + To preview the animation, select the \uicontrol {Play (Space)} + button or press \key Space. To preview the whole UI, select the + \inlineimage live_preview.png + (\uicontrol {Show Live Preview}) button on the canvas toolbar + or press \key {Alt+P}. + + \section1 Animating Rotation + + To animate components that rotate around a central point, you can use the + \l {basic-item}{Item} component as a parent for the rotating component. Then + create a timeline for the Item, and set the rotation property for the start + and end keyframes. + + \if defined(qtdesignstudio) + \section1 Animating Shapes + + You can use the \uicontrol {Qt Quick Studio Components} to animate the + following shapes: + + \list + \li \l Arc + \li \l Border + \li \l Pie + \li \l Rectangle + \li \l Triangle + \endlist + \endif +*/ diff --git a/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc new file mode 100644 index 0000000000..12ade5c3c4 --- /dev/null +++ b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page qtquick-transition-editor.html + \previouspage qtquick-states-view.html + \nextpage qtquick-timeline-view.html + + \title Transition Editor + + To make movement between states smooth, you can use + \uicontrol {Transition Editor} to animate the changes between + states. + + First, you need to \l{Adding States}{add states} in the \l States view + and \l{Specifying Component Properties}{edit some properties} that can be + animated, such as colors or numbers, in the \l Properties view. For example, + you can animate the changes in the position of a component. + + \image qtquick-transition-editor-view.png "Transition Editor view" + + In \uicontrol {Transition Editor}, you can set the start frame, end + frame, and duration for the transition of each property. You can also + set an \l{Editing Easing Curves}{easing curve} for each animation and + the maximum duration of the whole transition. + + \section1 Zooming in Transition Editor + + Use the slider on the toolbar to set the zooming level in + \uicontrol {Transition Editor}. Select the \inlineimage zoom_small.png + and \inlineimage zoom_big.png + buttons to zoom out of or into the view. + + \section1 Summary of Transition Editor Toolbar Actions + + \table + \header + \li Button/Field + \li Action + \li Read More + \row + \li \inlineimage animation.png + \li Opens \uicontrol {Transition Settings} dialog for editing + transition settings. + \li \l{Specifying Transition Settings} + \row + \li Transition ID + \li Displays a list of transitions that you can open in + \uicontrol {Transition Editor}. + \li \l{Animating Transitions Between States} + \row + \li \inlineimage curve_editor.png + \li Opens \uicontrol {Easing Curve Editor} for attaching an easing + curve to the selected transition. + \li \l{Editing Easing Curves} + \row + \li \inlineimage zoom_small.png + \li \uicontrol {Zoom Out} (\key Ctrl+-): zooms out of the view. + \li \l{Zooming in Transition Editor} + \row + \li Slider + \li Sets the zooming level. + \li \l{Zooming in Transition Editor} + \row + \li \inlineimage zoom_big.png + \li \uicontrol {Zoom In} (\key Ctrl++): zooms into the view. + \li \l{Zooming in Transition Editor} + \row + \li Maximum Duration + \li Specifies the maximum duration of the transition. + \li + \endtable + + \section1 Animating Transitions Between States + + To animate transitions: + + \list 1 + \li Select \uicontrol View > \uicontrol Views > + \uicontrol {Transition Editor}. + \image qmldesigner-transition-editor-startup.png "Empty Transition Editor" + \li Select the \inlineimage plus.png + (\uicontrol {Add Transition}) button to add a transition. This + works only if you have added at least one state and modified at + least one property in it. + \image qtquick-transition-editor-view.png "Transition Editor view" + \li Move the blue bar next to the component or property name to set + the start and end frame of the animation of the property. Pull its + left and right edges to set the duration of the animation. + \li To attach an \l{Editing Easing Curves}{easing curve} to the + selected transition, select the \inlineimage curve_editor.png + (\uicontrol {Easing Curve Editor (C)}) button. + \endlist + + \section1 Specifying Transition Settings + + To modify transition settings, select the \inlineimage animation.png + (\uicontrol {Transition Settings (S)}) button in + \uicontrol {Transition Editor}. + + \image qtquick-transition-editor-settings.png "Transition settings" + + To add transitions: + + \list 1 + \li Select the \inlineimage plus.png + (\uicontrol {Add Transition}) button. + \li In the \uicontrol {Transition ID} field, enter an ID for the + transition. + \li In the \uicontrol From field, select the state to transition from. + \li In the \uicontrol To field, select the state to transition to. + \endlist + + To remove the current transition, select the \inlineimage minus.png + (\uicontrol {Remove Transition}) button. + + \if defined(qtcreator) + For an example of animating transitions between states, see + \l {Creating a Qt Quick Application}. + \endif +*/ |