LAST REVISED: 05/03/10 17:48

CPC VIEW
PROGRAMMER'S GUIDE
VERSION 6.4

CPC View provides inline viewing capabilities for images in a variety of formats including TIFF, CALS, JEDMICS, JFAX, and CPC. The viewer supports multi-page document navigation, scaling, rotation, anti-aliased images, thumbnails, annotations, and much more. Consult the CPC View User's Guide for a complete description of the viewer's capabilities and user interface.

CPC View is packaged in a number of variants (e.g., browser plugin; ActiveX control). Regardless of the specific package, CPC View exposes a common programming and event interface allowing complete programmable control of the viewer by external applications. This document describes the common programmable interface to CPC View.

Note: The current version of the browser plugin does not yet support programmable control.

1. Parameter Lists

The CPC View programming model is based on string descriptions known as parameter lists. As the name implies, a parameter list is simply a list of parameters and their values. CPC View uses parameter lists to describe programmable aspects of its internal state and to describe asynchronous events such as mouse clicks or user keystrokes.

Within a parameter list, each parameter is described by a string of the form name=value, where name is the parameter name and value is the parameter value (similar to the URL parameters). The =value portion of the parameter may be omitted, in which case the value is taken to be the empty string. Multiple parameters are separated with a semi-colon (;) and the entire parameter list may optionally be terminated with a semi-colon.

For example, the string foo=123;wingbat;bar=this is a message describes a parameter list containing three parameters, foo, wingbat, and bar. The value of foo is the string, 123, the value of wingbat is the empty string, and the value of bar is the string, this is a message.

1.1. Parameter Names

Parameter names are case insensitive. For example, CPC View considers the the three names abc, ABC, and aBc to be equivalent.

1.2. Parameter Values

A parameter value is a string. Many parameter values are not naturally strings, and hence, must be transformed into a string according to some encoding. When setting parameter values, the results are undefined if the value does not conform to the appropriate encoding. The following encodings are defined. (Each parameter definition specifies the particular encoding used for its parameter value.)

1.2.1. INTEGER

Integers are encoded in their natural decimal string representation. For example, the integer 173 is encoded as the three character string 173. Negative integers are encoded with a leading minus sign. For example, the integer -173 is encoded as the four character string -173. If the value portion of the parameter is omitted or is empty, the value is interpreted as zero.

1.2.2. BOOLEAN

A BOOLEAN can be either TRUE or FALSE. FALSE is encoded as 0. TRUE is any other value including the empty string. Hence, if the parameter name is specified without a value, the value is interpreted as TRUE. As a convenient shorthand, when sending parameters to CPC View, FALSE can also be encoded by omitting the value and prefixing the name with a leading exclamation mark. For example, the parameter specification !foobar would set the parameter foobar to FALSE.

1.2.3. COLOR

A color is encoded as an RGB triplet of the form RRGGBB where RR is the red component, GG is the green component, and BB is the blue component. Each component value is encoded as a two character hexadecimal string falling in the range 00 - 0xff where 00 represents minimum intensity and 0xff represents maximum intensity. For example, the value FF0080 specifies the color in which the red component is at maximum intensity, the green component is at minimum intensity, and the blue component is at half intensity.

Colors may also be encoded by name. The following color names are defined. (Color names are case insensitive.)

Name As of Description
WHITE V5.2 White as defined by the current desktop color scheme
LIGHTGRAY V5.2 Light gray as defined by the current desktop color scheme
DARKGRAY V5.2 Dark gray as defined by the current desktop color scheme
BLACK V5.2 Black as defined by the current desktop color scheme
OFFWHITE V5.2 A color midway between WHITE and LIGHTGRAY
WINDOWBG V5.2 The application background color as defined by the current desktop color scheme

Note: The color names are only used when setting parameter values. CPC View will always return color values in the RRGGBB format.

1.2.4. ENUMERATION

An enumeration specifies one of a list of allowable choices. Each possible choice is given a string name. The value of the enumeration is simply the name of the current choice. The available choices are defined separately for each parameter that specifies an ENUMERATION encoding. Enumeration names are case insensitive.

1.2.5. STRING

A STRING specifies an arbitrary sequence of characters. To allow for arbitrary characters within the string specification, the sequence %xx is interpreted as the single character with ASCII code xx (where xx is the two digit hexadecimal encoding of the ASCII code). For example, the raw value 123%3B456 is interpreted as the string 123;456 (since ASCII 3B is a semi-colon).

1.2.6. CUSTOM

CUSTOM encodings are used for parameters which do not conform to any of the general encodings listed above. The parameter definition will describe the specific nature of the encoding.

1.3. Manipulating Parameter Lists

The following Javascript code sample demonstrates one method for retrieving specific parameter values from a parameter list. The function paramGet returns the value of the parameter name in the parameter list, plist. If name is not found in plist, the function returns null. 

function paramGet(plist, name)
{
 
We iterate over each parameter in the string. On each iteration,
  i is the index of the next name=value entry in the string.

  var i=0;
  while(i<plist.length) {
   
The parameter is terminated by a semi-colon or the end of the string.

    var end = plist.indexOf(";", i), thisName, thisVal;
    if(end == -1) { end = plist.length; }
    thisName = plist.substring(i, end);
   
The value is separated from the name by an '='.

    var sep = thisName.indexOf('=', 0);
    if(sep >= 0) { 
        thisVal = thisName.substring(sep+1, thisName.length);
        thisName = thisName.substring(0, sep);
    }
   
If this is the desired name, return its value.

    if(thisName.toUpperCase() == name.toUpperCase()) { return thisVal; }
   
Move to the next entry.

    i = end+1;
  }
  return null;
}

2. Parameter Spaces

The state of the viewer is organized into sets of related parameters known as parameter spaces. Each parameter space has a name which identifies it and is described by a parameter list. For example, the UI parameter space contains those parameters related to the CPC View user interface. The following table enumerates the CPC View parameter spaces. The specifics of each parameter space are discussed later in this document.

Space Name Related To Type As Of
AnnotationProgrammable annotations write only V5.2
CmdUser interface commands write only V5.8.5
Document Current document read only V5.2
Page Current page read only V5.2
UI User interface settings read write V5.2
Version Software version information read only V5.2

The state of a parameter space is the value of all of the space's parameters. CPC View provides three methods for manipulating the state of parameter spaces. The getState method retrieves the state of a parameter space and the setState and setStateS methods modify the state of a parameter space.

2.1. getState

CPC View Method: getState
Prototype: String getState(String spaceName)
Returns: A parameter list describing the current state of the parameter space named spaceName.
Note: Not all parameter spaces support this method. Some spaces (e.g., Annotation space) are write-only and hence support only the setState and setStateS methods.

2.2. setState

CPC View Method: setState
Prototype: BOOL setState(String spaceName, String plist)
Modifies the state of the parameter space whose name is spaceName. The modifications are specified in the parameter list plist. Only those parameters explicitly referenced by plist are modified. All other parameters within the space remain unchanged.
Returns: Non-zero if spaceName was a recognized parameter space. Otherwise, returns zero.
Note: The return value does not indicate whether or not all of the parameters in the list were successfully updated. Unrecognized parameters are simply ignored.
Note: Not all parameter spaces support this method. Some spaces (e.g., Document space) are read-only and hence support only the getState method.

2.3. setStateS

CPC View Method: setStateS
Prototype: String setStateS(String spaceName, String plist)
Modifies the state of the parameter space whose name is spaceName. The modifications are specified in the parameter list plist. Only those parameters explicitly referenced by plist are modified. All other parameters within the space remain unchanged.
Returns: A parameter list describing the result of the operation. The parameter worked will be set to 1 if the operation worked. If the operation fails, the parameter err will be set to a string describing the error. If the operation was cancelled by the user, the parameter usercancel will be set to 1.

Other parameters that are specific to the parameter space may also be included in the returned parameter list. These parameters are described in the documentation for the specific parameter space.

Note: Not all parameter spaces support this method. Some spaces (e.g., Document space) are read-only and hence support only the getState method.
Note: This method requires version 6.5.6 or later of the viewer.

2.4. Subspaces

Certain parameter spaces are further partitioned into subspaces. The state of one subspace is totally independent of all other subspaces. Subspaces provide a mechanism by which a single parameter space can be used to describe an unlimited number of objects. For example, the Annotation space uses subspaces to provide for an unlimited number of independent programmable annotations. Each subspace describes a different programmable annotation.

A subspace name is constructed by appending a parameter list to the space name, separated by a colon. The parameter list specifies whatever additional parameters are used to address subspaces within the specific parameter space. The particular parameters used to address a subspace are defined by the controlling parameter space. For example, the name foo:id=123 would refer to the subspace whose id is 123 within the mythical FOO parameter space.

If a parameter space supports subspaces, the subspace name is used as the spaceName argument to the getState and setState method calls.

3. Document Space

The DOCUMENT parameter space describes attributes of the current document. The DOCUMENT space is a read-only space. It does not support the setState method.

Note: The DOCUMENT space parameters are not available until the document has been opened. CPC View opens documents asynchronously in the background, and hence, the document is opened sometime after the viewer is loaded. CPC View sends the DOCOPEN event after the document is opened.

3.1. File Format

An image document is encoded in some underlying file format. (See the CPC View User's Guide for a list of supported file formats.) Once the document is open, its underlying file format is provided by the format parameter of DOCUMENT space.

DOCUMENT PARAMETER: format=name[ENUMERATION]
name specifies the document's underlying file format. Possible values are cpc, tiff, cals, pbm, or c4.
If omitted by getState: CPC View has not yet opened the document.
Example: format=tiff
The document is in TIFF format.

3.2. Page Count

A document can be composed of multiple images or pages. (CPC View supports many file formats, such as CPC or TIFF, which allow multiple images to be stored in a single file.) Each image within the document is considered to be a separate page of the document. Once the document is open, the number of pages is provided by the numPages parameter of DOCUMENT space.

DOCUMENT PARAMETER: numPages=n[INTEGER]
n is the number of pages in the current document.
If omitted by getState: The number of pages in the document has not yet been determined.
Example: numPages=3
The document has three pages.

3.3. Example

INVOCATION: getState("Document")
RESULT: numPages=2;format=cpc
The current document has 2 pages and is in CPC format.

4. Page Space

At any time, one page in the document is considered to be the selected page. In page view, the selected page is the page that is displayed; in thumbnail view, the selected page is highlighted in the display. The PAGE parameter space describes attributes of the current selected page. The PAGE space is a read-only space. It does not support the setState method.

4.1. Dimensions

The pixel dimensions of the selected page are available though the dim parameter of PAGE space.

PAGE PARAMETER: dim=width[INTEGER],height[INTEGER]
The dimensions of the selected page in pixels. width is the number of pixels in one row of the image and height is the number of pixel rows in the image. The height and width are separated by a comma.
If omitted by getState: The dimensions of the page are not yet known.
Example: dim=1200,1888
The current page is 1200 pixels wide and 1888 pixels high.

4.2. Resolution

The underlying file format may provide information regarding the resolution of the image. The resolution specifies the number of pixels that fit into a single inch. The resolution can differ in the two dimensions. For example, low resolution FAX images have approximately 100 pixels per inch in the vertical direction and 200 pixels per inch in the horizontal direction. The resolution of the current page is provided by the dpi parameter of PAGE space.

PAGE PARAMETER: dpi=xres[INTEGER],yres[INTEGER]
The resolution of the current page in dots per inch. xres is the horizontal resolution and yres is the vertical resolution. The horizontal and vertical resolutions are separated by a comma.
If omitted by getState: The resolution of the page is not known.
Example: dpi=204,96
The current page has a horizontal resolution of 204 dpi and a vertical resolution of 96 dpi.

4.3. Annotations

A page can contain annotations created by the user. The number of annotations on the current page is provided by the numAnnotations parameter of the PAGE space.

PAGE PARAMETER: numAnnotations=n[INTEGER]
n is the number of annotations on the current page. Programmable annotations are not included in the count.
If omitted by getState: There are no annotations on the current page (or there is no current page because the document is not yet loaded).
Example: numAnnotations=1
The current page contains 1 annotation.

4.4. Example

INVOCATION: getState("Page")
RESULT: dim=1280,1500;dpi=300,300;numAnnotations=2
The currently selected page is 1280 pixels wide and 1500 pixels high. The image has a resolution of 300 dpi. The page contains 2 annotations.

5. UI Space

The UI parameter space describes the current state of the CPC View user interface. (This space is an extension of the CPC View URL parameters.) The UI space supports both the getState and setState methods.

5.1. View Mode

The viewer can be in one of two view modes. In page mode, the viewer displays a single page of the document. In thumbnail mode, the viewer displays thumbnail images of all of the pages in the document. The current view mode is available though the thumbnail parameter of UI space. Changes to the value of thumbnail (via setState) will be reflected in the user interface immediately.

UI PARAMETER: thumbnail=cols[INTEGER],rows[INTEGER]
The current view mode. If set, the viewer is in thumbnail view. To set page mode, use !thumbnail.
Width and height are used to determine the layout of the thumbnails (Width and height are optional. If they are not specified when setting thumbnail mode, the most recent thumbnail layout is restored.)
  • If both height and width are zero, a layout is used in which all of the cells fit into the view.
  • If height is zero and width is non-zero, the layout is arranged with width cells in each row, and the cells are sized such that width cells fit within the width of the view.
  • If width is zero and height is non-zero, the layout is arranged with height cells in each column, and the cells are sized such that height cells fit within the height of the view.
  • If both width and height are non-zero, the height parameter is treated as zero.
If omitted by getState: The viewer is in page mode.
Example: !thumbnail
Put the viewer in page mode.
Example: thumbnail
Put the viewer in thumbnail mode.
Example: thumbnail=3,0
Put the viewer in thumbnail mode and layout the thumbnails three to a row.

5.2. Selected Page

At any time, one page is considered to be the selected page. (In page view, the selected page is the displayed page. In thumbnail view, the selected page is the highlighted thumbnail.) The page number of the currently selected page is available though the page parameter of UI space. Changes to the value of page (via setState) will be reflected in the user interface immediately.

UI PARAMETER: page=n[INTEGER]
n is the page number of the currently selected page. Pages are numbered from one.
Example: page=3
Select the third page of the document.

5.3. Base Display Page

Typically, the first page of a document is numbered page one. However, this might not be the case if the document is a sub-section of some larger entity. CPC View allows the specification of a base display page for the document. The base display page is the page number that CPC View displays for the first page of the document. (The sequence of pages in the document is assumed to be contiguous. Hence, the i-th page of the document is displayed as the base display page plus i.) The base display page is available though the baseDisplayPage parameter of UI space. Changes to the value of baseDisplayPage (via setState) will be reflected in the user interface immediately.

Note: The base display page affects the display of page numbers to the user. It does not alter the page numbering used by the parameters of the UI space. The statement page=1 always specifies the first page of the document.

UI PARAMETER: baseDisplayPage=n[INTEGER]
n is the page number to display for the first page in the document.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.
Example: baseDisplayPage=123
The first page of the document is displayed to the user as page 123.

5.4. Rotation

The images within the document can be displayed at any of the four ninety degree rotations. The current rotation is available though the rotation parameter of UI space. Changes to the value of rotation (via setState) will be reflected in the user interface immediately.

UI PARAMETER: rotation=r[ENUMERATION]
The current rotation is r which must be either 0, 90, 180, or 360. The rotation is measured clockwise and applies to every page of the document.

5.5. Position

When the image is larger than the window, scrolling is used to display the entire image. The current display origin of the image is available though the position parameter of UI space. Changes to the value of position (via setState) will be reflected in the user interface immediately.

UI PARAMETER: position=x[CUSTOM],y[CUSTOM]
The position within the image of the upper left hand corner of the display window is specified by the two coordinates x and y. Each of the coordinates can be specified as either:
  • FLOAT: The coordinate is interpreted as the fraction of the way across or down the page. For example, position=.25,.5 would specify the upper left corner as the point which lies one quarter of the way across the image and one half of the way down the image. The value must be between 0 and 1.
  • INTEGER: The coordinate is interpreted as the absolute pixel coordinate. Thus, position=1000,500 would specify the upper left corner as column 1000 and row 500 of the image.
getState Notes: The position coordinates will always use FLOAT values.

5.6. Scale

The viewer can display the document pages at an arbitrary magnification. The current magnification is available though the scale parameter of UI space. Changes to the value of scale (via setState) will be reflected in the user interface immediately. The scale parameter affects all pages in the document.

UI PARAMETER: scale=spec[CUSTOM]
Specifies the magnification of the image. spec must be one of the following:
  • fitheight: Fit the image to the height of the image window.
  • fitwidth: Fit the image to the width of the image window.
  • fit: Fit the image to the image window.
  • val[FLOAT]: The image is scaled by the factor val. e.g., .25 for a four-fold reduction.
  • width[INTEGER],height[INTEGER]: Specifies the size in pixels of the image region displayed in the window. The image is scaled to contain at least width pixels horizontally and height pixels vertically.
getState Notes: The value of scale will be set to the fitwidth or fitheight value if either of these modes is active. Otherwise, the value will be set to the absolute scale factor (val[FLOAT]).

UI PARAMETER: scalevalue=val[FLOAT]
Specifies the actual magnification of the image, when the value of scale is either fitwidth or fitheight.
READ ONLY: This parameter is read-only. Its value can not be modified by setState.
Note: Requires CPC View v6.4 or later.

The image reduction algorithm used by the viewer is optimized for integral reductions of the image. When reducing the image, the viewer may round the reduction up to improve rendering speed and image appearance. This adjustment can be disabled to allow for slightly better use of screen space when fitting the image to the window and greater accuracy when zooming with the mouse. The enablement of this adjustment is available though the preciseZoom parameter of UI space. Changes to the value of preciseZoom (via setState) will take effect on the next change in the scale.

UI PARAMETER: preciseZoom [BOOLEAN]
If TRUE, the reduction algorithm scales images exactly. Otherwise, the reduction algorithm adjusts the scale to optimize performance. To disable exact scaling, use !preciseZoom.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.

5.7. Toolbar

The viewer allows a toolbar of useful controls to be placed along one edge of the frame. The current position of the toolbar is available though the toolbar parameter of UI space. Changes to the value of toolbar (via setState) will be reflected in the user interface immediately.

UI PARAMETER: toolbar=pos[ENUMERATION]
The position of the toolbar. pos must be one of the following:
Name As of Description
TOP V5.2 The toolbar is placed along the top edge of the window
BOTTOM V5.2 The toolbar is placed along the bottom edge of the window
LEFT V5.2 The toolbar is placed along the left edge of the window
RIGHT V5.2 The toolbar is placed along the right edge of the window
NONE V5.2 The toolbar is hidden
As a convenient shorthand, the toolbar can also be hidden by specifying !toolbar.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.
Example: !toolbar
Hide the toolbar.
Example: toolbar=bottom
The toolbar is placed along the bottom edge of the window.

The viewer has several different controls that can be placed on the toolbar. The current set of controls is available though the controls parameter of UI space. Changes to the value of controls (via setState) will be reflected in the user interface immediately.

UI PARAMETER: controls=spec[CUSTOM]
Spec is a list of the controls that should appear on the toolbar. Each control name may be preceded by an exclamation mark (!) to specify removal of the control from the toolbar. The following control names are recognized:
Name As of Description
COLOR V5.2 Selects foreground and background display colors
MOUSE V5.2 Selects mouse behavior
PAGE V5.2 Selects page number within document
ROTATION V5.2 Selects display rotation of image
SCROLLPAD V5.2 Allows image scrolling from the toolbar
STATUS V5.2 Status information regarding the document
VIEW V5.2 Selects page or thumbnail mode
ZOOM V5.2 Selects display magnification
ALL V5.2 All of the controls listed above
Values can be separated by either commas (,) or plus signs (+). The plus sign separators are used to specify relative placement of the controls within the toolbar. The plus signs delimit groups of controls whose relative placement is significant. All of the controls in a group to the left of a plus sign will be placed to the left of (or above) the controls to the right of the plus sign. The ordering of controls within a comma separated group is undefined.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.
Example: controls=all,!scrollpad
Enables all the controls except for the scroll pad control.
Example: controls=page+scrollpad+zoom+status
The tool bar contains (in order) the page, scrollpad, zoom and status controls.

5.8. Display Colors

The viewer allows control of the foreground and background colors of black-and-white or grayscale images. The foreground color is used to display pixels of maximal intensity and the background color is used to display pixels of minimal intensity. For grayscale images, the intermediate gray levels are scaled appropriately into the range of colors between the background and foreground colors.

Note: The foreground and background colors are not used when displaying color images.

The current foreground color is available though the foregroundColor parameter of UI space. Changes to the value of foregroundColor (via setState) will be reflected in the user interface immediately.

UI PARAMETER: foregroundColor=c[COLOR]
The foreground color is c. This parameter has no effect on color images.

The current background color is available though the backgroundColor parameter of UI space. Changes to the value of backgroundColor (via setState) will be reflected in the user interface immediately.

UI PARAMETER: backgroundColor=c[COLOR]
The background color is c. This parameter has no effect on color images.

5.9. Mouse Mode

CPC View provides several different mouse modes which define the primary behavior when the user presses the left mouse button over the image. The current mouse mode is available though the mouseMode parameter of UI space. Changes to the value of mouseMode (via setState) will be reflected in the user interface immediately.

UI PARAMETER: mouseMode=mode[ENUMERATION]
The mouse mode. Mode must be one of the following:
Name As of Description
SCROLL V5.2 Scrolls the image window by dragging the mouse
ZOOM V5.2 Zooms the image display to the selected rectangle
ANNOTATE V5.2 Annotate the document

5.10. Title

CPC View displays a title for the document in the status control of the toolbar. By default, the title is the last component of the document's URL after stripping any file extension and URL parameters. The document title is available though the docTitle parameter of UI space. Changes to the value of docTitle (via setState) will be reflected in the user interface immediately.

UI PARAMETER: docTitle=s[STRING]
The title of the document to display in the status tool. If no title is specified, a title is derived from the document's URL.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.

5.11. Persistence

Certain UI space parameters, known as document parameters, are maintained persistently on a per URL basis. On return to the same URL, CPC View will restore the document parameter settings to what they were the last time the document was visited.

Note: Only the most recently visited URLs are maintained. There is no guarantee that on return to a URL, the document parameters will be restored.

In some instances, it is desirable to override the document parameters. In this way, the application can be certain that the UI is restored to a particular setting. This can be accomplished via the strict parameter of the UI space.

UI PARAMETER: strict [BOOLEAN]
If set, the document parameters for the current document are not used. Additionally, any changes made to the UI by the user will not be saved in the user's document preferences.
WRITE ONLY: This parameter is write-only. Its value is not returned by getState.

6. Version Space

The VERSION parameter space describes the currently installed version of CPC View. The VERSION space is a read-only space. It does not support the setState method.

6.1. Revision

Each production release of CPC View is assigned a unique revision level. The CPC View revision level is available through the rev parameter of VERSION space.

VERSION PARAMETER: rev=major[INTEGER],minor[INTEGER],respin[INTEGER]
The revision level of the installed version of CPC View. The revision level is specified as a triplet of integers separated by commas. The first number (major) is the major revision level. The second number (minor) is the minor revision level (within the specified major revision). The third number (respin) is the respin number (within the specified minor revision).
Example: rev=5,2,1
The currently installed revision of CPC View is 5.2.1. That is, the major revision is 5, the minor revision is 2, and the respin number is 1.

6.2. Variant

Each variant of CPC View is assigned a unique name. The CPC View variant is available through the variant parameter of VERSION space.

VERSION PARAMETER: variant=val[ENUMERATION]
Specifies the variant of CPC View that is installed. Currently, this is the string ActiveX Control.

6.3. Build Information

The following parameters provide information about the specific build of CPC View.

VERSION PARAMETER: buildNum=n[INTEGER]
Each build of CPC View is given a unique build number. n is the build number of the current version.

VERSION PARAMETER: buildTime=t[INTEGER]
The time at which this version was built. The time (t) is expressed as the number of seconds since January 1, 1970.

6.4. Example

INVOCATION: getState("Version")
RESULT: buildNum=123;buildTime=12345678;rev=5,2,1;variant=ActiveX Control
This is revision 5.2.1 of CPC View. The build number for the revision is 123. The revision was built 12345678 seconds after January 1, 1970.

7. Annotation Space

CPC View provides a number of sophisticated annotation tools for marking up documents. The ANNOTATION parameter space allows external programs to manipulate these annotation tools programmatically, creating new annotations and modifying the properties of existing annotations. Using programmable annotations, an application can highlight specific regions of interest within the image, provide document hyperlinks, or provide additional controls such as image measurement tools.

Virtually all of the annotation functionality available in the CPC View user interface is also available programmatically. (The only user interface functionality that is not available programmatically is the popup sound functionality.) Annotations created and manipulated under programmable control, known as programmable annotations, are distinct from any annotations created by the user via the CPC View user interface, known as user annotations. This means that:

The ANNOTATION space is a write-only space. It does not support the getState method. The state of each programmable annotation is completely specified by the controlling application, so there should not be a need to retrieve the state of an annotation.

7.1. Defaults

Associated with each parameter is a default value (marked Default: ). When an annotation is created, each parameter is initialized to its default value. Once a particular annotation is created, subsequent setState calls for that annotation only modify the parameters explicitly mentioned in the parameter list. Omitted parameters will not be changed.

7.2. Subspaces

CPC View provides the ability to manipulate an unlimited number of programmable annotations simultaneously. Each annotation is assigned a unique annotation ID which is used to uniquely identify the annotation. Each page of the document maintains its own annotation ID namespace. Within a given page, a particular ID value always refers to the same programmable annotation. Multiple annotations may only share the same ID if they reside on different pages.

Each annotation exists in its own subspace. The page and id parameters of the subspace parameter list are used to specify the page number and ID of the annotation. The page number is one based. That is, the first page of the document is page 1. If page is not specified, the currently selected page is used. For example, the string Annotation:id=123 refers to the annotation on the currently selected page whose id is 123. The string Annotation:id=321;page=1 refers to the annotation on page one whose id is 321.

An annotation is created the first time it is referred to by a setState method invocation. The value of the ID has no semantic meaning other than as a means of identification. The external program is free to use whatever values are most convenient.

ANNOTATION SUBSPACE PARAMETER: id=n[INTEGER]
The ID of the annotation (n). This parameter identifies the particular annotation that the setState method call applies to. If the named annotation does not exist, it is created with default properties.
Default: 0

ANNOTATION SUBSPACE PARAMETER: page=n[INTEGER]
The page number on which the annotation resides (n). Pages are numbered from one. If n is zero, the currently selected page of the document is used.
Default: 0

7.3. Class

Each annotation is a member of exactly one annotation class. The annotation class defines the drawing style of the annotation. The annotation class is specified via the class parameter.

Warning: Unlike other parameters, the class parameter is only used on the call that creates the annotation. Subsequent specifications for the class parameter are ignored. There is no way to change the class of an existing annotation.

ANNOTATION PARAMETER: class=className[ENUMERATION]
Specifies the class of the annotation. className must be one of the following names:
Name As of Description
BOX V5.2 A filled rectangle
OVAL V5.2 A filled oval
LINE V5.2 A straight line with or without arrowheads
FREEHANDLINE V5.2 A line through a set of points
TEXT V5.2 A text message
Default: Box

Although most of the parameters in ANNOTATION space are shared by all annotation classes, certain ANNOTATION space parameters are specific to the class. For example, the TEXT annotation supports a drawText parameter describing the text message to display.

7.4. Paper

Annotations are drawn over a rectangular background known as the annotation paper. There are several parameters which affect the annotation paper. (These parameters are supported by all annotation classes.)

ANNOTATION PARAMETER: paperRect=left[INTEGER],top[INTEGER],width[INTEGER],height[INTEGER]
Specifies the origin and size of the paper rectangle in absolute image pixels. The paper is positioned such that its left edge is at column left and the top edge is at row top. The paper is width pixels wide and height pixels high. If the width or height of the paper rectangle is zero, the paper occupies no space on the page and hence the annotation is invisible. As a convenient shorthand, the specification !paperRect is equivalent to the specification paperRect=0,0,0,0.
Default: 0,0,0,0

ANNOTATION PARAMETER: paperColor=color[COLOR]
This parameter specifies the color of the annotation paper (color). Prior to drawing, the paper rectangle is filled with this color.
The paper can also be uncolored. With uncolored paper, only the foreground portions of the annotation are drawn. To specify uncolored paper, use !paperColor.
Default: FFFFA0 The default value is overridden by some annotation classes.

ANNOTATION PARAMETER: paperBorder=name[ENUMERATION]
The paper can be embossed with a border. name specifies the name of the border style and can be one of the following:
Name As of Description
BUTTON V5.2 The paper appears to be raised off the image like a button
PRESSED V5.2 The paper appears to be pressed into the image like a pressed button
FRAMED V5.2 The paper is surrounded by a frame
RECESSED V5.2 The paper appears to be recessed into the image
The paper can also have no border. To specify no border, use !paperBorder.
Default: !paperBorder The default value is overridden by some annotation classes.

ANNOTATION PARAMETER: paperTransparent [BOOLEAN]
The paper can be opaque or transparent. Any drawing which occurs on transparent paper is composited with the underlying image. Any drawing which occurs on opaque paper obscures the underlying image. If paperTransparent is TRUE, the paper is transparent. To make the paper opaque, use !paperTransparent.
Default: !paperTransparent The default value is overridden by some annotation classes.

7.5. Actions

Each annotation can have actions associated with it. The actions control the behavior of the annotation in response to mouse events. The following parameters control the actions associated with an annotation.

ANNOTATION PARAMETER: actionUrl=url[STRING]
Specifies a hyperlink for the annotation. When the user pushes the hyperlink, the URL url will be loaded into the browser. To clear the hyperlink, specify !actionUrl.
If the URL consists solely of URL parameters (i.e., it begins with a leading # or ?), the parameters are applied to the current document. For example, if url is ?page=1, pushing the hyperlink will cause the viewer to return to page 1 of the current document.
Default: !actionUrl

ANNOTATION PARAMETER: actionText=msg[STRING]
Specifies a popup text message for the annotation. When the user presses the mouse over the annotation, msg will be displayed in a popup window. To clear the popup text, specify !actionText.
Default: !actionText

ANNOTATION PARAMETER: actionTip=msg[STRING]
Specifies a status line tip for the annotation. Whenever the mouse is over the annotation, msg will be displayed in the browser's status line. To clear the tip, specify !actionTip.
Default: !actionTip

ANNOTATION PARAMETER: actionIcons [BOOLEAN]
As with user annotations, a programmable annotation with actions can automatically display icons indicating the nature of the actions (i.e., popup text; hyperlink). The display of icons is controlled by this parameter. If actionIcons is TRUE, icons are displayed indicating the nature of the actions. To remove the icons, use !actionIcons.
Default: actionIcons

7.6. Box Class

The BOX annotation class displays the annotation paper and nothing else. There are no additional parameters associated with the BOX class and the class does not override any of the general parameter defaults.

7.7. Oval Class

The OVAL annotation class draws a colored oval on the annotation paper. The oval is sized to fit the interior of the annotation paper. The class overrides the following general parameter defaults: The following class-specific parameters control the appearance of the oval.

OVAL ANNOTATION PARAMETER: drawColor=color[COLOR]
color specifies the color of the interior of the oval.
Default: FFA0A0

OVAL ANNOTATION PARAMETER: edgeColor=color[COLOR]
A one pixel edge is drawn around the oval. color specifies the color of the edge.
Default: 000000 (pure black)

7.8. Line Class

The LINE annotation class draws a straight line between two points on the edge of the annotation paper. The class overrides the following general parameter defaults: The following class-specific parameters control the appearance of the line.

LINE ANNOTATION PARAMETER: drawColor=color[COLOR]
color specifies the color of the line.
Default: C00000

LINE ANNOTATION PARAMETER: drawSize=n[INTEGER]
n specifies the pixel thickness of the line at full scale. (The thickness of the line is automatically scaled with the image.)
Default: 4

LINE ANNOTATION PARAMETER: lineType=type[ENUMERATION]
The lineType determines the edge points of the annotation paper through which the line is drawn. type must be one of the following values:
Name As of Description
HORIZ V5.2 The line is drawn from the mid-point of the left edge to the mid-point of the right edge
VERT V5.2 The line is drawn from the mid-point of the top edge to the mid-point of the bottom edge
DIAGNE V5.2 The line is drawn along the diagonal from the southwest corner to the northeast corner
DIAGNW V5.2 The line is drawn along the diagonal from the southeast corner to the northwest corner
X V5.2 Lines are drawn along both diagonals
Default: DIAGNW

LINE ANNOTATION PARAMETER: startArrow [BOOLEAN]
If set, an arrow is drawn over the starting point of the line. To clear the arrow, specify !startArrow.
Default: !startArrow

LINE ANNOTATION PARAMETER: endArrow [BOOLEAN]
If set, an arrow is drawn over the ending point of the line. To clear the arrow, specify !endArrow.
Default: !endArrow

7.9. FreehandLine Class

The FREEHANDLINE annotation class draws a series of connected line segments within the annotation paper. The line is specified as a set of n points pi. The annotation is drawn as n-1 line segments with the i-th segment connecting the points pi and pi+1.

The class overrides the following general parameter defaults:

The following class-specific parameters control the appearance of the freehand line.

FREEHANDLINE ANNOTATION PARAMETER: drawColor=color[COLOR]
color specifies the color of the line.
Default: 0000FF

FREEHANDLINE ANNOTATION PARAMETER: drawSize=n[INTEGER]
n specifies the pixel thickness of the line at full scale. (The thickness of the line is automatically scaled with the image.)
Default: 1

FREEHANDLINE ANNOTATION PARAMETER: points=point-list[CUSTOM]
Specifies the list of points to connect. Each point is specified as a coordinate pair, (x y), where x is the column offset (in pixels) of the point from the left edge of the annotation paper and y is the row offset (in pixels) of the point from the top edge of the annotation paper. The coordinate pairs are separated by commas.
Example:
The string (1 1), (3 1), (1 5) specifies a line consisting of two segments. The first segment is from column 1 and row 1 of the annotation paper to column 3 and row 1. The second segment is from column 3 and row 1 to column 1 and row 5.

7.10. Text Class

The TEXT annotation class draws text onto the annotation paper. The class overrides the following general parameter defaults:

The following class-specific parameters allow control of the text font, color, and alignment.

TEXT ANNOTATION PARAMETER: drawHAlign=type[ENUMERATION]
Specifies the horizontal alignment of the text within the paper rectangle. type must be one of the following:
Name As of Description
LEFT V5.2 Align the text against the left edge of the paper
CENTER V5.2 Align the text centered horizontally within the paper
RIGHT V5.2 Align the text against the right edge of the paper
Default: Left

TEXT ANNOTATION PARAMETER: drawColor=color[COLOR]
color specifies the color of the text.
Default: FF0000

TEXT ANNOTATION PARAMETER: drawText=msg[STRING]
msg specifies the text to display. To clear the string, specify !drawText.
Default: !drawText

TEXT ANNOTATION PARAMETER: fontSize=n[INTEGER]
n specifies the point size of the text at full scale. The font size is automatically scaled with the image.
Default: 36

TEXT ANNOTATION PARAMETER: fontFace=name[STRING]
name specifies the name of the font to use to display the text.
Default: The system variable width font as specified in the desktop settings.
Note: The available fonts will differ from computer to computer. If the specified font face is not available, a default font will be used instead. No attempt is made to match the default font to the style of the specified font.

TEXT ANNOTATION PARAMETER: paperAutoSize [BOOLEAN]
If set, the font is automatically resized such that the message fits within the scaled paper rectangle. Otherwise, the font is merely scaled to match the current display setting; the message may not fit within the scaled paper rectangle.
Default: paperAutoSize

8. Cmd Space

The CMD parameter space allows an external program to invoke certain user interface commands (e.g., print; save as). The CMD space is a write-only space. It does not support the getState method.

8.1. Subspaces

The specific command to invoke is determined by the subspace. The subspace is specified as a member of the following enumeration:

CMD SUBSPACE PARAMETER: op=which[ENUMERATION]
The specific command to invoke. which must be one of the following:
Name As of Description
PRINT V5.8.5 Invokes the "Document/Print..." command
SAVEAS V5.8.5 Invokes the "Document/Save As..." command
Note: For brevity, the OP= portion of the subspace name may be omitted. That is, you may write the subspace name as CMD:PRINT or CMD:SAVEAS.

8.2. Execution

Commands invoked via the CMD parameter space are typically executed in the same manner as when the user invokes the corresponding command directly from the user interface. This means that a parameter window is displayed (e.g., the Select print options window), allowing the user to adjust command parameters and confirm the execution of the command. Any command parameters specified by the plist parameter to setState or setStateS are used to override the initial values displayed by the parameter window.

8.2.1. AutoExec

In some applications, it is desirable to bypass the parameter window so that the command runs without user interaction. To support this capability, CPC View provides the AutoExec parameter. When the AutoExec parameter is specified, the command is executed without user interaction.

8.2.2. Security Permits

The AutoExec capability opens up a minor security hole. For example, a nefarious web page could use this capability to consume all of a computer's free disk space, by repeatedly invoking the SAVEAS command.

To provide a level of security against misuse of the feature, CPC View requires that the value of the AutoExec parameter be a valid security permit. A security permit is simply an arbitrary string which is checked against a list of allowable security permits maintained in the Windows registry. If the permit is in the allowed list, the operation proceeds without user interaction; otherwise, the AutoExec parameter is ignored and the operation proceeds exactly as if the AutoExec parameter was not specified.

The list of allowed security permits is maintained in the sub-keys of the following registry key:

HKEY_CURRENT_USER\Software\Cartesian Products\CPC View\Permits

The name of each sub-key that exists within this key is an allowable security permit.

For example, if the permit foo123bar is an allowable security permit, the following key must exist in the Windows registry:

HKEY_CURRENT_USER\Software\Cartesian Products\CPC View\Permits\foo123bar

Note: CPC View does not create allowable security permits in the registry. The registry's list of allowable security permits must be configured via external means. For example, if the host application has an installation program, the installation program could create the necessary keys.

8.3. Print

To invoke the Document/Print... command, call the setState or setStateS method specifying the CMD:PRINT subspace. plist specifies parameters to the print command, as described below.

Note: Unless otherwise noted below, unspecified parameters are initialized to the default values for the current user; that is, the default values will be identical to the default values when the user invokes the print command directly via the user interface.

Note: Prior to version 6.2, plist was not used by this subspace. All parameters were simply initialized to their default values.

8.3.1. Scaling

CMD:PRINT PARAMETER: AutoScale=type[ENUMERATION]
Specifies the mode of scaling to use when printing the images. type must be one of the following:
Name As of Description
DISABLE V6.2 Do not scale
MATCHPRINTERPAGESIZE V6.2 Scale each image to match the printer page size
MATCHPRINTERRESOLUTION V6.2 Scale each image to match the printer resolution
Example: autoScale=MatchPrinterResolution
Scale each image to match the printer resolution.

CMD:PRINT PARAMETER: MatchPrinterResolution:DefaultRes=res[INTEGER]
The default page resolution to use when MatchPrinterResolution is specified. The default page resolution is used when the source image does not specify a resolution.
Example: matchPrinterResolution:DefaultRes=400
Use a resolution of 400 dpi for any image that does not specify a resolution.

CMD:PRINT PARAMETER: MatchPrinterResolution:Scale=scale[FLOAT]
Additional scaling to apply when MatchPrinterResolution is specified. The additional scaling is applied after calculating the scale necessary to match the page image resolution to the printer resolution.
Example: matchPrinterResolution:Scale=.5
Print the images at 1/2 the calculated size.

8.3.2. Page Range

CMD:PRINT PARAMETER: PageRange=range[CUSTOM]
Specifies the range of pages to print. range must be one of the following:
Name As of Description
ALL V6.2 Print all of the document pages.
CURRENTVIEW V6.2 Print the current view of the document.
range[STRING] V6.2 A specific range of pages to print. The page range is specified as a comma-separated list of sub-ranges. Each sub-range is specified as either a single page (e.g., 5) or a contiguous range of pages (e.g. 3-7). Pages are numbered from 1.

The end page of a contiguous range can be left empty. This is interpreted as a range that ends with the last page of the document. For example, the range 3- specifies all pages from the 3rd page on.

Default: All
Example: pageRange=1,5,7-9,12-
Prints pages 1, 5, 7, 8, 9, and 12 through the last page of the document.

CMD:PRINT PARAMETER: IncludePages=which[ENUMERATION]
Specifies the types of pages to include in the print job. which must be one of the following:
Name As of Description
ALL V6.2 Include all pages in the specified page range
ODD V6.2 Include only odd pages in the specified page range
EVEN V6.2 Include only even pages in the specified page range
Default: All
Example: includePages=Odd
Include only the odd pages that are in pageRange.

CMD:PRINT PARAMETER: NumCopies=copies[INTEGER]
Specifies the number of copies to print.
Default: 1
Example: numCopies=3
Print 3 copies of each page.

CMD:PRINT PARAMETER: Collate [BOOLEAN]
If TRUE and multiple copies are specified, the copies are collated.

8.3.3. Printer

CMD:PRINT PARAMETER: PrinterName=printer[STRING]
The name of the printer to use. printer should be specified exactly as it is displayed in the printer dropdown menu of the Select print options dialog box.
Example: printerName=HP LaserJet 4V
Send the images to the printer whose name is HP LaserJet 4V.

CMD:PRINT PARAMETER: PrintToFile [BOOLEAN]
If TRUE, printer output is saved in a file rather than sent to the printer.
Default: FALSE

CMD:PRINT PARAMETER: OutputFileName=path[STRING]
The full pathname of the file in which to save the printer output. Specifying this parameter implies PrintToFile.
Warning: The specified file must NOT exist. If the file already exists, the user will be asked whether or not to overwrite the existing file. This prompt will occur even if the AutoExec parameter is specified.

8.3.4. Other Options

CMD:PRINT PARAMETER: IncludePageTitles [BOOLEAN]
If TRUE, the viewer adds page titles to the top of each page. Otherwise, it does not add page titles.

CMD:PRINT PARAMETER: IncludeAnnotations [BOOLEAN]
If TRUE, the viewer includes any annotations in the printout. Otherwise, annotations are not included.

CMD:PRINT PARAMETER: AutomaticOrientation [BOOLEAN]
If TRUE, the viewer will automatically select landscape or portrait orientation based on the dimensions of each page. Otherwise, the viewer uses the printer's default orientation.

CMD:PRINT PARAMETER: QuickPrint [BOOLEAN]
If TRUE, the viewer cuts the resolution of the images in half prior to printing. Otherwise, the images are printed at full resolution.

CMD:PRINT PARAMETER: InvertImageColors [BOOLEAN]
If TRUE, the colors of the image are inverted prior to printing. That is, black pixels print as white and white pixels print as black.

8.3.5. Returned Parameter List

If invoked via the setStateS method, the returned parameter list will include the pagesprinted parameter which specifies the number of pages that were successfully printed.

8.3.6. Examples

INVOCATION: setState("cmd:print", "")
RESULT: Invokes the Document/Print... command, exactly as if the user had invoked it from the right mouse menu.

INVOCATION: setState("cmd:print", "pagerange=1-2;AutoExec=mypermit")
RESULT: Print pages 1-2 of the current document without any additional user interaction.

8.4. Save As

To invoke theDocument/Save As... command, call the setState or setStateS method on the CMD:SAVEAS subspace. plist specifies parameters to the save command, as described below.

Note: Unspecified parameters are initialized to the default values for the current user; that is, the default values will be identical to the default values when the user invokes the save command directly via the user interface.

Note: Prior to version 6.2, plist was not used by this subspace. All parameters were simply initialized to their default values.

8.4.1. Output File

CMD:PRINT PARAMETER: FileName=path[STRING]
The full pathname of the file in which to save the document.
Example: filename=c:\temp\foo.cpc
Save the document to the file c:\temp\foo.cpc.
Warning: The specified file must NOT exist. If the file already exists, the user will be asked whether or not to overwrite the existing file. This prompt will occur even if the AutoExec parameter is specified.

CMD:PRINT PARAMETER: FileType=type[ENUM]
Specifies the file format in which to save the document. type must be one of the following:
Name As of Description
cpc V6.2 Save the images in the CPC file format.
cpc:annBurn V6.2 Burn the annotations into the images and save the result in the CPC file format.
cpc:annBinary V6.2 Save only the annotations in the CPC binary annotation format
cpc:annXML V6.2 Save only the annotations in the CPC XML annotation format
cpc:annDoc V6.2 Save the annotations and the images in the CPC file format
tiff V6.2 Save the images in the TIFF file format.
tiff:annBurn V6.4 Burn the annotations into the images and save the result in the TIFF file format.
pdf V6.2 Save the images in the PDF file format.
pdf:annBurn V6.4 Burn the annotations into the images and save the result in the PDF file format.
pbm V6.2 Save the images in the Portable Bitmap file format.
pbm:annBurn V6.4 Burn the annotations into the images and save the result in the Portable Bitmap file format.
Example: filetype=cpc:annBurn
Burn any annotations into the images and save the resultant images in the CPC file format.

8.4.2. Page Range

CMD:PRINT PARAMETER: PageRange=range[STRING]
The pages within the document to save. The page range is specified as a comma-separated list of sub-ranges. Each sub-range is specified as either a single page (e.g., 5) or a contiguous range of pages (e.g., 3-7). Pages are numbered from 1.
The end page of a contiguous range can be left empty. This is interpreted as a range that ends with the last page of the document. For example, the range 3- specifies all pages from the 3rd page on.
Example: pagerange=1,5,7-9,12-
Saves pages 1, 5, 7, 8, 9, and 12 through the last page of the document.

8.4.3. Returned Parameter List

If invoked via the setStateS method, the returned parameter list will include the pagessaved parameter which specifies the number of pages that were successfully saved.

8.4.4. Examples

INVOCATION: setState("cmd:saveas", "")
RESULT: Invokes the Document/Save As... command, exactly as if the user had invoked it from the right mouse menu.

INVOCATION: setState("cmd:saveas", "filename=c:/temp/foo.cpc;pagerange=1-2;AutoExec=mypermit")
RESULT: Save pages 1-2 of the current document to the file c:/temp/foo.cpc without any additional user interaction.

9. Events

CPC View uses parameterized events to inform the external program of asynchronous changes to the viewer's state (e.g., the document has been opened) or explicit actions performed by the user (e.g., a mouse button was pressed).

9.1. Event Description

An event is described by an event type and a parameter list. The event type specifies the type of asynchronous event which occurred and the parameters provide additional information regarding the specific occurrence of the event. The event type and parameters are combined into a single string known as the event description. The event description is composed of the event type, followed by a colon, followed by the parameter list. If there are no parameters to the event, the colon is omitted.

For example, the string SimpleEvent describes a fictional SIMPLEEVENT event with no parameters. The string FakeEvent:x=1;y=2 describes a fictional FAKEEVENT event with two additional event parameters: x whose value is 1; and y whose value is 2.

The following event types are defined:

Name As of Description
DOCOPEN V5.2 The document has been opened
VIEWCHANGE V5.2 The display of the document has changed
MOUSEMOVE V5.2 The mouse cursor was moved within the viewer window
MOUSEBUTTON V5.2 A mouse button was pressed or released within the viewer window
MOUSEEXIT V5.2 The mouse cursor was moved from inside the viewer window to outside the viewer window
KEYPRESS V5.2 The user typed a key on the keyboard

9.2. Event Handler

The external program specifies a single event handler, which is invoked by CPC View each time an event occurs, and is passed the event description as its only argument. Where applicable, the return value from the event handler is used to control whether or not the internal CPC View event handling also takes place. A return value of zero indicates that CPC View should process the event normally. A non-zero return value indicates that CPC View should ignore the event.

For example, when the user presses the right mouse button, the internal CPC View handling would normally cause a context menu to pop up. In order to prevent the context menu from appearing, the event handler should return a non-zero value when called with the description of a right mouse button press event.

Note: The DOCOPEN, VIEWCHANGE, MOUSEMOVE, and MOUSEEXIT events do not use the return value of the event handler. There is no additional internal processing for these events.

9.2.1. Receiving events in Internet Explorer

In order to define the CPC View event handler in HTML under Internet Explorer, you should use the FOR and EVENT attributes of the <SCRIPT> tag. For example, the following code causes an alert panel to appear for every event generated by the viewer whose ID attribute is cpc. The description of the event is received in the string ev. <SCRIPT FOR=cpc EVENT="cpcevent(ev)" LANGUAGE="JavaScript"> alert("Event is: " + ev); return 0; </SCRIPT>

9.3. Display Events

The following events are generated in response to changes in the state of the viewer display.

9.3.1. DocOpen

The DOCOPEN event is a one time event generated when CPC View has received enough of the image data stream to determine the file format and other document related state information such as the number of pages.

There are no parameters associated with this event. The return value of the event handler is not used.

Note: CPC View asynchronously loads the image data for the document. Hence, there is some delay between the instantiation of the control and the opening of the document.

9.3.2. ViewChange

The VIEWCHANGE event is sent whenever the view of the selected page is changed. This can occur because of changes to the selected page, display scale, display rotation, view mode, scroll position, or annotation visibility.

There are no parameters associated with this event. The return value of the event handler is not used.

Note: Changes to the scroll position only generate VIEWCHANGE events in CPC View v6.4 or later. Earlier versions of the viewer did not generate VIEWCHANGE events when the scroll position changes.

9.4. Mouse Events

The following events are generated when the user manipulates the mouse within the CPC View window.

9.4.1. MouseMove

The MOUSEMOVE event is generated whenever the mouse cursor is moved within the CPC View window. The following parameters are used to describe the event:

MOUSEMOVE EVENT PARAMETER: x=col[INTEGER]
Specifies the absolute column of the image pixel that the mouse is over (col).

MOUSEMOVE EVENT PARAMETER: y=row[INTEGER]
Specifies the absolute row of the image pixel that the mouse is over (row).

Example

MouseMove:x=123;y=456
The mouse has moved over the pixel at column 123 and row 456 in the image

Return Value

The return value from the event handler is not used.

9.4.2. MouseButton

The MOUSEBUTTON event is generated whenever the user presses or releases a mouse button. The following parameters are used to describe the event:

MOUSEBUTTON EVENT PARAMETER: button=which[ENUMERATION]
The button that was pressed or released. which will be one of the following:
Name As of Description
LEFT V5.2 the left button was pressed or released
RIGHT V5.2 the right button was pressed or released
Note: The middle mouse button does not generate MOUSEBUTTON events.

MOUSEBUTTON EVENT PARAMETER: state=which[ENUMERATION]
The current state of the button. which will be one of the following values:
Name As of Description
DOWN V5.2 the button was pressed
UP V5.2 the button was released

MOUSEBUTTON EVENT PARAMETER: x=col[INTEGER]
x specifies the absolute column of the pixel in the image which the mouse is over.

MOUSEBUTTON EVENT PARAMETER: y=row[INTEGER]
y specifies the absolute row of the pixel in the image which the mouse is over.

Examples

MouseButton:x=123;y=456;button=left;state=down
The left mouse button was pressed over the pixel at column 123 and row 456 in the image

MouseButton:x=123;y=456;button=left;state=up
The left mouse button was released over the pixel at column 123 and row 456 in the image

Return Value

The return value from the event handler determines whether or not the MOUSEBUTTON event is processed internally by CPC View or is ignored. A non zero return value will cause CPC View to ignore the MOUSEBUTTON event. Otherwise, the event is processed normally.

9.4.3. MouseExit

The MOUSEEXIT event is generated whenever the mouse is moved from inside the CPC View window to outside the CPC View window and a MOUSEMOVE or MOUSEBUTTON event was generated while the mouse was in the window.

There are no parameters associated with this event. The return value from the event handler is not used.

9.5. Keyboard Events

Keyboard events are generated in response to user actions on the keyboard such as typing. Keyboard events are only generated when the CPC View window has the input focus. The CPC View window is given the input focus by either

Note: CPC View does not provide any visual indication that it has input focus.

9.5.1. KeyPress

A KEYPRESS event is generated whenever the user types on the keyboard and the CPC View window has the input focus. KEYPRESS events are not generated for modifier keys (such as the ALT or CTRL keys). The following parameters are used to describe the event.

KEYPRESS EVENT PARAMETER: char=c[INTEGER]
The ASCII value of the character that was typed (c).

KEYPRESS EVENT PARAMETER: ctrl [BOOLEAN]
The CTRL key was pressed simultaneously.
If omitted from the parameter list: The CTRL key was not pressed simultaneously

KEYPRESS EVENT PARAMETER: alt [BOOLEAN]
The ALT key was pressed simultaneously.
If omitted from the parameter list: The ALT key was not pressed simultaneously

KEYPRESS EVENT PARAMETER: shift [BOOLEAN]
The SHIFT key was pressed simultaneously.
If omitted from the parameter list: The SHIFT key was not pressed simultaneously

Example

KeyPress:char=67;ctrl
The CTRL-C key was pressed. That is, the C and CTRL keys were simultaneously pressed.

Return Value

The return value from the event handler determines whether or not the KEYPRESS event is processed internally by CPC View or is ignored. A non-zero return value will cause CPC View to ignore the KEYPRESS event. Otherwise, the event is processed normally.

Index

THE FINE PRINT (regarding copyrights and trademarks)

Cartesian Products, Inc.
cpi@cartesianinc.com