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

Application

Methods 9  
Properties 21
Examples 4

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 the ORM 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. Quitting the application while license screen is shown will be slightly delayed.

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 section 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 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. Note: 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:

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

appName : STRING Read Only

Application name.

Property Access:

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

appsBundleFolder : STRING Read Only

Path to apps folder inside the application bundle.

Property Access:

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

badLinkURI : STRING Read Only

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

Property Access:

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

bundleFolder : STRING Read Only

Path to application bundle folder.

Property Access:

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

configPath : STRING Read Only

Path to the configuration file.

Property Access:

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

country : STRING Read Only

Current application country code.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.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:

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

defaultNativeMenu : ARRAY Read Only

Native Menu items.

  • Object : HASH

    Same values as nativeMenu.

    • Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.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:

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

    locale : STRING Read Only

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

    Property Access:

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

    modelsManifestPath : STRING Read Only

    Path to file with the model list.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.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:

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

    publicFolder : STRING Read Only

    Path to the application’s public folder.

    Property Access:

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

    securityTokenNotPassed : BOOLEAN Read Only

    Indicates if 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:

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

    settingsPageURI : STRING

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

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.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:

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

    startURI : STRING

    Startup page for your application.

    Property Access:

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

    title : STRING

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

    Property Access:

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

    userFolder : STRING Read Only

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

    Property Access:

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

    version : STRING Read Only

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

    Property Access:

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

    Examples

    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