Global.js File Reference

Global object properties. More...

Functions
Boolean	array_contains (Mixed aElement)
	Check if an element is contained in the array. More...
void	debug (...)
	Print the expressions (applying toString() if necessary) to the debugger output. More...
void	importExtension (String aExtensionName)
	Imports the named extension into the script engine. More...
void	perror (...)
	Print the expressions (applying toString() if necessary) to the console error output (stderr), followed by a newline. More...
void	print (...)
	Print the expressions (applying toString() if necessary) to the console standard output (stdout), followed by a newline. More...

Variables
String	applicationDirPath
	The directory where the executable running the script is located. More...
String	country
	The system country expressed as 2 char uppercase abbreviation. More...
Engine	engine
	Reference to the scripting engine object. More...
Boolean	isGui
	GUI environment indicator. More...
String	language
	The system language expressed as 2 char lowercase abbreviation. More...
String	locale
	The system locale as 2 char lowercase language, underscore, 2 char uppercase country. More...
String	scriptFileName
	Name of the current script being executed. More...

Detailed Description

Global object properties.

Function Documentation

array_contains()

Boolean array_contains

(

Mixed

aElement

)

Check if an element is contained in the array.

This function would basically qualify as Array prototype function, however that would break the useful for/in loops. For this reason we add the function selectively to array objects where needed and where it is safe nobody uses a for/in loop on the array:

var a = [ 'apple', 'rose', 'baseball' ];
a.contains = array_contains;
print(a.contains('banana'));   // false
print(a.contains('rose'));     // true

Parameters

[in]

aElement

The element to check (must be a scalar, for example String or Number).

Returns

True if array contains the element, false if not.

debug()

void debug

(

...

)

Print the expressions (applying toString() if necessary) to the debugger output.

For command line programs the debugger output is sent to stderr, for GUI applications to the debugger. No output is created for programs where QT_NO_DEBUG_OUTPUT was defined during compilation. An arbitrary number of expressions can be passed as parameters to print. Multiple expressions will be separated by a blank.

importExtension()

void importExtension

(

String

aExtensionName

)

Imports the named extension into the script engine.

The script engine ensures that a particular extension is only imported once; subsequent calls to importExtension() with the same extension name will do nothing.

There are three ways to create an extension:

• Writing a C++ extension plugin by subclassing QScriptExtensionPlugin and implementing the desired functionality. Check the Qt documentation for details how this is done.
• Implement the functionality in a script file. See documentation below how this is done.
• Use a hybrid approach, where part of the functionality is implemented in C++ as a QScriptExtensionPlugin, and part is implemented in a script file.

The (dot-qualified) extension name is used to determine the path (relative to a directory script within the application's plugin path) where the script engine will look for the script file that will initialize the extension; if a file called __init__.js is found in the corresponding folder, its contents will be evaluated by the engine when the extension is imported. As an example, if the extension is called foo.bar.baz, the engine will look for __init__.js in foo/bar/baz.

Additionally, before importing foo.bar.baz, the engine will ensure that the extensions foo and foo.bar are imported, locating and evaluating the corresponding __init__.js in the same manner (in folders foo and foo/bar, respectively).

The contents of __init__.js are evaluated in a new context, as if it were the body of a function. The engine's global object acts as the this object.

The following local variables are initially available to the script:

• extension : The name of the extension (e.g. foo.bar.baz).
• setupPackage : A convenience function for setting up a "namespace" in the script environment. A typical application is to call setupPackage() with extension as argument; e.g. setupPackage("foo.bar.baz") would ensure that the object chain represented by the expression foo.bar.baz exists in the script environment.
• postInit : By default, this variable is undefined. If you assign a function to it, that function will be called after the C++ plugin's initialize() function has been called. You can use this to perform further initialization that depends on e.g. native functions that the C++ plugin registers.

An example of a simple __init__.js :

print("importing cool.stuff");
__setupPackage__("cool.stuff");
 
cool.stuff.add = function(a, b) { return a + b; }
cool.stuff.subtract = function(a, b) { return a - b; } 

Same example where the package name is not hardcoded:

log("importing " + __extension__);
__setupPackage__(__extension__);
 
eval(__extension__).add = function(a, b) { return a + b; }
eval(__extension__).subtract = function(a, b) { return a - b; } 

The script engine will look for a QScriptExtensionPlugin that provides the relevant extension by querying each plugin for its keys() until a match is found. The plugin's initialize() function will be called after the relevant __init__.js (if any) has been evaluated.

Continuining with the example of our imaginary extension foo.bar.baz, the following steps will be performed by importExtension():

• If it exists, foo/__init__.js is evaluated.
• If a C++ plugin with "foo" in its list of keys is found, its
  initialize() function is called with "foo" as key.
• If it exists, foo/bar/__init__.js is evaluated.
• If a C++ plugin with "foo.bar" in its list of keys is found, its initialize() function is called with "foo.bar" as key.
• If it exists, foo/bar/baz/__init__.js is evaluated.
• If a C++ plugin with "foo.bar.baz" in its list of keys is found, its initialize() function is called with "foo.bar.baz" as key.

Parameters

aExtensionName

Name of the extension to import.

perror()

void perror

(

...

)

Print the expressions (applying toString() if necessary) to the console error output (stderr), followed by a newline.

An arbitrary number of expressions can be passed as parameters to print. Multiple expressions will be separated by a blank.

print()

void print

(

...

)

Print the expressions (applying toString() if necessary) to the console standard output (stdout), followed by a newline.

An arbitrary number of expressions can be passed as parameters to print. Multiple expressions will be separated by a blank.

Variable Documentation

applicationDirPath

String applicationDirPath

The directory where the executable running the script is located.

Might be the location of the bps.exe standalone script interpreter or a graphical BPS application.

country

String country

The system country expressed as 2 char uppercase abbreviation.

Example: CH

engine

Engine engine

Reference to the scripting engine object.

 

isGui

Boolean isGui

GUI environment indicator.

This property is true for scripts executed in a GUI environment, and false for non-GUI execution such as by bps.exe.

With this variable it is easy to create combined scripts runnable in both modes:

if (isGui) {
    importExtension('bps.gui');
    var m = new bps.gui.MessageBox;
    m.text = 'Hello world!';
    m.show();
} else {
    print('Hello world!');
}

language

String language

The system language expressed as 2 char lowercase abbreviation.

Example: de

locale

String locale

The system locale as 2 char lowercase language, underscore, 2 char uppercase country.

Example: de_CH

scriptFileName

String scriptFileName

Name of the current script being executed.