Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

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.

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

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.

JavaScript Ruby iphone, ipod touch, ipad

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Phone 8, Windows Embedded 8 Windows Desktop

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.

JavaScript
Ruby

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.

JavaScript
Ruby

// Make the third tab active
Rho.NativeTabbar.switchTab(2);

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

Remove tabbar

Remove the tabbar.

JavaScript
Ruby

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.

NativeTabbar

Methods - Class

Enabling the API

JavaScript Usage

Ruby Usage

Methods

Examples

Remarks