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