Qt Reference Documentation

QML Button Element

Provides a button with an icon and a text that the user can click. More...

This element was introduced in Qt Quick Components 1.0.

Properties

Signal Handlers

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. When a button has the focus, the button can be pressed using the Qt.Key_Select, Qt.Key_Return, and Qt.Key_Enter hardware keys that will send the 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.

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

Responding to a long-press

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

You can define how a button responds to a long-press by using the button's platformAutoRepeat property. 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.

         CheckBox {
             id: chkPlatformAutoRepeat
             text: "platformAutoRepeat"
         }

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 application shows what signals the 'Signals' button sends depending on the platformAutoRepeat value 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 the platformAutoRepeat value.
  • 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.
         Button {
             id: btnSignals
             anchors.left: parent.left
             anchors.right: parent.right
             text: "Signals"

             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 property 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.


platformInverted : bool

Symbian:

If platformInverted is true, the component is visualized with the inverted style. For more information, see Using Inverted Style with Symbian Components. By default platformInverted is false.

This property group was introduced in Qt Quick Components 1.1.


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 Handler 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 is pressed for a long time.


Button::platformReleased ()

Symbian:

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