Qt Quick Components

TabGroup

TabGroup is a set of pages for a tabbed interface. More...

  • List of all members, including inherited members
  • Properties

    Methods

    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 item 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.

    A TabGroup and a TabBarLayout 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 Page::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 i.e. 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
    
         //! [1]
         // 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" }
         }
         //! [1]
    
         // 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"
             }
         }
    
         // add the tab content items to the tab group
         Component.onCompleted: {
             tabGroup.addTab(tab1content)
             tabGroup.addTab(tab2content)
             tabGroup.addTab(tab3content)
         }
     }

    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(null)
             var button = tabButtonComponent.createObject(null);
             button.text = "1"
             addTab(button,page)
    
             // add a component page to the tab bar
             page = pageComponent.createObject(null)
             page.message = "Original"
             button = tabButtonComponent.createObject(null);
             button.text = "2"
             addTab(button,page)
    
             // add an item page to the tab bar
             button = tabButtonComponent.createObject(null);
             button.text = "3"
             addTab(button,myPage)
         }

    To keep the code tidier, a simple addTab function implements the actual adding of the button and content.

         // add a new tab with the given tab button and tab content
         function addTab(button, content)
         {
             tabGroup.addTab(content)        // add the content to the tab group
             button.parent = tabBarLayout    // reparent the button so it is a child of the layout
             button.tab = content            // associate the button with the content
         }

    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 TabGroup's removeTab() 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) {
                 tabGroup.removeTab(tabBarLayout.data[index]) // remove the tab button
                 tabBarLayout.data[index].destroy()           // remove the tab content
             }
             // TODO: If the removed page was the current page, choose a new current page
         }

    Managing the tabs

    A good way to manage the tabs in your interface is to maintain a separate list of the tab buttons. When you create a new tab, you can add the button to the list. When you delete a tab, you can delete the button from the list (after first using removeTab to delete the actual content).

    Using a list of tab buttons makes it easy to reorder the tabs. You can simply change the order in your main list and then apply this newly ordered list to the layout.

    ### Needs expanding and code snippets

    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].text == buttonText) {
                     return i
                 }
             }
             return -1 // button text not found
         }

    Property Documentation

    contents : list<Item>

    A list of all the children of the tab group. You can traverse the list to search for information about particular pages.


    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.


    Method Documentation

    TabGroup::addTab ( content )

    Symbian: Adds dynamically new tab content. Use this function instead of adding new children into TabGroup directly.


    TabGroup::removeTab ( content )

    Symbian: Removes the tab content from the group.