/****************************************************************************
**
** 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 loginui1
    \ingroup studioexamples
    \ingroup gstutorials
    \nextpage {Log In UI - Part 2}

    \title Log In UI - Part 1
    \brief Illustrates how to use wizard templates to create a simple UI that
    contains a text label, push buttons, and a logo.

    \image loginui1.png

    \e{Log In UI - Part 1} is the first 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 fields. Part 1 describes
    how to use the \QDS wizard templates to create a project and a
    button UI control, and how to modify the files generated by the wizard
    templates to design your own UI.

    The \e {Learn More} sections provide additional information about the
    tasks performed by the wizards and about other basic tasks and concepts.

    \section1 Creating the UI Project

    For the purposes of this tutorial, you will use the empty wizard template.
    Wizard templates are available also for creating UIs that are optimized for
    mobile platforms and for launcher applications. For more information about
    the options you have, see \l {Creating Projects}.

    To create a project:

    \list 1
        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \uicontrol General > \uicontrol {Qt Quick Application - Empty} >
            \uicontrol Choose.
        \li In the \uicontrol Name field, enter the project name: \e {loginui1}.
            When naming your own projects, keep in mind that they cannot be
            easily renamed later.
        \li In the \uicontrol {Create in} field, enter the path to the folder
            where you want to store the project files. You can move project
            folders later without problems.
        \li Select \uicontrol Next (or \uicontrol Continue on \macos) to
            continue to the \uicontrol {Define Project Details} page.
        \li In the \uicontrol {Screen resolution} field, select the initial
            size of the UI. In this tutorial, we use the smallest predefined
            size, \e {640 x 480}. You can easily change the screen size later
            in \l Properties.
        \li Select \uicontrol Finish (or \uicontrol Done on \macos) to create
            the project.
    \endlist

    Your project should now look something like this in the \uicontrol Design
    mode:

    \image loginui1-project.png "Log In UI project in the Design mode"

    The wizard constructs the \e Screen01 \l{glossary-component}{component}
    using instances of a \l{basic-rectangle}{Rectangle} component that forms
    the background and a \l Text component that displays some text.

    \note The visibility of views depends on the selected workspace,
    so your \QDS might look somewhat different from the above image.
    To open hidden views, select \uicontrol View > \uicontrol Views
    in the \uicontrol Design mode. For more information about moving
    views around, see \l {Managing Workspaces}.

    \section2 Learn More - Projects and Files

    \QDS creates a set of boilerplate files and folders that you need to create
    a UI. The files are listed in the \l Projects view.

    \image loginui1-project-files.png

    \list
        \li The \e {loginui1.qmlproject} project file defines that all
            component, JavaScript, and image files in the project folder belong
            to the project. Therefore, you do not need to individually list new
            files when you add them to the project.
        \li The \e {loginui1.qml} file defines the functionality of
            the UI. For the time being, it does not do anything.
        \li The \e {Screen01.ui.qml} file is a custom component created by
            the wizard template. For more information, see \l {UI Files}.
        \li The \e {qtquickcontrols2.conf} file specifies the selected
            \l {Styling Qt Quick Controls}{UI style} and some style-specific
            arguments.
        \li The \e imports folder contains a \e {Constants.qml} file that
            specifies a font loader for the Arial font and a \e qmldir module
            definition file that declares the Constant component. For more
            information, see \l {Module Definition qmldir Files}. The
            \e EventListModel.qml and \e EventListSimulator.qml files are
            not used in this example, so you can ignore them for now.
    \endlist

    UI files define a hierarchy of components with a highly-readable, structured
    layout. Every UI file consists of two parts: an imports section and an
    component declaration section. The components and functionality most common to
    UIs are provided in the QtQuick import. You can view the code of an
    .ui.qml file in the \l{Text Editor} view.

    Next, you will edit the values of the properties of the component instances
    to create the main page of the UI.

    \section1 Creating the Main Page

    You will now change the values of the properties of the \l{basic-rectangle}
    {Rectangle} component instance to add a gradient to the UI background and
    those of the \l Text component instance to set the title text in a larger
    strong font. In addition, you will import an image as an asset and add it
    to the page.

    To add an image to your UI, you should first click
    \l {https://doc.qt.io/qtdesignstudio/images/used-in-examples/loginui1/qt_logo_green_64x64px.png}
    {here} to open the Qt logo in a browser and save it as a file on your
    computer. Next, you need to add the image to \l Library:
    \list 1
        \li Select \uicontrol Library > \uicontrol Assets
            > \inlineimage plus.png
            .
        \li Select the image file, and then select \uicontrol Open.
        \li Select the location where the image will be saved in the
            \uicontrol {Add Resources} dialog.
        \li Select \uicontrol OK.
    \endlist

    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 \uicontrol {Form Editor}
    view toolbar or press \key {Alt+P}.

    The \e Screen01.ui.qml file that the wizard template created for you should
    be open in the \uicontrol Design mode. If it is not, you can double-click it
    in the \uicontrol Projects view to open it.

    To modify the \e Screen01 component in \uicontrol {Form Editor}:

    \list 1
        \li Select the \e Rectangle instance in the \l Navigator view to display
            its properties in the \l Properties view.
        \li In the \uicontrol Color field, select the
            \inlineimage icon_color_gradient.png
            (\uicontrol {Linear Gradient}) button to add a linear gradient to
            the screen background. Click the start point (1) and end point (2)
            to specify the gradient colors. Drag-and-drop the points along the
            gradient bar to specify where the gradient starts and ends. In this
            tutorial, the color changes from white to green (#41cd52), starting
            mid-screen, at position 0.5. You can use your favorite colors or
            select a predefined gradient in the \uicontrol {Gradient Picker}.
            For more information, see \l{Picking Gradients}.
            \image loginui1-background-gradient.png "Rectangle color properties"
        \li Select \e Text in \uicontrol Navigator to display its properties in
            \uicontrol Properties.
            \list a
                \li In the \uicontrol ID field, enter the ID \e pageTitle,
                    so that you can easily find the title component in
                    \uicontrol Navigator and other \QDS views.
                    \image loginui1-text-properties.png "Text properties"
                \li In the \uicontrol Text field, enter the page title:
                    \e {Qt Account}.
                \li In the \uicontrol Font group, \uicontrol Size field,
                    set the font size of the title: \e 24 pixels.
                    \image loginui1-text-font-properties.png "Font properties"
                \li In the \uicontrol {Font style} field, select the
                    \uicontrol B button to use a strong font.
            \endlist
        \li Drag-and-drop the Qt logo from \uicontrol Library > \uicontrol Assets
            to the top-left corner of the rectangle.
            \image loginui1-library-assets.png "Library view Assets tab"
            \QDS automatically creates an instance of the \l{Images}{Image}
            component for you with the path to the image file set as the value of
            the \uicontrol Source field in \uicontrol Properties.
            \image loginui1-image-properties.png "Image properties"
        \li In the \uicontrol ID field, change the ID of the image to \e logo.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    Your UI should now look something like this in \uicontrol {Form Editor}
    and live preview:

    \image loginui1-main-page.png "Modified UI in the Design mode"

    \section2 Learn More - Components

    \QDS provides preset \l{glossary-component}{components} for creating
    UIs, including components for creating and animating visual components,
    receiving user input, and creating data models and views.

    To be able to use the functionality of preset components, the wizard template
    adds the following \e import statements to the UI files (.ui.qml) that it
    creates:

    \quotefromfile loginui1/Screen01.ui.qml
    \skipto import
    \printuntil Controls

    You can view the import statements in the \uicontrol {Text Editor} view.

    The \l Library view lists the components in each module that are
    supported by \QDS. You can use the basic components to create your own
    components, and they will be listed in \uicontrol Components >
    \uicontrol {My Components}. This section is only visible if you have created
    custom components.

    The \l {basic-rectangle}{Rectangle}, \l Text, and \l {Images}{Image}
    components used in this tutorial are based on the \l Item component.
    It is the base component for all visual elements, with implementation
    of basic functions and properties, such as component name, ID, position,
    size, and visibility.

    For more information, see \l{Use Case - Visual Elements In QML}. For
    descriptions of all components, see \l{All QML Types} in the Qt reference
    documentation.

    \section3 Regtangle Properties

    The default \l {basic-rectangle}{Rectangle} component is used for drawing
    shapes with four sides and four corners. You can fill rectangles either with
    a solid fill color or a gradient. You can specify the border color separately.
    By setting the value of the radius property, you can create shapes with
    rounded corners.

    If you want to specify the radius of each corner separately, you can use the
    \l{studio-rectangle}{Rectangle} component from the
    \uicontrol {Qt Quick Studio Components} module instead of the basic rectangle
    component. It is available in \uicontrol Library > \uicontrol Components
    > \uicontrol {Qt Quick Studio Components}.

    \section3 Text Properties

    The \l Text component is used for adding static text to the UI, such as
    titles and labels. You can select the font to use and specify extensive
    properties for each text component, such as size in points or pixels,
    weight, style, and spacing.

    To add custom fonts in the list of available fonts in \l Properties:

    \list 1
        \li Select \uicontrol Library > \l Assets
         > \inlineimage plus.png
         .
        \li Browse to the folder that contains the font files and select them,
            and then select \uicontrol Open.
        \li Select the location where the file will be saved in the
            \uicontrol {Add Resources} dialog.
        \li Select \uicontrol OK to save the fonts.
    \endlist

    If you want to create a label with a background, use the \l Label component
    from the \uicontrol {Qt Quick Controls} module instead of the Text component.

    \section3 Image Properties

    The \l {Images}{Image} component is used for adding images to the UI in several
    supported formats, including bitmap formats such as PNG and JPEG and vector
    graphics formats such as SVG. To add an image you wish to use in your
    designs to \uicontrol Library, select \uicontrol Library > \uicontrol Assets
    > \inlineimage plus.png
    , and then select the image file.

    If you need to display animated images, use the \l {Animated Image}
    component, also available in \uicontrol Library > \uicontrol Components >
    \uicontrol {Default Components} > \uicontrol Basic.

    \section1 Creating a Push Button

    You can use another wizard template to create a push button and to add it to
    the project. The wizard template creates a reusable button component that
    appears in \uicontrol Library > \uicontrol Components >
    \uicontrol {My Components}. You can drag-and-drop it to \l {Form Editor}
    to create button instances and modify their properties in the
    \uicontrol Properties view to change their appearance and functionality.

    If you find that you cannot use the wizard template nor the preset
    button controls available in \uicontrol Library > \uicontrol Components >
    \uicontrol {Qt Quick Controls} to create the kind of push button that you
    want, you can create your button from scratch using default components. For
    more information, see \l {Creating Buttons} and
    \l {Creating Scalable Buttons and Borders}.

    To create a push button by using the wizard template:

    \list 1
        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \uicontrol {Files and Classes} > \uicontrol {Qt Quick Controls} >
            \uicontrol {Custom Button} > \uicontrol Choose.
        \li In the \uicontrol {Component name} field, enter a name for your
            button component: \e {PushButton}.
        \li Select \uicontrol Finish (or \uicontrol Done on \macos) to create
            the button.
    \endlist

    Your button should now look something like this in the \uicontrol Design
    mode:

    \image loginui1-button.png "Button in the Design mode."

    \section2 Learn More - UI Controls

    The \e {Custom Button} wizard template creates a button component
    based on the \l {Button} control in the \l {Qt Quick Controls} module. It
    is a push-button control that can be pushed or clicked by the user. Buttons
    are normally used to perform an action or to answer a question. The
    properties and functionality inherited from the Button component enable
    you to set text, display an icon, react to mouse clicks, and so on.

    To be able to use the functionality of the Button control, the wizard template
    adds the following \e import statements to the \e PushButton.ui.qml file:

    \quotefromfile loginui1/PushButton.ui.qml
    \skipto import
    \printuntil Controls

    Next, you will change the appearance of the PushButton component by
    modifying its properties.

    \section1 Styling the Button

    You can now modify the properties of the PushButton component to your
    liking. To make the changes apply to all the PushButton instances, you
    must make them in the \e PushButton.ui.qml file.

    The Custom Button wizard template adds a \e normal state and a \e down state
    to change the button background and text color when the button is clicked.
    You will now change the colors in all states. When you make changes to the
    button in the \e base state, they are automatically applied to the other
    states. However, the property values that have been explicitly changed in
    the \e normal or \e down state are not changed automatically and you have
    to change them separately in that state.

    To change the button property values:

    \list 1
        \li Select the button background in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In the \uicontrol Color field, select
            \inlineimage icon_color_none.png
            to use a solid background color (white) instead of transparent.
        \li In the \uicontrol {Border Color} field, select
            \inlineimage icons/action-icon.png
            (\uicontrol Actions) > \uicontrol {Set Binding} to use the
            gradient color (\e #41cd52) as the border color. You can also
            use the color picker to change the color.
            \image loginui1-binding-editor.png "Binding Editor"
        \li Press \key Enter or select \uicontrol OK to save the new value.
        \li In the \uicontrol Radius field, enter 20 to give the button
            rounded corners.
        \li In the \uicontrol States view, select the \e normal state and set
            the background color to white and the border color to green, as
            instructed above. Repeat for the \e down state.
        \li Select the \e base state, and then select the text component
            in \uicontrol Navigator to display its properties in
            \uicontrol Properties.
        \li In the \uicontrol {Text Color} field, select \uicontrol Actions >
            \uicontrol Reset to reset the text color to the default color,
            black.
        \li In the \uicontrol {Font style} field, select the \uicontrol B button
            to use the strong font.
        \li In the \uicontrol States view, select the \e down state to set the
            button text color to the same green as the border.
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    Your button should now look something like this:

    \image loginui1-button-styled.png "Modified button in the Form Editor"

    \section2 Learn More - Property Bindings

    A component's property can be assigned a static value which stays constant
    until it is explicitly assigned a new value. In this tutorial, the color
    values you set in \uicontrol {Binding Editor} are static.

    However, to make the fullest use of the built-in support for dynamic
    component behavior, you can use property bindings that specify relationships
    between different component properties. When a property's dependencies change
    in value, the property is automatically updated according to the specified
    relationship.

    Behind the scenes, the property's dependencies are monitored (that is, the
    variables in the binding expression). When a change is detected, the binding
    expression is re-evaluated and the new result is applied to the property.

    For more information, see \l {Property Binding}.

    Next, you will add two instances of the \e PushButton component to the
    \e Screen01 component and modify their text labels.

    \section1 Adding Buttons to the UI

    You will now add two PushButton instances to the UI and modify their labels.

    \list 1
        \li Double-click \e Screen01.ui.qml in \uicontrol Projects
            to open it in \uicontrol {Form Editor}.
        \li Drag-and-drop two instances of the PushButton component from
            \uicontrol Library > \uicontrol Components > \uicontrol {My Components}
            to \uicontrol {Form Editor}.
            \image loginui1-library.png "My Components tab of Library view"
        \li Select one of the PushButton instances in \uicontrol Navigator
            to modify its ID and text label in \uicontrol Properties.
        \li In the \uicontrol ID field, enter \e loginButton.
        \li In the \uicontrol Text field, enter \e {Log In} and select
            \uicontrol tr to mark the text
            \l {Internationalization and Localization with Qt Quick}
            {translatable}.
        \li Select the other PushButton instance, and change its ID to
            \e registerButton and text label to \e {Create Account}.
            Again, mark the text translatable.
        \li When a component instance is selected, selection handles are
            displayed in its corners and on its sides. Use the selection
            handles to resize the button instances so that the text fits
            comfortably on the button background.
            In this tutorial, the button width is set to 120 pixels.
        \li Move the cursor on the selected button instance to make the
            selection icon appear. You can now drag the button instance
            to another position in \uicontrol {Form Editor}. Use the
            guidelines to align the button instances below the page title:
            \image loginui1-align-buttons.png
        \li Select \uicontrol File > \uicontrol Save or press \key {Ctrl+S}
            to save your changes.
    \endlist

    The first iteration of your UI is now ready and should now look something
    like this in \uicontrol {Form Editor} and live preview:

    \image loginui1-ready.png "The finished UI in Form Editor"

    \section2 Learn More - Component IDs

    Each component and each instance of a component has an \e ID that uniquely
    identifies it and enables other components' properties to be bound to it.
    An ID must be unique, it must begin with a lower-case letter or an
    underscore character, and it can contain only letters, numbers, and
    underscore characters.

    For more information, see \l{The id Attribute}.

    \section1 Next Steps

    To learn how to add more UI controls and position them on the page using
    anchors and layouts so that the UI is scalable, see the next tutorial in
    the series, \l {Log In UI - Part 2}.

    For a more advanced example of creating a menu button and using it to
    construct a button bar, see \l {Side Menu}.
*/
