System API

Provides access to system information.

For code examples, see Rhodes System API Samples view file and Rhodes System API Samples System Test.

• Using JavaScript API
• get_property
• app_install
• app_installed?
• app_uninstall
• exit
• get_start_params
• open_url
• run_app
• set_application_icon_badge
• set_locale
• set_http_proxy_url
• unset_http_proxy
• set_network_status_notify
• clear_network_status_notify
• set_screen_rotation_notification
• set_sleeping
• set_push_notification
• set_window_frame
• set_window_position
• set_window_size
• lock_window_size
• unzip_file
• zip_file
• zip_files

Using JavaScript API

You can call some of the System methods from JavaScript as well as Ruby. To use the JavaScript API, add the public/js/rho_javascript_api.js file – created at build time as part of the application package – to the .html, .erb, or .js file calling the JavaScript method.

The JavaScript API methods with a return value can pass it as a parameter in jQuery-compatible continuation (deferred object, a kind of callback). Possible continuations to handle are done, fail, and complete.

Rho.Class.method(params).done(function(handler) { /* handler... */ })

You must enable JavaScript by putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

You must have a RhoElements license to use the JavaScript API.

get_property

Get the value of a system property.

Ruby syntax:

System.get_property(system_property)

JavaScript syntax:

Rho.System.get_property(system_property)

system_property can be any of the properties below:

• platform - APPLE, Blackberry, WINDOWS, ANDROID, WINDOWS_DESKTOP, SYMBIAN
• has_camera - is camera available on the device
• screen_width - screen width in logical pixels (used for set coordinates)
• screen_height - screen height in logical pixels (used for set coordinates)
• real_screen_width - screen width in real pixels
• real_screen_height - screen height in real pixels
• screen_orientation - screen orientation ‘portrait’, ‘landscape’
• ppi_x - horizontal PPI (Pixels Per Inch)
• ppi_y - vertical PPI (Pixels Per Inch)
• has_network - is device connected to the network
• has_cell_network - is device connected to the cell network
• has_wifi_network - is device connected to the wifi network
• device_owner_email - primary email of phone owner (works only on Android)
• device_owner_device_owner_name - name(account name) of phone owner (works only on Android)
• device_id - returns device ID which may be used to receive push messages. This is not phone device id, this is PUSH device id - you should register your phone for PUSH before you get this parameter. Read Push Notification documentation about it. On iPhone, it may be empty right after application started while Rhodes registers to receive PUSH notifications; you should wait till it become non-empty.
• phone_id - returns hardware based id. It depends on capabilities configured for an application and has to remain same even across application uninstall/install.
• full_browser - is full browser in the WebView control on Blackberry (see Blackberry browser support in device capabilities for more details)
• device_name - name of device application running on. Examples: ‘9000’ (BB), ‘iPhone’, ‘dream’ (Android)
• os_version - version of OS of device. Examples: ‘4.6.0.192’ (BB), ‘3.0’ (iPhone), ‘1.6’ (Android)
• locale - current language like ‘en’, ‘ru’ etc.
• country - country abbreviation
• is_emulator - return true if application is running on emulator
• has_calendar - return true if calendar support is available. By default, Calender db is empty. Please ensuer that you have configured and synced your Email/Calendar prior to this.
• is_motorola_device – return true if device supports Zebra device capabilities, such as Scanner, etc.

app_install

Install an application.

System.app_install(url)

app_installed?

Returns true if the specified application is installed on the device. See System.run_app for appname information.

System.app_installed?(appname)

app_uninstall

Uninstall an application. See System.run_app for appname information.

System.app_uninstall(appname)

exit

Exit the application.

System.exit

get_start_params

Return the command line parameters as a string (iPhone only). Resetting when the application goes to background. If your URLBundle is “myapp” and you open application by url: “myapp:/app/page1”, then start params will be “/app/page1”.

System.get_start_params()

open_url

Open the application associated with the URL. Used to prepare for printing.

Ruby syntax:

System.open_url(url)

JavaScript syntax:

Rho.System.open_url(url)

Note: On iPhone, if you post path of local file, then the specific iOS control (UIDocumentInteractionController) where the file will previewed and user will be able to open this file by selected application which supported this filetype.

run_app

Run an application.

System.run_app(appname, params)

iPhone: appname is the same with registered application URL scheme. params is string. Example:

System.run_app('myapp', 'someparams'). 

This call is the same as:

System.open_url('myapp:someparams')

Android: appname is package name: com.<vendor>.<app_name>. For example:

System.run_app('com.rhomobile.store', 'someparams')

Windows Mobile, Windows CE: appname is path in registry: <vendor> <app_name>/<app_name>.exe. For example:

System.run_app('rhomobile store/store.exe', 'someparams')

Windows Desktop: appname is path in registry: <vendor>/<app_name>/<app_name>.exe. For example:

System.run_app('rhomobile/store/store.exe', 'someparams')

Blackberry: appname is <app_name>. For example:

System.run_app('store', 'someparams')

set_application_icon_badge

Set application icon badge number – only for iPhone.

System.set_application_icon_badge(badge_number)

set_locale

Switch application locale at runtime. This does not change OS Locale, it will change only the LocalizationSimplified locale used in helper methods. See Localization in Device Capabilities for more information.

System.set_locale('es') # set current locale to Spanish

To get current application Locale:

LocalizationSimplified::get_cur_locale #get current application locale

set_http_proxy_url

To use client with the HTTP proxy, you should pass its URL as the first command line argument -http_proxy_url=http://<login>:<passwod>@<host>:<port> (Windows Desktop only), add it to rhoconfig.txt, or call the setter method from Ruby code (only for Windows Mobile, WinCE and Windows Desktop).

System.set_http_proxy_url(url)

unset_http_proxy

Stop using HTTP proxy that was set by the command line, rhoconfig.txt or set_http_proxy_url (only for Windows Mobile, WinCE and Windows Desktop).

System.unset_http_proxy()

set_network_status_notify

Set a network status notification for a callback which receives notifications when the network goes up or down. This callback application can check if there are any local changes and perform a full sync if necessary. Full sync method will be extended with parameter to sync only models with local changes, so sync time will be minimized.

Platforms: iPhone, Android, Windows Mobile, and WinCE.

System.set_network_status_notify(callback, poll_interval)

On iOS, network status is polled with a period specified in the poll_interval parameter. {See Reachability on the Apple developer site](http://developer.apple.com/library/ios/#samplecode/Reachability/Introduction/Intro.html).

On Android, network status changes can be asynchronously monitored via BroadcastReceiver mechanism.

Two parameters are passed to the user-defined callback.

clear_network_status_notify

Clear network status callback from set_network_status_notify so notifications will not be fired.

Platforms: iPhone, Android, Windows Mobile, and WinCE.

System.clear_network_status_notify()

set_screen_rotation_notification

Notify (call a callback method) when the screen rotates.

System.set_screen_rotation_notification(callback_url, params)

set_sleeping

Set to true/false (0/1) to enable/disable phone sleeping. For iOS, Android, and Blackberry.

System.set_sleeping

set_push_notification

Register push callback, the method to call upon receiving a push message.

System.set_push_notification(url, url_params, push_client)

set_window_frame

Change application window position and size. Implemented only for Windows desktop.

System.set_window_frame(x,y,width,height)

set_window_position

Change application window position. Implemented only for Windows desktop.

System.set_window_position(x,y)

set_window_size

Change application window size. Implemented only for Windows desktop.

System.set_window_size(width,height)

lock_window_size

Lock/unlock the window size change by the user. Implemented only for Windows desktop.

System.lock_window_size(locked)

unzip_file

Ruby syntax:

System.unzip_file(local_path_to_zip)

JavaScript syntax:

Rho.System.unzip_file(local_path_to_zip)

zip_file

Zip one file to a specified zip.

Ruby syntax:

System.zip_file(local_path_to_zip, local_path_to_file, password)

JavaScript syntax:

Rho.System.zip_files(local_path_to_zip, local_path_to_file, password)

zip_files

Zip several files to a specified zip.

Ruby syntax:

System.zip_files(local_path_to_zip, base_path, array_of_files_to_be_zipped, password)

JavaScript syntax:

Rho.System.zip_files(local_path_to_zip, base_path, array_of_files_to_be_zipped, password)