QML ToolBar Element

Provides a container for accessing quickly to commonly used actions. More...

Inherits Item

List of all members, including inherited members

Properties

• tools : Item
• transition : string

Methods

• setTools

Detailed Description

The ToolBar contains a current ToolBarLayout, which in turn contains tools such as ToolButton components.

If there is a PageStack whose toolBar property is set to be this ToolBar, the ToolBarLayout set to be the tools of the current Page will be automatically set as the tools of the ToolBar, using the specified transition. This occurs each time the current Page changes.

Using the ToolBar

Basic Usage

The easiest way to use a ToolBar is to declare one to be anchored to the bottom of your Window or Page.

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

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

Note: The tools are declared as a ToolBarLayout, in this case a simple layout containing two ToolButtons is used.

Dynamically Setting the Tools in a ToolBar

In some cases, the tools required by an application Window will change depending on the application state. It is straightforward to set the current ToolBarLayout instance displayed on a ToolBar such as this example:

 ToolBar {
     id: sharedToolBar
     anchors {
         left: parent.left
         right: parent.right
         bottom: parent.bottom
     }
 }

In this case, a button is used to set the current tools for sharedToolBar:

 Button {
 onClicked: sharedToolBar.setTools(toolBarLayout5)
 }

Here is the corresponding ToolBarLayout declaration:

 ToolBarLayout {
     id: toolBarLayout5

     ButtonRow {
         checkedButton: stop5

         ToolButton {
             iconSource: "toolbar-mediacontrol-backwards"
         }
             ...
 }
 }

However, note that if your application is using a PageStack, then it is not necessary to set the tools directly on the ToolBar in this way, as described in the section on Using a ToolBar with a PageStack

Using a ToolBar with a PageStack

If your application is using a PageStack to manage a number of Pages, then there is no need to manually set the tools belonging to the ToolBar, as the PageStack provides the functionality.

Firstly, you only need to declare a single ToolBar which should be anchored at the bottom of the Page:

 ToolBar {
     id: sharedToolBar
     anchors {
         left: parent.left
         right: parent.right
         bottom: parent.bottom
     }
 }

Set the toolBar property of the PageStack to the ToolBar. Remember to anchor the PageStack to the top of the ToolBar:

 PageStack {
     id: pageStack
     anchors {
         left: parent.left
         right: parent.right
         top: parent.top
         bottom: sharedToolBar.top
     }

     // the PageStack has a single shared ToolBar
     toolBar: sharedToolBar
 }

Next, set the tools property of each Page as follows:

 Page {
     id: page1
     tools: toolBarLayout1
     anchors {
         fill: parent;
         margins: platformStyle.paddingMedium
     }
         ...
 }

     ...

Finally you would declare a ToolBarLayout corresponding to each page.

 ToolBarLayout {
     id: toolBarLayout1
         ...
 }

     ...

When the Page is pushed, setTools will be called, so that the ToolBar transitions are applied.

 Component.onCompleted: {
     pageStack.push(page1)
 }

Note: If you want to reuse ToolBarLayout instances between pages, you will need to define each unique ToolBarLayout as a Component, and dynamically create objects as needed. In practice, for a bounded number of pages, it is more maintainable to create one ToolBarLayout corresponding to each Page.

Using a ToolBar with a TabGroup

TabGroup and TabButton can be used to create a multi-section design for your application. However, there may not be sufficient screen space to fit the TabBar at the top of the page, especially if the application is already displaying a ToolBar (for example, if there is a back button and a menu button required).

Therefore, it can be a tidy solution to put the TabButton instances into the ToolBar itself, using the space that would otherwise have been blank (assuming that no other ToolButtons were needed in the middle of the ToolBarLayout).

The first step is to define your ToolBar as normal:

 ToolBar {
     id: sharedToolBar
     anchors.bottom: parent.bottom
     tools: toolBarLayout1
 }

Then create the TabGroup as you would normally do for the case of a TabBar, but in this case you will use the ToolBar instead of the TabBar:

 TabGroup {
     id: tabGroup
     anchors {
 bottom: sharedToolBar.top
 left: parent.left
 right: parent.right
 }

 // tab definitions
         ...
 }

Within the TabGroup, create the Items corresponding to each tab as normal:

 Item {
     id: tab1
     anchors.fill: parent

     // tab contents
             ...
 }

         ...

Finally, define your ToolBarLayout, but replace ToolButton instances with TabButton instances.

 ToolBarLayout {
     id: toolBarLayout1
     ToolButton {
         iconSource: "toolbar-back"
     }
     ButtonRow {
         TabButton {
             id: tabButton1
             tab: tab1
             text: "Tab1"
         }
         TabButton {
             id: tabButton2
             tab: tab2
             text: "Tab2"
         }
         TabButton {
             id: tabButton3
             tab: tab3
             text: "Tab3"
         }
     }
 }

Remember:

1. Ensure that you set the tab property correctly for each TabButton, as usual.
2. Ensure that you use a ButtonRow so that the TabButton instances adopt the segmented appearance.

Note: See the documentation for ToolBarLayout for examples of how the ButtonRow layout is applied within the ToolBar, and the number of child items that can be supported.

See also ToolBarLayout, PageStack, and Page.

Property Documentation

Method Documentation