NativeTabbar

The NativeTabbar methods let you use multiple instances of the RhoMobile webview in separate tabs.

On Android, iOS and WIndows Phone 8 the tabs are true Native Tabbar controls to give your application a native look and feel.No more than 4 tabs can be created in the Windows Phone 8 tabbar. A tabbar separator doesn’t exist in Windows Phone 8. On Windows Mobile/CE there are no visible tabs. Either Tabbar or Toolbar should be used in an application - Tabbar and Toolbar shouldnot be used simultaneously.

Enabling the API

This API is part of the coreapi extension that is included automatically. :::ruby extensions: [“coreapi”]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

create
(ARRAY tabElements, HASH tabBarProperties, CallBackHandler callback)

Removes the current tabbar and replaces it with this one. Callback will be called when tab is switched. Whilst the actual number of tabs you can create will depend on the memory available on your device there is an absolute upper limit of 30 tabs in any one application.

Parameters

  • tabElements : ARRAY

    Array of Tab elements.

    • tabElement : HASH

      Properties of Tab elements.

      • label : STRING

        Visible label to display on the tabbar. Label is required property. If you do not want to display label - set it to empty string.

      • action : STRING

        URL to page which will be loaded into tab. Predefined actions are not supported. It may be path to Ruby controller action; i.e. ‘/app/Account’ would load the Account index action. For ruby callback use ‘callback:/app/Account’ Or javascript method to call: ‘javascript: methodOnTab();’. Or path to html page to load.

      • icon : STRING

        Relative path to tabbar item icon in your application; typically located in /public/images/. iPhone and Android: Icons must be no more than 30x30 pixels and must be in .png format.

        Platforms:Win32, Android, iOS, WP8
      • reload : BOOLEAN Default: false

        When tab is activated - page in tab will be reloaded.

      • selectedColor : INTEGER

        Change the selected color of this tab. On Android this works only if you setup selectedColor for all tabs and also setup backgroundColor for the whole Tabbar. This property change background color on Android and icon’s color on iOS according to the platform’s UI-style specifications.

        Platforms:Win32, Android, iOS, WP8
      • disabled : BOOLEAN Default: false

        Tab will be displayed as disabled.

        Platforms:Win32, Android, iOS, WP8
      • backgroundColor : INTEGER

        Background color for tab. Use when your application background color is not white for removing blink during switch tabs.

        Platforms:Win32, Android, iOS, WP8
      • useCurrentViewForTab : BOOLEAN Default: false

        Gives a smooth transfer to a newly opened tab from the current view into this Tab and make this Tab active. Only one Tab can have this parameter.

        Platforms:WM, CE, Win32, Android, iOS
      • perishable : BOOLEAN Default: false

        Sets whether this tab is allowed to be destroyed when a memory limit is reached (Windows Mobile)

        Platforms:WM
      • createOnInit : BOOLEAN Default: false

        Create tab immediately when TabBar is created. Action also will be executed. If false, the tab will be created when it is switched to. Don’t use this parameter on the devices with a small amount of RAM.

        Platforms:WM
  • tabBarProperties : HASH

    Properties of TabBar.

    • verticalOrientation : BOOLEAN Default: false

      Creates a vertical tabbar on the iPad.

      Platforms:iOS
    • backgroundColor : INTEGER

      Background color of the tabbar.

      Platforms:Win32, Android, iOS, WP8
    • hiddenTabs : BOOLEAN Default: true

      Do not display Tabs with labels.Only hiddenTab=true is currently supported.

      Platforms:WM
    • createOnInit : BOOLEAN Default: false

      Create tabs immediately when TabBar is created. Action also will be executed. If false, then each tab will be created when first switch to the tab is executed. Don’t use this parameter on the devices with a small amount of RAM.

      Platforms:WM
    • placeTabsBottom : BOOLEAN

      Place TabBar to bottom instead of default top - only for Android.

      Platforms:Android
    • invisibleTabControl : BOOLEAN

      Make TabBar control invisible. Application developer should switch between tabs programatically.

      Platforms:iOS
  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • tab_index : INTEGER

      New tab index.

    • newTabIndex : INTEGER

      New tab index.

      Platforms:WM
    • oldTabIndex : INTEGER

      New tab index. If you switched to first activated tab, when oldTabIndex will be -1, which means that there was no old tab index exists.

      Platforms:WM
    • tabEvent : STRING

      Platforms:WM

      Possible Values :

      onTabFocus

      Fires when a tab gains focus.

      onTabNewError

      Fires when a new tab cannot be created.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.create(ARRAY tabElements, HASH tabBarProperties, CallBackHandler callback)
    • Ruby: Rho::NativeTabbar.create(ARRAY tabElements, HASH tabBarProperties, CallBackHandler callback)
currentTabIndex
()
Replaces: get_current_tab

Returns the current tab 0-based index.

Synchronous Return:

  • INTEGER

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.currentTabIndex()
    • Ruby: Rho::NativeTabbar.currentTabIndex()
remove
()

Removes all tabbar except the default tabbar whose index value is 0. Does nothing if there is no active tabbar other than tab 0.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.remove()
    • Ruby: Rho::NativeTabbar.remove()
removeTab
(INTEGER tabIndex)

Removes the Tab by index. Method will remove the WebView for the specific tab, it will not remove the tab from the tab array, so all indexes will remain the same.You cannot delete the tab with useCurrentViewForTab flag.If you switch to previously removed tab, tab will be recreated.

Parameters

  • tabIndex : INTEGER

    The index for tab (index numbered from 0) to delete.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.removeTab(INTEGER tabIndex)
    • Ruby: Rho::NativeTabbar.removeTab(INTEGER tabIndex)
setTabBadge
(INTEGER tabIndex, STRING badge)

Set the iPhone badge to tab.

Parameters

  • tabIndex : INTEGER

    The index for this tab (index numbered from 0). You can also set -1 to select current tab for set badge.

  • badge : STRING

    String for iPhone badge, such as ‘12’.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.setTabBadge(INTEGER tabIndex, STRING badge)
    • Ruby: Rho::NativeTabbar.setTabBadge(INTEGER tabIndex, STRING badge)
switchTab
(INTEGER tabIndex)

Switch active tab.

Parameters

  • tabIndex : INTEGER

    The index for this tab (index numbered from 0).

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.NativeTabbar.switchTab(INTEGER tabIndex)
    • Ruby: Rho::NativeTabbar.switchTab(INTEGER tabIndex)

Examples

Create native tabbar

Create a platform-native tabbar. Tabs can link to internal application links (such as those built with “url_for”) as well as external URLs.

function create_tabbar() {
    Rho.NativeTabbar.create([{
            label: "Home",
            action: "/app"
        }, {
            label: "example.com"
            action: "http://www.example.com"
        }], {}, tabbar_callback
    );
}

function tabbar_callback(params) {
    alert("Switching to tab "+params["tab_index"]);
}
                   
                 
def create_tabbar
    Rho::NativeTabbar.create([{
      :label => "Home",
      :action => url_for(Rho::Application.startURI)
      },
      {
      :label => "example.com",
      :action => "http://www.example.com",
      }], {}, url_for(:action => :tabbar_callback)
    )
end

def tabbar_callback
    Alert.show_popup("Switching to tab #{@params["rab_index"]}")
end
                   
                 
Switch tab

Switch the active tab.

// Make the third tab active
Rho.NativeTabbar.switchTab(2);
                   
                 
# Make the third tab active
Rho::NativeTabbar.switchTab(2);
                   
                 
Remove tabbar

Remove the tabbar.

Rho.NativeTabbar.remove();
                   
                 
Rho::NativeTabbar.remove
                   
                 

Remarks

Device Limitations With Multiple Tabs

Please consider the limitations of the device when creating multiple tabs with the Native TabBar. The number of tabs that can be created will depend on the resources of the device and the complexities of the pages displayed in those tabs but, as a general rule, a maximum of 10 tabs on an MC75a should be enforced. Also consider setting the createOnInit property to false so that not all tabs are initialized when the TabBar is first created and using the in-process engine for a more responsive experience.