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

Application

Methods9
Methods - Class
databaseFilePathexpandDatabaseBlobFilePathminimizemodelFolderPathprocessApplicationEventquitrelativeDatabaseBlobFilePathrestoresetApplicationNotify
Properties22
Class Properties
appBundleFolderappNameappsBundleFolderbadLinkURIbundleFolderconfigPathcountrydatabaseBlobFolderdefaultNativeMenuinvalidSecurityTokenStartPathlocalemodelsManifestPathnativeMenupublicFolderrhoPlatformVersionsecurityTokenNotPassedsettingsPageURIsplashstartURItitleuserFolderversion
Examples4
Get folders where items are storedMinimize your applicationQuit your applicationRestore your application

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.

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 "::" for all "." when referencing constants)
      String:Activated

      The application has been activated.

      Constant: Rho.Application.APP_EVENT_DEACTIVATED (For Ruby use "::" for all "." when referencing constants)
      String:Deactivated

      The application has been deactivated. Not supported on iOS.

      Constant: Rho.Application.APP_EVENT_UICREATED (For Ruby use "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      String:ConfigConflict

      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. To customise the native application menu and controller menu items in ruby follow Application Menu API

  • 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
    rhoPlatformVersion
    : STRING Read Only

    The version of RhoMobile platform, which was used to build the application.

    Property Access:

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