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.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.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.getCurrentLocation: Returns the current location in the URL bar.
HostApp.getDatabase: Returns the application's current database connection
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.open: Opens a database table, document, or web page
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(force : Boolean)

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.execute

function HostApp.execute(path : String) : Boolean

Arguments

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

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. The execution occurs asynchronously, meaning that code execution returns immediately to the calling scope, while the executable specified by path is executed simultaneously.

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.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.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.open

function HostApp.open()

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.

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.

About Us·Terms of Use·Privacy Policy·Contact Us