Qt Reference Documentation

QML ToolButton Element

Provides a tool button within a ToolBar enabling quick access to a function. More...

This element was introduced in Qt Quick Components 1.0.

Properties

Signal Handlers

Detailed Description

ToolButton provides a different style of appearance compared to a normal Button. It is designed to only be used inside a ToolBarLayout. Alternatively it can be used inside a ButtonRow that is itself inside a ToolBarLayout.

It is recommended that you use ToolButton for a button inside a ToolBar and Button for a button outside a ToolBar. Button may be shown incorrectly if it is placed inside a ToolBar. It may be too tall, for example.

Note: The ToolBarLayout will override the height and width of contained ToolButton children. Therefore you should not attempt to define the size or implicit size of a ToolButton.

For more information on how to use ToolButton within a ToolBar, see the ToolBar documentation. It provides also various use cases.

See also ToolBar, ToolBarLayout, ButtonRow, and TabButton.

Property Documentation

checkable : bool

If checkable is true, the tool button acts like a pushable switch and stays "down" (or checked) if you press and release the button. If you press and release the tool button again, the tool button returns to the "up" (or unchecked) position.

See also checked.


checked : bool

If checked is false, the button appears as normal or "up". If checkable and checked are both true, and the button is not being pressed, the button appears as "down" or "checked".

Note: if checkable is true, the value of checked will be updated dynamically as the button is pressed and released.

Note: If the button contains just an icon, and the flat property is true, the checked button will have a distinctive appearance (when not pressed), whilst still appearing to be flat.

See also checkable.


enabled : bool

Indicates whether the ToolButton can be used or not. If the value is true, the ToolButton's appearance indicates to the user that they can use it; otherwise not. If the user presses the button whose value is false, neither signal is sent nor feedback is given.


flat : bool

Defines whether the ToolButton looks "flat" or not. If the value is true:

  • The ToolButton does not have a border and it looks flat when it is not pressed.
  • The ToolButton with only an icon has a distinctive highlighted border when it is pressed.

If the value is false, the ToolButton has a border.

The value is automatically set to true if the ToolButton has only an icon; otherwise it is set to false. The default appearance of a ToolButton with an icon should be flat.

Generally, if the ToolButton is an icon, you should leave this value to true, so that the icon merges with the toolbar. If the ToolButton has text, you should leave this value to false, so that the ToolButton's text stands out from the toolbar same way as a normal button. The screenshot below shows the non-flat and the flat ToolButton.

Note:

  • If the ToolButton is within a ButtonRow, the value also applies to the segmented border appearance.
  • If the button has neither icon nor text, the flat value is ignored, and only the border is shown. Otherwise the ToolButton would be invisible until the user presses it.

iconSource : url

The location or the name of the icon that is shown on the ToolButton. If the value is empty, neither icon is shown nor space is reserved within the layout for it.

Note: If the iconSource is set to one of the values below, the icon location in the resources will be automatically used.

Normally it is expected that toolbar-back and toolbar-menu icons are used for the back button (in ToolBarLayout's first position) and the menu button (in ToolBarLayout's last position) respectively. The following example illustrates how to use this feature:

 ToolBar {
     anchors.bottom: parent.bottom
     tools: ToolBarLayout {

         ToolButton {
             iconSource: "toolbar-back"
         }
         ToolButton {
             iconSource: "toolbar-menu"
         }
     }
 }

You can place additional content between the back button and the menu button. The ToolBarLayout documentation illustrates various possible layout configurations.

Note: You should use only the "toolbar-back" icon in the leftmost position. This is to enforce consistency between different applications.


platformExclusiveGroup : QtObject

Symbian:

The exclusive group that this tool button belongs to. In an exclusive group only one of the tool buttons can be selected at a time.


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

While the user presses the ToolButton, the value is true; otherwise false.


text : string

The text shown on the button. If the value is empty, no text is shown on the button, and no space will be reserved in the layout for it.

If both a text and an icon are specified, the platform style determines whether either of them or both are shown. Often the icon is shown in preference to the text.


Signal Handler Documentation

ToolButton::clicked ()

This signal is emitted when the ToolButton is pressed and released within a short time.


ToolButton::platformPressAndHold ()

Symbian:

This signal is emitted if the button is pressed for a long time.


ToolButton::platformReleased ()

Symbian:

This signal is emitted when the button is released.