TabGroup is a set of pages for a tabbed interface. More...
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.
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) } }
In some cases you might want to be able to add or remove tabs in the interface. This makes things a little more complicated.
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 } }
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 }
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 }
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
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 }
A list of all the children of the tab group. You can traverse the list to search for information about particular pages.
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.
Symbian: Adds dynamically new tab content. Use this function instead of adding new children into TabGroup directly.