QML ToolBar Element

Styled tool item container with page synchronized transitions More...

Inherits Item

This element was introduced in qt-components 4.7.

• List of all members, including inherited members

Properties

• platformStyle : Style
• tools : Item
• transition : string

Methods

• setTools

Detailed Description

The ToolBar can be used either with or without the PageStack. Logically the toolbar is split into three levels:

• The actual ToolBar component, which forms the visual toolbar that is typically created once per application and placed in some static place on the edge of the screen.
• Tools, also known as items, that go in the toolbar. These are things like toolbar buttons but can also in principle be anything else such as text fields, icons, and so on.
• A container for the tools. This handles the layout of the tools inside the toolbar. Depending on the situation this could be the QML standard Row element or the Qt Components ToolBarLayout component, which implements a very particular algorithm that is suitable for many standard toolbar item layouts.

Using the toolbar is a simple matter of specifying the tools - as a single QML item - with the tools property of the ToolBar item. This single QML item is typically the tool container (level #3 according to the definition above) and contains items (level #2 above) that are the actual tools.

When the tools property changes the ToolBar performs a transition animation between the old and new tools. The transition that is used is specified using the transition property. By default this is "set", which means an immediate change of tools without any animation. Other supported transitions are "push", "pop" and "replace", which correspond to the page stack navigation methods.

The tools can also be changed with a particular transition using the setTools() method. The first argument of this function is the new tools and the second is the transition to use. The tools property of the ToolBar will be updated as a result of calling this method but the transition property will remain unchanged. That is, the transition that is specified in setTools() applies only to this particular change of tools rather than all subsequent changes.

The tools that are in the toolbar for a particular page are defined using the tools property in a page. When the toolbar property of the PageStack references a particular toolbar then whenever a page is activated its tools properties are set to that toolbar using the same transition that was used to activate that page. For example a push() call in the PageStack results in the tools being changed in the toolbar using the "push" transition.

A typical tools definition in a page would look something like this:

 Page {
     tools: ToolBarLayout {
         ToolItem { iconId: "icon-m-toolbar-back"; onClicked: pageStack.pop(); }
         ToolButton { text: "One" }
         ToolButton { text: "Two" }
         ToolItem { iconId: "icon-m-toolbar-view-menu" }
     }
 }

When used without the PageStack the tools are defined exactly the same way but in the application instead of in the page. Instead of automatically being set to the toolbar, you have to manually set the tools property of the toolbar to refer to the property or id that defines the new tools, as follows:

 Rectangle {
     someTools: ToolBarLayout {
          ToolItem { iconId: "icon-m-toolbar-back"; onClicked: pageStack.pop(); }
          ToolButton { text: "One" }
          ToolButton { text: "Two" }
          ToolItem { iconId: "icon-m-toolbar-view-menu" }
     }

     ToolBar {
         id: toolBar
         transition: "replace"
         tools: ToolBarLayout {
             ToolButton { text: "Old One" }
             ToolButton { text: "Old Two" }
         }
     }

     Button {
         text: "Change Tools"
         onclicked: toolBar.tools = someTools
     }
 }

In the example above the tools are changed when the button is pressed. The tool bar would perform a "replace" transition animation between the old tools (buttons "Old One" and "Old Two") and the new tools defined by someTools.

Property Documentation

Method Documentation