System

The System API is used to control and modify core aspects of the device such as the screen, OS and device capabilities.

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

applicationInstall
(STRING applicationUrl)
Replaces: app_install

Install an application.

Parameters

  • applicationUrl : STRING

    The url of an application to install on the device.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.applicationInstall(STRING applicationUrl)
    • Ruby: Rho::System.applicationInstall(STRING applicationUrl)
applicationUninstall
(STRING applicationName)
Replaces: app_uninstall

Uninstall the application. Not Supported on Windows CE devices.

Parameters

  • applicationName : STRING

    The name of the application.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.applicationUninstall(STRING applicationName)
    • Ruby: Rho::System.applicationUninstall(STRING applicationName)
bringToFront
()
Deprecated

Bring application window to the top of the screen.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.bringToFront()
    • Ruby: Rho::System.bringToFront()
clearNetworkStatusNotify
()
Deprecated

Use Network.clearStatusNotify: Clear network status callback.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.clearNetworkStatusNotify()
    • Ruby: Rho::System.clearNetworkStatusNotify()
deleteFolder
(STRING pathToFolder)
Deprecated

Delete folder.

Parameters

  • pathToFolder : STRING

    Path to folder.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.deleteFolder(STRING pathToFolder)
    • Ruby: Rho::System.deleteFolder(STRING pathToFolder)
deleteRegistrySetting
(HASH propertyMap)

Deletes the specified value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS.

Parameters

  • propertyMap : HASH

    Map of properties associated with the registry key being set.

    • hive : STRING

      The hive name, setRegistrySetting.

    • key : STRING

      Full path of the key, including ‘\’ separators as required. Remember to use ‘\’ in JavaScript to specify backslash.

    • setting : STRING

      The name of the setting to be deleted.

    • persistent : BOOLEAN

      If the registry value was set to be persistent, ie a corresponding .reg file was created in the \Application folder then setting true here will delete that .reg file.

Synchronous Return:

  • BOOLEAN :

    Whether or not the registry key was successfully deleted.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.deleteRegistrySetting(HASH propertyMap)
    • Ruby: Rho::System.deleteRegistrySetting(HASH propertyMap)
exit
()
Deprecated

Use Application.quit: exit application.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.exit()
    • Ruby: Rho::System.exit()
getAllProperties
(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

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

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::System.getAllProperties(CallBackHandler callback)
getProperties
(ARRAY arrayofNames, CallBackHandler callback)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

Parameters

  • arrayofNames : ARRAY

    List of properties I want to know about

    • Object : STRING

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of properties I want to know about

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

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.System.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Ruby: Rho::System.getProperties(ARRAY arrayofNames, CallBackHandler callback)
getProperty
(STRING propertyName, CallBackHandler callback)
Replaces: get_property

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

Parameters

  • propertyName : STRING

    The property to return info about.

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • STRING :

      The property to return info about.

      : 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.System.getProperty(STRING propertyName, CallBackHandler callback)
      • Ruby: Rho::System.getProperty(STRING propertyName, CallBackHandler callback)
    getRegistrySetting
    (HASH propertyMap)

    Retrieve a value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS.

    Parameters

    • propertyMap : HASH

      Map of properties associated with the registry key being set.

      • hive : STRING

        The hive name, see setRegistrySetting.

      • key : STRING

        Full path of the key, including ‘\’ separators as required. Remember to use ‘\’ in JavaScript to specify backslash.

      • setting : STRING

        The name of the setting to be retrieved.

    Synchronous Return:

    • STRING :

      Registry value of the key.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.getRegistrySetting(HASH propertyMap)
      • Ruby: Rho::System.getRegistrySetting(HASH propertyMap)
    getStartParams
    ()

    Return the command line parameters. At Android start parameters are returned as URL query string starting with ‘?’, name-value delimiter ‘=’ and name value pairs delimiter ‘&’.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.getStartParams()
      • Ruby: Rho::System.getStartParams()
    getSystemInfo
    ()

    Gathers system dependent information ( hw info, installed packages etc ). Return key/value pairs depend on platform.

    Synchronous Return:

    • HASH

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.getSystemInfo()
      • Ruby: Rho::System.getSystemInfo()
    get_locale
    ()
    Deprecated

    Use System.locale property: Current device locale.

    Synchronous Return:

    • STRING

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.get_locale()
      • Ruby: Rho::System.get_locale()
    hideSplashScreen
    ()

    Hide Splash Screen if delay is configured as -1 in rhoconfig.txt

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.hideSplashScreen()
      • Ruby: Rho::System.hideSplashScreen()
    isApplicationInstalled
    (STRING applicationName)
    Replaces: app_installed?

    Checks if the specified applicationName is installed on the device.

    Parameters

    • applicationName : STRING

      The name of the application.

    Synchronous Return:

    • BOOLEAN

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.isApplicationInstalled(STRING applicationName)
      • Ruby: Rho::System.isApplicationInstalled(STRING applicationName)
    isBlobAttr
    (STRING partition, INTEGER sourceID, STRING attrName)
    Deprecated

    Use Database.SQLite3.isBlobAttr: is model attribute is blob.

    Parameters

    • partition : STRING

    • sourceID : INTEGER

    • attrName : STRING

    Synchronous Return:

    • BOOLEAN

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.isBlobAttr(STRING partition, INTEGER sourceID, STRING attrName)
      • Ruby: Rho::System.isBlobAttr(STRING partition, INTEGER sourceID, STRING attrName)
    openUrl
    (STRING url)

    Open the application associated with the URL. Behavior may be different on different platforms and depend on installed software. For example, open URL with http:// prefix will execute the Web Browser installed on system and open URL in executed browser. Note: For opening pdf files on android devices it is necessary to add option “no_compression: [ pdf ]” to android section in build.yml. In android, “sms:”,“mailto:”,“tel:”,“http:”,“https:”,“file:” are supported. For file url the proper permission and path has to be given. For external storage space fully qualified path has to be given.(Example:-file:///storage/sdcard/sample.jpg). Hence only external storage space and userFolder are supported for file uri in android.

    Parameters

    • url : STRING

      URL as string.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.openUrl(STRING url)
      • Ruby: Rho::System.openUrl(STRING url)
    runApplication
    (STRING appName, STRING params, BOOLEAN blockingCall)
    Replaces: run_app

    Run an application.

    Parameters

    • appName : STRING

      The name of the application on the device to run. It depends from platform. On iOS it is BundleURLScheme of executed application.

    • params : STRING Optional

      Start parameters string. Executed Application can receive this string by getStartParams method. Parameter could be just value, or key-value pair separated by ‘=’ sign. Please note that for each platform there are distinct ways to write several params at once. On Android parameters should be separated by an amperstand, on other platforms by a comma or a space.

    • blockingCall : BOOLEAN Optional

      Not Implemented.

      False by default.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.runApplication(STRING appName, STRING params, BOOLEAN blockingCall)
      • Ruby: Rho::System.runApplication(STRING appName, STRING params, BOOLEAN blockingCall)
    setDoNotBackupAttribute
    (STRING pathToFile, BOOLEAN doNotBackup)
    Replaces: set_do_not_bakup_attribute

    Set do not backup attribute for file.

    Parameters

    • pathToFile : STRING

      Path to file.

    • doNotBackup : BOOLEAN

      True set doNotBackup attribute to file (exclude this file from backup), false for remove doNotBackup attribute from file.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setDoNotBackupAttribute(STRING pathToFile, BOOLEAN doNotBackup)
      • Ruby: Rho::System.setDoNotBackupAttribute(STRING pathToFile, BOOLEAN doNotBackup)
    setNetworkStatusNotify
    (STRING url, INTEGER poll_interval)
    Deprecated

    Use Network.setStatusNotify: set network notification callback.

    Parameters

    • url : STRING

      The url to the user-defined callback method.

    • poll_interval : INTEGER

      IOS. The network status polling period for systems that can not notify network status change immediately. Default value is 20 seconds.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setNetworkStatusNotify(STRING url, INTEGER poll_interval)
      • Ruby: Rho::System.setNetworkStatusNotify(STRING url, INTEGER poll_interval)
    setProperties
    (HASH propertyMap)

    This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

    Parameters

    • propertyMap : HASH

      Map of properties I want to set

      • Object : STRING

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setProperties(HASH propertyMap)
      • Ruby: Rho::System.setProperties(HASH propertyMap)
    setProperty
    (STRING propertyName, STRING propertyValue)

    This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

    Parameters

    • propertyName : STRING

      The one property name that I want to set

    • propertyValue : STRING

      The one property value that I want to set

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setProperty(STRING propertyName, STRING propertyValue)
      • Ruby: Rho::System.setProperty(STRING propertyName, STRING propertyValue)
    setPushNotification
    (STRING url, STRING url_params, STRING push_client)
    Deprecated

    Use Push.setPushNotification: Register push callback, the method to call upon receiving a push message.

    Parameters

    • url : STRING

      URL of the callback method. If empty, unregisters rhoconnect-push.

    • url_params : STRING Optional

      Parameters which will be added to callback URL.

    • push_client : STRING Optional

      Name of a push service client. Current values can be ‘rhoconnect_push’ or ‘gcm’ or ‘legacy’ or empty.

      The call will be applied to every push client.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setPushNotification(STRING url, STRING url_params, STRING push_client)
      • Ruby: Rho::System.setPushNotification(STRING url, STRING url_params, STRING push_client)
    setRegistrySetting
    (HASH propertyMap)

    Set a value in the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS.

    Parameters

    • propertyMap : HASH

      Map of properties associated with the registry key being set.

      • hive : STRING

        The hive name.

        Possible Values :

        Constant: Rho::System.REGKEY_CLASSES_ROOT (For Ruby use "::" for all "." when referencing constants)
        String:HKCR

        Set the property in the HKEY_CLASSES_ROOT hive.

        Constant: Rho::System.REGKEY_CURRENT_USER (For Ruby use "::" for all "." when referencing constants)
        String:HKCU

        Set the property in the HKEY_CURRENT_USER hive.

        Constant: Rho::System.REGKEY_LOCAL_MACHINE (For Ruby use "::" for all "." when referencing constants)
        String:HKLM

        Set the property in the HKEY_LOCAL_MACHINE hive.

        Constant: Rho::System.REGKEY_USERS (For Ruby use "::" for all "." when referencing constants)
        String:HKU

        Set the property in the HKEY_USERS hive.

      • type : STRING

        The type.

        Possible Values :

        Constant: Rho::System.REGTYPE_SZ (For Ruby use "::" for all "." when referencing constants)
        String:String

        The type of the value being set is a string.

        Constant: Rho::System.REGTYPE_BINARY (For Ruby use "::" for all "." when referencing constants)
        String:Binary

        The type of the value being set is a binary number.

        Constant: Rho::System.REGTYPE_DWORD (For Ruby use "::" for all "." when referencing constants)
        String:DWORD

        The type of the value being set is a natural number (DWORD)

        Constant: Rho::System.REGTYPE_MULTI_SZ (For Ruby use "::" for all "." when referencing constants)
        String:MultiSZ

        The type of the value being set is a multi line string. Separate your lines with \n (\n in JavaScript)

      • key : STRING

        Full path of the key, including ‘\’ separators as required. Remember to use ‘\’ in JavaScript to specify backslash.

      • setting : STRING

        The name of the registry setting to be set.

      • value : STRING

        The registry value to be set.

      • persistent : BOOLEAN

        Whether or not to create a corresponding merge file, setting to true will cause your value to persist across a device clean boot. A .reg file is written to the \Application folder on the device to persist the setting.

    Synchronous Return:

    • BOOLEAN :

      Whether or not the registry key was successfully set.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setRegistrySetting(HASH propertyMap)
      • Ruby: Rho::System.setRegistrySetting(HASH propertyMap)
    setScreenRotationNotification
    (STRING url, STRING url_params)
    Deprecated

    Use ScreenOrientation.setScreenOrientationEvent: Notify (call a callback method) when the screen rotates.

    Parameters

    • url : STRING

      URL of the callback method. If empty, unregisters notification callback.

    • url_params : STRING Optional

      Parameters which will be added to callback URL.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setScreenRotationNotification(STRING url, STRING url_params)
      • Ruby: Rho::System.setScreenRotationNotification(STRING url, STRING url_params)
    setWindowFrame
    (INTEGER x, INTEGER y, INTEGER width, INTEGER height)

    Change application window position and size.

    Parameters

    • x : INTEGER

      Left corner of window.

    • y : INTEGER

      Top corner of window.

    • width : INTEGER

      Width of window.

    • height : INTEGER

      Height of window.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setWindowFrame(INTEGER x, INTEGER y, INTEGER width, INTEGER height)
      • Ruby: Rho::System.setWindowFrame(INTEGER x, INTEGER y, INTEGER width, INTEGER height)
    setWindowPosition
    (INTEGER x, INTEGER y)

    Change application window position.

    Parameters

    • x : INTEGER

      Left corner of window.

    • y : INTEGER

      Top corner of window.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setWindowPosition(INTEGER x, INTEGER y)
      • Ruby: Rho::System.setWindowPosition(INTEGER x, INTEGER y)
    setWindowSize
    (INTEGER width, INTEGER height)

    Change application window size.

    Parameters

    • width : INTEGER

      Width of the window.

    • height : INTEGER

      Width of the of window.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.setWindowSize(INTEGER width, INTEGER height)
      • Ruby: Rho::System.setWindowSize(INTEGER width, INTEGER height)
    set_application_icon_badge
    (INTEGER badgeNumber)
    Deprecated

    Use System.applicationIconBadge: Set the application icon to have this badge number. Set to 0 (zero) to remove badge.iOS only.

    Parameters

    • badgeNumber : INTEGER

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.set_application_icon_badge(INTEGER badgeNumber)
      • Ruby: Rho::System.set_application_icon_badge(INTEGER badgeNumber)
    set_http_proxy_url
    (STRING proxyURI)
    Deprecated

    Use System.httpProxyURI property: To use client with the HTTP proxy.

    Parameters

    • proxyURI : STRING

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.set_http_proxy_url(STRING proxyURI)
      • Ruby: Rho::System.set_http_proxy_url(STRING proxyURI)
    set_locale
    (STRING locale_code, STRING country_code)
    Deprecated

    Use Application.setLocale method: set application specific locale.

    Parameters

    • locale_code : STRING

    • country_code : STRING

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.set_locale(STRING locale_code, STRING country_code)
      • Ruby: Rho::System.set_locale(STRING locale_code, STRING country_code)
    set_sleeping
    (BOOLEAN enable)
    Deprecated

    Use System.screenSleeping property: enable / disable phone sleeping.

    Parameters

    • enable : BOOLEAN

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.set_sleeping(BOOLEAN enable)
      • Ruby: Rho::System.set_sleeping(BOOLEAN enable)
    startTimer
    (INTEGER interval, STRING url, STRING url_params)
    Deprecated

    Start timer. (It’s works only with Ruby)

    Parameters

    • interval : INTEGER

      Timer interval.

    • url : STRING

      URL of the callback method.

    • url_params : STRING Optional

      Parameters which will be added to callback URL.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.startTimer(INTEGER interval, STRING url, STRING url_params)
      • Ruby: Rho::System.startTimer(INTEGER interval, STRING url, STRING url_params)
    stopTimer
    (STRING url)
    Deprecated

    Stop timer. (It’s works only with Ruby)

    Parameters

    • url : STRING

      URL of the callback method which identify the timer to stop.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.stopTimer(STRING url)
      • Ruby: Rho::System.stopTimer(STRING url)
    unset_http_proxy
    ()
    Deprecated

    Use System.httpProxyURI property: Stop using HTTP proxy that was set by the command line, rhoconfig.txt or set_http_proxy_url.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.unset_http_proxy()
      • Ruby: Rho::System.unset_http_proxy()
    unzipFile
    (STRING localPathToZip, STRING password, STRING outputFileName)

    Unzip file.

    Parameters

    • localPathToZip : STRING

      The path to the file to be unzipped. Application should have write permissions to this folder.

    • password : STRING Optional

      Password for the zip.

    • outputFileName : STRING Optional

      Output file name. Used when decompressing gzip streams.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.unzipFile(STRING localPathToZip, STRING password, STRING outputFileName)
      • Ruby: Rho::System.unzipFile(STRING localPathToZip, STRING password, STRING outputFileName)
    updateBlobAttribs
    (STRING partition, INTEGER sourceID)
    Deprecated

    Use Database.updateBlobAttribs: update model blob attributes list.

    Parameters

    • partition : STRING

    • sourceID : INTEGER

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.updateBlobAttribs(STRING partition, INTEGER sourceID)
      • Ruby: Rho::System.updateBlobAttribs(STRING partition, INTEGER sourceID)
    zipFile
    (STRING localPathToZip, STRING localPathToFile, STRING password)

    Zip one file. Zip archive must placed to the folder where application can write files.

    Parameters

    • localPathToZip : STRING

      The path to the specified zip. Application should have write permissions to this folder.

    • localPathToFile : STRING

      The path to the file to be zipped.

    • password : STRING Optional

      Password for the zip.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.zipFile(STRING localPathToZip, STRING localPathToFile, STRING password)
      • Ruby: Rho::System.zipFile(STRING localPathToZip, STRING localPathToFile, STRING password)
    zipFiles
    (STRING localPathToZip, STRING basePath, ARRAY filePathsToZip, STRING password)

    Zip list of files.

    Parameters

    • localPathToZip : STRING

      The path to the specified zip.

    • basePath : STRING

      Base path to the files to be zipped.

    • filePathsToZip : ARRAY

      List of file paths to be zipped.

    • password : STRING Optional

      Password for the zip.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.System.zipFiles(STRING localPathToZip, STRING basePath, ARRAY filePathsToZip, STRING password)
      • Ruby: Rho::System.zipFiles(STRING localPathToZip, STRING basePath, ARRAY filePathsToZip, STRING password)

    Properties

    NodejsServerPort
    : INTEGER Read Only

    Port of the local (embedded) Node.js HTTP server if it started (only for Node.js type applications).

    Default: 3000

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.NodejsServerPort
    applicationIconBadge
    : INTEGER

    Set the application icon to have this badge number. Set to 0 (zero) to remove badge.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.applicationIconBadge
    country
    : STRING Read Only

    Current device country code.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.country
    deviceName
    : STRING Read Only

    Name of device application running on. Examples: ‘9000’ (BB), ‘iPhone’, ‘dream’ (Android). In Consumer Android device, name of the Industrial Design along with manufacturer name shall be shown.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.deviceName
    deviceOwnerEmail
    : STRING Read Only

    Primary email of phone owner. To access this property ‘pim’ capability must be enabled in your build.yml.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.deviceOwnerEmail
    deviceOwnerName
    : STRING Read Only

    Name(account name) of phone owner. To access this property ‘pim’ capability must be enabled in your build.yml.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.deviceOwnerName
    devicePushId
    : STRING Read Only
    Replaces:deviceId

    Push notifications device ID which may be used to receive push messages.To get this ID , Push service should be configured on the device. Please refer to Push documentation.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.devicePushId
    externalStorageDirectoryPath
    : STRING Read Only

    Return the primary shared/external storage directory. This directory may not currently be accessible if it has been mounted by the user on their computer, has been removed from the device, or some other problem has happened.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.externalStorageDirectoryPath
    freeServerPort
    : INTEGER Read Only

    Get free local server port, available for binding.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.freeServerPort
    hasCalendar
    : BOOLEAN Read Only

    Returns true if calendar support is available.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasCalendar
    hasCamera
    : BOOLEAN Read Only

    Returns true if there is a camera available on the device.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasCamera
    hasCellNetwork
    : BOOLEAN Read Only
    Deprecated

    Use Network.hasCellNetwork to tell if device is connected to the cell network.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasCellNetwork
    hasNetwork
    : BOOLEAN Read Only
    Deprecated

    Use Network.hasNetwork to tell if the device is connected to the network.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasNetwork
    hasSqlite
    : BOOLEAN Read Only
    Deprecated

    Returns true if the device has sqlite capabilities (previously only BlackBerry did not support this).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasSqlite
    hasTouchscreen
    : BOOLEAN Read Only

    Returns true if the device has touch screen capabilities. For Win32 desktop builds this API will return whether mouse support is available.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasTouchscreen
    hasWifiNetwork
    : BOOLEAN Read Only
    Deprecated

    Use Network.hasWifiNetwork to tell if the device is connected to the wifi network.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hasWifiNetwork
    httpProxyURI
    : STRING
    Replaces:http_proxy_url

    Set HTTP proxy parameters for using the Network module. Example: ‘user:password@url:port’. Supports basic authentication only. Do not include ‘http://’. Setting this property overrides http_proxy_uri, http_proxy_host, http_proxy_port, http_proxy_user and http_proxy_password. Proxy settings for Windows Mobile/CE with Zebra WebKit should be configured in the config.xml file.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.httpProxyURI
    isEmulator
    : BOOLEAN Read Only

    Returns true if the application is running on a platform emulator.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.isEmulator
    isRhoSimulator
    : BOOLEAN Read Only

    Returns true if the application is running on RhoSimulator.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.isRhoSimulator
    isSymbolDevice
    : BOOLEAN Read Only

    Returns true if the device supports Symbol device capabilities. APIs will indicate if the property or method is available on Symbol devices only. You can use this property to help your application decide when to take advantage of advanced Symbol capabilities.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.isSymbolDevice
    keyboardState
    : STRING

    For Windows Mobile and Windows CE the keyboard can be manually shown or hidden as required. All other platforms only support ‘automatic’. The default state for Windows Mobile and Windows CE is manual, for all other platforms it is automatic.

    Default: See Description

    Possible Values (STRING):

    Constant: Rho.System.KEYBOARD_SHOWN (For Ruby use "::" for all "." when referencing constants)
    String: shown

    Shows the on screen keyboard, after setting the keyboard to shown or hidden it will no longer appear / disappear automatically until you set this property to automatic.

    Constant: Rho.System.KEYBOARD_HIDDEN (For Ruby use "::" for all "." when referencing constants)
    String: hidden

    Hides the on screen keyboard, after setting the keyboard to shown or hidden it will no longer appear / disappear automatically until you set this property to automatic. This is most useful if your device has a hardware keyboard or you are scanning / capturing data to an input field.

    Constant: Rho.System.KEYBOARD_AUTOMATIC (For Ruby use "::" for all "." when referencing constants)
    String: automatic

    Automatically shows or hides the keyboard as needed by the application.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.keyboardState
    localServerPort
    : INTEGER Read Only

    Port of the local (embedded) HTTP server. This parameter is mainly for debug purposes. If not specified, the platform will detect a free port on the device and use that one.

    Default: 8080

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.localServerPort
    locale
    : STRING Read Only

    Current device locale Like ‘en’, ‘ru’ etc.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.locale
    lockWindowSize
    : BOOLEAN

    Lock / unlock the window size change by the user. When running on RhoSimulator, this method is supported only for Windows OS.

    Default: false

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.lockWindowSize
    oemInfo
    : STRING Read Only

    The OEM Information string for the terminal.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.oemInfo
    osVersion
    : STRING Read Only

    Version OS of device. Examples: ‘4.1’ (Android).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.osVersion
    phoneId
    : STRING Read Only

    Hardware based ID. It depends on capabilities configured for an application and has to remain same even across application uninstall/install.(except iOS ! - on iOS unisntall/reinstall will update this property - used UIDebice.identifierForVendor)

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.phoneId
    platform
    : STRING Read Only

    Platform where application is running.

    Possible Values (STRING):

    Constant: Rho.System.PLATFORM_WM_CE (For Ruby use "::" for all "." when referencing constants)
    String: WINDOWS
    Constant: Rho.System.PLATFORM_ANDROID (For Ruby use "::" for all "." when referencing constants)
    String: ANDROID
    Constant: Rho.System.PLATFORM_IOS (For Ruby use "::" for all "." when referencing constants)
    String: APPLE
    Constant: Rho.System.PLATFORM_WP8 (For Ruby use "::" for all "." when referencing constants)
    String: WP8
    Constant: Rho.System.PLATFORM_SAILFISH (For Ruby use "::" for all "." when referencing constants)
    String: SAILFISH
    Constant: Rho.System.PLATFORM_UWP (For Ruby use "::" for all "." when referencing constants)
    String: UWP
    Constant: Rho.System.PLATFORM_WINDOWS_DESKTOP (For Ruby use "::" for all "." when referencing constants)
    String: WINDOWS_DESKTOP

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.platform
    ppiX
    : INTEGER Read Only

    Horizontal PPI (Pixels Per Inch).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.ppiX
    ppiY
    : INTEGER Read Only

    Vertical PPI (Pixels Per Inch).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.ppiY
    realScreenHeight
    : INTEGER Read Only

    Screen height in real pixels.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.realScreenHeight
    realScreenWidth
    : INTEGER Read Only

    Screen width in real pixels.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.realScreenWidth
    screenAutoRotate
    : BOOLEAN

    Screen auto rotate.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.screenAutoRotate
    screenHeight
    : INTEGER Read Only

    Screen height in logical pixels (used for set coordinates).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.screenHeight
    screenOrientation
    : STRING Read Only

    Current screen orientation.

    Possible Values (STRING):

    Constant: Rho.System.SCREEN_PORTRAIT (For Ruby use "::" for all "." when referencing constants)
    String: portrait

    The return value if the screen is in portrait mode.

    Constant: Rho.System.SCREEN_LANDSCAPE (For Ruby use "::" for all "." when referencing constants)
    String: landscape

    The return value if the screen is in landscape mode.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.screenOrientation
    screenSleeping
    : BOOLEAN

    If true, then screen will go to sleep by system inactivity timeout. If false then screen never go to sleep while application is in foreground.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.screenSleeping
    screenWidth
    : INTEGER Read Only

    Screen width in logical pixels (used for set coordinates).

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.screenWidth
    uuid
    : STRING Read Only

    The Unique Unit IDentifier for the terminal.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.uuid
    webviewFramework
    : STRING Read Only

    Browser framework identity string.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.webviewFramework

    Examples

    Get device capabilities

    You can find out whether the device has access to several system-dependent features such as calendar, camera, touchscreen, etc.

    // Returns true if device supports Symbol device capabilities, such as Scanner, etc.
    var is_symbol_device = Rho.System.isSymbolDevice;
    
    var has_calendar = Rho.System.hasCalendar;
    var has_camera = Rho.System.hasCamera;
    var has_cell_network = Rho.System.hasCellNetwork;
    var has_wifi_network = Rho.System.hasWifiNetwork;
    var has_network = Rho.System.hasNetwork;
    var has_sqlite = Rho.System.hasSqlite;
    var has_touchscreen = Rho.System.hasTouchscreen;
    
    message = "Symbol device: "+is_symbol_device+"\n"+
      "Calendar: "+has_calendar+"\n"+
      "Camera: "+has_camera+"\n"+
      "Cell network: "+has_cell_network+"\n"+
      "WiFi: "+has_wifi_network+"\n"+
      "Network: "+has_network+"\n"+
      "SQLite: "+has_sqlite+"\n"+
      "Touchscreen: "+has_touchscreen;
    
    alert(message);
    
                                
    # Returns true if device supports Symbol device capabilities, such as barcode scanner, etc.
    is_symbol_device = Rho::System.isSymbolDevice
    
    has_calendar = Rho::System.hasCalendar
    has_camera = Rho::System.hasCamera
    has_cell_network = Rho::System.hasCellNetwork
    has_wifi_network = Rho::System.hasWifiNetwork
    has_network = Rho::System.hasNetwork
    has_sqlite = Rho::System.hasSqlite
    has_touchscreen = Rho::System.hasTouchscreen
    
    message = "
    Symbol device: #{is_symbol_device}
    Calendar: #{has_calendar}
    Camera: #{has_camera}
    Cell network: #{has_cell_network}
    WiFi: #{has_wifi_network}
    Network: #{has_network}
    SQLite: #{has_sqlite}
    Touchscreen: #{has_touchscreen}
    "
    Alert.show_popup(message)
    
                                
    Get version information

    Retrieve the version of the underlying Operating System.

    var version_info = Rho.System.osVersion;
    alert(version_info);
    
                                    
    version_info = Rho::System.osVersion
    Alert.show_popup(version_info)
    
                                    
    Install / uninstall other applications

    You can ask the system to install or uninstall a different application. This feature is useful for installing sub-applications, custom upgrades, etc.

    // install an application from given url
    Rho.System.applicationInstall("/bin/target/android/rhodes-app-debug.apk");
    
    // uninstall the application
    Rho.System.applicationUninstall("rhodes-app");
    
                                    
    #install an application from given url
    Rho::System.applicationInstall("/bin/target/android/rhodes-app-debug.apk")
    
    # uninstall the application
    Rho::System.applicationUninstall("rhodes-app")
    
                                    
    Get the local server port for debug purposes

    If necessary, you can read the embedded HTTP server’s port, for debugging purposes.

    // Get port of the local (embedded) HTTP server
    var local_port = Rho.System.localServerPort;
    alert(local_port);
    
                                    
    # Get port of the local (embedded) HTTP served
    local_port = Rho::System.localServerPort()
    Alert.show_popup(local_port)
    
                                    
    Zipping and unzipping files

    If you ever need to build or extract zip archives, RhoMobile includes easy-to-use APIs for this task.

    // unzip file
    Rho.System.unzipFile("/app/public/sample.zip");
    
    // zip file
    Rho.System.zipFile("/app/public/zipfile.zip", "/app/public/sample.txt");
    
                                    
    # unzip a file
    Rho::System.unzipFile("/app/public/sample.zip")
    
    # zip a file
    Rho::System.zipFile("/app/public", "/app/public/sample.txt")
    
                                    
    Working with the Windows Registry

    On devices running Windows Mobile, Windows CE, Windows Embedded Handheld and Windows Embedded CE it is possible to interact with the registry, this example shows how to do that.

    #/app/Model
    
    #  Retrieve a value from the Registry
    def get_registry_sync
        theRegSetting = Rho::System.getRegistrySetting({hive:'HKLM', key:'software', Setting:'RhoElementsTest'})
        puts "Registry Setting retrieved: #{theRegSetting}"
    end
    
    #  Set a value in the registry which will persist across a clean boot of the device
    def set_registry_sync
        theRegSetting = Rho::System.setRegistrySetting({hive:'HKLM', type:'String', key:'Software', setting:'RhoElementsTest', value:'MVC ftw', persistent:true})
        puts "Registry Setting Success?: #{theRegSetting}"
    end
    
    #  Delete a value from the registry
    def delete_registry_sync
        theRegSetting = Rho::System.deleteRegistrySetting({hive:'HKLM', key:'Software', setting:'RhoElementsTest', persistent:true})
        puts "Registry Deleting Success?: #{theRegSetting}"
    end