diff options
Diffstat (limited to 'doc/qtdesignstudio/src/components')
15 files changed, 4286 insertions, 0 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 +*/ |