Doc: Add docs for Studio Logic Helper types

Task-number: QDS-3248
Change-Id: I348d82be4a9a5574046cd590b07e711eb862d2ec
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>

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"

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
 

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

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
+*/

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