Javascript Events with csXImage Running in Internet Explorer.

This is a description of how to use events exported by an ActiveX control in Internet Explorer and Javascript. It is based around our csXImage control although the principle is the same for other ActiveX controls. Over time the recommended method has changed and we now suggest using a method that was considered obsolete until Internet Explorer 11 deprecated a Javascript method used to define events in earlier versions.

Declaring events in a Javascript SCRIPT block

The method of calling ActiveX events shown below is not supported by XHTML and so, although it will work, it is an older specification of HTML (our example uses HTML 4.01 Transitional). The event must be declared in a <script> block. This block can be anywhere in the page.

Example:

<script language="JavaScript" for="csxi" event="onMouseDown(Button, ShiftState, X, Y);" type="text/javascript">
csXIMouseDown(Button, ShiftState, X, Y);
</script>

In this example the csXImage object has already been declared with the name "csxi" and this name must also be used in the FOR attribute. The event and its parameters is specified in the EVENT attribute. The code that is executed when the event fires is inside the <script> block and in this case it is a function, which will have been defined elsewhere in the script.

We have a downloadable example which is aimed for use with the trial version of csXImage - mouseevents.zip. This is available to view as a live demo. Note that the online demo uses the unsigned trial version of csXImage so it will generate a browser security warning unless you have already downloaded and installed the csXImage trial.

The next example shows an event without parameters. Note the empty parentheses for the function calls. Also, it is important to remember that Javascript is case sensitive and any capitalisation of the function name in the script block must match that of the function itself.

<script language="JavaScript" for="csxi" event="onAcquire();" type="text/javascript">
csXIAcquire();
</script>

This event declaration would run the following function when the OnAcquire event fires.

function csXIAcquire()
{
  csxi.redraw();
  csxi.AddToPDF(0);
}

The window.onload and window.unload events

Before Internet Explorer 11, ActiveX control events could be declared when the Javascript page first loads. The place to do this is inside the Javascript window.onload event handler. This event fires when the page loads and the syntax is as follows:

window.onload = function() {

  //add Javascript code here

}

Javascript also has a window.onunload event. This event fires when the user navigates away from the web page by following a link. A time to use this event is when the csXImage built in selection methods are used, MouseSelectRectangle and MouseSelectEllipse. This is unrelated to the example below. When a selection is being made, csXImage is waiting for user input and if the user does not complete the selection the CancelSelection command must be called. This should be added to the onunload event handler if a selection is used on the page.

Example:

<body onunload="csxi.CancelSelection();">

Declaring the ActiveX Events

The ActiveX event is declared by first assigning a variable to the element ID, then the attachEvent method is used to attach the event to the event handler function. Here is an example of creating an event handler for the csXImage onMouseDownEvent:

window.onload = function() {

  var onMouseDownEvent = document.getElementById("csxi");
  onMouseDownEvent.attachEvent('onMouseDown', csXIMouseDown);

  //other JavaScript code could be put here to run on page loading

}

function csXIMouseDown(Button, ShiftState, X, Y)
{
  //this code runs when the mouse down event fires
  //the parameters Button, ShiftState, X, and Y are defined in the ActiveX event
}

The ID of the csXImage control is set in the <object> tag and we have assumed it is csxi. The function used as the event handler is called csXIMouseDown. Any name could be used but it must match the name used in attachEvent. For details of csXImage event names and parameters, refer to the product instructions.

Not all events have parameters, and one such event that is often used in Javascript applications is OnAcquire, which is used when scanning and producing multi-page TIFF or PDF documents. Without parameters, the attachEvent command would look like this:

window.onload = function() {

  var onAcquireEvent = document.getElementById("csxi");
  onAcquireEvent.attachEvent('onAcquire', csXIAcquire);

  //the event handler function would be called csXIAcquire in this case

}

IMPORTANT - In Internet Explorer 11 the attachEvent method has been deprecated and replaced by addEventListener, which takes the same parameters but does not work with ActiveX events. We suggest using the older method of declaring events, described earlier, to avoid issues with different versions of Internet Explorer.