Qt Reference Documentation

QML TabGroup Element

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

Inherits Item

  • List of all members, including inherited members
  • 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

    read-onlycurrentTab : 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.


    read-onlyplatformAnimated : bool

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