Qt Reference Documentation

QML TabGroup Element

Provides a set of pages for a tab-based interface. More...

This element was introduced in Qt Quick Components 1.0.

Properties

Detailed Description

A tabbed interface is made up of tab buttons plus content for each button. A TabGroup component has, as its children, each page of content in the interface. These pages can be any QML items but are typically Page components for a single page of content or PageStack components when a hierarchical navigation system is required for the tab content.

As well as being the container for the tabbed interface content, TabGroup displays the content of the pages. It will layout the content to fill itself, so you must anchor the tab group item appropriately. Generally this means you anchor it to the bottom of the TabLayout item that contains the buttons and then to the sides and bottom of the screen.

The TabGroup and the TabBarLayout componenents go hand-in-hand. The layout contains the buttons and each button refers to a content page in the group. This is illustrated in the following diagram.

If you use Page components for your tab content, the status property of each page is updated appropriately when the current tab is changed: the current page has status PageStatus.Active and other pages have the status PageStatus.Inactive. During page transitions, PageStatus.Activating (for the page that is becoming the current page) and PageStatus.Deactivating (for the page that was the current page) statuses are also set.

Because of the platform specific transition requirements, these children might be reparented internally, that is, refer to the TabGroup from content with id instead of parent.

Creating a Static Tabbed Interface

If the tabs in your tabbed interface are always the same, you can create your tabbed interface simply as a set of items.

The following code creates a TabGroup with three items in it.

 Window {
     height: 350
     width: 350

     // define a tab bar layout with three buttons and link them to the content
     TabBarLayout {
         id: tabBarLayout
         anchors { left: parent.left; right: parent.right; top: parent.top }
         TabButton { tab: tab1content; text: "Tab 1" }
         TabButton { tab: tab2content; text: "Tab 2" }
         TabButton { tab: tab3content; text: "Tab 3" }
     }

     // define a blank tab group so we can add the pages of content later
     TabGroup {
         id: tabGroup
         anchors { left: parent.left; right: parent.right; top: tabBarLayout.bottom; bottom: parent.bottom }

         // define the content for tab 1
         Page {
             id: tab1content
             Text {
                 anchors.centerIn: parent
                 text: "Tab 1 content"
                 font.pointSize: 25
                 color: "white"
             }
         }

         // define the content for tab 2
         Page {
             id: tab2content
             Text {
                 anchors.centerIn: parent
                 text: "Tab 2 content"
                 font.pointSize: 25
                 color: "pink"
             }
         }

         // define content for tab 3
         Page {
             id: tab3content
             Text {
                 anchors.centerIn: parent
                 text: "Tab 3 content"
                 font.pointSize: 25
                 color: "cyan"
             }
         }
     }
 }

Creating a Dynamic Tabbed Interface

In some cases you might want to be able to add or remove tabs in the interface. This makes things a little more complicated.

Creating a Blank Tabbed Interface

The TabBarLayout and TabGroup go together

 // create a tab bar layout and anchor it to the top of the window
 TabBarLayout {
     id: tabBarLayout
     anchors { left: parent.left; right: parent.right; top: parent.top }
 }

 // create the content area for the tabs and fill the remaining window space
 TabGroup {
     id: tabGroup
     anchors { left: parent.left; right: parent.right; top: tabBarLayout.bottom; bottom: parent.bottom }
 }

Adding Pages to The Interface

Generally you add the pages in the onCompleted() signal handler. The snippet here creates three different pages. Each page has a button which is added to the tab bar layout and content which is added to the tab group.

 // create some tabs for the tab bar
 Component.onCompleted: {
     var page = pageComponent.createObject(tabGroup)
     var button = tabButtonComponent.createObject(tabBarLayout);
     button.text = "1"
     button.tab = page

     // add a component page to the tab bar
     page = pageComponent.createObject(tabGroup)
     page.message = "Original"
     button = tabButtonComponent.createObject(tabBarLayout);
     button.text = "2"
     button.tab = page

     // add an item page to the tab bar
     myPage.parent = tabGroup
     button = tabButtonComponent.createObject(tabBarLayout);
     button.text = "3"
     button.tab = myPage
 }

Removing Pages from The Interface

As well as adding pages to a tabbed interface, you might need to remove pages. You do this by calling the content's destroy() function to delete the page content and then you delete the button for the tab. Each tab buttons is a child of the TabBarLayout so, either you keep track of the buttons in a separate list, or you search the children of the TabBarLayout to find the button. The code snippet here uses the searching option.

 // remove a tab by the text on the button
 function removeTabByButtonText(buttonText) {
     var index = findTabIndexByButtonText(buttonText)
     if (index != -1) {
         tabBarLayout.data[index].tab.destroy()  // remove the tab content
         tabBarLayout.data[index].destroy()      // remove the tab button
     }
     // TODO: If the removed page was the current page, choose a new current page
 }

Finding a Particular Tab in a Tab Bar Layout

If you don't have an array keeping track of the buttons, you can also search the child items of the tab bar layout item to find the tab you want.

 // find the tab with the given text in the button and return the index
 function findTabIndexByButtonText(buttonText) {
     // find the button in the children of the tab bar layout item
     for (var i=0; i<tabBarLayout.data.length; i++) {
         if (tabBarLayout.data[i].hasOwnProperty("text")
                 && tabBarLayout.data[i].text == buttonText) {
             return i
         }
     }
     return -1 // button text not found
 }

Property Documentation

currentTab : Item

The tab that is currently active and visible to the user.

The currentTab property is initialized to null and is automatically set to point to the first tab when content is added. You can set the currentTab at any time to activate a particular tab.


platformAnimated : bool

The platformAnimated property is initialized to true and can be changed by the user to disable animations while switching currentTab property.