diff --git a/doc/qtcreator/images/qmldesigner-bindings.png b/doc/qtcreator/images/qmldesigner-bindings.png index 32ccc569074..ad7dde04b7a 100644 Binary files a/doc/qtcreator/images/qmldesigner-bindings.png and b/doc/qtcreator/images/qmldesigner-bindings.png differ diff --git a/doc/qtcreator/images/qmldesigner-connections.png b/doc/qtcreator/images/qmldesigner-connections.png index 950c804306b..827359bf497 100644 Binary files a/doc/qtcreator/images/qmldesigner-connections.png and b/doc/qtcreator/images/qmldesigner-connections.png differ diff --git a/doc/qtcreator/images/qmldesigner-custom-component-properties.png b/doc/qtcreator/images/qmldesigner-custom-component-properties.png index b935f941325..9fbb8b7901d 100644 Binary files a/doc/qtcreator/images/qmldesigner-custom-component-properties.png and b/doc/qtcreator/images/qmldesigner-custom-component-properties.png differ diff --git a/doc/qtcreator/images/qmldesigner-dynamicprops.png b/doc/qtcreator/images/qmldesigner-dynamicprops.png index 82cd304888b..fc321c4c7e2 100644 Binary files a/doc/qtcreator/images/qmldesigner-dynamicprops.png and b/doc/qtcreator/images/qmldesigner-dynamicprops.png differ diff --git a/doc/qtcreator/images/qmldesigner-editing-components.png b/doc/qtcreator/images/qmldesigner-editing-components.png index 1fe80e23c11..e7a7d21fe7e 100644 Binary files a/doc/qtcreator/images/qmldesigner-editing-components.png and b/doc/qtcreator/images/qmldesigner-editing-components.png differ diff --git a/doc/qtcreator/images/qmldesigner-properties-view.png b/doc/qtcreator/images/qmldesigner-properties-view.png index 36c2e9ca15d..eb9cf6356f3 100644 Binary files a/doc/qtcreator/images/qmldesigner-properties-view.png and b/doc/qtcreator/images/qmldesigner-properties-view.png differ diff --git a/doc/qtcreator/images/qmldesigner-qml-components.png b/doc/qtcreator/images/qmldesigner-qml-components.png index 46918eee924..209d6fe0afe 100644 Binary files a/doc/qtcreator/images/qmldesigner-qml-components.png and b/doc/qtcreator/images/qmldesigner-qml-components.png differ diff --git a/doc/qtcreator/images/qtcreator-move-component-into-separate-file.png b/doc/qtcreator/images/qtcreator-move-component-into-separate-file.png index 3e444ab1bd5..fe946a3303f 100644 Binary files a/doc/qtcreator/images/qtcreator-move-component-into-separate-file.png and b/doc/qtcreator/images/qtcreator-move-component-into-separate-file.png differ diff --git a/doc/qtcreator/src/qtquick/qtquick-component-context-menu.qdocinc b/doc/qtcreator/src/qtquick/qtquick-component-context-menu.qdocinc index 149077c6497..3132605f1d4 100644 --- a/doc/qtcreator/src/qtquick/qtquick-component-context-menu.qdocinc +++ b/doc/qtcreator/src/qtquick/qtquick-component-context-menu.qdocinc @@ -76,8 +76,8 @@ \li Merge File with Template \li \l{Merging Files with Templates} \row - \li Move Component into Separate File - \li \l{Moving Components into Separate Files} + \li Move Component Instances into Separate Files + \li \l{Moving Component Instances into Separate Files} \row \li Add New Signal Handler \li \l{Adding Signal Handlers} diff --git a/doc/qtcreator/src/qtquick/qtquick-components.qdoc b/doc/qtcreator/src/qtquick/qtquick-components.qdoc index 5e76c0068f2..bce279787bf 100644 --- a/doc/qtcreator/src/qtquick/qtquick-components.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-components.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. @@ -42,73 +42,84 @@ A \e component is a reusable building block for a UI. - \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. + \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. + as spin boxes or sliders. You can also add instances of preset + \l {Using 3D Components}{3D components} to your UIs. - You can modify the \e properties of the preset components and combine them - to build your own components. + 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). + 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{Moving Component Instances into Separate Files} + {move component instances into separate component files}. - The \l {Library} view \uicontrol Components tab lists the components that - have been added to your project. + 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 qmldesigner-qml-components.png "Components" + \image qtquick-components-tab.png "Components in Library" \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. + instances. Using component instances instead of duplicating the components + reduces the time needed to load and build the application, as well as the + size of the application package. - \section1 Adding Components to Designs + \section1 Creating Component Instances - \image qmldesigner-editing-components.png "Editing components in Form Editor" + \image qmldesigner-editing-components.png "Creating Component Instances" \list 1 - \li Drag and drop components from \uicontrol Library (1) to - \uicontrol Navigator (2) or \uicontrol {Form Editor} (3). - \li Select components in \uicontrol Navigator to edit the + \li Drag-and-drop components from \uicontrol Library (1) to + \uicontrol Navigator (2), \uicontrol {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 your components in ways - that are not supported out of the box, you can define custom - properties for your components in the \uicontrol Connections view, - \uicontrol Properties tab. - \image qmldesigner-dynamicprops.png "Connections view Properties tab" + \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}. + \image qmldesigner-dynamicprops.png "Connection View Properties tab" For more information, see \l{Specifying Dynamic Properties}. - \li To enable users to interact with components, connect the components - to signals in the \uicontrol Connections view. For example, you can - specify what happens when a component is clicked. - For more information, see \l{Connecting Components to Signals}. - \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 {Connection View}, \uicontrol Bindings tab. + \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 "Connections view Bindings tab" + \image qmldesigner-bindings.png "Connection View Bindings tab" \li Add states to apply sets of changes to the property values of one - or several components in the \uicontrol States view. + or several component instances in the \uicontrol States view. For more information, see \l{Adding States}. - \li Animate component properties in the \uicontrol Timeline view. - For more information, see \l{Creating Animations}. + \li Animate the properties of component instances in the \uicontrol + Timeline view. For more information, see \l{Creating Animations}. \endlist \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 - into separate files} to make them reusable in other components. + 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. \section2 Creating Components from Scratch @@ -128,27 +139,30 @@ tab in the \uicontrol Library view only if the filename begins with a capital letter. - \li Click \uicontrol Design to open the component file (ui.qml] in + \li Click \uicontrol Design to open the component file (ui.qml) in \uicontrol {Form Editor}. - \li Drag and drop a component from \uicontrol Library to + \li Drag-and-drop a component from \uicontrol Library to \uicontrol Navigator or \uicontrol {Form Editor}. - \li Edit component properties in \uicontrol Properties. - + \li Edit component properties in the \uicontrol Properties view. \image qmldesigner-custom-component-properties.png 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}. + 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 basic components: + using instances of basic components: \list @@ -166,26 +180,26 @@ \include qtdesignstudio-components.qdocinc creating studio components \endif - \section2 Moving Components into Separate Files + \section2 Moving Component Instances into Separate Files - 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 + An alternative way of creating reusable components is to move component + instances 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 + 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. + 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 + 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}. + additional ways of opening base components, see \l{Moving Within Components}. For an example of creating a reusable custom component, see \if defined(qtcreator) @@ -194,17 +208,17 @@ \l{Progress Bar}. \endif - 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. + 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 and using the second file in a way similar to using a - CSS stylesheet. + 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 diff --git a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc index dc651b68cba..b4297871abd 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc @@ -78,7 +78,7 @@ \list \li \l{Creating Components}{Library} \li \l{Component Types}{Preset Components} - \li \l{Adding Components to Designs}{My Components} + \li \l{Creating Component Instances}{My Components} \endlist \section1 Device