// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \previouspage qmldesigner-connections.html
    \page quick-signals.html
    \nextpage quick-property-bindings.html

    \title Connecting components to signals

    A signal and handler mechanism enables components to respond to application
    events, which are represented by \e signals. When a signal is emitted, the
    corresponding \e {signal handler} is invoked to respond to the event by
    using scripts or other operations placed in the handler.

    To receive a notification when a particular signal is emitted for a
    particular component, the component definition should declare a signal handler
    named \e {on<Signal>} where \e {<Signal>} is the name of the signal, with
    the first letter capitalized. The signal handler should contain the
    JavaScript code to be executed when the signal handler is invoked.

    Components have predefined signals that are emitted when users interact with
    the application. For example, the \l {Mouse Area} component has a \c clicked
    signal that is emitted whenever the mouse is clicked within the area. Since
    the signal name is \c clicked, the signal handler for receiving this signal
    is named \c onClicked.

    A signal is automatically emitted when the value of a property changes.
    This type of signal is a \e{property change signal} and signal handlers
    for these signals are written in the form \c on<Property>Changed, where
    \e <Property> is the name of the property, with the first letter
    capitalized.

    For example, the Mouse Area component has a \c pressed property. To receive
    a notification whenever this property changes, you would use a signal handler
    called \c onPressedChanged.

    For more information about signals and signal handlers, see
    \l{Signal and Handler Event System}.

    \section1 Connecting components to signals in the Connection view

    You can connect components to signals that are available to them in
    \uicontrol Connections. Then define \uicontrol Action for them. You can
    put \b {logical conditions} on this \uicontrol Actions to control them
    according to your needs.

    \image {qmldesigner-connections-advanced.webp} {The Connections tab in the Connections view.}

    Initiate a new connection for a component:

    \list 1
        \li Select the component you want to connect in the \uicontrol Navigator or \uicontrol 2D
        view.
        \li Go to the \uicontrol Connections tab in the \uicontrol Connections view.
        \li Select the \imageplus
            (\uicontrol Add) button to add a connection.
    \endlist

    \image {qmldesigner-connections-editor.webp} {The Add Connection dialog.}

    Connect component \uicontrol Signal to \uicontrol Action:

    \list 1
        \li Select the interaction \uicontrol Signal for the \uicontrol Target component with
            which you want to connect an \uicontrol Action.
        \li Select an \uicontrol Action that you want to implement when the selected
            \uicontrol Signal for the \uicontrol Target component is initiated.
        \li You get different properties or sub-sections associated with the selected
            \uicontrol Action. Select \uicontrol {Item/Method/State/Property/Value} from related
            sub-sections. This way you can formulate changes in the design by manipulating
            components.
        \li Select \uicontrol {Add Condition} to include a logic to the selected \uicontrol Action.
            To do this, you can first select the component you want to put logic on, and then
            select the conditional statements \e {(AND, OR, EQUAL, NOT EQUAL, GREATER, LESS,
            GREATER OR EQUAL, LESS OR EQUAL)} and then select another component to compare
            between them.
        \li Optional. You can include an \uicontrol {Else Statement} by selecting the
            \uicontrol {Else Statement} control and adding components and conditional
            statements in a similar way to the previous step.
        \li Optional. To use complex conditional statements, select the \uicontrol {Manual Edit}
            control. After you have entered your JavaScript statements, close the window to apply
            them.
    \endlist

    \note Select a connection to re-open the \uicontrol {Connection Editor} for any
        previously created \uicontrol Connection.
    \note Select \imageminus
          (\uicontrol Remove) to delete a connection.


    \section1 Actions and conditions

    You use the \uicontrol {Connection Editor} to create the JavaScript
    expressions for \e actions with \e conditions. An \e action connects
    a component to a signal, whereas \e conditions fetch property values
    from other components and compare them to each other. Based on that, you can later change
    the components with JavaScript expressions.

    For more information about the logical operators that you can use to
    construct conditional expressions, see \l {Summary of Logical Operators}.

    \section2 Creating JavaScript expressions

    To create JavaScript expressions for actions, do one of the following:

    \list
      \li Follow the steps described above in Connect component \uicontrol Signal to
          \uicontrol Action. For a list of \uicontrol Actions and their properties, see
          \l {Action Properties}.
          \image {qmldesigner-connections-ConditionalAction-Autometic.webp} {The Add Connection dialog with a JavaScript expression.}
      \li Open the \uicontrol {Manual Code Edit} window from the
          \uicontrol {Connections} view and write JavaScript expressions with components
          and logical expressions manually.

          \note If you create a conditional expression by selecting options from the
            drop-down menus in the \uicontrol {Connection} view, you can only create a single
            level \e {if-else} expression. For nested level \e {if-else} expressions,
            use the \uicontrol {Manual Code Edit}.

        \image {qmldesigner-connections-ConditionalAction-Manual.webp} {A JavaScript code snippet in the Manual Code Edit dialog.}
    \endlist

    \section2 Action properties

    \table
        \header
            \li Action
            \li 1st property
            \li 2nd property
        \row
            \li \uicontrol {Call Function}
            \li \uicontrol {Item}: [Sets the component that is affected by the action of the
                \b Target component's \b Signal.]
            \li \uicontrol {Method}: [Sets the item component's method that is affected by the
                \b Target component's \b Signal.]
        \row
            \li \uicontrol {Assign}
            \li \uicontrol {From}: [Sets the component and its property from which the value
                is copied when the \b Target component initiates the \b Signal.]
            \li \uicontrol {To}: [Sets the component and its property to which the copied value
                is assigned when the \b Target component initiates the \b Signal.]
        \row
            \li \uicontrol {Change State}
            \li \uicontrol {State Group}: [Sets a \b {State Group} that is accessed when the
                \b Target component initiates the \b Signal.]
            \li \uicontrol {State}: [Sets a \b State within the assigned \b {State Group}
                that is accessed when the \b Target component initiates the \b Signal.]
        \row
            \li \uicontrol {Set Property}
            \li \uicontrol {Item}: [Sets the component that is affected by the action
                of the \b Target component's \b Signal.]
            \li \uicontrol {Property}: [Sets the property of the component that is
                affected by the action of the \b Target component's \b Signal.]
        \row
            \li \uicontrol {Print Message}
            \li \uicontrol {Message}: [Sets a text that is printed when the \b Signal
                of the \b Target component initiates.]
            \li N/A
    \endtable

    Watch this video for practical examples of the \uicontrol {Connection} view workflow:
    \youtube KDxnMQzgmIY

*/
