/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator 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.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage quick-components.html
    \page quick-buttons.html
    \nextpage quick-scalable-image.html

    \title Creating Buttons

    To create a button type:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \if defined(qtcreator)
            \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
            \else
            \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
            \endif
            \uicontrol Choose to create a QML file called Button.qml (for
            example).

            \note Types are listed in the \uicontrol Library only if the
            filename begins with a capital letter.

        \li Click \uicontrol {Design} to edit the file in the
            \uicontrol {Form Editor}.

        \li In the \uicontrol Navigator, select \uicontrol Item and set the
            width (\uicontrol W) and height (\uicontrol H) of the button in the
            \uicontrol Properties pane.

        \li Drag and drop a \uicontrol Rectangle from the \uicontrol Library to
            the item in the navigator. This creates a nested item where the
            item is the parent of the rectangle. Items are positioned relative
            to their parents.

        \li In the \uicontrol Properties pane, modify the appearance of the
            rectangle:

        \list a

            \li In the \uicontrol Color field, select the button color.

            \li In the \uicontrol Radius field, use the slider to set the radius of
                the rectangle and produce rounded corners for the button.

            \li Select \uicontrol {Layout}, and then select the
                \inlineimage anchor-fill.png
                (\uicontrol {Fill to Parent}) button to anchor the rectangle to
                the item.


        \endlist

        \li Drag and drop a \uicontrol {Text} type to the item in the navigator.

        \li In the \uicontrol Properties pane, edit the properties of the \uicontrol Text
            type.

        \list a

            \li In the \uicontrol Text field, type \b Button.

                You can select the text color in the \uicontrol {Text color} field and the
                font, size, and style in the
                \uicontrol Font section.

            \li In the \uicontrol Alignment field, select the center buttons to align
                the text to the center of the button.

            \li Select \uicontrol Layout > \uicontrol {Fill to Parent}
                to anchor the text to the whole button area.

        \endlist

        \li Press \key {Ctrl+S} to save the button.

            \image qmldesigner-button.png "Button component"

    \endlist

    To create a graphical button that scales beautifully without using vector
    graphics, use the \l [QML]{BorderImage}{Border Image} type. For more
    information, see \l{Creating Scalable Buttons and Borders}.

    */


/*!

    \contentspage index.html
    \previouspage quick-buttons.html
    \page quick-scalable-image.html
    \nextpage qtquick-navigator.html

    \title Creating Scalable Buttons and Borders

    You can use the \l [QML]{BorderImage}{Border Image} type to display an
    image, such as a PNG file, as a border and a background.

    Use two border images and suitable graphics to make it look like the
    button is pushed down when it is clicked. One of the border images
    is visible by default. You can specify that it is hidden and the other one
    becomes visible when the mouse is clicked.

    Add a \l [QML]{MouseArea}{Mouse Area} type that covers the whole area and
    emits the clicked signal (\c {item.clicked()}) when it detects a mouse
    click.

    You can add text to the button and set it up as a property. The text can
    then be initialized from the outside, making the button a reusable UI
    component. The font size is also available in case the default size is too
    big. You can scale down the button text and use smooth text rendering for
    some extra quality.

    \image qmldesigner-borderimage.png "Graphical button"

    To create a graphical button:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \if defined(qtcreator)
            \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
            \else
            \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
            \endif
            \uicontrol Choose to create a QML file called Button.qml (for
            example).

            \note Types are listed in the \uicontrol Library only if the
            filename begins with a capital letter.

        \li Click \uicontrol {Design} to edit the file in the
            \uicontrol {Form Editor}.

        \li In the \uicontrol Navigator, select \uicontrol Item and set the
            width (\uicontrol W) and height (\uicontrol H) of the button in the
            \uicontrol Properties pane.

        \li Select \uicontrol Connections > \uicontrol {Properties} >
            \uicontrol Add to add properties for the item:

            \image qmldesigner-borderimage-properties.png "Properties"

            \list a

                \li Double-click in the columns in the view to specify a \c text
                     property with the type \c string and an empty value.

                \li Specify another property, \c fontSize, with the type \c int
                    and the value \c 10.

            \endlist

        \li Drag and drop two \uicontrol {Border Image} types from the
            \uicontrol Library to the item in the \uicontrol Navigator.

        \li Drag and drop a \uicontrol Text type to the item in the navigator.

        \li Drag and drop a \uicontrol {Mouse Area} to the item in the
            navigator.

        \li In the navigator, select a border image to specify settings for it
            in the \uicontrol Properties pane:

        \list a

            \li Select \uicontrol Connections > \uicontrol {Bindings}
                > \uicontrol Add to hide the image when the mouse button is not
                pressed down. Specify the \c visible property with the
                \c !mouseArea source item and \c pressed source property.

                \image qmldesigner-borderimage-bindings.png "Border image bindings"

            \li In the \uicontrol Source field, select the image file for the button,
                for example button_up.png.

            \li  Click \uicontrol {Layout}, and then click the
                \inlineimage anchor-fill.png
                (\uicontrol {Fill to Parent}) button to anchor the border image to the
                \uicontrol Item.

        \endlist

        \li Select the other border image to specify similar settings for it:

        \list a

            \li In \uicontrol Bindings, specify the \c visible property
                with the \c mouseArea source item and \c pressed source
                property to show the image when the mouse button is pressed
                down.

            \li In the \uicontrol Source field, select the image file for the button
                when it is clicked, for example button_down.png.

            \li Select \uicontrol {Layout} > \uicontrol {Fill to Parent}
                button to anchor the border image to the \uicontrol Item.

        \endlist

        \li Select the text to specify font size and color, and text scaling
            and rendering:

        \list a

            \li In the \uicontrol Color field, use the color picker to select
                the font color, or enter a value in the field.

            \li In \uicontrol Bindings, create bindings to properties:

                \image qmldesigner-borderimage-bindings-text.png "Text bindings"

                \list

                    \li Set the source property of the \c text property as
                        \c text and the source item as \c parent.

                    \li Set the source property of the \c font.pixelSize as
                        \c fontSize and the source item as \c parent.

                    \li Set the source property of \c scale as
                        \c {if (!mouseArea} and the source item as
                        \c {pressed) { 1 } else { 0.95 }}.

                \endlist

            \li Click \uicontrol {Layout}, and then click the
                \inlineimage anchor-vertical-center.png
                (\uicontrol {Vertical Center}) and
                \inlineimage anchor-horizontal-center.png
                (\uicontrol {Horizontal Center}) buttons to inherit the
                vertical and horizontal centering from the parent.

        \endlist

        \li Select \uicontrol mouseArea in the navigator and then select
            \uicontrol Connections > \uicontrol Add to set \c item.clicked()
            as the value of the \c onClicked signal handler.

           \image qmldesigner-borderimage-connections.png "Item connections"

        \li In the \uicontrol {Text Editor}, specify the \c clicked signal for
            the Item:

            \qml
            Item {
                id: item
                property string text: ""
                property int fontSize: 10

                signal clicked
            }
            \endqml

    \endlist

    \note To test the button, add it to a Qt Quick Application or Qt
    Quick UI project and run the application.

*/

