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 databaes 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)

Default processing of an 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

    Event specific data.

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)

Set application activation/deactivation callback.

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • applicationEvent : STRING

      Possible Values :

      Application.APP_EVENT_ACTIVATED - (Activated)
      The application has been activated
      Application.APP_EVENT_DEACTIVATED - (Deactivated)
      The application has been deactivated
      Application.APP_EVENT_UICREATED - (UICreated)
      APP_EVENT_UICREATED is 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.
      Application.APP_EVENT_UIDESTROYED - (UIDestroyed)
      This event is triggered when the application is closing and the UI has been cleared.
      Application.APP_EVENT_SYNCUSERCHANGED - (SyncUserChanged)
      Event when the current RhoConnect user has changed. This is available under Ruby Only
      Application.APP_EVENT_CONFIGCONFLICT - (ConfigConflict)
      This is available under Ruby Only.
      Application.APP_EVENT_DBMIGRATESOURCE - (DBMigrateSource)
      This is available under Ruby Only.
    • eventData : HASH

      Event specific data.

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 attibute 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 for 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 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 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 choosed 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