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

/*!
    \page quick-buttons.html
    \previouspage quick-components-creating.html

    \ingroup creator-how-to-design-qtquick-components

    \title Create buttons

    To create a button component:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File} >
            \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} >
            \uicontrol Choose to create a \l{UI files}{UI file} called
            \c {Button.ui.qml} (for example).

            \note Components are listed in \uicontrol Components >
            \uicontrol {My Components} only if the filename begins with a
            capital letter.
        \li Select \uicontrol {Design} to edit the file in the \uicontrol {2D} view.
        \li In \uicontrol {Navigator}, select \uicontrol Item and set the width
            (\uicontrol W) and height (\uicontrol H) of the button in
            \uicontrol {Properties}.
        \li Drag a \uicontrol Rectangle from \uicontrol Components >
            \uicontrol {Default Components} > \uicontrol Basic to the component
            in \uicontrol Navigator. This creates a nested component where the
            Item is the parent of the Rectangle. Components are positioned
            relative to their parents.
        \li In the \uicontrol Properties view, modify the appearance of the
            rectangle:
        \list
            \li In the \uicontrol Color field, select the button color.
            \li In the \uicontrol Radius field, set the radius of
                the rectangle to produce rounded corners for the button.
            \li Select \uicontrol {Layout}, and then select the \imageanchorfill
                (\uicontrol {Fill to Parent}) button to anchor the Rectangle to
                the Item.
        \endlist
        \li Drag a \uicontrol {Text} component to the Item in
            \uicontrol Navigator.
        \li In the \uicontrol Properties view, edit the properties of the
            \uicontrol Text component:
        \list
            \li In the \uicontrol Text field, enter \e 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 Select \key {Ctrl+S} to save the button.
            \image {qmldesigner-button.png} {Button component.}
    \endlist

    To be useful, the button component has to be created in a project.
    When you work on other files in the project to create screens
    or other components for the UI, the button component appears in
    \uicontrol Components > \uicontrol {My Components}.
    You can use it to create button instances and modify their properties
    to assign them useful IDs, change their appearance, and set the button
    text for each button instance, for example.

    To create a graphical button that scales beautifully without using
    vector graphics, use the \l [QML] {BorderImage} component. For more
    information, see \l{Create scalable buttons and borders}.

    \sa {Use UI components}{How to: Use UI components}, {Qt Quick UI design},
    {Designing Qt Quick UIs}
*/

/*!
    \page quick-scalable-image.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-design-qtquick-components

    \title Create scalable buttons and borders

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

    Use two border images and suitable graphics to change the appearance of
    a button when it is clicked. You can use use \l{Working with states}{states}
    to determine which image is visible depending on whether the mouse
    button is pressed down. You could add more images and states to
    change the appearance of the button depending on other mouse events,
    such as hovered.

    Use a \l Text component to add button text.
    You can use states also to change the button text color and font size. For
    example, you can scale the button text up or down.

    Add a \l {Enable a mouse area}{Mouse Area} component that covers the whole
    area and reacts to mouse events.

   \image {qmldesigner-borderimage-type.png} {Button component in the 2D and States views.}

    \section1 Create the button component

    To create a button component, select \uicontrol File >
    \uicontrol {New File} >
    \uicontrol {Qt Quick Files} > \uicontrol {Qt Quick UI File} >

    \uicontrol Choose to create a \l{UI files}{UI file} called \c {Button.ui.qml}
    (for example).

    \note Components are listed in \uicontrol Components >
    \uicontrol {My Components} only if the filename begins with a
    capital letter.

    \section1 Construct the button component

    To construct the button component:

    \list 1
        \li Select \uicontrol {Design} to edit the UI file in the \uicontrol {2D} view.
        \li Select \uicontrol Assets > \imageplus
            to copy the image files you want to use to the project folder.
        \li In \uicontrol {Navigator}, select the root component and set the
            width (\uicontrol W) and height (\uicontrol H) of the button in the
            \uicontrol {Properties} view to match the size of the images
            you plan to use. This specifies the initial size of the button
            component.
        \li Drag two \uicontrol {Border Image} components from
            \uicontrol Components > \uicontrol {Default Components} >
            \uicontrol Basic to the root component in \uicontrol Navigator.
        \li Drag a \uicontrol Text component to the root component.
        \li In \uicontrol {Navigator}, select the root component, and then select
            \uicontrol {Add Mouse Area} in the context menu to add a mouse area.
        \li Select a border image to edit the values of its properties:
            \list 1
                \li In the \uicontrol Id field, enter an ID for the border
                    image. In this example, we use the ID \e inactiveButton.
                \li In the \uicontrol Source field, select the image file for
                    the border image. For example, \c {inactive_button.png}.
                \li In the \uicontrol {Layout} tab, select the
                    \imageanchorfill
                    (\uicontrol {Fill to Parent}) button to always make the
                    image the same size as its parent. This makes the button
                    component scalable because the image size is bound to the
                    component size.
            \endlist
        \li Select the other border image to edit the values of its properties
            similarly:
            \list 1
                \li In the \uicontrol Id field, enter \e activeButton.
                \li In the \uicontrol Source field, select the image file
                    for the button when it is clicked. For example,
                    \c {active_button.png}.
                \li In the \uicontrol {Layout} tab, select the
                    \imageanchorfill
                    (\uicontrol {Fill to Parent}) button.
            \endlist
        \li Select the text component to specify font size and color in
            \uicontrol Properties:
            \list 1
                \li In the \uicontrol Color field, use the \l{Pick colors}
                    {color picker} to select the font color, or enter a value
                    in the field.
                \li In \uicontrol Font group, \uicontrol Size field, enter the
                    font size.
                \li In the \uicontrol {Layout} tab, select
                    \imageanchorcentervertical
                    (\uicontrol {Vertical Center}) and
                    \imageanchorcenterhorizontal
                    (\uicontrol {Horizontal Center}) buttons to inherit the
                    vertical and horizontal centering from the parent.
                    This ensures that the button label is centered when the
                    component is resized.
            \endlist
    \endlist

    \section1 Use states to change component property values

    \list 1
        \li In the \uicontrol {States} view, select \imageplus
            twice to create two new states.
            \image {qmldesigner-borderimage-states.png} {Active and inactive states.}
        \li Select \uicontrol State1.
        \li Change the state name to \e active.
        \li Select \imageactionicon
            , and then select \uicontrol {Set when Condition} to determine
            when the state should be applied.
        \li In the \uicontrol {Binding Editor}, select the \c mouseArea
            component and the \c pressed signal to specify that the state is
            applied when the mouse button is pressed down.
            \image qmldesigner-borderimage-bindings.png "Active state when condition"
        \li Select the text component in \uicontrol Navigator to specify that the
            text size is scaled up when the button is pressed down.
        \li In \uicontrol Properties, select the \uicontrol Advanced section, and
            increase the value of the \uicontrol Scale property.
        \li Select \e inactiveButton in \uicontrol Navigator to hide
            it in the \e active state by changing the value of its
            \uicontrol Visibility property in \uicontrol Properties.
        \li Select \uicontrol State2.
        \li Change the state name to \e inactive.
        \li Set the when condition for the state to \c !mouseArea.pressed to
            specify that the state is applied when the mouse button is not
            pressed down.
            \image {qmldesigner-borderimage-bindings1.png} {Inactive state when condition.}
        \li Select \key {Ctrl+S} to save the button.
        \li Select the
            \uicontrol {Live Preview} button on the top toolbar to see how the
            button behaves when you select it. Drag the preview
            window borders to see what happens when you resize the
            component.
    \endlist

    To be useful, the button component has to be created in a project.
    When you work on other files in the project to create screens
    or other components for the UI, the button component appears in
    \uicontrol Components > \uicontrol {My Components}.
    You can drag it to the \uicontrol {2D} or
    \uicontrol Navigator view to create button instances and modify the values
    of their properties to assign them useful IDs, change their appearance,
    and set the button text for each button instance, for example.

    For more information about positioning buttons on screens, see
    \l{Make layouts scalable}.

    \image {qmldesigner-borderimage.png} {Button preview as part of a screen.}

    \sa {Use UI components}{How to: Use UI components}, {Qt Quick UI design},
    {Designing Qt Quick UIs}
*/
