ScriptX scripting: technical manual

October 2003


Contents

Overview
How to reference ScriptX on an HTML page
General scripting extensions
Dynamic Event Binding (DEB)
DHTML dialogs
JScript: SafeArrays, Invoke 'ByRef', Formatting
Internet Explorer specific functionality
Reference
 
Summary of examples
Dynamic Event Binding with JScript and VBScript (Windows Scripting Host»)
Modal HTML Dialog
SafeArrays with JScript
Invoke 'By Ref' with JScript
Formatting with JScript
OleView-based Object Viewer

Overview

MeadCo ScriptX is a non-visual ActiveX control, originally designed to extend the scripting capabilities of the standard Microsoft Scripting Languages JScript» and VBScript» and to add more resemblance between the two. Currently the functionality provided by ScriptX can be conditionally grouped under the following headings:

All ScriptX functionality is licensed free of charge, with the exception of the control's advanced printing features which are only accessible in the presence of a paid-for publishing license. HTML Printing facilities are described in the printing manual.

How to reference ScriptX on an HTML page

ScriptX comes in two signed CABs: ScriptX.cab or smsx.cab, both of which are part of a download package obtainable from the ScriptX site. All free-of-charge functionality is available in ScriptX.cab:

<object id=factory style="display:none" classid="clsid:1663ed61-23eb-11d2-b92f-008048fdd814"
  viewastext codebase="ScriptX.cab#Version=6,1,431,2">
</object>

The viewastext parameter prevents an authoring tool like FrontPage or Visual Interdev from instantiating the object at design time.

General scripting extensions

General scripting extensions are independent of a particular scripting host. They are used as extensions to the default scripting runtime environment.

Dynamic Event Binding (DEB)

As its name may indicate, DEB enables the binding/unbinding of a script handler to any ActiveX object event on the fly. It works well for all Active Scripting hosts: WSH, HTML or custom.

Another useful DEB feature is Wait, the ability to 'sleep' script execution (with an optional timeout) without 'eating' any CPU cycles until an event occurs. 'Sleep' is conceptually close to VB's DoEvents» statement in that it serves the application message loop.

The best way to illustrate DEB is by example. Here is a Windows Scripting Host (WSH») example in both JScript and VBScript that creates and navigates an instance of the InternetExplorer» object and hooks up to its events.

See also: eventSink, NewEventSink, Wait, CancelWait.

DHTML dialogs

Here is an example of a native look & feel HTML dialog.

See also: ShowHtmlDialog.

JScript: SafeArrays, Invoke 'ByRef', Formatting

These extensions were designed to provide JScript with more resemblance to VBScript.

Jscript has limited read-only support for VB Arrays» (also known as SafeArrays) with a VBArray» object. ScriptX allows the creation of -- and direct access to -- a SafeArray with JScript. It's now possible to convert a JScript Array» to a SafeArray. Note that only single dimension SafeArrays are supported. Here is an example illustrating SafeArrays with JScript.

See also: Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet

Invoke 'ByRef' was developed to allow JScript to call ActiveX controls that take byref arguments. It also allows OLE errors that the calling method may return to be handled, and any corresponding script exceptions to be avoided. Here is an example illustrating how to use InvokeByRefResult with JScript.

See also: InvokeByRef, InvokeByRefResult.

Formatting functions match those of VBScript. They require the newer OLE Automation binaries to be available (they're part of Windows 98, come with Internet Explorer 5, or can be downloaded as part of free Visual Basic 6.0 Run-Time», see MSKB Q192461»). Here is an example of JScript formatting.

See also: Format, FormatCurrency», FormatDateTime», FormatNumber», FormatPercent».

Object Viewer

It's possible to learn on the fly what methods and properties an object supports. Microsoft's OleViewer» is required and is available for free download». Here is an example of how to use the object viewer which shows the object model of an HTML window» and the ScriptX factory object itself.

Other

See also: Shutdown, IsClosed, GetComponentVersion, MessageBeep, MessageBox.

Internet Explorer specific functionality

When ScriptX is hosted as an <OBJECT> on an HTML page, it provides the following Internet Explorer specific functionality:


Reference

Objects

factory, js, printing, eventSink

Properties

baseURL, ctx, js, handler, relativeURL, script, src

Methods

CancelWait, InvokeByRef, InvokeByRefResult, IsClosed, Format, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, GetComponentVersion, MessageBeep, MessageBox, NewEventSink, OnDocumentComplete, ShowHtmlDialog, Shutdown, Unadvise, Vec, VecCopy, VecFill, VecFromArray, VecGet, VecGetSize, VecResize, VecPut, Wait

Objects

factory


Description

Represents the ScriptX object itself as it is named on an HTML page.

For WSH or ASP (i.e. server-side) use only it's possible to create a ScriptX instance dynamically with the JScript new ActiveXObject» or the VBScript CreateObject». In such cases the Shutdown method should be called when ScriptX is no longer being used.

Properties

script, baseURL, relativeURL, printing, js, sourceText

Methods

NewEventSink, IsClosed, Shutdown, ShowHtmlDialog, MessageBeep, MessageBox, Wait, CancelWait, OnDocumentComplete, GetComponentVersion

js


Description

Represents ScriptX helper facilities for JScript. See JScript: SafeArrays, Invoke 'ByRef', Formatting for more information and examples.

Methods

Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet, Format, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, InvokeByRef, InvokeByRefResult

Applies To

factory

eventSink


Description

An object used to connect script handlers to, or disconnect them from, events of an ActiveX control. The object is created dynamically with the NewEventSink method. See Dynamic Event Binding (DEB) for more information.

Properties

handler, src, ctx

Methods

Wait, CancelWait, Unadvise

See Also

NewEventSink

Properties

script


Description

This property is for use with dynamic event binding, when a ScriptX object is created dynamically with VBscript. In this case the script namespace object should be assigned to this property, because ScriptX looks for an event handler by name. See the example below.

Syntax

factory.script = object

Settings

This read/write property takes an object that has all the event handlers defined within.

Applies To

factory

Example

' Handle events from browser
Set Browser = CreateObject("InternetExplorer.Application")
Browser.Visible = true

Set Factory = CreateObject("ScriptX.Factory")
Factory.script = me
Set Sink = Factory.NewEventSink(Browser)
Sink("BeforeNavigate2")="BeforeNavigate2"
Sink("DocumentComplete")="DocumentComplete"
Sink("OnQuit")="OnQuit"

Sub BeforeNavigate2(ByVal pDisp, URL, Flags, TargetFrameName, PostData, Headers, Cancel)
' handling code
End Sub

Sub DocumentComplete(ByVal pDisp, URL)
' handling code
End Sub

Sub OnQuit
' handling code
End Sub

See Also

NewEventSink

baseURL


Description

This property is for use in an HTML script. It returns a full URL based upon the URL of the hosting document.

Syntax

fullUrl = factory.baseURL[(url)]

Settings

This is a read-only property which returns either the full URL of the hosting document or the base url of the document's URL.

Applies To

factory

Example

<script>
function window.onload() {
  childWindow.navigate(factory.baseURL("loaded.htm"))
}
</script>

See Also

relativeURL

relativeURL


Description

This property is for use in an HTML script. It returns the URL relative to the hosting document's URL.

Syntax

relUrl = factory.relativeURL[(url)]

Settings

This is a read-only property.

Applies To

factory

See Also

baseURL

sourceText


Description

This property is for use in an HTML script. It retrieves the raw HTML source of the hosting document.

Syntax

htmlText = factory.sourceText

Settings

This is a read-only property.

Applies To

factory

handler


Description

This is the default property of the eventSink object. It is used to connect or disconnect a script event handler to or from a specified event. See dynamic event binding for more information.

Syntax

eventSink.handler(sEventName) = EventHandler

or

eventSink(sEventName) = EventHandler

or

eventSink(sEventName) = null

Settings

This is a read/write property. EventHandler can be either the string name of a script function or a direct function reference. null is used to disconnect the event handler.

Example

sink("StatusTextChange") = onStatusTextChange
function onStatusTextChange(Text) { /* handling code */ }

Applies To

eventSink

See Also

eventSink, src, ctx, NewEventSink

src


Description

Specifies the event source object passed to NewEventSink. See dynamic event binding for more information.

Settings

This is a read-only property.

Applies To

eventSink

See Also

handler, ctx, NewEventSink

ctx


Description

Specifies the context value assigned to the eventSink object with NewEventSink. See dynamic event binding for more information.

Settings

This is a read-only property.

Applies To

eventSink

See Also

handler, src, NewEventSink

Methods

NewEventSink


Description

Creates a new event sink for a given object for dynamic event binding. To handle an event, a script handler must be assigned to the sink with the handler property. An optional context value can be passed to be available at the event handler when the event occurs.

Syntax

eventSink = factory.NewEventSink(src[, ctx])

Parameter Description
src (Object) the object to handle events from
ctx (Any type) optional context value

Return Value

Returns a new eventSink object. At event time the object is available to the script handler via implicit this (JScript) or me (VBScript) reference.

Applies To

factory

Example

var browser = new ActiveXObject("InternetExplorer.Application")
var sink = factory.NewEventSink(browser)
sink("StatusTextChange") = onStatusTextChange
sink("NavigateComplete2") = onNavigateComplete2
sink("DocumentComplete") = onDocumentComplete
sink("OnQuit") = onQuit
browser.Navigate2("http://www.meadroid.com")
sink.Wait()
// ...
factory.Shutdown()

// handlers
function onStatusTextChange(Text) { /* handling code */ }
function onNavigateComplete2(pDisp, URL) { /* handling code */ }
function onDocumentComplete(pDisp, URL) { this.CancelWait() }
function onQuit() { this.Unadvise() }

See Also

eventSink, handler, src, ctx, Wait, CancelWait, Unadvise, Shutdown

Wait


Description

Suspends (sleeps) the script execution for a specified timeout or until CancelWait is called. Events are serviced during sleep.

Syntax

object.Wait([timeout])

Parameter Description
timeout (Number) the optional timeout in milliseconds, -1 by default means to sleep until CancelWait is called.

Return Value

Returns true if the sleep was timed out.

Applies To

factory, eventSink

Example

var browser = new ActiveXObject("InternetExplorer.Application")
var sink = factory.NewEventSink(browser)
sink("DocumentComplete") = onDocumentComplete
sink("OnQuit") = onQuit
browser.Navigate2("http://www.meadroid.com")
sink.Wait()
// ...
factory.Shutdown()

// handlers
function onDocumentComplete(pDisp, URL) { this.CancelWait() }
function onQuit() { this.Unadvise() }

See Also

CancelWait

CancelWait


Description

Cancels the pending sleep (that is, the active Wait call).

Syntax

object.CancelWait()

Applies To

factory, eventSink

Example

var browser = new ActiveXObject("InternetExplorer.Application")
var sink = factory.NewEventSink(browser)
sink("StatusTextChange") = onStatusTextChange
sink("NavigateComplete2") = onNavigateComplete2
sink("DocumentComplete") = onDocumentComplete
sink("OnQuit") = onQuit
browser.Navigate2("http://www.meadroid.com")
sink.Wait()
// ...
factory.Shutdown()

// handlers
function onStatusTextChange(Text) { /* handling code */ }
function onNavigateComplete2(pDisp, URL) { /* handling code */ }
function onDocumentComplete(pDisp, URL) { this.CancelWait() }
function onQuit() { this.Unadvise() }

See Also

Wait

Unadvise


Description

Disconnects (unadvises) the eventSink object from its event source.

Syntax

eventSink.Unadvise()

Applies To

eventSink

Example

var browser = new ActiveXObject("InternetExplorer.Application")
var sink = factory.NewEventSink(browser)
sink("OnQuit") = onQuit
browser.Navigate2("http://www.meadroid.com")
sink.Wait()

// handlers
function onQuit() { this.Unadvise() }

See Also

NewEventSink

Shutdown


Description

The clean-up method for ScriptX. Should be called in cases where a dynamically created ScriptX object is no longer being used. All active event sinks get disconnected.

Syntax

factory.Shutdown()

Applies To

factory

IsClosed


Description

Checks whether or not the remote object is shut down. E.g. this can be a pop-up HTML window.

Syntax

closed = factory.IsClosed(obj)

Parameter Description
obj (Object) the remote object to check.

Applies To

factory

Example

function IsWindowClosed(popup) {
  return !popup || factory.IsClosed(popup) || popup.closed;
}

ShowHtmlDialog


Description

Invokes a native look & feel modal HTML dialog. See DHTML dialogs for more information and an example.

Syntax

result = factory.ShowHtmlDialog(url, argIn[, options])

Parameter Description
url (String) the URL of HTML page to be a dialog
argIn (Any type) input parameter to reference within dialog
options (String) optional features. See showModalDialog» on MSDN.

Applies To

factory

See Also

showModalDialog»

GetComponentVersion


Description

Retrieves the versioning information of a specified component.

Syntax

factory.GetComponentVersion(class, a, b, c, d)

Parameter Description
class (String) either class name or GUID
a, b, c, d (Number) variables to receive four digits version info

Examples

' VBScript
dim a, b, c, d
on error resume next
factory.GetComponentVersion "msxml", a, b, c, d
error = Err.Number
on error goto 0
if error = 0 then alert "msxml version: " & a & "." & b & "." & c & "." & d

Applies To

factory

Vec


Description

Creates a single-dimensional SafeArray (vector) of a specified size. See SafeArrays for more information and an example.

Syntax

vec = js.Vec(size)

Parameter Description
size (Number) number of elements in new vector

Return Value

Returns the value of a SafeArray type.

Applies To

js

See Also

VecFill, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet

VecFill


Description

Creates a one-dimensional SafeArray (vector) containing the specified elements. See SafeArrays for more information and an example.

Syntax

vec = js.VecFill(elem1[, elem2[, ...]])

Parameter Description
elem1...elemN (Any type) elements to fill the vector with

Return Value

Returns the value of a SafeArray type.

Applies To

js

See Also

Vec, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet

VecCopy


Description

Creates a copy of a specified one-dimensional SafeArray (vector). See SafeArrays for more information and an example.

Syntax

vec = js.VecCopy(srcVec)

Parameter Description
srcVec (SafeArray) source vector to make a copy of

Return Value

Returns the value of a SafeArray type.

Applies To

js

See Also

Vec, VecFill, VecFromArray, VecGetSize, VecResize, VecPut, VecGet

VecFromArray


Description

Creates a one-dimensional SafeArray (vector) from a JScript array. See SafeArrays for more information and an example.

Syntax

vec = js.VecFromArray(array)

Parameter Description
array (Array) a source JScript array

Return Value

Returns the value of a SafeArray type.

Applies To

js

See Also

Vec, VecFill, VecCopy, VecGetSize, VecResize, VecPut, VecGet

VecGetSize


Description

Retrieves the size of specified one-dimensional SafeArray (vector). See SafeArrays for more information and example.

Syntax

size = js.VecGetSize(vec)

Parameter Description
vec (SafeArray) vector

Return Value

Returns the size of the vector.

Applies To

js

See Also

Vec, VecFill, VecCopy, VecFromArray, VecResize, VecPut, VecGet

VecResize


Description

Changes the size of a specified one-dimensional SafeArray (vector). See SafeArrays for more information and an example.

Syntax

js.VecResize(vec, newSize)

Parameter Description
vec (SafeArray) vector
newSize (Number) new size of the vector

Applies To

js

See Also

Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecPut, VecGet

VecPut


Description

Puts the element at the specified position of a one-dimensional SafeArray (vector). See SafeArrays for more information and an example.

Syntax

js.VecPut(vec, pos, elem)

Parameter Description
vec (SafeArray) vector
pos (Number) position
elem (Any type) element to put at the position

Applies To

js

See Also

Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecGet

VecGet


Description

Retrieves the element at the specified position of a one-dimensional SafeArray (vector). See SafeArrays for more information and example.

Syntax

elem = js.VecGet(vec, pos)

Parameter Description
vec (SafeArray) vector
pos (Number) position

Return Value

Returns the element at the specified position.

Applies To

js

See Also

Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecPut

Format


Description

Formats the data according to the corresponding format specification. See Formatting for more information and an example.

Syntax

string = js.Format(strFormat[, param1[, param2[, ...]]])

Parameter Description
strFromat (String) the format-control specification. See remarks below
param1...param2 (Type as specifed at strFromat) paramters to format

Remarks

The format-control string contains format specifications that determines the output format for the arguments following the strFromat parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, %% produces a single percent-sign character).

The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the output buffer according to the format specification. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

A format specification has the following form:

%[-][#][0][width][.precision]type

Each field is a single character or a number signifying a particular format option. The type characters that appear after the last optional format field determine whether the associated argument is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields control other aspects of the formatting. The following lists the optional and required fields and their meanings:

Field Meaning
Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying it to the right.
# Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0 Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
For strings, copy the specified maximum number of characters to the output buffer.
type Output the corresponding argument as a character, a string, or a number. This field can be any of the following character sequences:


Sequence Insert
C A single character.
d A signed decimal integer argument. This sequence is equivalent to the i sequence.
i A signed decimal integer. This sequence is equivalent to the d sequence.
ls, lS A string.
u An unsigned integer argument.
x, X An unsigned hexadecimal integer in lowercase or uppercase.

Return Value

Returns the formatted string.

Applies To

js

See Also

FormatCurrency, FormatDateTime, FormatNumber, FormatPercent

FormatCurrency, FormatDateTime, FormatNumber, FormatPercent


Description

Formatting functions which match those of VBScript: Format, FormatCurrency», FormatDateTime», FormatNumber», FormatPercent». They require the newer OLE Automation binaries to be available. See Formatting for more information and example.

InvokeByRef


Description

Allows JScript to call a method of an ActiveX object that takes a parameter by reference. See Invoke 'ByRef' for more information.

Syntax

value = js.InvokeByRef(object, method, argArray)

Parameter Description
object (Object) object on which to call the method
method (String) method to call
argArray (Array) JScript array of arguments

Return Value

Returns the same result as a direct object.method(...) call.

Example

  // pack params to "args" array
  args = new Array("msxml", 0, 0, 0, 0)

  // call the "GetComponentVersion" method on "factory" object
  factory.js.InvokeByRef(factory, "GetComponentVersion", args)

  alert("MSXML Version: "+args[1]+"."+args[2]+"."+args[3]+"."+args[4])

Applies To

js

See Also

InvokeByRefResult

InvokeByRefResult


Description

Allows JScript to call a method of an ActiveX object that takes a parameter by reference, and handle a possible failure case. See Invoke 'ByRef' for more information.

Syntax

error = js.InvokeByRefResult(object, method, argArray)

Parameter Description
object (Object) object on which to call the method
method (String) method to call
argArray (Array) JScript array of arguments

Return Value

Returns the error code number of an object.method(...) call. Zero means the call has succeeded. The invocation result value (if applicable) is available as argArray.value.

Example

  // pack params to "args" array
  args = new Array("msxml", 0, 0, 0, 0)

  // call the "GetComponentVersion" method on "factory" object
  error = factory.js.InvokeByRefResult(factory, "GetComponentVersion", args)

  if ( error == 0 )
    alert("MSXML Version: "+args[1]+"."+args[2]+"."+args[3]+"."+args[4])
  else
    alert("Error: "+error)

Applies To

js

See Also

InvokeByRef

MessageBeep


Description

Plays a waveform sound. The waveform sound for each sound type is identified by an entry in the [sounds] section of the registry.

Syntax

factory.MessageBeep([type])

Parameter Description
type (Number) Specifies the sound type, as identified by an entry in the [sounds] section of the registry. This parameter can be one of the following values:
Value Sound
-1 Standard beep using the computer speaker
0x00000040 SystemAsterisk
0x00000030 SystemExclamation
0x00000010 SystemHand
0x00000020 SystemQuestion
0x00000000 SystemDefault

Applies To

factory

See Also

MessageBox

MessageBox


Description

Creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

Syntax

result = factory.MessageBox(text[, caption[, type]])

Parameter Description
text (String) the message to display
caption (String) message box caption
type (Number) Specifies a set of bit flags that determine the contents and behavior of the dialog box. This parameter can be a combination of flags from the following groups of flags. Specify one of the following flags to indicate the buttons contained in the message box:
Value Sound
0x00000000 The message box contains one push button: OK. This is the default
0x00000001 The message box contains two push buttons: OK and Cancel
0x00000004 The message box contains two push buttons: Yes and No
0x00000003 The message box contains three push buttons: Yes, No, and Cancel
0x00000030 An exclamation-point icon appears in the message box
0x00000040 An icon consisting of a lowercase letter i in a circle appears in the message box
0x00000010 A stop-sign icon appears in the message box
0x00010000 The message box becomes the foreground window
0x00040000 The message box is created as topmost window

Return Value

The return value is one of the following menu-item values:

Value Meaning
3 Abort button was selected.
2 Cancel button was selected.
7 No button was selected.
1 OK button was selected.
6 Yes button was selected.

Applies To

factory

See Also

MessageBeep

OnDocumentComplete


Description

Notifies the caller about the HTML frame or window download completition.

Syntax

factory.OnDocumentComplete(frameOrWindow, callback)

Parameter Description
frameOrWindow (Object) frame or window object loading HTML content
callback (Object) refrences to JScript function object to be called upon download completition

Examples

var child = open("child.htm")
function onChildLoad() {
  alert("Window loaded: "+child.document.title)
}
factory.OnDocumentComplete(child, onChildLoad)

Applies To

factory