diff --git a/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc b/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc index 27a7fb08de3..1f1f7162f10 100644 --- a/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc +++ b/doc/qtcreator/src/qtquick/library/qtquick-controls.qdoc @@ -293,6 +293,13 @@ \image qtquickcontrols2-button-flat.gif "Flat button" + \if definded(qtdesignstudio) + 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 item. For an example of using the + wizard template, see \l{Creating a Push Button}. + \endif + \section2 Delay Button \image qtquickcontrols2-delaybutton.gif "Delay button" diff --git a/doc/qtcreator/src/qtquick/qtquick-components.qdoc b/doc/qtcreator/src/qtquick/qtquick-components.qdoc index 20460bbe152..94912f038f9 100644 --- a/doc/qtcreator/src/qtquick/qtquick-components.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-components.qdoc @@ -125,6 +125,7 @@ \li \l {Lists and Other Data Models} \if defined(qtdesignstudio) \li \l {2D Effects} + \li \l {Logic Helpers} \endif \endlist diff --git a/doc/qtdesignstudio/images/icons/lc-and-operator-16px.png b/doc/qtdesignstudio/images/icons/lc-and-operator-16px.png new file mode 100644 index 00000000000..cc35051c894 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-and-operator-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-bidirectional-binding-16px.png b/doc/qtdesignstudio/images/icons/lc-bidirectional-binding-16px.png new file mode 100644 index 00000000000..8cbadb537c1 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-bidirectional-binding-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-min-max-16px.png b/doc/qtdesignstudio/images/icons/lc-min-max-16px.png new file mode 100644 index 00000000000..1f77ed3f545 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-min-max-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-not-operator-16px.png b/doc/qtdesignstudio/images/icons/lc-not-operator-16px.png new file mode 100644 index 00000000000..4453938ac64 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-not-operator-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-or-operator-16px.png b/doc/qtdesignstudio/images/icons/lc-or-operator-16px.png new file mode 100644 index 00000000000..092bbcdf54c Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-or-operator-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-range-mapper-16px.png b/doc/qtdesignstudio/images/icons/lc-range-mapper-16px.png new file mode 100644 index 00000000000..d4a830f2742 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-range-mapper-16px.png differ diff --git a/doc/qtdesignstudio/images/icons/lc-string-mapper-16px.png b/doc/qtdesignstudio/images/icons/lc-string-mapper-16px.png new file mode 100644 index 00000000000..34f41f7b310 Binary files /dev/null and b/doc/qtdesignstudio/images/icons/lc-string-mapper-16px.png differ diff --git a/doc/qtdesignstudio/images/studio-bidirectional-binding.gif b/doc/qtdesignstudio/images/studio-bidirectional-binding.gif new file mode 100644 index 00000000000..b0c3ebdae3b Binary files /dev/null and b/doc/qtdesignstudio/images/studio-bidirectional-binding.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-and-checkbox3.png b/doc/qtdesignstudio/images/studio-logic-helper-and-checkbox3.png new file mode 100644 index 00000000000..3b1c1120104 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-and-checkbox3.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-and-operator-multiselect.gif b/doc/qtdesignstudio/images/studio-logic-helper-and-operator-multiselect.gif new file mode 100644 index 00000000000..03c3455b3ca Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-and-operator-multiselect.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-and-operator.gif b/doc/qtdesignstudio/images/studio-logic-helper-and-operator.gif new file mode 100644 index 00000000000..4b74da7fbf2 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-and-operator.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-and.png b/doc/qtdesignstudio/images/studio-logic-helper-and.png new file mode 100644 index 00000000000..fff59d88817 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-and.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-bidirectional-binding.png b/doc/qtdesignstudio/images/studio-logic-helper-bidirectional-binding.png new file mode 100644 index 00000000000..db8f5c51177 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-bidirectional-binding.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-input.png b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-input.png new file mode 100644 index 00000000000..b9300d29969 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-input.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-string-mapper-input.png b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-string-mapper-input.png new file mode 100644 index 00000000000..13361cbf153 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper-string-mapper-input.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper.gif b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper.gif new file mode 100644 index 00000000000..b83d8942bf5 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-minmax-mapper.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-not-check-box.png b/doc/qtdesignstudio/images/studio-logic-helper-not-check-box.png new file mode 100644 index 00000000000..cc33e26e3de Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-not-check-box.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-not-operator.gif b/doc/qtdesignstudio/images/studio-logic-helper-not-operator.gif new file mode 100644 index 00000000000..7104d97610a Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-not-operator.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-not.png b/doc/qtdesignstudio/images/studio-logic-helper-not.png new file mode 100644 index 00000000000..e17d53d781b Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-not.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-inputmin.png b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-inputmin.png new file mode 100644 index 00000000000..1c2fad2f5da Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-inputmin.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-properties.png b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-properties.png new file mode 100644 index 00000000000..99b74ecd201 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper-properties.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-range-mapper.gif b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper.gif new file mode 100644 index 00000000000..81a4b9b8349 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-range-mapper.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-input.png b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-input.png new file mode 100644 index 00000000000..a910f0b5a43 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-input.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-text.png b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-text.png new file mode 100644 index 00000000000..99b0c308f33 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper-text.png differ diff --git a/doc/qtdesignstudio/images/studio-logic-helper-string-mapper.gif b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper.gif new file mode 100644 index 00000000000..6697b0ba6b0 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helper-string-mapper.gif differ diff --git a/doc/qtdesignstudio/images/studio-logic-helpers.png b/doc/qtdesignstudio/images/studio-logic-helpers.png new file mode 100644 index 00000000000..5b0feadc59a Binary files /dev/null and b/doc/qtdesignstudio/images/studio-logic-helpers.png differ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index e247aebb56c..8fa6babf59f 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -92,6 +92,7 @@ \li \l{User Interaction Methods} \li \l{Lists and Other Data Models} \li \l{2D Effects} + \li \l{Logic Helpers} \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 new file mode 100644 index 00000000000..a29fd7aa856 --- /dev/null +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-logic-helpers.qdoc @@ -0,0 +1,300 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page quick-logic-helpers.html + \previouspage quick-2d-effects.html + \nextpage quick-buttons.html + + \title Logic Helpers + + To have your UI perform certain operations, you might need to write + JavaScript expressions for conditions or convert numbers to strings. + \QDS attempts to make this easier by providing a set of components + called \e {Qt Quick Studio Logic Helpers} that you can import to your + project to make them available in the \uicontrol Library view. + + \image studio-logic-helpers.png "Logic Helper types in Library" + + Logic helpers are available for binding property values using the boolean + AND, NOT, and OR operators, as well as for mapping numbers and numerical + ranges. In addition, you can synchronize the property values of two + components bi-directionally. + + Logic helpers are invisible types that you can use in connection with + Qt Quick Controls, such as a \l {slider-control}{Slider} or \l {Check Box}. + To use a logic helper, drag-and-drop it from \uicontrol Library > + \uicontrol {Studio Logic Helper} to \uicontrol Navigator. The following + sections describe the different types of logic helpers in more detail. + + \section1 Boolean Helpers + + You can use logic helpers to bind property values using the boolean AND, OR, + and NOT operators. + + \section2 AND Operator + + The \uicontrol {And Operator} type evaluates two boolean inputs. + The output is evaluated as \c true if both inputs are \c true. + + For example, we could use the checked state of two check boxes to determine + the checked state of a third one. First we drag-and-drop three + \uicontrol {Check Box} types and an \uicontrol {And Operator} to + \uicontrol Navigator (1). Then we select the \uicontrol {And Operator} + component (2) and set its properties in \uicontrol Properties (3). + + We select \inlineimage icons/action-icon.png + next to the \uicontrol Input01 field to display the \uicontrol Actions + menu, and then \uicontrol {Set Binding} (4) to open the + \uicontrol {Binding Editor} (5). There we bind the value of the \c input01 + property of the AND operator to the value of the \c checked property of the + first check box. Then, we do the same in the \uicontrol Input02 field, where + we bind the \c input02 property to the \c checked property of the second + check box. + + \image studio-logic-helper-and.png "AND operator properties" + + Then, we select the first and second check box, and set their + \uicontrol Checked property to \c true in \uicontrol Properties. + We can multiselect the controls and make the change simultaneously + for both of them. + + \image studio-logic-helper-and-operator-multiselect.gif "Multiselecting check boxes and changing Checked property" + + Finally, we select the third check box and bind its \uicontrol Checked + property to the \uicontrol Output property of the AND operator. + + \image studio-logic-helper-and-checkbox3.png "Binding Checked property to Output property." + + When we \l{Previewing on Desktop}{preview} our UI, all the check boxes are + initially unchecked. However, when we select the first and second check box, + the third one also becomes checked. + + \image studio-logic-helper-and-operator.gif "Previewing AND operator" + + \section2 OR Operator + + The \uicontrol {Or Operator} type does the same as the AND operator, but + the output is \c true if one or both inputs are \c true. + + \section2 NOT Operator + + The \uicontrol {Not Operator} type is evaluated to \c true if the condition + is not met. + + For example, we could specify that if one check box is checked, another + one cannot be checked. First we drag-and-drop two \uicontrol {Check Box} + types and a \uicontrol {Not Operator} to \uicontrol Navigator. Then we + select \uicontrol {Not Operator} and set its properties in + \uicontrol Properties. In the \uicontrol {Binding Editor}, we bind the + value of the \c input property of the NOT operator to the value of the + \c checked property of the check box. + + \image studio-logic-helper-not.png "NOT operator properties" + + We then select the second check box and bind the value of its + \uicontrol Checked field to the value of of \uicontrol Output + field of the \uicontrol {Not Operator} component. + + \image studio-logic-helper-not-check-box.png "Check box checked property bound to NOT operator output" + + When we preview our UI, the second check box is initially checked. However, + when we select the first check box, the second one is automatically cleared. + + \image studio-logic-helper-not-operator.gif "Previewing two check boxes bound with a NOT operator" + + \section1 Bi-directional Binding + + The \uicontrol {Bi Direct. Binding} type binds the values of two controls + together, so that when one value is changed, the other one follows it. + This type could be used to synchronize two sliders or a slider and checkbox. + Typically, it is used to bind a backend value to a control, such as a + slider. + + For example, to synchronize the values of two sliders, drag and drop two + \uicontrol Slider components and one \uicontrol {Bi Direct. Binding} + component to the same parent component in \uicontrol Navigator. Then select + the bi-directional binding and set its properties in \uicontrol Properties. + + \image studio-logic-helper-bidirectional-binding.png "Bi-directional binding properties" + + In the \uicontrol {Target 01} and \uicontrol {Target 02} fields, enter + the ids of the components that you want to bind together. In the + \uicontrol {Property 01} and \uicontrol {Property 02} fields, enter the + names of the properties to synchronize. In our example, we bind the + \c value property of two slider components together, so that when we move + one slider handle in the preview, the other one moves along with it. + + \image studio-bidirectional-binding.gif "Previewing a bi-directional binding of two sliders" + + If you want to add a text field that displays the value of the slider, you + can use a \l {String Mapper} component. + + \section1 String Mapper + + The \uicontrol {String Mapper} type maps numbers to strings. First you + \l{Adding Bindings Between Properties}{add a binding} between the string + mapper \c input property and the \c value property of the control that you + want to fetch the values from. Then, you add a binding between the \c text + property of the string mapper and that of the component that will display + the string. + + For example, to use a \l Text component to display the value of a + slider, we drag and drop \uicontrol Text, \uicontrol Slider, and + \uicontrol {String Mapper} components to the same parent item. Then + we select \uicontrol {String Mapper} in \uicontrol Navigator to display + its properties in \uicontrol Properties. There we bind the value of the + \c input property of the string mapper to the value of the \c value + property of the slider. + + \image studio-logic-helper-string-mapper-input.png "Binding slider value property to string mapper" + + Next, we bind the value of the \uicontrol Text field of the + \uicontrol Text component to the value of the \uicontrol Text + field of the \uicontrol {String Mapper} component. + + \image studio-logic-helper-string-mapper-text.png "Binding text property value to string mapper" + + When we move the slider handle in the preview, the value displayed in the + text component changes accordingly. + + \image studio-logic-helper-string-mapper.gif "Previewing text property binding to string mapper" + + The value of the \uicontrol Decimal field determines the number of digits + after the decimal separator. + + \section1 Minimum-Maximum Mapper + + The \uicontrol {Min Max Mapper} type has output values even if the input + value is out of range or too small or big. This enables you to apply + actions to values even if they are out of range, such as changing a color + in a state. + + To access the values of a control, bind the \c input property of the + minimum-maximum mapper to that of the \c value property of the control. + + For example, to restrict the maximum value of a slider to 0.60, + regardless of the maximum value set in the slider properties, + we drag and drop a \uicontrol {Min Max Mapper} to our example + above. We select it to display its properties in \uicontrol Properties. + Then, we bind the value of the \c input property of the mapper to + the value of the \c value property of the slider and set the value + of the \uicontrol Max field to 0.60. + + \image studio-logic-helper-minmax-mapper-input.png "Binding slider value property to string mapper" + + To have the maximum value displayed by the \l Text component, we select + the \uicontrol {String Mapper} component and change the binding we set + as the value of the \uicontrol Input field from \c slider.value to + \c minMaxMapper.value. + + \image studio-logic-helper-minmax-mapper-string-mapper-input.png "Binding string mapper input to min max mapper" + + When we move the slider handle in the preview, it only moves up to the + value 0.60. + + \image studio-logic-helper-minmax-mapper.gif "Previewing a minimum-maximum mapper" + + The \uicontrol OutOfRange, \uicontrol MaxClipped and \uicontrol MinClipped + check boxes are set to \c true if the value of the \uicontrol Input field + is out of range. + + For example, in the context of speed, \uicontrol MaxClipped being \c true + would mean \e {too fast}, whereas \uicontrol MinClipped being \c true, would + mean \e {too slow}, and \uicontrol OutOfRange being \c true would mean + \e {either too fast or too slow}. + + \section1 Range Mapper + + The \uicontrol {Range Mapper} type maps a numerical range to another range, + so that the output value of the second range follows the input value of the + original range. This is useful when remapping the current frame on the + timeline, for example. + + \image studio-logic-helper-range-mapper-properties.png "Range Mapper properties" + + Specify the minimum and maximum input and output values in the + \uicontrol InputMin, \uicontrol InputMax, \uicontrol OutputMin, + and \uicontrol OutputMax fields and the original value in the + \uicontrol Value field. + + For example, we can specify that the values of a slider range from -1 to 1. + If we want to display values from 10 to 1000, instead, we can bind the + values of the \uicontrol From and \uicontrol To fields of the \l Slider + type to the values of the \uicontrol InputMin and \uicontrol InputMax + fields of a \uicontrol {Range Mapper} type. We then set the value of the + \uicontrol OutputMin field to 10 and the value of the \uicontrol OutputMax + field to 1000. + + \image studio-logic-helper-range-mapper-inputmin.png "Binding range mapper minimum input to slider.from property" + + When we move the slider handle in the preview, so that the input value + from the \l Slider type changes from -1 to 1, the output value changes + from 10 to 1000. + + \image studio-logic-helper-range-mapper.gif "Previewing a range mapper" + + \section1 Summary of Logic Helpers + + The following table summarizes the available effects and contains links to + the documentation of the inherited QML type. + + \table + \header + \li Icon + \li Qt Quick Studio Effect + \li Description + \row + \li \inlineimage icons/lc-and-operator-16px.png + \li And Operator + \li Boolean AND. + \row + \li \inlineimage icons/lc-bidirectional-binding-16px.png + \li Bi Direct. Binding + \li A bi-directional binding that binds two values in both directions + and keeps them in sync. + \row + \li \inlineimage icons/lc-min-max-16px.png + \li Min Max Mapper + \li Maps a number to another number with a minimum and maximum value. + \row + \li \inlineimage icons/lc-not-operator-16px.png + \li Not Operator + \li Boolean NOT. + \row + \li \inlineimage icons/lc-or-operator-16px.png + \li Or Operator + \li Boolean OR. + \row + \li \inlineimage icons/lc-range-mapper-16px.png + \li Range Mapper + \li Maps a numerical range to another range, so that the output value + of the second range follows the input value of the original range. + \row + \li \inlineimage icons/lc-string-mapper-16px.png + \li String Mapper + \li Maps a number to a string with the defined precision. + \endtable +*/ diff --git a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc index dd56ac8855e..1476e3e2879 100644 --- a/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc +++ b/doc/qtdesignstudio/src/qtquickdesigner-components/qtdesignstudio-visual-effects.qdoc @@ -26,7 +26,7 @@ /*! \page quick-2d-effects.html \previouspage quick-data-models.html - \nextpage quick-buttons.html + \nextpage quick-logic-helpers.html \title 2D Effects