path: root/doc/qtdesignstudio/examples/doc/loginui1.qdoc

/****************************************************************************
**
** Copyright (C) 2020 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 examples 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 \QDS wizard templates to create a Qt Quick 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 Qt Quick} sections provide additional information about the
    tasks performed by the wizards and about the basics of QML and Qt Quick.

    \section1 Creating the UI Project

    For the purposes of this example, 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 example, we use the smallest predefined
            size, \e {640 x 480}. You can easily change the screen size later
            in \uicontrol 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 Design mode:

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

    The UI is built using a \l Rectangle QML type that forms the background and
    a \l Text type that displays some text.

    \section2 Learn Qt Quick - Projects and Files

    \QDS creates a set of boilerplate files and folders that you need to create
    a UI using Qt Quick and QML. The files are listed in the \uicontrol Projects
    view. For more information, see \l {Viewing Project Files}.

    \image loginui1-project-files.png

    \list
        \li The \e {loginui1.qmlproject} project file defines that all
            QML, 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 defines the appearance of the
            UI. For more information, see \l {Qt Quick UI Forms}.
        \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 QML type. For more
            information, see \l {Module Definition qmldir Files}. In addition,
            the \e QtQuick subfolder contains the Studio components and effects
            QML types. You can ignore the subfolder for now, because it is not
            used in this example.
    \endlist

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

    For more information about creating a QML file from scratch, see
    \l{First Steps with QML}.

    Next, you will edit the values of the properties of the UI elements 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 Rectangle
    component to add a gradient to the UI background and those of the
    \l Text component 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 be able to use an image in the UI, you must add it to your project
    in the \uicontrol Assets tab of \uicontrol Library. 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. The image is only used for decoration, so you can also use
    any other image or just leave it out.

    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 Design mode. If it is not, you can double-click it in the
    \uicontrol Projects view to open it.

    \note The visibility of views depends on the selected workspace. To open
    hidden views, select \uicontrol View > \uicontrol Views in the Design
    mode. For more information, see \l {Managing Workspaces}.

    To modify \e Screen01.ui.qml in \uicontrol {Form Editor}:

    \list 1
       \li Select \e Rectangle in the \uicontrol Navigator view to display its
            properties in \uicontrol Properties.
        \li In the \uicontrol Color field, select the
            \inlineimage icon_color_gradient.png
            (\uicontrol Gradient) button to add a linear gradient to the
            screen background. In this example, the color changes from
            white to green (#41cd52), with a stop point set at position 0.5.
            You can use your favorite colors or select a predefined gradient
            in the \uicontrol {Gradient Picker}.
            \image loginui1-background-gradient.png "Rectangle color properties"
        \li Select \e Text in \uicontrol Navigator to display its properties in
            \uicontrol Properties.
            \image loginui1-text-properties.png "Text 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.
                \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.
                \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 the \uicontrol Assets tab of
            \uicontrol Library to the top-left corner of the rectangle.
            \image loginui1-library-assets.png "Library view Assets tab"
            \QDS automatically creates a component of the \l Image type
            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 the Design mode and live
    preview:

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

    \section2 Learn Qt Quick - QML Types

    The \l {Qt Quick} module provides all the basic types necessary for creating
    UIs. It provides a visual canvas and includes types for creating and
    animating visual components, receiving user input, and creating data models
    and views.

    To be able to use the functionality of Qt Quick types, the wizard template
    adds the following \e import statements to the QML files that it creates:

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

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

    The \l [QtQuick] {Rectangle}, \l Text, and \l Image types used in this example are
    based on the \l Item type. It is the base type for all visual elements,
    with implementation of basic functions and properties, such as type
    name, ID, position, size, and visibility.

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

    \section3 Regtangle Properties

    The basic \l [QtQuick] {Rectangle} QML type is used for drawing shapes
    with 4 sides and 4 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 Rectangle type from the Qt Quick Studio Components module
    instead of the basic rectangle type. It is available in the
    \uicontrol {Studio Components} tab of \uicontrol Library.

    \section3 Text Properties

    The \l Text type 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 item, such as size in points or pixels, weight, style, and
    spacing.

    To display custom fonts in the list of available fonts in
    \uicontrol Properties, add them in the \uicontrol Assets
    tab of \uicontrol Library.

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

    \section3 Image Properties

    The \l Image type 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. You must add the images to your project in the
    \uicontrol Assets tab of \uicontrol Library to be able to use them in
    designs.

    If you need to display animated images, use the \l {AnimatedImage}
    {Animated Image} type, also available in the \uicontrol {Qt Quick - Basic}
    tab of \uicontrol Library.

    \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 under \uicontrol {My QML Components} in \uicontrol Library. You can
    drag and drop it to \uicontrol {Form Editor} and modify its properties
    in \uicontrol Properties to change its appearance and functionality.

    If you find that you cannot use the wizard template nor the ready-made
    button controls available in the \uicontrol {Qt Quick Controls 2} tab
    in \uicontrol Library to create the kind of push button that you want,
    you can create your button from scratch using basic QML types. For more
    information, see \l {Creating Buttons} and
    \l {Creating Scalable Buttons and Borders}.

    To create a push button:

    \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 type: \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 Design mode:

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

    \section2 Learn Qt Quick - Qt Quick Controls

    The \e {Custom Button} wizard template creates a \l [Qt Quick Controls 2] {Button}
    QML type that belongs to the \l {Qt Quick Controls 2} 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 Button
    type inherits properties and functionality from another QML type. These
    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 type, the wizard template
    adds the following \e import statements to the \e PushButton.ui.qml file:

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

    The \l {Qt Quick Templates 2} module provides the functionality of the
    Button type. The module is imported as \e T, and the alias is added to
    the Button type definition to indicate that the Button type from the
    Qt Quick Controls 2 module is used, instead of some other type with the
    same name.

    \printuntil text
    \dots
    \skipto Rectangle {
    \printuntil }
    \dots

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

    \section1 Styling the Button

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

    The Custom Button wizard template adds a \e down state to change the button
    background and text color when the button is clicked. You will now change
    the colors in both states.

    To change the button properties:

    \list 1
        \li Select the button background in \uicontrol Navigator to display its
            properties in the \uicontrol Properties view.
        \li In the \uicontrol Color field, select
            \inlineimage icons/action-icon.png
            (\uicontrol Actions) > \uicontrol Reset to reset the button
            background color to the default color, white.
        \li In the \uicontrol {Border Color} field, select \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 Select the text item in \uicontrol Navigator to display its
            properties in \uicontrol Properties.
        \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 Qt Quick - Property Bindings

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

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

    Behind the scenes, the QML engine monitors the property's dependencies
    (that is, the variables in the binding expression). When it detects a
    change, it re-evaluates the binding expression and applies the new result
    to the property.

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

    Next, you will use the \e PushButton type in the main UI QML file,
    \e Screen01.ui.qml to add two instances of the button to the UI
    and to modify their text labels.

    \section1 Adding Buttons to the UI

    You will now add two button 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 type from
            \uicontrol Library to \uicontrol {Form Editor}.
            \image loginui1-library.png "My QML Components tab of Library view"
        \li Select one of the buttons 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 button, and change its id to \e registerButton
            and text label to \e {Create Account}. Again, mark the text
            translatable.
        \li When an element is selected, selection handles are displayed in its
            corners and on its sides. Use the selection handles to resize the
            buttons so that the text fits comfortably on the button background.
            In this example, the button width is set to 120 pixels.
        \li Move the cursor on the selected button to make the selection icon
            appear. You can now drag the button to another position in the
            \uicontrol {Form Editor}. Use the guidelines to align the buttons
            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 the Design mode and live preview:

    \image loginui1-ready.png "The finished UI in the Design mode"

    \section2 Learn Qt Quick - QML Ids

    Each QML type and each instance of a QML type has an \e id that uniquely
    identifies it and enables other objects' 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}.
*/