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

/*!
    \example Loginui1
    \ingroup gstutorials
    \nextpage {Login UI: Positioning}

    \title Login UI: Components
    \brief Illustrates how to use wizard templates to create a simple UI
    that contains a text label, images, and push buttons.

    \image loginui1.webp The finished tutorial in Live Preview.
    \e{Login UI: Components} is the first of the \QDS \e{Login UI} tutorials, which
    build on each other to illustrate how to create a simple UI with some basic UI
    components, such as pages, buttons, and entry fields.

    This tutorial 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 a UI.

    You can download the completed project from
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui1}{here}.

    \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 Project}.
        \li In the \uicontrol Presets tab, select \uicontrol General >
        \uicontrol {Empty} (1).
        \li In the \uicontrol Details tab:
            \list
                \li Enter \e Loginui1 as the name (2) for the project. Keep in mind
                that projects cannot be easily renamed later.
                \li Select the path (3) for the project files. You can move project
                folders later.
                \li Set \uicontrol Width to 720 and \uicontrol Height to 1280 (4).
                You can change the screen size later in \l Properties.
            \endlist
        \li Select \uicontrol Create (5) to create the project.
    \image loginui1-new-project.webp Creating a new project in Qt Design Studio.
    \endlist

    Your project should now look something like this in the \uicontrol Projects view:

    \image loginui1-project.webp A new project in Qt Design Studio.

    The wizard constructs the \e Screen01 \l{glossary-component}{component}
    using a \l{basic-rectangle}{rectangle} component as the background,
    a \l Button, and a \l Text component that displays some text.

    \note The visibility of views depends on the selection of views on the
    selected workspace, so your \QDS might look somewhat different from the
    image above. To open and close views, select \uicontrol View > \uicontrol Views.
    For more information about arranging the \QDS workspace, see \l {Workspaces}.

    Remove the button and the text component from the UI to have a clean workspace. Later
    in this tutorial, you will add and modify them as you need.

    To remove this button, select it and select \key {Backspace}. Repeat for the
    text component.

    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 create the main page of your UI. First, you will download
    a logo, a background image, and a custom font and import them to \QDS as
    assets. You will then use these assets to add a background image, a logo,
    and a tag line to your main page.

    Download the logo and the background image from here:

    \list
        \li \l{https://git.qt.io/public-demos/qtdesign-studio/-/blob/master/tutorial%20projects/Loginui1/content/images/qt_logo_green_128x128px.png}
            {qt_logo_green_128x128px.png}
        \li \l{https://git.qt.io/public-demos/qtdesign-studio/-/blob/master/tutorial%20projects/Loginui1/content/images/adventurePage.jpg}
            {Background image} (\e adventurePage.jpg)

            Photo by \l{https://unsplash.com/photos/a2MgJdG6UvE}
            {Benjamin DeYoung} on \l{https://unsplash.com}{Unsplash}.
    \endlist

    Download the Titillium Web ExtraLight font from
    \l{https://fonts.google.com/specimen/Titillium+Web#standard-styles}
    {here} or use Arial as a substitute.

    To add the assets:
    \list 1
        \li Select \uicontrol Assets > \imageplus
        (If you can't see the \uicontrol Assets view, select \uicontrol View >
        \uicontrol Views > \uicontrol Assets.)
        \image loginui1-add-assets.webp The Assets view.
        \li Select the asset files, and then select \uicontrol Open.
        \li Select the location where the files will be saved in the
            \uicontrol {Add Resources} dialog.
        \li Select \uicontrol OK.
    \endlist

    Alternatively, drag the asset files from the file browser to the \uicontrol Fonts
    or \uicontrol Images tab in the \uicontrol Assets view.

    To preview the changes that you make, select the run dropdown menu from the
    top toolbar, and then select \uicontrol {Live Preview}, or select \key {Alt+P}.

    \note If you can't see the changes that you make in the \uicontrol 2D view,
    select \imagereset on the \uicontrol {2D} view toolbar to refresh the
    \uicontrol{2D} view.

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

    To modify the \e Screen01 component in the \uicontrol {2D} view:

    \list 1
        \li Drag the background image (1) from \uicontrol Assets to the
            \uicontrol 2D view (2). Use the guidelines (3) to drag the background
            image so that it covers the whole \uicontrol 2D view.
            \image loginui1-add-background.webp Adding the background image to the main page.
            Adding an image to the \uicontrol 2D view creates an \l{Images}{Image}
            component to your project, which appears under \e rectangle in
            \uicontrol Navigator. The component is created with the path to the image
            file set as the value of \uicontrol Properties > \uicontrol Image >
            \uicontrol Source.
            \image loginui1-properties-image.webp Image properties.
        \li Drag the Qt logo from \uicontrol Assets to the background image in
            the \uicontrol {2D} view. Use the guidelines to drag the logo
            precisely to the top horizontal center of the background image.
        \li Drag a \uicontrol Text component from \uicontrol Components >
            \uicontrol {Default Components} > \uicontrol Basic below the logo image
            in the \uicontrol {2D} view.
        \li Select the \uicontrol Text component to edit the text properties in the
            \uicontrol Properties view:
            \list
                \li In \uicontrol Component > \uicontrol ID, enter the ID
                    \e tagLine.
                \li In \uicontrol Character > \uicontrol Text, enter the tag
                    line: \e {Are you ready to explore?}.
                \li In \uicontrol Character > \uicontrol Font, select
                    \e {Titillium Web}.
                \li In \uicontrol {Style name}, enter \uicontrol ExtraLight.
                \li In \uicontrol Character > \uicontrol Size, set font size of the
                    tag line to \e 50 \e px.
                \li In \uicontrol Character > \uicontrol {Text color}, set the text color to
                    white (\e #ffffff).
                    \image loginui1-properties-text.webp Text properties.
            \endlist
        \li Drag the tagline to the horizontal center below the logo using the guidelines.
        \li Select \uicontrol File > \uicontrol Save or \key {Ctrl+S} to save
            your changes.
    \endlist

    Your UI should now look something like this in the \uicontrol {2D} view
    and \uicontrol {Live Preview}:

    \image loginui1-project-main-page.webp Modified UI with background image, logo, and text.

    Resize the \uicontrol {Live Preview} window to see the whole screen.

    \section1 Creating a Push Button

    Next, you will use another wizard template to create a push button and add it to
    the project. The wizard template creates a reusable button component that
    appears in \uicontrol Components > \uicontrol {My Components}.
    You can drag it to the \uicontrol 2D view and modify its properties in
    the \uicontrol Properties view to change its appearance and functionality.

    If you cannot use the wizard template nor the preset \l {Button controls}{button 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} >
            \uicontrol {Qt Quick Controls} >
            \uicontrol {Custom Button} > \uicontrol Choose.
            \image loginui1-new-button.webp The New File window for creating a button.
        \li In the \uicontrol {Component name} field, enter a name for your
            button component: \e {EntryField}.
        \li Select \uicontrol Finish (or \uicontrol Done on \macos) to create
            the button UI file, \c EntryField.ui.qml.
    \endlist

    Your button should now look something like this:

    \image loginui1-button-new.webp A new button in Qt Design Studio.

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

    \section1 Styling the button

    To style your new button, you will edit some of the properties of
    the \e EntryField component. To make the changes apply to all the
    EntryField instances, you must make them in the \c EntryField.ui.qml file.

    The \uicontrol {Custom Button} wizard template adds a \e normal state
    and a \e down state to change the button background and the 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 \uicontrol normal or \uicontrol down state
    are not changed automatically, and you have to either reset them to the
    \uicontrol {Base State} or set them separately in that state.

    To change the button property values:

    \list 1
        \li Select \e control in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol {Geometry - 2D} > \uicontrol Size, set button
            width (\uicontrol W) to \e 500 and height (\uicontrol H)
            to \e 100, to match the width of the tag line.
        \li In the \uicontrol Control section, clear the \uicontrol Hover
            checkbox because you don't want the hover effect for the button.
        \li Select \e buttonBackground in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol Properties > \uicontrol Rectangle, set:
            \list
                \li \uicontrol {Fill color} to transparent light gray (\e #28e7e7e7).
                    You can also use the \l{Picking colors}{color picker} to set the color.
                \li \uicontrol {Border color} to white (\e #ffffff).
                \li \uicontrol Radius to \e 50 to give the button rounded corners.
            \endlist
            \image loginui1-button-background-properties-rectangle.webp Background properties.
        \li Select \e textItem in \uicontrol Navigator to display its properties
            in \uicontrol Properties.
        \li In \uicontrol Properties > \uicontrol Character, set:
            \list
                \li \uicontrol Font to \e {Titillium Web}
                \li \uicontrol {Style name} to \e ExtraLight.
                \li \uicontrol Size to \e 34 \e px.
                \li \uicontrol {Text color} to white (\e #ffffff).
                \li \uicontrol {Alignment H} to left to align the text horizontally to the left.
                \li \uicontrol {Alignment V} to center to align the text vertically to the center.
            \endlist
        \li In \uicontrol Properties > \uicontrol Padding > \uicontrol Horizontal >
            \uicontrol Left, set the padding in the field between background
            border and text to \e 50.
            \image loginui1-button-text-properties.webp Text properties of the Button component.
        \li In the \uicontrol States view, select the \e normal state and
            repeat the changes in the background color and text properties,
            as necessary. Repeat for the \e down state.
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    Your button should now look something like this:

    \image loginui1-entry-field-styled.webp Modified button in the 2D view.

    \note Do not edit the value of \uicontrol Text in the \uicontrol Character
    property because this will break the connection, and later you won't be able
    to change the text in \uicontrol {Button Content} > \uicontrol Text.

    Next, you will add instances of the \e EntryField component to the
    \e Screen01 component and modify their properties.

    \section1 Adding entry fields to the UI

    You will now add two entry fields to the UI and modify their properties:

    \list 1
        \li Double-click \c Screen01.ui.qml in \uicontrol Projects
            to open it in the \uicontrol {2D} view.
        \li Drag two \e EntryField components (1) from \uicontrol Components >
            \uicontrol {My Components} below the tagline in the \uicontrol {2D} view.
            Use the guidelines (2) to align the buttons directly below the tagline.
            \image loginui1-add-entry-fields.webp Aligning EntryFields in the 2D view.
        \li Select the first \e EntryField button in the \uicontrol 2D view or
            \uicontrol Navigator to modify it in \uicontrol Properties.
            \list
                \li In \uicontrol Component > \uicontrol ID, enter \e username.
                \li In \uicontrol {Button Content} > \uicontrol Text, enter
                \e {Username or Email} and select \uicontrol tr to mark the text
                \l {Mark Strings for Translation}{translatable}.
            \endlist
            \image loginui1-entry-field-properties.webp Entry field properties.
        \li Select the second \e EntryField, and change its ID to
            \e password and text to \e Password. Again, mark the text
            translatable.
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    \section1 Creating another button

    Next, you will add two more buttons to your UI. This time, you want to center-align
    the text of the buttons and use brighter colors for them, so you create a second
    button component as instructed in \l{Creating a Push Button}. This time you call it
    \e PushButton.

    To make the changes apply to all the PushButton instances, you
    must make them in the \c PushButton.ui.qml file.

    To change the button property values:

    \list 1
        \li Select \e control in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol {Geometry - 2D} > \uicontrol Size, set button
            width (\uicontrol W) to \e 500 and height (\uicontrol H)
            to \e 100.
        \li In the \uicontrol Control section, clear the \uicontrol Hover
            checkbox because you don't want the hover effect for the button.
            \image loginui1-button-control-properties.webp Control properties for the Button component.
        \li Select \e buttonBackground in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \li In \uicontrol Properties > \uicontrol Rectangle, set:
            \list
                \li \uicontrol {Border color} to the green used in the logo (\e #41cd52).
                \li \uicontrol Radius to \e 50 to give the button rounded corners.
            \endlist
            \image loginui1-button2-background-properties-rectangle.webp "Background properties."
        \li Select \e textItem in \uicontrol Navigator to display
            its properties in \uicontrol Properties.
        \li In \uicontrol Properties > \uicontrol Character, set:
            \list
                \li \uicontrol Font to \e {Titillium Web}
                \li \uicontrol {Style name} to \e ExtraLight..
                \li \uicontrol Size to \e 34 \e px.
                \li \uicontrol {Text color} to (\e #41cd52).
            \endlist
            \image loginui1-button2-background-properties-character.webp "Text properties."
        \li In the \uicontrol States view, select the \e normal state and repeat
            the changes, as necessary.
        \li Repeat for the \e down state. However, in \uicontrol Rectangle >
            \uicontrol {Fill color}, set the color to green (\e #41cd52) to
            turn the button background green when the button is pressed down.
            Also, in \uicontrol Text > \uicontrol Character >
            \uicontrol {Text color}, keep the text color as white (\e #ffffff).
        \li Select \uicontrol File > \uicontrol Save or select \key {Ctrl+S}
            to save your changes.
    \endlist

    Your button should now look something like this in \e {Base State}:

    \image loginui1-button-styled.webp Modified push button in the 2D view.

    \section1 Adding push buttons to the UI

    You will now add two buttons to the UI and modify their properties:

    \list 1
        \li Select the file dropdown menu (1) from the top toolbar, and then select
            \c Screen01.ui.qml to open it in the \uicontrol {2D} view.
        \li Drag two PushButton components (2) from \uicontrol Components >
            \uicontrol {My Components} to the bottom of the background image in
            the \uicontrol {2D} view. Use the guidelines (3) to align the push buttons
            horizontally with the entry fields.
            \image loginui1-add-push-buttons.webp Adding push buttons from the Components view.
        \li Select the first \e PushButton in \uicontrol Navigator or the \uicontrol 2D view
            to modify it in \uicontrol Properties.
            \list
                \li In \uicontrol Component > \uicontrol ID, enter \e login.
                \li In \uicontrol {Button Content} > \uicontrol Text, enter \e Continue and
                    select \uicontrol tr to mark the text translatable.
            \endlist
        \image loginui1-push-button-properties.webp Push button properties.
        \li Select the second \e PushButton and change its ID to
            \e createAccount and text label to \e {Create Account}. Again,
            mark the text translatable.
        \li Select \uicontrol File > \uicontrol Save or select \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 the \uicontrol {2D} view and \uicontrol {Live Preview}:

    \image loginui1-ready.webp The finished UI in the 2D view and Live Preview.

    \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 {Login UI: Positioning}.

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

    \sa {Creating projects}, {Rectangle}, {Text}, {Images}, {Use Case - Visual Elements In QML}
*/
