/****************************************************************************
**
** Copyright (C) 2021 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.
**
****************************************************************************/

/*!
    \example loginui3
    \ingroup studioexamples
    \ingroup gstutorials

    \title Log In UI - Part 3
    \brief Illustrates how to use states to create a second UI page.
    \previouspage {Log In UI - Part 2}
    \nextpage {Log In UI - Part 4}

    \image loginui3.gif "Log In UI"

    \e{Log In UI - Part 3} 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. Part 3
    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 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 \uicontrol {Create Account} button.

    These instructions build on:

    \list
        \li \l {Log In UI - Part 1}
        \li \l {Log In UI - Part 2}
    \endlist

    The \e {Learn More} sections provide additional information relevant to the
    task at hand.

    \section1 Adding UI Components

    You will add another text field for verifying the password that users
    enter to create an account and a back button for returning to the login
    page. You are already familiar with the tasks in this section from Part 1
    and Part 2 of this tutorial.

    To preview the changes that you make to the UI while you make
    them, select the \inlineimage live_preview.png
    (\uicontrol {Show Live Preview}) button on the \l {Form Editor}
    toolbar or press \key {Alt+P}.

    To add the text field and a back button needed on the registration page
    to the \e Screen01 component:

    \list 1
        \li Open \e {Screen01.ui.qml} in \uicontrol {Form Editor} for editing.
        \li Drag-and-drop a \uicontrol {Text Field} from \l Library
            > \uicontrol Components > \uicontrol {Qt Quick Controls} to
            \e fieldColumn in \l Navigator.
        \li In \l Properties, change the ID of the text field to
            \e verifyPasswordField.
        \li In the \uicontrol Geometry group, \uicontrol Size field, set the
            width of the field to \e 300 pixels to match the size of the
            existing fields.
        \li In the \uicontrol Placeholder field, set the placeholder text to
            \e {Verify password} and mark the text translatable.
        \li Drag-and-drop a PushButton component from \uicontrol Library >
            \uicontrol Components > \uicontrol {My Components} to the root
            rectangle in \uicontrol Navigator.
        \li Select the button in \uicontrol Navigator and change its ID to
            \e backButton in \uicontrol Properties.
        \li In the \uicontrol Geometry group, \uicontrol Size field, set the
            button width to \e 40 pixels to create a small round button.
        \li In the \uicontrol Text field, enter \e <.
        \li In the \uicontrol Font group, \uicontrol Size field, set the font
            size to \e 24 pixels.
        \li Under \uicontrol Layout, select the \inlineimage icons/anchor-top.png
            (\uicontrol Top) and \inlineimage icons/anchor-right.png
            (\uicontrol Right) anchor buttons to anchor \e backButton to
            the top right corner of its parent with 20- and 10-pixel margins,
            respectively.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    \e Screen01 should now look something like this in the \uicontrol Design
    mode and live preview:

    \image loginui3-base-state.png "Login page with new UI components"

    Next, you will add states for the login page and the registration page,
    where you use the visibility property to hide the password verification
    field and the back button on the login page and the login button on the
    registration page.

    \section1 Using States to Simulate Page Changes

    You will now add \l{Adding States}{states} to the UI to show and hide UI
    components in the \uicontrol {Form Editor}, depending on the current page:

    \list 1
        \li In the \l States view, select \uicontrol {Create New State}.
            \image loginui3-login-state.png "States view"
        \li Enter \e loginState as the state name.
        \li Select \e verifyPasswordField in the \uicontrol Navigator,
            and deselect the \uicontrol Visibility check box in
            \uicontrol Properties to hide the verify password field in
            the login state.
            \image loginui3-visibility.png
        \li Repeat the above step for \e backButton to hide it, too.
        \li In \uicontrol States, select \inlineimage icons/action-icon.png
            for \e loginState to open the \uicontrol Actions menu, and then
            select \uicontrol {Set as Default} to determine that \e loginState
            is applied when the application starts.
        \li With the base state selected, add another state and name it
            \e registerState. This state should now look identical to the base
            state.
        \li Select \e loginButton in the \uicontrol Navigator, and deselect
            the \uicontrol Visibility check box in \uicontrol Properties to
            hide the login button in the registration state.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    You can now see all the states in the \uicontrol States view. The live
    preview displays the default state, \e loginState:

    \image loginui3-states.png "States view"

    \section2 Learn More - States

    The \l{Adding States}{state} of a particular visual component is the set of
    information which describes how and where the individual parts of the visual
    component are displayed within it, and all the data associated with that
    state. Most visual components in a UI will have a limited number of states,
    each with well-defined properties.

    For example, a list item may be either selected or not, and if
    selected, it may either be the currently active single selection or it
    may be part of a selection group. Each of those states may have certain
    associated visual appearance (neutral, highlighted, expanded, and so on).

    Youn can apply states to trigger behavior or animations. UI components
    typically have a default state that contains all of a component's initial
    property values and is therefore useful for managing property values before
    state changes.

    You can specify additional states by adding new states. Each state within a
    component has a unique name. To change the current state of an component,
    the state property is set to the name of the state. State changes can be
    bound to conditions by using the \c when property.

    Next, you will create connections to specify that clicking the
    \uicontrol {Create Account} button on the login page triggers a
    transition to the registration page and that clicking the back
    button on the registration page triggers a transition to the login
    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 \l {Connection View} to
    \l{Connecting Components to Signals}{connect} the clicked signal of
    \e registerButton to \e registerState and that of \e backButton
    to \e loginState:

    \list 1
        \li Select \uicontrol View > \uicontrol Views >
            \uicontrol {Connection View} to open the \uicontrol Connections tab.
        \li Select \e registerButton in the \uicontrol Navigator.
        \li In the \uicontrol Connections tab, select the \inlineimage plus.png
            button to add the action that the \c onClicked signal handler of
            \e registerButton should apply.
        \li Double-click the value \uicontrol Action column and select
            \uicontrol {Change state to registerState} in the drop-down menu.
        \li Repeat the steps above to connect \e backButton to \e loginState
            by selecting \uicontrol {Change state to loginState} in the last
            step.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    You can now see the following connections in the \uicontrol Design mode:

    \image loginui3-connections.png "Connections tab"

    In the live preview, you can now click the \uicontrol {Create Account}
    button to go to the registration page and the back button to return to
    the login page.

    \image loginui3.gif "Moving between login page and registration page"


    \section2 Learn More - Signal and Event Handlers

    UI components need to communicate with each other. For example, a button
    needs to know that the user has clicked on it. In response, the button may
    change color to indicate its state and perform an action.

    A \e {signal-and-handler} mechanism is used, where the \e signal is the
    event that is responded to through a \e {signal handler}. When a signal is
    emitted, the corresponding signal handler is invoked. Placing logic, such
    as a script or other operations, in the handler allows the component to
    respond to the event.

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

    \section1 Next Steps

    For a more complicated UI, you would typically use components that specify
    a view of items provided by a model, such as a \l{List and Grid Views}
    {List View} or \l StackView. For more information, see
    \l{Lists and Other Data Models}.

    To learn how to use a timeline to animate the transition between the login
    and registration pages, see the next tutorial in the series,
    \l {Log In UI - Part 4}.
*/
