Tabs

You can use a  TabbedPane to manage multiple screens in your app and let users navigate between the screens. A TabbedPane stores screens as a set of tabs that are located at the bottom of the screen, in the same area where actions are displayed. Users can tap a tab to display the associated screen. Only the screen that's associated with the currently selected tab is displayed, and the others are hidden.

A Tab represents an individual screen in a TabbedPane. A Tab can include a  Page or NavigationPane as its content, each of which can have their own content and actions associated with them.


Screen showing three tabs on a tab bar.

TabbedPane includes properties that specify the set of tabs in the TabbedPane (the  tabs property) and the tab that's currently displayed (the  activeTab property). A TabbedPane also includes signals that are emitted when tabs are added or removed, and when the active tab changes.

To specify how a tab appears at the bottom of the TabbedPane, you can use various properties of Tab and its superclass,  AbstractActionItem. For example, you can use the title property to set the name of the tab, or the image property to specify an image to display with the name of the tab.

You can also use the showTabsOnActionBar property of Tab to determine whether tabs appear in the action bar at the bottom of the screen or in the tab menu on the left side of the action bar. If showTabsOnActionBar is true, tabs are displayed directly on the action bar. If showTabsOnActionBar is false, tabs appear in the tab menu and users can tap the tab menu button to access all of the available tabs. When tabs are placed in the tab menu, the name and icon of the current tab are displayed on the tab menu button.


Screen showing the tab menu.

Note that even if the showTabsOnActionBar property is true, if you add more tabs than can fit on the action bar (more than four tabs), the tab menu is created automatically. In this case, the tab menu contains all of the tabs in the TabbedPane, even the ones that fit on the action bar. When the tab menu is added, the left-most tab on the action bar becomes a button that opens the tab menu, leaving three other tabs displayed on the action bar.

To add tabs to a TabbedPane, you can call  TabbedPane::add(). This function appends the specified tab to the list of existing tabs at the bottom of the screen. You can also call TabbedPane::insert() to add a tab to a specified location in the list of existing tabs.

The tabs that you add to a TabbedPane appear at the bottom of the screen. This area also contains actions that are associated with the screen that's currently displayed. When you use a TabbedPane and one of the screens includes actions, these actions are displayed to the right of the tabs at the bottom of the screen.

If the screen includes a single action on the action bar, that action is displayed to the right of the tabs.


Screen showing three tabs and one action on the action bar.

If the screen includes more than one action, the actions appear in the action menu to the right of the tabs. Users can tap the action menu button to display the action menu for that screen.


Screen showing an action menu button.

Using a TabbedPane in QML

In QML, you can create a TabbedPane as the root element of your app and then add Tab components to it. Here's how to create a TabbedPane with two initial tabs. Each tab's content is a Page.

import bb.cascades 1.0
  
TabbedPane {
    id: tabbedPane
    showTabsOnActionBar: true
     
    Tab {
        title: "Tab 1"
         
        content: Page {
            content: Label {
                text: "This is tab 1."
            }
        }
    } // end of first Tab
      
    Tab {
        title: "Tab 2"
         
        content: Page {
            content: Label {
                text: "This is tab 2."
            }
        }
    } // end of second Tab
} // end of TabbedPane

Using a TabbedPane in C++

In C++, you can create a TabbedPane object and Tab objects, and call add() or insert() to add the Tab objects to the TabbedPane. Here's how to create the TabbedPane from the previous QML code sample, this time in C++.

// Create the root TabbedPane, and specify that tabs should appear on
// the action bar
TabbedPane *root = new TabbedPane;
root->setShowTabsOnActionBar(true);
 
// Create the first tab and its content
Tab *firstTab = Tab::create()
                .title("Tab 1");
Page *firstTabContent = new Page;
firstTabContent->setContent(Label::create("This is tab 1."));
firstTab->setContent(firstTabContent);
 
// Create the second tab and its content
Tab *secondTab = Tab::create()
                 .title("Tab 2");
Page *secondTabContent = new Page;
secondTabContent->setContent(Label::create("This is tab 2."));
secondTab->setContent(secondTabContent);
 
// Add the tabs to the TabbedPane
root->add(firstTab);
root->add(secondTab);
 
// Display the TabbedPane
Application::instance()->setScene(root);

Dynamic loading of tabs

To reduce the start times of your app, you can delay the loading of content until it's absolutely necessary. For content in tabs, you do this by using the Delegate and the TabDelegateActivationPolicy classes.

The Delegate class provides a generic delegate that instantiates an object when it's active, and deletes it when it's not active. The delegateActivationPolicy property specifies when a Tab sets the active property of its delegate. Using these classes, you can define a delegated tab and control its loading and deletion.

In this code sample, the Page to be dynamically loaded is included as the source of the Delegate:

TabbedPane {
   Tab {
      id: tab1
      delegate: Delegate {
          id: tabDelegate
          source: "page1.qml"
      }
      delegateActivationPolicy: TabDelegateActivationPolicy.Default
  }  
}

Here, delegateActivationPolicy is set to TabDelegateActivationPolicy.Default, which sets the active property of the delegate to true, meaning the content is loaded on tab selection. The available activation policies are:

  • Default: The system chooses the activation policy, typically the object activates with selection.
  • None: The tab never sets the active property, you decide when to load or delete the object.
  • ActivatedWhileSelected: The tab content is loaded (active set to true) when the tab is selected and deleted (active set to false) when it's no longer selected. This improves start time but switching between tabs may be slow.
  • ActivateWhenSelected: The tab content is loaded (active set to true) when the tab is selected and never deleted during the lifetime of the object. Since the content is never deleted, performance is impacted only the first time the tab is selected.
  • ActivateImmediately: The active property is immediately set to true and the tab content is created when the delegate's source property is set. Clearing source deletes the content.

In the following code sample, using a delegateActivationPolicy of TabDelegateActivationPolicy.None, you must include code that sets the active property explicitly:

TabbedPane {
    Tab {
        id: tab1
        delegate: Delegate {
            id: tabDelegate1
            source: "page1.qml"
        }
        delegateActivationPolicy: TabDelegateActivationPolicy.None
    }

    Tab {
        id: tab2
        delegate: Delegate {
            id: tabDelegate2
            source: "page2.qml"
        }
        delegateActivationPolicy: TabDelegateActivationPolicy.None
    }

    onActiveTabChanged: {
        if (activeTab == tab1) {
            tabDelegate1.active = true;
            tabDelegate2.active = false;
        }
        if (activeTab == tab2) {
            tabDelegate1.active = false;
            tabDelegate2.active = true;
        }
    }

    onCreationCompleted: {
        tabDelegate1.active = true;
    }
}  

In this way, you are controlling the loading and unloading of content explicitly.

Last modified: 2013-12-21



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus