Developer Resources

HostApp

Overview

The HostApp class is an important class for interfacing with the host application. It provides access to the host application's frame, menus, document infrastructure, job queue, and other important aspects.

Events

HostApp.activeChildChanged
Fired when the active child document changes.
HostApp.commandEntered
Fired when a command is entered in the console.
HostApp.frameDestroyed
Fired when the main application frame is destroyed.
HostApp.locationChanged
Fired when the location in the URL bar changes.

Methods

HostApp.checkVersion
Checks the version number of the host application
HostApp.close
Closes a specified document window
HostApp.crash
Simulates a host application crash
HostApp.createDatabase
Creates a new database
HostApp.execute
Executes a script, template, or executable object in the host application
HostApp.executeAndWait
Executes a script, template, or executable object in the host application in synchronous fashion
HostApp.exit
Causes the host application to exit
HostApp.getActiveDocument
Returns the active document
HostApp.getApplicationId
Returns the application identification tag
HostApp.getCommandLineArguments
Returns an array of command line arguments
HostApp.getCurrentLocation
Returns the current location in the URL bar.
HostApp.getDatabase
Returns the application's current database connection
HostApp.getDocumentById
Returns an array of open documents in the program.
HostApp.getDocuments
Returns an array of open documents in the program.
HostApp.getFrameCaption
Gets the frame's caption
HostApp.getFrameMenu
Returns an object representing the frame's menu bar
HostApp.getVersion
Returns the version of the host application as a string
HostApp.hang
Simulates a host application crash
HostApp.isGuiActive
Returns true if a user interface is present
HostApp.newDocument
Creates a new document in the host application
HostApp.open
Opens a database table, document, or web page
HostApp.openDatabase
Opens a new database project in the host application
HostApp.openWeb
Opens a web document.
HostApp.refresh
Refreshes the host application's panels
HostApp.sendWebRequest
Sends a web request
HostApp.setFrameCaption
Sets the frame's caption
HostApp.showFrame
Shows or hides the host application's main window
HostApp.showJobManager
Shows the host application's job manager

Example

// example 1: getting a list of open documents and closing
// the documents that begin with "http"


// get all the host application's open documents, which 
// are returned by HostApp.getDocuments() as an array of 
// HostDocument objects
var g_all_documents;
g_all_documents = HostApp.getDocuments();

for (var doc in g_all_documents)
{
    // for each open document, find the location
    var location;
    location = g_all_documents[doc].getLocation();
    
    // if the location starts with http, close it; note: 
    // this doesn't close all web documents, but only
    // those that start with http; this is simply to
    // demonstrate some of the functions for working with
    // open host documents
    if (location.substr(0,4) == "http")
        HostApp.close(g_all_documents[doc]);
}



// example2: storing a list of browsed locations in a
// database table


// create a browse history object and call Application.run(), 
// which starts the event loop that processes frame events
var history = new BrowseHistory();
Application.run();


// browse history class definition
class BrowseHistory
{
    // class member variables for the local database and output table
    var m_db = HostApp.getDatabase();
    var m_table = "browse_history";

    function BrowseHistory()
    {
        // note: this is the browse history class constructor
        // and is called when a browse history object is created;
        // this constructor simply connects the host application 
        // location changed event to the onLocationChanged function
 
        // connect the onLocationChanged event handler to process
        // location changed events
        HostApp.locationChanged.connect(this, onLocationChanged);
    }

    function onLocationChanged(sender, evt)
    {
        // note: this function is called when the host application
        // location changed event is fired; when this happens, this
        // function checks if a browse history table exists, and if 
        // it doesn't, it creates one; then it adds a new row to the
        // table that contains the new location along with a timestamp 
        // indicating when the location changed

        if (!m_db.exists(m_table))
        {
            // if the browse history table doesn't exist, create it
            m_db.execute
            ("
                CREATE TABLE " + m_table + "
                (
                    TITLE          VARCHAR(200),
                    LINK           VARCHAR(200),
                    BROWSE_DATE    DATETIME(8)
                );
            ");

            // refresh the host application project tree
            HostApp.refresh();
        }

        // find out the date and time
        var dt = new Date();
        var browse_date =  dt.getFullYear() + "-" +
                          (dt.getMonth() + 1) + "-" +
                           dt.getDate() + " " +
                           dt.getHours() + ":" +
                           dt.getMinutes() + ":" +
                           dt.getSeconds();        

        // create a SQL statement to insert the new location into the
        // browse history table, along with a timestamp indicating when 
        // the location changed
        var sql = "INSERT INTO " + m_table + 
                  " (TITLE, LINK, BROWSE_DATE) VALUES ('" + 
                  evt.caption + "','" + evt.location + "','" + browse_date + "');";
 
        // execute the SQL statement to actually add the record
        // to the history
        m_db.execute(sql);
    }
}

HostApp.checkVersion

function HostApp.checkVersion(major : Number, minor : Number, subminor : Number, build_serial : Number) : Boolean

Arguments

major
The major version number (zero if not specified)
minor
The minor version number (zero if not specified)
subminor
The sub-minor version number (zero if not specified)
build_serial
The build serial number (zero if not specified)

Returns

True if the host application is equal or newer to the specified version number

Description

Calling checkVersion() checks the version number specified as four parameters against the host application's version number. If the host application's version number is greater or equal to the specified version, the function returns true. Otherwise, it returns false. This is useful for scripts that rely on certain features only present in newer versions of the host app.

HostApp.close

function HostApp.close(doc : HostDocument, force : Boolean) : Boolean

Arguments

doc
The document to close. This object may be obtained from either the getActiveDocument() method or the getDocuments() method.
force
Optional. If true, suppresses any dialog prompting while closing the document. The default is false.

Returns

Returns true upon success, false otherwise.

Description

Closes the document window represented by the specified doc parameter. If the window contains unsaved information, the user will normally be prompted as to whether the information should be saved. If this prompting is not desired, passing true in the optional force parameter will suppress this behavior.

HostApp.crash

function HostApp.crash()

Description

Calling crash() will simulate a general protection fault, which will cause the program to crash. This is useful for testing script applications which have recovery mechanisms for this eventuality.

HostApp.createDatabase

function HostApp.createDatabase(location : String, type : DbDatabaseType) : Boolean

Returns

true if the operation succeeded, otherwise false if an error occurred

Description

Creates a new database at the specified location. The type of database created is indicated by the type parameter, which is one of the values included in the DbDatabaseType enumeration.

HostApp.execute

function HostApp.execute(target : String, flags : Number) : Boolean

Arguments

target
The path, url, or source code of the script, template, or executable object
flags
Optional flags changing the execution behavior.

Returns

True upon success, false otherwise

Description

The execute() method allows the caller to execute a script, template, or executable object in the project panel. By default, the execution occurs synchronously, meaning that code execution returns immediately to the calling scope, while the executable specified by path is executed simultaneously. In the flags parameter, one or more flags may be specified which alter the behavior of the call. If the user specifies ExecuteWait, the execution will run asychronously. If the ExecuteSource flag is specified, target must contain the source code that is to be executed.

HostApp.executeAndWait

function HostApp.executeAndWait(path : String) : Boolean

Arguments

path
The path or url of the script, template, or executable object

Returns

True upon success, false otherwise

Description

The executeAndWait() method allows the caller to execute a script, template, or executable object in the project panel. The execution occurs asynchronously, meaning that code execution returns immediately to the calling scope, while the executable specified by path is executed simultaneously.

HostApp.exit

function HostApp.exit(force : Boolean)

Arguments

force
If true, save dialogs will be suppressed and exiting will happen immediately.

Description

Calling exit() causes the host application to exit. The force parameter, which may optionally be specified, indicates whether the application should force closing. If exiting is forced, the application will not prompt the user to save unsaved documents. The default value for force, false, is assumed if the force parameter is not specified. In this case, the application will display prompt dialogs to save modified documents.

HostApp.getActiveDocument

function HostApp.getActiveDocument() : HostDocument

Description

This method returns the active document in the system. The active document is the window that current has the user focus. If no documents are open in the system, null is returned.

HostApp.getApplicationId

function HostApp.getApplicationId() : String

Returns

The application identification tag

Description

Returns an identification tag that corresponds to the host application.

HostApp.getCommandLineArguments

function HostApp.getCommandLineArguments() : Array(String)

Returns

An array of strings containing the command line parameters

Description

This method retrieves the command line arguments that were specified upon program execution.

HostApp.getCurrentLocation

function HostApp.getCurrentLocation() : String

Returns

Returns a string containing the current location in the URL bar.

Description

Returns the current location in the URL bar.

HostApp.getDatabase

function HostApp.getDatabase() : DbConnection

Returns

A DbConnection object

Description

Returns a DbConnection object representing the application's current database connection. Using this object allows programs to access and manipulate the host application's current database project.

HostApp.getDocumentById

function HostApp.getDocumentById() : HostDocument

Returns

Returns a HostDocument object

Description

Each HostDocument object has an associated numeric ID. This number may be retrieved by calling HostDocument.getId(). The same document can be looked up again by utilizing HostApp.getDocumentById(). If a document with the specified ID exists, this method will return the corresponsing HostDocument object. If not, null is returned.

HostApp.getDocuments

function HostApp.getDocuments() : Array(HostDocument)

Returns

Returns an array of HostDocument objects

Description

Returns an array of HostDocument objects which represent all open documents inside the program. A 'document' is a window or container which holds information in the system, such as a web control, table, report, or text editor. See HostDocument for more information on how documents can be manipulated.

HostApp.getFrameCaption

function HostApp.getFrameCaption() : String

Returns

Returns a string containing the frame caption

Description

A call to HostApp.getFrameCaption() allows the script application to get the existing frame caption of the host application.

HostApp.getFrameMenu

function HostApp.getFrameMenu() : MenuBar

Returns

A MenuBar object. Null is returned if there is no menu.

Description

A call to getFrameMenu() returns a MenuBar object which represents the host application's menu bar. This is useful for script applications that wish to add or remove menu items from the host application's menu hierarchy.

HostApp.getVersion

function HostApp.getVersion() : String

Returns

The host application's version number

Description

Returns the version of the host application as a string. This string is formatted as four period-separated integers (for example, 1.2.3.4). The numbers mean, from left to right, major version number, minor version number, sub-minor version number, and build serial. The individual elements can be parsed out using the String functions.

HostApp.hang

function HostApp.hang()

Description

Calling hang() will simulate an application freeze by blocking the main GUI thread. This is useful for testing script applications which have recovery mechanisms for this eventuality.

HostApp.isGuiActive

function HostApp.isGuiActive() : Boolean

Returns

True if a gui is active, false otherwise

Description

This method returns true if a graphical user interface is being used to run the software. False is returned if console mode is being used.

HostApp.newDocument

function HostApp.newDocument(doc_type : String) : HostDocument

Returns

A valid HostDocument object upon success, null in the case of an error.

Description

Creates a new document in the host application. The document type can specify any document type that the application supports. Possible values are "table", "web", "query", "editor", or "report"

HostApp.open

function HostApp.open() : HostDocument

Returns

A valid HostDocument object upon success, null in the case of an error.

Description

Opens and browses a database table, document, or web page. For some data types, such as text files, if the file is already open, that document is instead shown. A host document object is returned. If the document could not be opened, null is returned

HostApp.openDatabase

function HostApp.openDatabase(connection : String) : Boolean
function HostApp.openDatabase(database : DbConnection) : Boolean

Returns

true if the operation succeeded, otherwise false if an error occurred

Description

Opens a database as the host application's current database project. The database may be specified with a connection string, a path to the database, or a database connection object.

HostApp.openWeb

function HostApp.openWeb(url : String, post_params : Array)

Arguments

url
The url location of the page to open
post_params
Optional. If specified, the array should be a key/value array where the key is the post variable name and the value is the value for the post variable.

Description

Much of the functionality of openWeb() is similar to open(). The openWeb() function, however, exposes additional functionality allowing post parameters to be specified. This is useful for filling out forms and displaying the resulting web page in a browser

HostApp.refresh

function HostApp.refresh()

Description

During the execution of the script, if new database objects are created, removed, or modified, it might become necessary to refresh the host application's panels, most notably the project panel. This allows new database objects to be displayed in the project panel, and makes deleted ones disappear.

HostApp.sendWebRequest

function HostApp.sendWebRequest(url : String, post_params : Array) : String

Arguments

url
The url location of the page to open
post_params
Optional. If specified, the array should be a key/value array where the key is the post variable name and the value is the value for the post variable.

Returns

A string value containing the result of the web request. A null value indicates failure. An empty string likely indicates failure as well, though certain web requests may normally result in an empty string.

Description

The sendWebRequest() method is similar to the openWeb() method, with one difference: Instead of the resulting page being opened in a browser window, it is returned to the application as a string.

HostApp.setFrameCaption

function HostApp.setFrameCaption(caption : String)

Arguments

caption
A string containing the new frame caption

Description

By default, the host application sets its own frame caption. A call to HostApp.setFrameCaption() allows the script application to modify the frame caption of the host application.

HostApp.showFrame

function HostApp.showFrame(show : Boolean)

Arguments

show
A boolean value of true or false, directing the host application's main window to either show or hide. If this parameter is omitted, a value of true is assumed.

Description

Shows the host application's main window if the show parameter is true, and hides it if the parameter is false.

HostApp.showJobManager

function HostApp.showJobManager(show : Boolean)

Arguments

show
A boolean containing true or false, directing the window to either show or hide. If this parameter is omitted, a value of true is assumed.

Description

Shows the host application's job manager if the show parameter is true, and hides it if the parameter is false.