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

Application

Methods 9  
Properties 21
Examples 5

The Application class is used for accessing or setting application level configuration settings.

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

databaseFilePath(STRING partitionName)

Path to database file by partition name. Please note that this function does not create a database file. This function only generates the file path based on the application path and partition name.

Parameters

  • partitionName : STRING

    Partition name.

Synchronous Return:

  • STRING :

    Full path to the database file for given partition.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.databaseFilePath(STRING partitionName)
    • Ruby: Rho::Application.databaseFilePath(STRING partitionName)

expandDatabaseBlobFilePath(STRING relativePath)

Generates the absolute path to database blob file. Please note that this function does not the create database file. This function only generates the file path based on application path and partition name.

Parameters

  • relativePath : STRING

    Relative path to the blob file, as it is stored in the database.

Synchronous Return:

  • STRING :

    Full path to the database blob.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.expandDatabaseBlobFilePath(STRING relativePath)
    • Ruby: Rho::Application.expandDatabaseBlobFilePath(STRING relativePath)

minimize()

Minimize or move the application to background. When running in RhoSimulator this method is supported only for Windows OS.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.minimize()
    • Ruby: Rho::Application.minimize()

modelFolderPath(STRING name)

Folder of the model by name.

Parameters

  • name : STRING

    Model name.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.modelFolderPath(STRING name)
    • Ruby: Rho::Application.modelFolderPath(STRING name)

processApplicationEvent(STRING applicationEvent, HASH eventData)

Ruby applications must use this method for processing of the application Event. May be called from setApplicationNotify callback.This method should be called for each event. The only exception is SyncUserChanged, where you can choose your own reset database logic.

Parameters

  • applicationEvent : STRING

    See setApplicationNotify for applicationEvent values.

  • eventData : HASH

    This will only contain values for the APP_EVENT_CONFIGCONFLICT event. This event may be triggered after an application was upgraded. If your rhoconfig.txt file contains custom properties that are different then what is being provided in the application upgrade package. By default local values are kept in place but you may overwrite configuration with new values and any other steps required for your application upgrade. eventData will be a hash. It will look like {“conflicting key” : [“new value”,“old value”].. }

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Ruby: Rho::Application.processApplicationEvent(STRING applicationEvent, HASH eventData)

quit()

Quit the application.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.quit()
    • Ruby: Rho::Application.quit()

relativeDatabaseBlobFilePath(STRING absolutePath)

Generates the relative path to database blob file. Please note that this function does not create a database file. This function only generates the file path based on the application path and partition name.

Parameters

  • absolutePath : STRING

    Absolute path to database blob file.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.relativeDatabaseBlobFilePath(STRING absolutePath)
    • Ruby: Rho::Application.relativeDatabaseBlobFilePath(STRING absolutePath)

restore()

Restores the application to be in the foreground. When running in RhoSimulator the method is supported only for windows OS.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Application.restore()
    • Ruby: Rho::Application.restore()

setApplicationNotify(CallBackHandler callback)

This method allows your application to register for application specific events like application activation/deactivation, UI creation/destruction as well as others. Check the Callback tab for details.

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • applicationEvent : STRING

      Possible Values :

      Constant: Rho.Application.APP_EVENT_ACTIVATED (For Ruby use "::" instead of ".")
      String:Activated

      The application has been activated.

      Constant: Rho.Application.APP_EVENT_DEACTIVATED (For Ruby use "::" instead of ".")
      String:Deactivated

      The application has been deactivated.

      Constant: Rho.Application.APP_EVENT_UICREATED (For Ruby use "::" instead of ".")
      String:UICreated

      Generated before the start page is loaded. There are no means to set callback and catch event in javascript. Ruby Application class descendant can to set callback and process this event.

      Constant: Rho.Application.APP_EVENT_UIDESTROYED (For Ruby use "::" instead of ".")
      String:UIDestroyed

      This event is triggered when the application is closing and the UI has been cleared.

      Constant: Rho.Application.APP_EVENT_SCREEN_OFF (For Ruby use "::" instead of ".")
      String:ScreenOff

      Device screen was turned off when power button was pressed or due to idle timeout. NB: On iOS application is also deactivated (APP_EVENT_DEACTIVATED is fired). On Android the application is not deactivated.Not supported on Windows CE.

      Platforms:

      Android, iOS, WM

      Constant: Rho.Application.APP_EVENT_SCREEN_ON (For Ruby use "::" instead of ".")
      String:ScreenOn

      Device screen was turned on and unlocked.Not supported on Windows CE.

      Platforms:

      Android, iOS, WM

      Constant: Rho.Application.APP_EVENT_SYNCUSERCHANGED (For Ruby use "::" instead of ".")
      String:SyncUserChanged

      Event when the current RhoConnect user has changed. This is available under Ruby Only.

      Constant: Rho.Application.APP_EVENT_CONFIGCONFLICT (For Ruby use "::" instead of ".")
      String:ConfigConflict

      This is available under Ruby Only.

      Constant: Rho.Application.APP_EVENT_DBMIGRATESOURCE (For Ruby use "::" instead of ".")
      String:DBMigrateSource

      This is available under Ruby Only.

    • eventData : HASH

      This will only contain values for the APP_EVENT_CONFIGCONFLICT event. This event may be triggered after an application was upgraded. If your rhoconfig.txt file contains custom properties that are different then what is being provided in the application upgrade package. By default local values are kept in place but you may overwrite configuration with new values and any other steps required for your application upgrade. eventData will be a hash. It will look like {“conflicting key” : [“new value”,“old value”].. }

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.Application.setApplicationNotify(CallBackHandler callback)
    • Ruby: Rho::Application.setApplicationNotify(CallBackHandler callback)

Properties

appBundleFolder : STRING Read Only

Path to apps/app folder inside the application bundle.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.appBundleFolder
    • Ruby: Rho::Application.appBundleFolder

appName : STRING Read Only

Application name.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.appName
    • Ruby: Rho::Application.appName

appsBundleFolder : STRING Read Only

Path to apps folder inside the application bundle.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.appsBundleFolder
    • Ruby: Rho::Application.appsBundleFolder

badLinkURI : STRING Read Only

Bad link URI to navigate in browser. This is defined in config.xml: Navigation\BadLinkURI.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.badLinkURI
    • Ruby: Rho::Application.badLinkURI

bundleFolder : STRING Read Only

Path to application bundle folder.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.bundleFolder
    • Ruby: Rho::Application.bundleFolder

configPath : STRING Read Only

Path to the configuration file.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.configPath
    • Ruby: Rho::Application.configPath

country : STRING Read Only

Current application country code.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Ruby: Rho::Application.country

databaseBlobFolder : STRING Read Only

Path to folder where the database blob files are stored. Blobs are usually images or binary files. In the ORM Model you would specify that the attribute is of type blob Ex. When capturing an image, the actual file is saved in the databaseBlobFolder.

Property Access:

  • Class: This property can only be accessed via the API class object.
    • Javascript: Rho.Application.databaseBlobFolder
    • Ruby: Rho::Application.databaseBlobFolder

defaultNativeMenu : ARRAY Read Only

Native Menu items.

  • Object : HASH

    Same values as nativeMenu.

    • Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.defaultNativeMenu
      • Ruby: Rho::Application.defaultNativeMenu

    invalidSecurityTokenStartPath : STRING Read Only

    Page to navigate to in case of check of SecurityToken failed. Can be set in rhoconfig.txt: invalid_security_token_start_path;

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.invalidSecurityTokenStartPath
      • Ruby: Rho::Application.invalidSecurityTokenStartPath

    locale : STRING Read Only

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

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Ruby: Rho::Application.locale

    modelsManifestPath : STRING Read Only

    Path to file with the model list.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.modelsManifestPath
      • Ruby: Rho::Application.modelsManifestPath

    nativeMenu : ARRAY

    Native Menu items.

  • Object : HASH

    • label : STRING

      Visible label.

    • action : STRING

      URL to page which will be loaded into tab. 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.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.nativeMenu
      • Ruby: Rho::Application.nativeMenu

    publicFolder : STRING Read Only

    Path to the application’s public folder.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.publicFolder
      • Ruby: Rho::Application.publicFolder

    securityTokenNotPassed : BOOLEAN Read Only

    Is the security token check was failed. Security token can be set in build.yml: security_token. Same security token should be passed as command line parameter ‘-security_token=token_value’ to application. If security token check failed : if this page exist then application navigate to it, otherwise application will exit.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.securityTokenNotPassed
      • Ruby: Rho::Application.securityTokenNotPassed

    settingsPageURI : STRING

    Settings page URI. Will be used when Options menu or toolbar item is chosen by user.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.settingsPageURI
      • Ruby: Rho::Application.settingsPageURI

    splash : STRING Read Only

    Splash screen image display options. This a string with several parameters divided by ‘;’: delay=5;center;hcenter;vcenter;vzoom;hzoom;zoom.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.splash
      • Ruby: Rho::Application.splash

    startURI : STRING

    Startup page for your application.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.startURI
      • Ruby: Rho::Application.startURI

    title : STRING

    Define Window caption text. If missed – caption from page used. Not supported on Windows CE devices.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.title
      • Ruby: Rho::Application.title

    userFolder : STRING Read Only

    Path to folder where the application can write files and create subfolders.

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.userFolder
      • Ruby: Rho::Application.userFolder

    version : STRING Read Only

    Version from build time configuration file (build.yml).

    Property Access:

    • Class: This property can only be accessed via the API class object.
      • Javascript: Rho.Application.version
      • Ruby: Rho::Application.version

    Examples

    Set the locale

    If your application is internationalized, you may want to set the locale depending on the user’s preference.

    Rho.Application.setLocale('en')
var current_locale = Rho.Application.locale();
alert(current_locale)
                   
                 
    Rho::Application.setLocale('en')
current_locale = Rho::Application.locale
Alert.show_popup(current_locale)
    Get folders where items are stored

    There are times where you need access to files bundled with your application, or to write files to a safe folder. These examples show how to retrieve each of the several important folders available.

         // Get and show the various app folders
     var appFolder = Rho.Application.appBundleFolder;
     var appsBundleFolder = Rho.Application.appsBundleFolder;
     var databaseBlobFolder = Rho.Application.databaseBlobFolder;
     var publicFolder = Rho.Application.publicFolder;
     var userFolder = Rho.Application.userFolder;
     
     var message = "App bundle folder: "+appFolder+"\n"+
     "Apps bundle folder: "+appsBundleFolder+"\n"+ 
     "Database blob folder: "+databaseBlobFolder+"\n"+ 
     "Public folder: "+publicFolder+"\n"+ 
     "User folder: "+userFolder;
     
     alert(message);
                   
                 
    # Get and show the various app folders
appFolder = Rho::Application.appBundleFolder
appsBundleFolder = Rho::Application.appsBundleFolder
databaseBlobFolder = Rho::Application.databaseBlobFolder
publicFolder = Rho::Application.publicFolder
userFolder = Rho::Application.userFolder

message = "App bundle folder: "+appFolder+"\n"+
"Apps bundle folder: "+appsBundleFolder+"\n"+ 
"Database blob folder: "+databaseBlobFolder+"\n"+ 
"Public folder: "+publicFolder+"\n"+ 
"User folder: "+userFolder
    
Alert.show_popup(message)
    Minimize your application

    This will minimize your application.

    Rho.Application.minimize();
                 
    Rho::Application.minimize
    Quit your application

    This will exit your application.

    Rho.Application.quit();
                 
    Rho::Application.quit
    Restore your application

    This will restore you application.

    Rho.Application.restore();
                 
    Rho::Application.restore