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