diff --git a/doc/qtcreator/images/qtquick-assets-tab.png b/doc/qtcreator/images/qtquick-assets-tab.png new file mode 100644 index 00000000000..c653cca67b3 Binary files /dev/null and b/doc/qtcreator/images/qtquick-assets-tab.png differ diff --git a/doc/qtcreator/images/qtquick-components-tab-add.png b/doc/qtcreator/images/qtquick-components-tab-add.png new file mode 100644 index 00000000000..9d7d9a4ddd6 Binary files /dev/null and b/doc/qtcreator/images/qtquick-components-tab-add.png differ diff --git a/doc/qtcreator/images/qtquick-components-tab.png b/doc/qtcreator/images/qtquick-components-tab.png new file mode 100644 index 00000000000..7ddf21135d0 Binary files /dev/null and b/doc/qtcreator/images/qtquick-components-tab.png differ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 85ae72493a5..10b5c1e76fb 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -92,6 +92,9 @@ \li \l {Creating Qt Quick Projects} \li \l {Editing QML Files in Design Mode} + \list + \li \l{Library} + \endlist \li \l {Creating UIs} \list \li \l {Creating Components} @@ -102,6 +105,7 @@ \li \l{Images} \li \l{User Interaction Methods} \li \l{Lists and Other Data Models} + \li \l{Animations} \li \l{Creating Buttons} \li \l{Creating Scalable Buttons and Borders} \endlist diff --git a/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc b/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc index 8e98df94d7a..d3db5c08b58 100644 --- a/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc +++ b/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -703,6 +703,48 @@ be used in horizontal or vertical toolbars by setting the value of the \uicontrol Orientation field. + \section1 Styling Controls + + The 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 User Interaction Methods The following table lists the QML types that you can use to add interaction diff --git a/doc/qtcreator/src/qtquick/library/qtquick-data-models.qdoc b/doc/qtcreator/src/qtquick/library/qtquick-data-models.qdoc index f807f45e0fc..5f646dbc5f9 100644 --- a/doc/qtcreator/src/qtquick/library/qtquick-data-models.qdoc +++ b/doc/qtcreator/src/qtquick/library/qtquick-data-models.qdoc @@ -29,7 +29,7 @@ \if defined(qtdesignstudio) \nextpage quick-2d-effects.html \else - \nextpage quick-buttons.html + \nextpage quick-animations.html \endif \title Lists and Other Data Models diff --git a/doc/qtcreator/src/qtquick/library/qtquick-shapes.qdoc b/doc/qtcreator/src/qtquick/library/qtquick-shapes.qdoc index c66d6d56f23..11b3f40a562 100644 --- a/doc/qtcreator/src/qtquick/library/qtquick-shapes.qdoc +++ b/doc/qtcreator/src/qtquick/library/qtquick-shapes.qdoc @@ -25,7 +25,7 @@ /*! \page quick-shapes.html - \previouspage qtquick-form-editor.html + \previouspage quick-components.html \nextpage quick-text.html \title Shapes diff --git a/doc/qtcreator/src/qtquick/qtquick-animation-types.qdocinc b/doc/qtcreator/src/qtquick/qtquick-animation-types.qdoc similarity index 92% rename from doc/qtcreator/src/qtquick/qtquick-animation-types.qdocinc rename to doc/qtcreator/src/qtquick/qtquick-animation-types.qdoc index 5bf1bafd954..3a8cdcc4da1 100644 --- a/doc/qtcreator/src/qtquick/qtquick-animation-types.qdocinc +++ b/doc/qtcreator/src/qtquick/qtquick-animation-types.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -24,9 +24,15 @@ ****************************************************************************/ /*! -//! [qtquick animation types] + \page quick-animations.html + \if defined(qtdesignstudio) + \previouspage quick-logic-helpers.html + \else + \previouspage quick-data-models.html + \endif + \nextpage quick-buttons.html - \section1 Using Qt Quick Animation Types + \title Animations To create an animation, use an appropriate animation type for the type of the property that is to be animated, and apply the animation depending on diff --git a/doc/qtcreator/src/qtquick/qtquick-components.qdoc b/doc/qtcreator/src/qtquick/qtquick-components.qdoc index 94912f038f9..0f7d989f6e4 100644 --- a/doc/qtcreator/src/qtquick/qtquick-components.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-components.qdoc @@ -36,51 +36,43 @@ \else \previouspage creator-using-qt-quick-designer.html \endif - \nextpage qtquick-form-editor.html + \nextpage quick-shapes.html \title Creating Components - A \l{glossary-component}{component} provides a way of defining a new visual item - that you can re-use in other QML files. A component is like a black box; it - interacts with the outside world through properties, signals, and slots, and - is generally defined in its own QML file. You can import components to - applications. + A \e component is a reusable building block for a UI. - The \uicontrol {Library} view lists the available QML types, UI - components, assets, and QML imports. + \QDS comes with \e {preset components} that you can use in your project. + These are similar to \e Symbols in Sketch or \e Prefab in Unity. - \image qmldesigner-qml-components.png "QML Components" + 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. - The \uicontrol {QML Types} tab displays the QML types grouped by category, - such as your own QML components, basic types, layouts, positioner types, and - views. + You can modify the \e properties of the preset components and combine them + to build your own components. - \section1 QML Imports + 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). - Sets of UI components with the look and feel of a particular mobile device - platform have been defined for Qt Quick 1. Since Qt 5.1, ready-made Qt - Quick Controls, Dialogs, and Layouts are available for creating user - interfaces using Qt Quick 2. The components and controls are based on - standard QML types. To view the components and controls in - \uicontrol {Library}, import the component sets in \uicontrol {QML Imports}. + The \l {Library} view \uicontrol Components tab lists the components that + have been added to your project. - The \uicontrol {Qt Quick Application} wizards for a particular platform add - the import statements automatically. You can remove import statements in - \uicontrol {QML Imports}. + \image qmldesigner-qml-components.png "Components" - \section1 Assets - - \uicontrol {Assets} displays the images and other files that you import to - the project folder by selecting \uicontrol {Add New Assets}. - - When you drag and drop assets from the tab to \uicontrol Navigator or - \uicontrol {Form Editor}, QML components with a suitable type are - automatically created for you. For example, when using graphical - assets to create components, the components will be of the Image type. + \note Use as few components as possible. 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 the time needed to load and build the application, + as well as the size of the application package. \section1 Adding Components to Designs - \image qmldesigner-editing-components.png "Editing QML components in Design mode" + \image qmldesigner-editing-components.png "Editing components in Form Editor" \list 1 \li Drag and drop components from \uicontrol Library (1) to @@ -102,7 +94,7 @@ \image qmldesigner-connections.png "Connections view Connections tab" \li To dynamically change the behavior of an object when another object changes, create bindings between components in the - \uicontrol Connections view, \uicontrol Bindings tab. + \uicontrol {Connection View}, \uicontrol Bindings tab. For more information, see \l{Adding Bindings Between Properties}. \image qmldesigner-bindings.png "Connections view Bindings tab" \li Add states to apply sets of changes to the property values of one @@ -112,71 +104,7 @@ For more information, see \l{Creating Animations}. \endlist - \section1 Component Types - - The following sections describe the types of components that you can create - in the Design mode. - - \list - \li \l Shapes - \li \l Text - \li \l Images - \li \l {User Interaction Methods} - \li \l {Lists and Other Data Models} - \if defined(qtdesignstudio) - \li \l {2D Effects} - \li \l {Logic Helpers} - \endif - \endlist - - \include qtquick-animation-types.qdocinc qtquick animation types - - \include qtquick-mcu-support.qdocinc mcu qtquick components - - \section1 Styling Controls - - Qt Quick Controls provide lightweight QML types for creating performant - user interfaces for \l{glossary-device}{devices}. The controls can be - \l {Styling Qt Quick Controls}{styled}. The visual editor reads the - \c qtquickcontrols2.conf file that specifies the preferred style and some - style-specific arguments. To change the style, select another style from - the list on the 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 QML types 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 Creating Components in Design Mode + \section1 Creating Your Own Components You can either use project wizard templates to create custom components and controls or \l{Moving Components into Separate Files}{move subcomponents @@ -196,20 +124,21 @@ \endif \uicontrol Choose to create a new .qml file. - \note Components are listed in the \uicontrol {My QML Components} + \note Components are listed in the \uicontrol {My Components} tab in the \uicontrol Library view only if the filename begins with a capital letter. - \li Click \uicontrol Design to open the .qml file in the Design mode. + \li Click \uicontrol Design to open the component file (ui.qml] in + \uicontrol {Form Editor}. - \li Drag and drop a QML type from \uicontrol Library to + \li Drag and drop a component from \uicontrol Library to \uicontrol Navigator or \uicontrol {Form Editor}. - \li Edit its properties in \uicontrol Properties. + \li Edit component properties in \uicontrol Properties. \image qmldesigner-custom-component-properties.png - The available properties depend on the QML type. You can + The available properties depend on the component type. You can \l{Specifying Dynamic Properties}{add properties for components} in the \uicontrol Properties tab of the \uicontrol {Connection View}. @@ -217,13 +146,16 @@ \endlist The following sections contain more information about how to use - \uicontrol {Form Editor} to edit 2D content, as well as examples of - how to create some common components using basic QML types: + \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 basic components: \list \li \l{Editing 2D Content} + \li \l{Working in 3D Editor}{3D Editor} + \li \l{Creating Buttons} \li \l{Creating Scalable Buttons and Borders} @@ -236,9 +168,9 @@ \section2 Moving Components into Separate Files - An alternative way of creating reusable components is to move them into - separate QML files. Right-click a component in the \uicontrol Navigator - or \uicontrol {Form Editor} view and select + An alternative way of creating reusable components is to move them + into separate component files (.ui.qml). Right-click a component + 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 @@ -246,6 +178,15 @@ 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 a + reference to the component is added to the code in the current component + file. The way things look 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 subcomponents, see \l{Moving Within Components}. + For an example of creating a reusable custom component, see \if defined(qtcreator) \l{Creating a Mobile Application}. @@ -253,31 +194,17 @@ \l{Progress Bar}. \endif - \section1 Moving Within Components + Custom components are listed in the \uicontrol {My Components} section + of the \uicontrol Components tab in \uicontrol Library and you can use + them to build more components. - The QML files that specify components can contain instances of other - components specified in separate QML files. You can open the QML file - that specifies a component in different ways from different views: - - \list - \li In \uicontrol {Form Editor} or \uicontrol Navigator, - right-click an instance of a component and then select - \uicontrol {Go into Component} in the context-menu or - press \key F2. - \li In \uicontrol Properties, select \uicontrol {Edit Master Component}. - \endlist - - The component hierarchy is displayed as a bread crumb path, where you can - click the component names to open the respective files. This enables you - to easily navigate back to the top level when you are done editing the - component. - - \image qmldesigner-breadcrumbs.png "Component hierarchy" + \include qtquick-mcu-support.qdocinc mcu qtquick components \section1 Merging Files with Templates - You can merge the current QML file against an existing second QML file and - using the second QML file in a way similar to using a CSS stylesheet. + You can merge the current component file against an existing second + component file and 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 diff --git a/doc/qtcreator/src/qtquick/qtquick-library.qdoc b/doc/qtcreator/src/qtquick/qtquick-library.qdoc new file mode 100644 index 00000000000..aaded8d48ac --- /dev/null +++ b/doc/qtcreator/src/qtquick/qtquick-library.qdoc @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-library.html + \if defined(qtdesignstudio) + \previouspage qtquick-form-editor.html + \else + \previouspage creator-using-qt-quick-designer.html + \endif + \nextpage qtquick-navigator.html + + \title Library + + The \uicontrol Library view lists the available components and assets. + + \section1 Components + + \image qtquick-components-tab.png "Library view Components tab" + + \uicontrol Components displays modules that have been added to your project. + The modules contain visual components, such as basic shapes, UI controls, + and 3D components, and add functionality to the project. All components have + a type. + + The UI controls can be styled to have the look and feel of a particular + operating system, such as \macOS, Windows, Android, or iOS. + + Some modules have no visible components. For example, the + \uicontrol {Qt.Multimedia} module adds support for audio and video + files to your UI. + + \section2 Component Types + + You can add the following types of components to your project: + + \list + \li \l Shapes + \li \l Text + \li \l Images + \li \l {User Interaction Methods} + \li \l {Lists and Other Data Models} + \if defined(qtdesignstudio) + \li \l {2D Effects} + \li \l {Logic Helpers} + \endif + \li \l Animations + \endlist + + For more information about creating your own components, see + \l{Creating Components}. + + \section2 Adding and Removing Modules + + When you create projects, modules typically needed in them are added by + default. For example, an empty application project contains only basic + components, while a 3D application project contains additional 3D + components. + + To add modules to the project, select \inlineimage plus.png + , and then select the module to add from the list of available + modules. + + \image qtquick-components-tab-add.png "Select Modules to Add" + + This adds an \e {import statement} to the component code that you + can see in \uicontrol {Text Editor}. For example, if you add the + \uicontrol QtQuick.Controls module, the following import statement + is added to the code: \c {import QtQuick.Controls}. + + You can search for components and modules by entering search criteria + in the \uicontrol Search field. + + The added components and modules are packaged with your UI into the final + application package, so it is recommended that you select + \uicontrol {Remove Module} to remove the ones you don't use in the project. + + \section1 Assets + + \uicontrol {Assets} displays the images and other files that you add to + the project folder by selecting \inlineimage plus.png + . + + \image qtquick-assets-tab.png "Library view Assets tab" + + When you drag and drop assets from the tab to \uicontrol Navigator + or \uicontrol {Form Editor}, components with a suitable type are + automatically created for you. For example, components of the + \l{Images}{Image} type will be created for graphics files. +*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-navigator.qdoc b/doc/qtcreator/src/qtquick/qtquick-navigator.qdoc index fc9e959d066..41559a292aa 100644 --- a/doc/qtcreator/src/qtquick/qtquick-navigator.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-navigator.qdoc @@ -142,5 +142,27 @@ the item into a new position. The topmost item under the cursor becomes the new parent of the item. + \section1 Moving Within Components + + The files that specify components (\c ui.qml, \c .qml) can contain + instances of other components specified in separate files. You can + open the file that specifies a component in different ways from + different views: + + \list + \li In \uicontrol {Form Editor} or \uicontrol Navigator, + right-click an instance of a component and then select + \uicontrol {Go into Component} in the context menu or + press \key F2. + \li In \uicontrol Properties, select \uicontrol {Edit Master Component}. + \endlist + + The component hierarchy is displayed as a bread crumb path, where you can + click the component names to open the respective files. This enables you + to easily navigate back to the top level when you are done editing the + component. + + \image qmldesigner-breadcrumbs.png "Component hierarchy" + \include qtquick-component-context-menu.qdocinc context-menu */ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-components.qdocinc b/doc/qtdesignstudio/src/qtdesignstudio-components.qdocinc index 94005e1be72..d0f7666b62b 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-components.qdocinc +++ b/doc/qtdesignstudio/src/qtdesignstudio-components.qdocinc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Design Studio documentation. @@ -36,12 +36,12 @@ \uicontrol {Files and Classes} > \uicontrol {Qt Quick Controls}. \li Select the control to create, and then select \uicontrol Choose. - \note Components are listed in the \uicontrol {My QML Components} + \note Components are listed in the \uicontrol {My Components} tab of the \uicontrol Library only if the filename begins with a capital letter. \li Edit component properties in the \uicontrol Properties view. - The available properties depend on the QML type. You can + The available properties depend on the component type. You can \l{Specifying Dynamic Properties}{add properties for components} in the \uicontrol Properties tab of the \uicontrol {Connection View}. \endlist diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index 8fa6babf59f..02af2c4b3f9 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -56,12 +56,13 @@ \li \l{User Interface} \list \li \l{Selecting Modes} - \endlist - \li \l{Editing QML Files in Design Mode} - \list + \li \l{Editing QML Files in Design Mode} + \list + \li \l{Library} + \endlist \li \l{Managing Workspaces} \li \l{Managing Sessions} - \endlist + \endlist \li \l{Tutorials} \li \l{Qt Quick Best Practices} \list @@ -93,6 +94,7 @@ \li \l{Lists and Other Data Models} \li \l{2D Effects} \li \l{Logic Helpers} + \li \l Animations \li \l{Creating Buttons} \li \l{Creating Scalable Buttons and Borders} \endlist diff --git a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc index 0d5b5e270f4..463a1358c95 100644 --- a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc @@ -26,7 +26,7 @@ /*! \page quick-logic-helpers.html \previouspage quick-2d-effects.html - \nextpage quick-buttons.html + \nextpage quick-animations.html \title Logic Helpers