October 2003
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.
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 are independent of a particular scripting host. They are used as extensions to the default scripting runtime environment.
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.
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».
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.
When ScriptX is hosted as an <OBJECT> on an HTML page, it provides the following Internet Explorer specific functionality:
factory, js, printing, eventSink
baseURL, ctx, js, handler, relativeURL, script, src
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
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.
NewEventSink, IsClosed, Shutdown, ShowHtmlDialog, MessageBeep, MessageBox, Wait, CancelWait, OnDocumentComplete, GetComponentVersion
Represents ScriptX helper facilities for JScript. See JScript: SafeArrays, Invoke 'ByRef', Formatting for more information and examples.
Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet, Format, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, InvokeByRef, InvokeByRefResult
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.
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.
factory.script = object
This read/write property takes an object that has all the event handlers defined within.
' 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
This property is for use in an HTML script. It returns a full URL based upon the URL of the hosting document.
fullUrl = factory.baseURL[(url)]
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.
<script> function window.onload() { childWindow.navigate(factory.baseURL("loaded.htm")) } </script>
This property is for use in an HTML script. It returns the URL relative to the hosting document's URL.
relUrl = factory.relativeURL[(url)]
This is a read-only property.
This property is for use in an HTML script. It retrieves the raw HTML source of the hosting document.
htmlText = factory.sourceText
This is a read-only property.
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.
eventSink.handler(sEventName) = EventHandler
or
eventSink(sEventName) = EventHandler
or
eventSink(sEventName) = null
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.
sink("StatusTextChange") = onStatusTextChange function onStatusTextChange(Text) { /* handling code */ }
Specifies the event source object passed to NewEventSink. See dynamic event binding for more information.
This is a read-only property.
Specifies the context value assigned to the eventSink object with NewEventSink. See dynamic event binding for more information.
This is a read-only property.
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.
eventSink = factory.NewEventSink(src[, ctx])
Parameter Description src (Object) the object to handle events from ctx (Any type) optional context 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.
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() }
eventSink, handler, src, ctx, Wait, CancelWait, Unadvise, Shutdown
Suspends (sleeps) the script execution for a specified timeout or until CancelWait is called. Events are serviced during sleep.
object.Wait([timeout])
Parameter Description timeout (Number) the optional timeout in milliseconds, -1 by default means to sleep until CancelWait is called.
Returns true if the sleep was timed out.
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() }
Cancels the pending sleep (that is, the active Wait call).
object.CancelWait()
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() }
Disconnects (unadvises) the eventSink object from its event source.
eventSink.Unadvise()
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() }
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.
factory.Shutdown()
Checks whether or not the remote object is shut down. E.g. this can be a pop-up HTML window.
closed = factory.IsClosed(obj)
Parameter Description obj (Object) the remote object to check.
function IsWindowClosed(popup) { return !popup || factory.IsClosed(popup) || popup.closed; }
Invokes a native look & feel modal HTML dialog. See DHTML dialogs for more information and an example.
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.
Retrieves the versioning information of a specified component.
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
' 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
Creates a single-dimensional SafeArray (vector) of a specified size. See SafeArrays for more information and an example.
vec = js.Vec(size)
Parameter Description size (Number) number of elements in new vector
Returns the value of a SafeArray type.
VecFill, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet
Creates a one-dimensional SafeArray (vector) containing the specified elements. See SafeArrays for more information and an example.
vec = js.VecFill(elem1[, elem2[, ...]])
Parameter Description elem1...elemN (Any type) elements to fill the vector with
Returns the value of a SafeArray type.
Vec, VecCopy, VecFromArray, VecGetSize, VecResize, VecPut, VecGet
Creates a copy of a specified one-dimensional SafeArray (vector). See SafeArrays for more information and an example.
vec = js.VecCopy(srcVec)
Parameter Description srcVec (SafeArray) source vector to make a copy of
Returns the value of a SafeArray type.
Vec, VecFill, VecFromArray, VecGetSize, VecResize, VecPut, VecGet
Creates a one-dimensional SafeArray (vector) from a JScript array. See SafeArrays for more information and an example.
vec = js.VecFromArray(array)
Parameter Description array (Array) a source JScript array
Returns the value of a SafeArray type.
Vec, VecFill, VecCopy, VecGetSize, VecResize, VecPut, VecGet
Retrieves the size of specified one-dimensional SafeArray (vector). See SafeArrays for more information and example.
size = js.VecGetSize(vec)
Parameter Description vec (SafeArray) vector
Returns the size of the vector.
Vec, VecFill, VecCopy, VecFromArray, VecResize, VecPut, VecGet
Changes the size of a specified one-dimensional SafeArray (vector). See SafeArrays for more information and an example.
js.VecResize(vec, newSize)
Parameter Description vec (SafeArray) vector newSize (Number) new size of the vector
Vec, VecFill, VecCopy, VecFromArray, VecGetSize, VecPut, VecGet
Puts the element at the specified position of a one-dimensional SafeArray (vector). See SafeArrays for more information and an example.
js.VecPut(vec, pos, elem)
Parameter Description vec (SafeArray) vector pos (Number) position elem (Any type) element to put at the position
Retrieves the element at the specified position of a one-dimensional SafeArray (vector). See SafeArrays for more information and example.
elem = js.VecGet(vec, pos)
Parameter Description vec (SafeArray) vector pos (Number) position
Returns the element at the specified position.
Formats the data according to the corresponding format specification. See Formatting for more information and an example.
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
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.
Returns the formatted string.
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.
Allows JScript to call a method of an ActiveX object that takes a parameter by reference. See Invoke 'ByRef' for more information.
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
Returns the same result as a direct object.method(...) call.
// 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])
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.
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
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.
// 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)
Plays a waveform sound. The waveform sound for each sound type is identified by an entry in the [sounds] section of the registry.
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
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.
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
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.
Notifies the caller about the HTML frame or window download completition.
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
var child = open("child.htm") function onChildLoad() { alert("Window loaded: "+child.document.title) } factory.OnDocumentComplete(child, onChildLoad)