QML ToolBarLayout Element

Provides a container for items on a ToolBar that automatically implements an appropriate layout for its children. More...

Inherits Item

Properties

• backButton : bool

Detailed Description

For more information on how to use ToolBarLayout inside ToolBar, see the ToolBar documentation. It provides also various use cases, for example, attaching a ToolBarLayout to a Page.

Using the ToolBarLayout

The ToolBarLayout is meant for specifying the tools within a ToolBar. The ToolBarLayout is a container that calculates the child positions based on platform specific rules.

Basic Usage

In this example, there is a simple ToolBarLayout that must be set to be the tools of a ToolBar (or Page) at some point. The screenshot below each code snippet shows the result of that code snippet.

 ToolBarLayout {
     id: toolBarLayout1

     ToolButton {
         iconSource: "toolbar-back"
         onClicked: Qt.quit()
     }
     ToolButton {
         iconSource: "toolbar-menu"
         onClicked: launchMenu()
     }
 }

In most cases, the layout should contain a back ToolButton and a menu ToolButton.

Using a ToolBarLayout with ToolButton

It is possible to add a number of ToolButton instances that contain icons.

 ToolBarLayout {
     id: toolBarLayout3a

     ToolButton {
         visible: false
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-stop"
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-pause"
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-play"
     }
     ToolButton {
         visible: false
     }
 }

It is also possible to add a number of ToolButton instances that contain text.

 ToolBarLayout {
     id: toolBarLayout2

     ToolButton {
         iconSource: "toolbar-back"
         onClicked: pageStack.pop()
     }
     ToolButton {
         text: "One"
     }
     ToolButton {
         text: "Two"
     }
     ToolButton {
         iconSource: "toolbar-next"
         onClicked: pageStack.push(page3)
     }
 }

However, it is recommended that you use either text or icons for all the remaining ToolButton instances, and avoid mixing up the two types (not counting the back button and menu button which should always contain icons).

Missing Items

In most cases, it is recommended that the back button and the menu button are shown in the ToolBar. However, in some cases it may be desirable or necessary to hide them. By setting either or both of the buttons to be hidden, they reserve space in the layout.

 ToolBarLayout {
     id: toolBarLayout2

     ToolButton {
         visible: false
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-stop"
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-play"
     }
     ToolButton {
         visible: false
     }
 }

Using a ToolBarLayout with ButtonRow

ToolBarLayout provides some special behavior when a ButtonRow is contained as a child item. The correct combination of child items can be used to achieve good quality layouts that still take advantage of the available screen real estate.

Consider the following example of a media player application. The media transport controls can be placed inside the ToolBar, but if they are first contained by a ButtonRow, then the behavior provides the appearance of a traditional "Cassette Recorder" controls. Here, the buttons are designed to mechanically move into the pressed state in order to illustrate the current playback state in a tactile way, whilst the segmented appearance is reminiscent of classic hardware design for the keypad arrangement.

 ToolBarLayout {
     id: toolBarLayout3b
     ToolButton { iconSource: "toolbar-back" }

     ButtonRow {
         checkedButton: stop3b

         ToolButton {
             id: stop3b;
             iconSource: "toolbar-mediacontrol-stop"
         }
         ToolButton {
             iconSource: "toolbar-mediacontrol-pause"
         }
         ToolButton {
             iconSource: "toolbar-mediacontrol-play"
         }
     }

     ToolButton {
         iconSource: "toolbar-menu"
     }
 }

Note that in this case the back and menu buttons are present, so that the ButtonRow occupies only the central area.

However, if either of the first or last icon ToolButton instances are missing, and if the ButtonRow contains a sufficient number of ToolButtons, then the layout will automatically adjust to utilize the optimum amount of screen space.

 ToolBarLayout {
     id: toolBarLayout4a
     ToolButton {
         iconSource: "toolbar-back"
     }

     ButtonRow {
         checkedButton: stop4a

         ToolButton {
             iconSource: "toolbar-mediacontrol-backwards"
         }
         ToolButton {
             id: stop4a
             iconSource: "toolbar-mediacontrol-stop"
         }
         ToolButton {
             iconSource: "toolbar-mediacontrol-play"
         }
         ToolButton {
             iconSource: "toolbar-mediacontrol-forward"
         }
     }
 }

Note also that in this case, the checkedButton belonging to the ButtonRow has been set to the item that should be checked by default. In the case of a media transport, the initial state is "stop" in this implementation.

Layout rules for ToolBarLayout

In the case of a Symbian toolbar, the layout rules are as follows:

1. All children of the ToolBarLayout are considered part of the layout, but special meaning is given to the first and last children (if they are a ToolButton with an icon). These correspond to the back ToolButton and the menu ToolButton.
2. If there is an icon ToolButton in the leftmost position, then it must always use the "toolbar-back" icon, so that it is consistent with all other applications. This is referred to as the "back button".
3. The back button occupies the leftmost space, separated with a margin in landscape. If there is no back button, or if a non-visible button is placed there, the space is left deliberately blank.
4. The last icon ToolButton occupies the rightmost space. If there is no last icon ToolButton, or if a non-visible button is placed there, the space is left deliberately blank.
5. If the remaining items are text ToolButton instances, they are distributed around the center of empty space in the middle of toolbar. In landscape, the size is always the size as if there are two buttons (even if there is only one). In portrait, there is extra spacing on each side, and the single item fills the remaining space.
6. If the remaining items are icon ToolButton instances, they are distributed evenly along the remaining area. The spacings are equal size in pixels, and any rounding is shared between left and right hand margins.
7. If the remaining item is a ButtonRow with one item, it behaves like a single ToolButton containing text (but in that case it is recommended to just use a tool button). If it has two texts or two icons, it fills the space as if there is a left and right hand icon present. If it has three or more icons, it fills the available remaining space (with special margins) depending on whether the left and right icon ToolButtons are present.

Restrictions on ToolBarLayout support for child items

Child items that are not ButtonRow or ToolButton are not guaranteed to fit. However, if a component happens to fit into the vertical space of the ToolBar (which may be different in landscape orientation), then it is possible to place other components inside the ToolBarLayout. In this case, the implicit size or size of the item will be used to space out the items evenly, but behaviour is not guaranteed.

Avoid placing too many items in the ToolBar as they may not fit within the portrait screen width. In the case of ToolButtons, the following combinations are supported (although additional items may fit at a particular screen size):

So, for example, in the case of a back button plus a menu button, it is possible to fit 3 ToolButtons containing icons in the remaining space. So the rules are:

• If the back and menu buttons are present or not visible, then the remaining space allows 2 text ToolButton instances, or 3 icon ToolButton instances (whether within a ButtonRow or not).
• If the back or menu buttons are missing, and there is a ButtonRow, then the remaining space allows different combinations of items, according to the values described in the table.

In practice, for a given Screen Device Profile, you may be able to fit additional children. However, it is not guaranteed that they will fit in all supported Screen Device Profiles. It is recommended that you stay within these limits in order to guarantee that the layout will always look correct.

See also ToolBar, ButtonRow, ToolButton, TabButton, and Page.

Property Documentation

 ToolBarLayout {
     id: toolBarLayout1

     ToolButton {
         visible: false
     }
     ToolButton {
         iconSource: "toolbar-mediacontrol-play"
     }
     ToolButton {
         visible: false
     }
 }