ImageGear .NET - Updated
ViewerControl API
User Guide > How to Work with... > Common Operations > Viewing > Viewing with the HTML5 Viewer > ViewerControl API

The HTML5 Viewer provides a simple UI that offers viewing functionality.

ViewerControl exists with the ImageGear.Web distribution under the IPCC namespace and can be instantiated independently as a stand-alone document viewer with no user interface.

Accessing IPCC.ViewerControl

From an instantiated IGViewer.Viewer, its underlying IPCC.ViewerControl instance can be accessed as demonstrated by the following code example:

JS
Copy Code 
<script type="text/javascript">
    var igViewer,
    ipccViewerControl;
    $(function () {
        igViewer = new IGViewer.Viewer("#viewer", {
            documentID: "mydocument.pdf",
            imageHandlerUrl: "/ImageGearService.svc",
            viewerIconsPath: "/Assets/Viewer/icons"
        });
        ipccViewerControl = igViewer.viewerControl;
    });
</script>

Once you obtain a reference to the ViewerControl instance beneath the Viewer GUI, you can use it to obtain information regarding the current view state, manipulate it directly, and register custom event listeners. A description of available ViewerControl properties, methods, and event types follows.

ECMAScript 2015 Accessor Properties

ECMAScript 2015 accessor properties function in a manner similar to C# properties in that they allow code execution upon getting or setting a value to be associated with the property’s identifier. Any reference to the accessor property will execute code that returns its value. Assigning a value to an accessor property using "object.accessorProperty = value;" will execute code which handles setting of the property to the desired value.

For ease of use on a supported browser, certain aspects of ViewerControl are configurable through accessor properties, however, there are always a set of getter/setter methods for each property to accommodate browsers which to not support accessor properties.

ViewerControl Properties

Accessor

Getter

Setter

Type

Description

atMaxScale

getAtMaxScale()

N/A

boolean

(accessor read-only) Gets a value that indicates whether the viewer is currently at the maximum scale factor. If this value is true, ViewerControl will be unable to zoom in further.

This method determines the value each time, and will be affected by the following:

1.       The viewer scale changes due to zoomIn, zoomOut, or fitContent.

2.       The window resizes.

3.       The div that holds the ViewerControl is resized.

Throws Error:

  • If the IPCC.EventType.ViewerReady event was not fired prior to access or method call.

atMinScale

getAtMinScale()

N/A

boolean

(accessor read-only) Gets a value that indicates whether the viewer is currently at the minimum scale factor. If this value is true, ViewerControl will be unable to zoom out further.

This method determines the value each time, and will be affected by the following:

1.       The viewer scale changes due to zoomIn, zoomOut, or fitContent.

2.       The window resizes.

3.       The div that holds the ViewerControl is resized.

Throws Error:

  • If the IPCC.EventType.ViewerReady event was not fired prior to access or method call.

pageCount

getPageCount()

N/A

number

(accessor read-only) Gets the known page count of the current document.

This value is updated when the viewer gets the page count or estimated page count from the server. Subscribe to the IPCC.EventType.PageCountReady event to be notified when the viewer gets the page count from the server.

Will report a page count of 1 before the PageCountReady event fires.

pageNumber

getPageNumber()

setPageNumber(x)

number

Gets or sets the currently displayed page starting at index 1 (the page number of the first page is 1).

Throws Error:

  • If attempting to set to a value less than 1 or greater than the value returned by IPCC.ViewerControl.pageCount.
  • If attempting to set to a value that is not a number or a string representation of a number.
  • If attempting to set to a number that has a fractional component.

scaleFactor

getScaleFactor()

setScaleFactor(x)

number

Gets or sets the scale factor to use in the viewer, with 1 being 100% zoom.

For "Document" and "SinglePage" view mode, the scale factor represents the amount that each page in the document is scaled. For "EqualFitPages" view mode, the scale factor represents the amount that the first page of the document is scaled.

The viewer has minimum and maximum scale limits. The limits depend on the size of the pages. Check IPCC.ViewerControl.minScaleFactor and IPCC.ViewerControl.maxScaleFactor to determine minimum and maximum scale.

 Throws Error:

  • If attempting to set to a scale factor that is out of the permissible range.
  • If attempting to set before the IPCC.EventType.ViewerReady event was fired.

viewMode

getViewMode()

setViewMode(x)

string

Gets or sets the view mode. This defines how the document pages will be scaled. Must be one of the values in the IPCC.ViewMode enum described in a later subsection "ViewerControl Enum Parameters".

When set to "Document" or "EqualFitPages", this property only has an effect on documents with different sized pages. Setting the view mode to "Document" maintains the relative size of each page when displaying a document. For example, if page 2 is smaller than page 1, it will appear smaller. Setting the view mode to "EqualFitPages" scales each page so that their width is the same. For example, if page 2 is smaller than page 1, it will be scaled larger so that its width is equal to the width of page 1.

Setting the view mode to "SinglePage" structures the view so that only a single page is shown at a time. Each page is scaled to fit within a view box, which is the initial size of the viewer and increases in size when zooming in (and decreases in size when zooming out). After the viewer initializes, the view mode may not be changed to or from SinglePage view mode (or an exception will occur).

Throws Error:

  • If attempting to set to an unknown value (not in the IPCC.ViewMode enum).
  • If attempting to set before the IPCC.EventType.ViewerReady event has fired.
  • If attempting to set to "SinglePage". This value must be set during initialization. See Instantiating and Customizing the HTML5 Viewer.

N/A

getGamma()

setGamma(x)

number

Gets or sets the gamma factor for the document. Values from 1 to 10 will darken the document. Values from 0 to 1 will effectively lighten it.

Throws Error:

  • If the gamma factor is not a valid number between 0 and 10 inclusive.

N/A

getPageLayout()

setPageLayout(x)

string

Gets or sets the layout of the pages.

This property defines the placement or arrangement of the pages in the viewer. The default page layout is "Vertical", in which the pages are displayed as a single vertical column and a vertical scroll bar is displayed to bring into view pages that are not in view. The "Horizontal" option displays the pages as a single horizontal row and has a horizontal scroll bar to bring into view the pages that are not in view.

Throws Error:

  • If attempting to set to a value not in the IPCC.PageLayout enum. Refer to the later subsection "ViewerControl Enum Parameters" for more information.

N/A

getSharpening()

setSharpening(x)

number

Gets or sets the sharpening factor for the document. The sharpening factor is a valid integer between 0 and 100 inclusive.

Throws Error:

  • If the sharpening factor is not a valid integer between 0 and 100 inclusive.

N/A

getSvgLineWidthMultiplier()

setSvgLineWidthMultiplier(x)

number

Gets or sets the current multiplier used to adjust SVG line widths in the document. This is a numeric value which all SVG Line width values should be multiplied by.

This value must be greater than 0 and must not be greater than 100. To make lines twice as thick as they originally were, use a value of 2. To make lines half as thick as they originally were, use a value of 0.5. To reset lines to their original thickness, use a value of 1.

Throws Error:

  • If attempting to set the line width multiplier to a value that is not greater than 0 or is greater than 100

Other ViewerControl Methods

Method

Description

changeToFirstPage()

Sets the current page of the viewer to the first page of the document.

changeToLastPage()

Sets the current page of the viewer to the last known page of the document.

changeToNextPage()

Sets the current page of the viewer to the next page of the document.

changeToPrevPage()

Sets the current page of the viewer to the previous page of the document.

destroy()

Closes the ViewerControl and cleans up its resources. After this action, a new viewer can be created in its place.

This method should not be called manually. Instead, use the destroy method of the overlying viewer or simply construct a new IGViewer using the same DOM Element.

fitContent(fitType)

Changes the scaling (zoom) of the document to fit the content in the viewer. fitType must be a value in the IPCC.FitType enum, described in the later subsection "ViewerControl Enum Paramters".

Throws Error:

  • If IPCC.EventType.ViewerReady was not fired prior to using this method.
  • If the value is fitType is not one of the values in the IPCC.FitType enum.
  • If the view mode is set to "EqualFitPages" or "EqualWidthPages" and the value of fitType is "ActualSize". Instead, pass a value of 1 to the IPCC.ViewerControl.setScaleFactor() method to cscale the first page to actual size.

getPageRotation(pageNumber)

Gets the page rotation value for the specified page number.

Throws Error:

  • If the IPCC.EventType.ViewerReady event was not fired before using this method.
  • If the provided optional parameter pageNumber is less than 1 or greater than the value returned by IPCC.ViewerControl.getPageCount()
  • If the provided optional parameter pageNumber is not a number or a string representation of a number.
  • If the provided optional parameter pageNumber is not an integer

pageNumber

number

Optional. A 1-based page number of the page whose rotation to retrieve. If this parameter is not provided, the implied pageNumber will be that of the currently displayed page.

rotatePage(degsClockwise)

Rotates the current page by the specified degrees clockwise, relative the page’s current orientation.

Throws Error:

  • If value of degsClockwise is not valid.
  • If the IPCC.EventType.ViewerReady event was not fired prior to using this method

degsClockwise

number

Degrees clockwise to rotate each page. Values values are multiples of 90: {..., -270, -180, -90, 0, 90, 180, 270, …}

rotateDocument(degsClockwise)

Rotates all pages in the document by the specified degrees clockwise, relative to each page’s current orientation.

Throws Error:

  • If value of degsClockwise is not valid.
  • If IPCC.EventType.ViewerReady has not been fired prior to using this method

degsClockwise

number

Degrees clockwise to rotate each page. Values values are multiples of 90: {..., -270, -180, -90, 0, 90, 180, 270, …}

scrollBy(offsetX, offsetY)

Scrolls by the specified offset.

Throws Error:

  • If IPCC.EventType.ViewerReady event was not fired prior to using this method.
  • If target is not an Object with valid offsetX and offsetY values

offsetX

number

Integer that specifies the value to scroll horizontally. Negative values will scroll to the left.

offsetY

number

Integer that specifies the value to scroll vertically. Negative values will scroll upward.

zoomIn(zoomFactor)

Zoom in on the document by the specified zoomFactor.

The viewer has minimum and maximum scale limits. zoomIn will only change the viewer’s scale up to, but not past, the maximum scale limit. zoomIn does not give an indication if the actual scale change was less than the requested zoom factor because the limit was reached. Instead, check IPCC.ViewerControl.atMaxScale to determine if the viewer is at max scale.

Throws Error:

  • If the zoomFactor value is invalid.
  • If the IPCC.EventType.ViewerReady event was not fired prior to calling this method.

zoomFactor

number

Zoom in by this factor. Valid values are between 1.01 and 20.

zoomOut(zoomFactor)

Zoom out on the document by the specified zoomFactor.

The viewer has minimum and maximum scale limits. zoomOut willl only change the viewer’s scale down to, but not past, the minimum scale limit. zoomOut does not give an indication if the actual scale change was less than the requested zoom factor because the limit was reached. Instead, check IPCC.ViewerControl.atMinScale to determine if the viewer is at minimum scale.

Throws Error:

  • If the zoomFactor value is invalid
  • If the IPCC.EventType.ViewerReady event has not fired prior to calling this method

zoomFactor

number

Zoom out by this factor. Valid values are between 1.01 and 20.

ViewerControl Enum Parameters

These enumerations are a convenience for API developers. Instead of using them, you can pass in the corresponding string values directly to the API.

IPCC.FitType

The FitType enumeration defines fit types known by IPCC.ViewerControl. The ViewerControl uses a specified fit type to set or update the scaling of the pages displayed in the viewer.

This enumeration is a convenience for API developers. Instead of using it, you can pass in the corresponding string values of the fit type enumeration directly to the API.

Enum Property

Type

Value

Description

IPCC.FitType.FullWidth

string

"FullWidth"

The viewer scales the content to fill the width of the viewer.

IPCC.FitType.ShrinkToWidth

string

"ShrinkToWidth"

The viewer will scale down the content until it fits fully width-wise into view. The page will into be scaled up if it already fits.

IPCC.FitType.ActualSize

string

"ActualSize"

The viewer shows the content at its actual size. The content is not scaled.

IPCC.FitType.FullHeight

string

"FullHeight"

The viewer scales the content to fill the height of the viewer based on the largest known page height.

IPCC.FitType.FullPage

string

"FullPage"

The viewer scales the content ot best fit the largest known page in the viewer.

IPCC.PageLayout

The PageLayout enumeration defines page layouts known by IPCC.ViewerControl. The ViewerControl uses a page layout to set or update the placement or arrangement of the pages in the viewer.

Enum Property

Type

Value

Description

IPCC.PageLayout.Horizontal

string

"Horizontal"

Pages are displayed as a single horizontal row and a horizontal scroll bar is displayed to bring into view the pages that are not in view.

IPCC.PageLayout.Vertical

string

"Vertical"

Pages are displayed as a single vertical column and a vertical scroll bar is displayed to bring into view the pages that are not in view.

IPCC.ViewMode

The ViewMode enumeration defines view modes known by IPCC.ViewerControl. The ViewerControl uses a view mode to set or update how documents that contain different sized pages are displayed in the viewer.

Enum Property

Type

Value

Description

IPCC.ViewMode.Document

string

"Document"

The viewer maintains the relative size of each page when displaying a document. For example, if page 2 is smaller than page 1, it will appear smaller.

IPCC.ViewMode.SinglePage

string

"SinglePage"

The viewer displays a single page at a time. Each page is scaled to fit within a view box, which is the initial size of the viewer and increases in size when zooming in (and decreases in size when zooming out). After the viewer initializes, the view mode may not be changed to or from SinglePage view mode (an Error will be thrown in this case).

IPCC.ViewMode.EqualFitPages

string

"EqualFitPages"

The viewer scales each page so that their width is the same, when using vertical page layout. For example, if page 2 is smaller than page 1, it will be scaled larger so that its width is equal to the width of page 1. If using horizontal page layout, the viewer scales each page so that their height is the same.

ViewerControl Events and Event Types

ViewerControl does its own internal routing of custom events and provides the following methods to register and unregister event handlers. An event handler is a function which accepts a single "event" parameter which contains information about the event that has occurred. For certain event types, ViewerControl may augment the event object passed to the handler with properties which relay further information about the event.

Methods

Method

Description

ViewerControl.on(eventType, handler)

Subscribe an event handler to an event of a specified type.

eventType

string

A string that specifies the event type. This value is case-insensitive. Refer to the list of event types below.

handler

function

A function that will be called whenever the event is triggered

ViewerControl.off(eventType, handler)

Unsubscribe an event handler from a specified event type. Typically, an event is unsubscribed from when you no longer want further notification of the event.

eventType

string

A string that specifies the event type. This value is case-insensitive. Refer to the list of event types below.

handler

function

A function that was previously registered with the same ViewerControl instance for that same eventType. 

This must be the same function object previously passed to IPCC.ViewerControl.on(...). It cannot be a different object that is functionally equivalent.

IPCC Event Types Enum

These enumerations are a convenience for API developers. Instead of using them, you can pass in the corresponding string values directly to the API.

Enum Property

Value

Description

IPCC.EventType.ViewerReady

"ViewerReady"

Triggered when the Viewer is ready. 

Augmented properties of the event object for this event: None.

IPCC.EventType.PageCountReady

"PageCountReady"

Triggered when the viewer has an actual page count from the server and the consumer can begin to interact with the viewer interfaces. 

Augmented properties of the event object for this event:

  • pageCount {number} - the actual page count of the document

IPCC.EventType.PageChanged

"PageChanged"

Triggered when the viewer changed the current page. 

Augmented properties of the event object for this event: None

IPCC.EventType.PageLoadFailed

"PageLoadFailed"

Triggered when the viewer fails to load a page. 

Augmented properties of the event object for this event:

  • pageNumber {number} - indicates the page number of the page that failed to load
  • statusCode {number} - indicates the HTTP status code returned by the image service

IPCC.EventType.PageDisplayed

"PageDisplayed"

Triggered when the viewer has displayed a page. If the content of a page is large, for example, an engineering drawing with several hundred nodes, then the browser may be busy still rendering/preparing the content when this event gets fired. 

Augmented properties of the event object for this event:

  • pageNumber {number} - the page number of the page that was displayed

IPCC.EventType.PageRotated

"PageRotated"

Triggered when the viewer has rotated a page. 

Augmented properties of the event object for this event:

  • pageNumber {number} - the page number of the page that was rotated

IPCC.EventType.DocumentRotated

"DocumentRotated"

Triggered when the rotation of all pages in the document changes. 

Augmented properties of the event object for this event:

  • degreesClockwise {number} - The amount in degrees clockwise the pages were rotated

IPCC.EventType.ScaleChanged

"ScaleChanged"

Triggered when the scaling of page(s) in the viewer changed. This may occur as a result of a number of user actions including zooming, fit type change, viewer mode change, or scale change. 

Augmented properties of the event object for this event:

  • scaleType {string} - Gives an indication of whether the content was "scaledUp" (got bigger), or "scaledDown" (got smaller)
  • scaleFactor {number} - indicates the new scale factor of the viewer. A value of 1 indicates 100% zoom.
  • trigger {string} - indicates how the scale change was triggered. Possible values are:
    • "Zoom" - indicates a direct zoom, such as using the ViewerControl.zoomIn(), ViewerControl.zoomOut(), or ViewerControl.setScaleFactor() methods.
    • "Fit" - indicates a change due to a fit type being applied through the ViewerControl.fitContent() method.
  • fitType {strring} - indicates the fit type that was applied, if applicable. This property will only be defined if the trigger was "Fit" and will be undefined otherwise.

IPCC.EventType.Click

"Click"

Triggered when a user clicks a page. 

Augmented properties of the event object for this event:

  • pageNumber {number} - the page number of the page that was clicked, or null if none
  • originalEvent {object} - a copy of the browser event
  • clientX {number} - the x window coordinate of the position where the user clicked
  • clientY {number} - the y window coordinate of the position where the user clicked

IPCC.EventType.PageOpening

"PageOpening"

Triggered when the width and height page attributes are retrieved. Note that this event will fire whenever a page opens, so if a page opens, it will fire, and if the page is scrolled out of view, disposed, and then scrolled back into view, the event will fire again. 

Augmented properties of the event object for this event:

  • width {number} - the width in pixels of the page that is opening
  • height {number} - the height in pixels of the page that is opening
  • pageNumber {number} - the 1-based number of the page that is opening
JS
Copy Code 
<script type="text/javascript">
    var igViewer,
        ipccViewerControl;
    $(function () {
        igViewer = new IGViewer.Viewer("#viewer", {
            documentID: "mydocument.pdf",
            imageHandlerUrl: "/ImageGearService.svc",
            viewerIconsPath: "/Assets/Viewer/icons"
        });
        ipccViewerControl = igViewer.viewerControl;
        ipccViewerControl.on(
            IPCC.EventType.PageChanged,
            function (evt) {
                console.log("page changed... "
                    + "current page number is: "
                    + evt.pageNumber);
            }
        );
    });
</script>

 

 

 

©2018. Accusoft Corporation. All Rights Reserved.

Send Feedback