LAST REVISED: 03/02/07 23:35


TECHNICAL NOTES
VERSION 6.4

is an ActiveX control implementing a high performance viewer for documents stored in a variety of document image formats, including TIFF, CALS, JEDMICS, JFAX, and CPC. The viewer supports document navigation, arbitrary scaling, anti-aliased images in both a page view and thumbnail view, and much more. Consult the CPC View User's Guide for a complete description of the viewer's capabilities and user interface.

is one member of the CPC View product family. This document describes installation notes and other technical details specific to . Consult the CPC View Programmer's Guide for general information on the CPC View programming model.

Note: This release of is targeted to developers of web based products using Internet Explorer 4 or later.


1. Manual Installation

Note: If used in conjunction with Internet Explorer, the control can be downloaded and installed automatically. See § Automatic Installation for more information.

Prior to use, the control must be installed on the host computer. You can download the latest version of from the Cartesian web site. To install the control manually, use the regsvr32 utility. (The regsvr32 utility is included as part of Windows 95, Windows 98, and Windows NT.) For example, if you saved the control to c:\Program Files\Cartesian Products\CpcViewAX.ocx, the following command would register the control:

regsvr32 "c:\Program Files\Cartesian Products\CpcViewAX.ocx"

Warning: Once the control has been installed, the CpcViewAX.ocx file should not be moved. If you do move the file, you must re-install the control.

The regsvr32 utility can also be used to uninstall the control. Continuing the previous example, the following command would uninstall the control:

regsvr32 /u "c:\Program Files\Cartesian Products\CpcViewAX.ocx" Once the control has been uninstalled, you can delete the CpcViewAX.ocx file.


2. Basic Operation

In order to use , it must be embedded in a host application that supports ActiveX controls (e.g., Internet Explorer; MFC). exposes a custom programming and event interface allowing complete interactive control of the viewer by the host application. Consult the CPC View Programmer's Guide for a complete description of the programming interfaces.


2.1. Class ID

Under Windows, each ActiveX control is assigned a unique class ID that is used to identify the control. Many host applications require specification of the control's class ID in order to instantiate the control. The class ID of the control is:

0F7A9297-7268-11D1-B81A-00A076C01B0A.

See § Using the Control with Internet Explorer for more information on instantiating the control under Internet Explorer. For all other host applications, consult the documentation for the host application.


2.2. SRC Property

An instance of the control displays exactly one image document at a time. The instance's SRC property specifies the URL of the current image document. The URL must point to an image file in one of the supported formats. If the host application supports it, retrieves the URL using the context of the host application. In particular, this means that HTML pages displayed within Internet Explorer can use URLs relative to the base URL of the HTML page.

will begin loading the image document as soon as its SRC property is set. All image loading is performed in the background, so the host application regains control immediately. If the value of the SRC property is changed, will dispose of the current image data and initiate loading of the new image from the new URL.

2.2.1. URL Parameters

The SRC property can be augmented with optional URL parameters which describe the desired initial state of the user interface. The URL parameters are specified by appending to the URL a '?' followed by the parameters. For example, the URL http://foobar.org/abc.cpc?strict;page=2 would cause the control to display page 2 of the image found in http://foobar.org/abc.cpc. For more information on URL parameters, consult the CPC View Author's Guide.

Warning: Internet Explorer will not pass the URL parameters to the control if the '#' separator is used. You must use the '?' separator.


2.3. fullscreen Property

Internet Explorer uses the fullscreen property to differentiate between fullscreen instances of the control, in which the control occupies the entire frame of the host, and embedded instances of the control, in which the control shares space with other elements within the host frame. uses this parameter to differentiate its behavior in the following ways


3. Using the Control with Internet Explorer

When used with Internet Explorer, can be used as either a full page or embedded viewer.


3.1. Full Page Viewing

Perhaps the easiest way to use is as a full page viewer. A full page viewer occupies an entire window or frame within Internet Explorer. Internet Explorer will automatically load into the full frame whenever the browser is directed to a URL of the appropriate mime type. Simply specify the image URL as the href attribute of an <A> tag or as the src attribute of a <FRAME> tag. For example, we can specify a hyperlink directly to an image file using the following HTML:

HTML Source Result
<a target=_blank href=gilman2.cpc> Open document in new window </a> Open document in new window

You can also apply URL parameters to the full page URL. The following code uses the page parameter to select page 3 of the document.

HTML Source Result
<a target=_blank href="http://cartesianinc.com/Demo/CPCStreams/Gilman2.cpi?strict;page=3"> Click here </a> Click here

Warning: Under full page viewing, URL parameters will only work as part of an http: URL. Internet Explorer will not pass on URL parameters specified as part of a file: URL.


3.2. Embedding the Control on an HTML Page

In addition to using the to view image documents in a full frame or window, the control can also be embedded within an HTML document using either the <EMBED> tag or the <OBJECT> tag.

3.2.1. The EMBED Tag

To use the <EMBED> tag, simply specify the URL of an appropriate image as the SRC attribute. As with the full page viewer, URL parameters may be specified using the '?' separator. For instance, the image to the left was inserted with the following HTML: <embed align=left width=200 height=260 src="gilman2.cpc? strict; scale=fitwidth; toolbar=none; thumbnail=3,2;"> Note the use of the thumbnail and toolbar parameters to affect the appearance of the embedded image. Embedded images are "live"; all the standard user interface techniques work as usual. (Go ahead. Try it!)

If you have not yet installed , the image above may fail to load. If you have the CPC View plugin installed, the image above will be loaded using the plugin.

3.2.2. The OBJECT Tag

The <OBJECT> tag is similar to the <EMBED> tag and is also used to embed instances of within an HTML page. To use the <OBJECT> tag:

As with the <EMBED> tag, URL parameters may be specified using the '?' separator. For instance, the image to the right was inserted with the following HTML:

<object width=156 height=220 align=right classid="CLSID:0F7A9297-7268-11D1-B81A-00A076C01B0A"> <param name=src value="gilman2.cpc? strict; scale=fitwidth; page=3; toolbar=none"> </object>
If you have not yet installed , the image above will fail to load.


3.3. Automatic Installation

The <OBJECT> tag allows for specification of the URL of the installation package using the codebase attribute. The product installation package (CpcViewAX.cab) is a signed Microsoft Cabinet file which Internet Explorer uses to automatically install the control. When the codebase is specified and is not already installed on the client machine, Internet Explorer will automatically download and install the control from the specified location.

For example, if we add the codebase attribute to the example above, Internet Explorer will, if necessary, automatically download and install control prior to displaying the image. In this example, the installation package is downloaded from the file CpcViewAX.cab located in the same directory as the HTML page itself.

<object width=156 height=220 align=right classid="CLSID:0F7A9297-7268-11D1-B81A-00A076C01B0A" codebase="CpcViewAX.cab"> <param name=src value="gilman2.cpc? strict; scale=fitwidth; page=3; toolbar=none;"> </object>

Note: Depending on the security settings of the client computer, Internet Explorer may ignore the automatic installation request. Alternatively, the security settings may be set such that Internet Explorer will query the user as to whether or not to proceed with the automatic installation.

As another example, the code below demonstrates a mechanism by which an HTML page can trigger the download and installation of the control without a visible image. In this example, we use a hidden object (the width and height are zero), and hence, there is no need to specify a src attribute.

<object width=0 height=0 align=right classid="CLSID:0F7A9297-7268-11D1-B81A-00A076C01B0A" codebase="CpcViewAX.cab"> </object>

3.3.1. Specifying a Version

The codebase attribute can be augmented with a version number specifying the version of the control that codebase points to. If the control installed on the host computer is older than the specified version, Internet Explorer will automatically download and install the newer version of the control. For example, the attribute codebase="CpcViewAX.cab#Version=6,1,2,0" would cause Internet Explorer to download and install the control if the currently installed version is less than 6.1.2 (or if is not currently installed).


3.4. Detection

Warning: The material presented in this section is based on undocumented features of Internet Explorer and is outside the technical control of Cartesian Products. It is subject to change without notice. Use at your own risk.

Internet Explorer does not appear to provide any direct mechanism by which a web page can determine if is installed on the host computer. There are, however, several indirect ways to make such a determination. The appropriate solution depends on the functional requirements of the web page.

Note: If a web page only wants to ensure that the control is installed, automatic installation can be used.

3.4.1. HTML Within the <OBJECT> Block

Any HTML (other than <PARAM> tags) appearing within the <OBJECT> block will be ignored if the object is successfully instantiated. Under Internet Explorer, the only reason that the instantiation fails is that is not installed. Hence, you can use the code within the block to handle the situation in which is not installed.

Note: The code within the block will also be executed if the host browser does not support the <OBJECT> tag or the host browser does not support ActiveX controls (i.e., every browser other than Internet Explorer).

As a simple example, the following code will display the warning if is not installed (or the host browser is not Internet Explorer).

<object width=...> <b>Warning: You need to install CPC View ax and/or use Internet Explorer</b> </object>

3.4.2. The onerror Handler

The onerror handler of the <OBJECT> will only be invoked if the object could not be instantiated. Under Internet Explorer, the only reason that the instantiation fails is that is not installed. Hence, you can use the onerror handler to handle the situation in which is not installed.

As a simple example, the following code will only display the alert panel if is not installed (and the host browser is Internet Explorer).

<object onerror="alert('Install CPC View ax')" ...> </object>

3.4.3. Reflection

If you assign the <OBJECT> an id attribute, a variable of that name will only be instantiated if the object is instantiated. Under Internet Explorer, the only reason that the instantiation fails is that is not installed. Hence, a web page can test if is installed by testing if the reflected variable was instantiated.

Note: The test is only valid after the document has finished loading. The test would typically be used in the onload handler for the <BODY>.

Note: There must be some HTML within the <OBJECT> block. If there is no HTML, Internet Explorer appears to instantiate the reflected variable even when the control fails to load.

For example, assume that the following HTML is used to embed an object on a web page.

<object id=cpcProbe ...> <b></b> </object>

The following JavaScript could then be used to test if is installed.

if(typeof(cpcProbe) == "undefined") { alert('failed'); }


THE FINE PRINT (regarding copyrights and trademarks)

Cartesian Products, Inc.
cpi@cartesianinc.com