Qt Quick Components

Button

A button component has an icon and a text and can be clicked by the user. More...

  • List of all members, including inherited members
  • Properties

    Signals

    Detailed Description

    A button component enables the user to perform a command. The button has a rectangular shape and typically there is a text describing its command and an icon shown on the button. When the user presses the button, it sends a clicked signal.

    You can set a button to be a toggle button by enabling the checkable property. A toggle button is a button that can be set to two states, 'on' and 'off'. A toggle button is 'on' when its checked property is true; otherwise the button is 'off'. If the toggle button's state is 'on', its background is highlighted, otherwise it looks the same as a button that is not a toggle button. The user can click the toggle button to switch it 'on' or 'off', for example, to switch between bold and plain style in selected text.

    You can also set a button to respond to a long-press. If the button's platformAutoRepeat property is true, the button sends the clicked signal repeatedly as long as the user presses the button. If the button's platformLongPress property is true, the button sends platformPressAndHold signal once when the user presses the button for a long period of time.

    Responding to a long-press

    Note: This use case illustrates Symbian-specific platformAutoRepeat and platformLongPress properties as well as platformPressAndHold and platformReleased signals.

    You can define how a button responds to a long-press by using the button's platformAutoRepeat and platformLongPress properties. When the button is pressed, it sends:

    In this example the user can enable and disable the 'Signals' button's (id: btnSignals) platformAutoRepeat property with the platformAutoRepeat check box and platformLongPress property with the platformLongPress check box.

             CheckBox {
                 id: chkPlatformAutoRepeat
                 text: "platformAutoRepeat"
             }
    
             CheckBox {
                 id: chkPlatformLongPress
                 text: "platformLongPress"
             }

    The 'Signals' button’s platformAutoRepeat property is bound to the platformAutoRepeat checkbox's checked property. When the user checks/unchecks the platformAutoRepeat checkbox, the 'Signals' button's platformAutoRepeat property is set/unset respectively. The same pattern applies to the 'Signal' button's platformLongPress property and the platformLongPress checkbox's checked property.

    The application shows what signals the 'Signals' button sends depending on platformAutoRepeat and platformLongPress values and the duration of the pressing. The button sends:

    • a platformReleased signal every time the user releases the 'Signals' button.
    • a clicked signal when the user presses and then releases the 'Signals' button in a short period of time, regardless of platformAutoRepeat and platformLongPress values.
    • a clicked signal repeatedly as long as the user keeps the 'Signals' button pressed if the button's platformAutoRepeat property is true. The sending starts after a short delay.
    • a platformPressAndHold signal when the user keeps the 'Signals' button pressed if the button's platformLongPress property is true.
             Button {
                 id: btnSignals
                 anchors.left: parent.left
                 anchors.right: parent.right
                 text: "Signals"
    
                 platformLongPress: chkPlatformLongPress.checked     // bind platformLongPress to the "platformLongPress" checkbox
                 platformAutoRepeat: chkPlatformAutoRepeat.checked   // bind platformAutoRepeat to the "checked" checkbox
                 checkable: chkCheckable.checked     // bind checkable to the "checkable" checkbox
                 onPlatformReleased: {
                     txtLog.text = txtLog.text + "The 'platformReleased' signal. <br>"
                 }
                 onClicked: {
                     txtLog.text = txtLog.text + "The 'clicked' signal. <br>"
                 }
                 onPlatformPressAndHold: {
                     txtLog.text = txtLog.text + "The 'platformPressAndHold' signal. <br>"
                 }
             }

    The screenshot below illustrates the case where the user has set the 'Signals' button's platformAutoRepeat property to true. When the user presses the 'Signals' button it sends a clicked signal repeatedly as long as the user keeps the button pressed. When the user releases the button it sends in Symbian environment a platformReleased signal.

    Using a button as a toggle button.

    A button can be used as a toggle button when its checkable property is true. The user can switch the toggle button 'on' and 'off' by pressing it.

    In this example the user can enable and disable the button's checkable property with the checkable check box. The 'Signal' button's checkable property is bound to checkable checkbox's checked property in the same way as its platformAutoRepeat and platformLongPress properties in the Responding to a long-press use case.

    The screenshot below illustrates the case where the 'Signals' button is used as a toggle button. The user has changed the 'Signals' button to a toggle button by checking the checkable check box. Then the user has switched 'on' the 'Signals' button by clicking it. When the user presses and then releases the button it sends a 'clicked' signal and in Symbian environment also a 'platformReleased' signal.

    Property Documentation

    checkable : bool

    If a button's checkable property is true, it can be used as a toggle button. The toggle button can be switched between two states, 'on' and 'off'. The checkable value is false by default.

    See also Button::checked.


    checked : bool

    The toggle button is:

    • 'on', if its checked value is true.
    • 'off', if its checked value is false. The default value if false.

    See also Button::checkable.


    font : font

    Holds the font of the button's label.


    iconSource : url

    URL for the icon that is displayed on the button. By default there is no icon.


    platformAutoRepeat : bool

    Symbian:

    If platformAutoRepeat is true, the clicked() signal is emitted repeatedly as long as the button is pressed. By default platformAutoRepeat is false.


    platformLongPress : bool

    Symbian:

    If platformLongPress is true, the platformPressAndHold() signal is emitted when the button is pressed for a long time. If platformLongPress is false, the platformPressAndHold() signal is not emitted. By default platformLongPress is false.


    pressed : bool

    Indicates if the button is currently pressed or not.


    text : string

    The text is displayed as the button's label. The default text is an empty string.


    Signal Documentation

    Button::clicked ()

    This signal is emitted after the button is pressed and then released.

    The signal handler, onClicked(), can bind to state changes or other actions.


    Button::platformPressAndHold ()

    Symbian:

    This signal is emitted when the button's platformLongPress property is true and the button is pressed for a long time.


    Button::platformReleased ()

    Symbian:

    This signal is emitted when the button is pressed and then released.