/****************************************************************************
**
** 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 loginui2
    \ingroup studioexamples
    \ingroup gstutorials
    \previouspage {Log In UI - Part 1}
    \nextpage {Log In UI - Part 3}

    \title Log In UI - Part 2
    \brief Illustrates how to position UI components on pages using anchors and
    positioners.

    \image loginui2.png "Log In UI"

    \e{Log In UI - Part 2} is the second 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 2
    describes how to position the UI components on pages to create a scalable
    UI.

    To ensure that the layout is responsive and all the UI components stay in
    their proper places when you resize the UI on the desktop or on devices
    with different screen sizes, you will use anchors and positioners.

    These instructions build on \l {Log In UI - Part 1}.

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

    \section1 Anchoring UI Components

    First, you will \l {Setting Anchors and Margins}{anchor} the static page
    elements, logo image (\e logo) and page title (\e pageTitle), to the page.
    When you created the project using the new project wizard template
    in Part 1 of this tutorial, the wizard template anchored \e pageTitle to the
    vertical and horizontal center of the page. Therefore, you will only
    need to replace the vertical anchor of \e pageTitle with a top anchor
    to align it with \e logo on the page.

    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 anchor component instances on a page:

    \list 1
        \li Open \e {Screen01.ui.qml} for editing in the
            \uicontrol {Form Editor} view.
        \li Select \e logo in the \l Navigator view.
        \li In the \l Properties view, \uicontrol Layout tab,
            select the \inlineimage icons/anchor-top.png
            (\uicontrol Top) and \inlineimage icons/anchor-left.png
            (\uicontrol Left) anchor buttons to anchor \e logo to the top left
            corner of its parent with 10-pixel margins.
        \li Select \e pageTitle in \uicontrol Navigator.
        \li Deselect the \inlineimage icons/anchor-center-vertical.png
            (\uicontrol {Vertical Center}) button to remove the
            anchor, and then select the \uicontrol Top button to anchor the
            title to the top of the page with a 70-pixel margin.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

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

    \image loginui2-loginpage.png "Login page in the Design mode"

    \section2 Learn More - Anchors

    In an anchor-based layout, each component instance can be thought of as
    having a set of invisible \e anchor lines: top, bottom, left, right, fill,
    horizontal center, vertical center, and baseline.

    Anchors enable placing a component instance either adjacent to or inside of
    another component instance, by attaching one or more of the instance's
    anchor lines to the anchor lines of the other component instance. If a
    component instance changes, the instances that are anchored to it will
    adjust automatically to maintain the anchoring.

    For more information, see \l{Positioning with Anchors}.

    \section1 Using Column Positioners

    You will now add two entry fields to the page and position them in a column
    to learn another method of \l{Using Positioners}{positioning components}.
    Next, you will position the push buttons on the page in another column.
    Finally, you will anchor the columns to the page to enable their positions
    to change when the screen size changes.

    To add entry fields to the page:

    \list 1
        \li Drag-and-drop two instances of the \uicontrol {Text Field}
            component from \l Library > \uicontrol Components >
            \uicontrol {Qt Quick Controls} to \l {Form Editor}.
        \li Select one of the text fields in \l Navigator, and
            change its ID to \e usernameField in \l Properties.
        \li In the \uicontrol Geometry group, \uicontrol Size field,
            make the field wide enough to accommodate long user names
            by setting its width to \e 300 pixels.
        \li In the \uicontrol Placeholder field, set the text to display
            inside the field before users type in it to \e Username
        \li Select \uicontrol tr to mark the text translatable.
            \image loginui2-field-properties.png "Text field properties"
        \li Select the other text field, and change its ID to
            \e passwordField, placeholder text to \e Password,
            and width to \e 300 pixels.
    \endlist

    The Text Field component has additional properties that you can use to change
    its appearance. For example, you can change the color, font, alignment, or
    word and letter spacing of the placeholder text.

    You will now position the fields and buttons as columns:

    \list 1
        \li Select \e usernameField and \e passwordField in \uicontrol Navigator
            (press the \key Shift key for multiple selection), and right-click
            either of them to open a context menu.
        \li Select \uicontrol Position > \uicontrol {Position in Column}
            to position the fields on top of each other in
            \uicontrol {Form Editor}.
        \li Select the column in \uicontrol Navigator and change its ID
            to \e fieldColumn in \uicontrol Properties.
        \li In the \uicontrol Spacing field, set the spacing between the
            fields to 5 pixels.
            \image loginui2-column-properties.png "Column properties"
        \li Select \e loginButton and \e registerButton, and then select
            \uicontrol Position > \uicontrol {Position in Column} to position
            them in a column.
        \li Select the button column, change its ID to \e buttonColumn, and
            set the spacing between the buttons to 5 pixels, as above.
    \endlist

    You will now anchor the field and button columns to the page:

    \list 1
        \li Select \e fieldColumn in \uicontrol Navigator.
        \li In \uicontrol Properties > \uicontrol Layout, select the
            \uicontrol Top button to anchor the top of the button column to
            the top of its parent with a 200-pixel margin.
        \li Select the \inlineimage icons/anchor-center-horizontal.png
            (\uicontrol {Horizontal Center}) button to center the field
            column horizontally on the page.
        \li Select \e buttonColumn in \uicontrol Navigator.
        \li In \uicontrol Properties > \uicontrol Layout, select the
            \inlineimage icons/anchor-bottom.png
            (\uicontrol Bottom) button to anchor the bottom of the button
            column to the bottom of its parent with a 50-pixel margin.
        \li Select the \uicontrol {Horizontal Center} button to center
            the button column horizontally on the page.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    The second iteration of your UI is now ready and should look something like
    this in the \uicontrol Design mode and live preview:

    \image loginui2-loginpage-ready.png "Login page in the Design mode"

    \section1 Learn More - Positioners

    For many use cases, the best positioner to use is a simple grid, row, or
    column, and \QDS provides components that will position children in these
    formations in the most efficient manner possible. For more information
    about using preset positioners, see \l {Using Positioners}.

    For more complicated UI designs, you can use components from the
    \l {Using Layouts}{Qt Quick Layouts module}.

    \section1 Next Steps

    To learn how to add a second page and move to it from the main page, see
    the next tutorial in the series, \l {Log In UI - Part 3}.
*/

