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

/*!
    \example Loginui3
    \ingroup gstutorials

    \title Login UI: States
    \brief Illustrates how to use states to create a second UI page.
    \previouspage {Login UI: Positioning}
    \nextpage {Login UI: Timeline}

    \image loginui3.gif "Login UI"

    \e{Login UI: States} is the third in a series of tutorials that build
    on each other to illustrate how to use \QDS to create a simple UI with
    some basic UI components, such as pages, buttons, and entry fields. The
    third tutorial in the series describes how to use \e states to add a
    second page to the UI. On the first page, users can enter a username
    and password to log in. On the second page, they can register as users if they
    do not already have an account.

    Because the second page will contain most of the same UI components as the
    login page, you will use \e states to show and hide UI components as necessary
    when a user selects the \e {Create Account} button.

    The starting point for this tutorial is the completed
    \l{Login UI: Positioning} project. You can download the project
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui2}{here}.

    Additionally, you can download the completed project of this tutorial
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui3}{here}.

    For more information, see \l{Working with states} and \l{Signal and Handler Event System}.

    \section1 Adding UI components

    You will add another entry field for verifying the password that users
    enter to create an account. You are already familiar with the tasks in
    this section from the previous \e {Login UI} tutorials.

    To preview the changes that you make, select the \uicontrol {Live Preview} button
    or select \key {Alt+P}.

    To add the entry field needed on the second page to the \e Screen01
    component:

    \list 1
        \li Double-click \e Screen01.ui.qml in \uicontrol Projects to open it
            in the \uicontrol {2D} view.
        \li Drag an instance of the EntryField component from
            \uicontrol Components > \uicontrol {My Components} to \e fields in
            \l Navigator.
        \li Select the EntryField instance in \uicontrol Navigator to modify
            its ID and text in \uicontrol Properties.
        \li In \uicontrol Component > \uicontrol ID, enter
            \e repeatPassword.
        \li In \uicontrol {EntryField} > \uicontrol {Button Content} > \uicontrol Text,
            enter \e {Repeat Password} and select \uicontrol tr to mark the text
            translatable.
            \image loginui3-new-entryfield-properties.webp "Entryfield properties"
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    \e Screen01 should now look something like this in the
    \uicontrol {2D} view:

    \image loginui3-base-state.webp "Login page with a Repeat Password field"

    Next, you will add states for the login page and the account creation page,
    where you use the visibility property to hide the \e {Repeat Password} field on
    the login page and the \e {Create Account} button on the account creation
    page.

    \section1 Using states to simulate page changes

    You will now add \l{Working with states}{states} to the UI to show and hide UI
    components in the \uicontrol {2D} view, depending on the current page:

    \list 1
        \li In the \l States view, select \imageplus
        .
        \li Enter \e login as the state name.
            \image loginui3-login-state.webp "States view"
        \li Select \e repeatPassword in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In the \uicontrol Visibility section, clear the
            \uicontrol Visible checkbox to hide the \e {Repeat Password} field in the login state.
            \image loginui3-visibility.png
        \li In \uicontrol States, select \uicontrol Default for \e login to determine that the
            \e login state is applied when the application starts.
        \li With the base state selected, add another state and name it
            \e createAccount. This state should now look identical to the base
            state.
        \li Select the \e createAccount button in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol Visibility, clear the \uicontrol Visible checkbox
            to hide the \e {Create Account} button in the account creation
            state.
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    You can now see all the states in the \uicontrol States view:

    \image loginui3-states.webp "All states in the States view"

    The live preview displays the default state, \e login:

    \image loginui3-login-state-preview.webp "Preview of the login state"

    Next, you will create connections to specify that clicking the
    \e {Create Account} button on the login page triggers a
    transition to the account creation page.

    \section1 Connecting buttons to states

    Components have predefined signals that are emitted when users interact
    with the UI. The \e PushButton component contains a \l{Mouse Area} component
    that has a \e clicked signal. The signal is emitted whenever the mouse
    is clicked within the area.

    You will now use the \l {Connections} view to
    \l{Connecting components to signals}{connect} the clicked signal of the
    \e createAccount button to \e createAccount state:

    \list 1
        \li Select \uicontrol View > \uicontrol Views >
            \uicontrol {Connections} to open the \uicontrol Connections view.
        \li Select \e createAccount in \uicontrol Navigator.
        \li In the \uicontrol Connections tab, select the \imageplus
            button to open the connection setup options.
        \li Set \uicontrol Signal to \c clicked, \uicontrol Action to
            \c {Change State}, \uicontrol {State Group} to \c rectangle, and
            \uicontrol State to \c createAccount in the respective
            drop-down menus.
        \li Select the \imageclose
            button to close the connection setup options.

        \image loginui3-connections.webp "Connections tab"

        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.

            \note Alternatively, right-click the \e createAccount button in
            \uicontrol Navigator. Then select \uicontrol {Connections} >
            \uicontrol {Add new Connection} > \uicontrol {clicked} >
            \uicontrol {Change State to createAccount}.
    \endlist

    In the live preview, you can now select the \e {Create Account}
    button to go to the account creation page.

    \image loginui3.gif "Moving between login page and account creation page"

    \section1 Next steps

    To learn how to use a timeline to animate the transition between the login
    and account creation pages, see the next tutorial in the series,
    \l {Login UI: Timeline}.
*/
