Namespace: Util

Methods

(static) calculateNonOverlappingSelections(selections, backgroundColor) → {Array.<selection>}

This method takes several selection objects -- ranges of start indices and lengths -- and determines if and split overlapping ranges into separate selections objects. It will also interpret the new color in the overlapping regions using PCCViewer.Util.layerColors. The non-overlapping selections from this function should be used when highlighting text inside marks to ensure the best display. See PCCViewer.Mark#highlightText.

Parameters:

Name Type Description

Name	Type	Description
`selections`	Array.<Object> \| Object	An array of objects or a single object that defines a highlight. Each object has the following properties: startIndex {number} - required The start index of the selection, in a 0-based index of string characters. The valid range is `startIndex >= 0`. length {number} - required The length of the selection, in characters. The valid range is `length > 0`. color {string} - required Specifies the Hexadecimal color for the selection. Valid values are any 7-character string representing a color. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color. opacity {number} - required Specifies the opacity of the selection. Valid values are from 0 to 255 (inclusive).
`backgroundColor`	string	A valid 7-character Hexadecimal color string. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color.

selections

Array.<Object> | Object

An array of objects or a single object that defines a highlight.

Each object has the following properties:

startIndex {number} - required
- The start index of the selection, in a 0-based index of string characters.
- The valid range is startIndex >= 0.
length {number} - required
- The length of the selection, in characters.
- The valid range is length > 0.
color {string} - required
- Specifies the Hexadecimal color for the selection.
- Valid values are any 7-character string representing a color. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color.
opacity {number} - required
- Specifies the opacity of the selection.
- Valid values are from 0 to 255 (inclusive).

backgroundColor

string

A valid 7-character Hexadecimal color string. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color.

See:

Throws:

If any of the selection objects have an invalid startIndex number, or the value is undefined.

Type
Error
If any of the selection objects have an invalid length number, or the value is undefined.

Type
Error
If any of the selection objects have an invalid color Hex string, or the value is undefined.

Type
Error
If any of the selection objects have an invalid opacity number, or the value is undefined.

Type
Error
If the backgroundColor argument is not a valid Hex string, or the value is undefined.

Type
Error

Returns:

A collection of non-overlapping selection objects, representing the same selections that were passed into the function.

Type: Array.<selection>

(static) convertPageRangeToArray(range, optionsopt) → {Array.<number>}

Converts the supplied page range to an array, where each element in the array is a page number. The returned array will be sorted ascending by page number and will not contain duplicates.

Parameters:

Name Type Attributes Description

range

string

A string specifying page numbers or ranges.

Valid values are any string using this format (specified using EBNF):

range      = "all" | pageRange;
pageRange  = pageNumber, [",", range]
           | subRange, [",", range];
pageNumber = naturalNumber;
subRange   = pageNumber, "-", pageNumber;

For example: "all", "1,2,3", and "1, 5-10" are all valid ranges.

options

object

An object specifying validation options.

Properties

Name	Type	Attributes	Default	Description
`lowerLimit`	number	<optional>	1	the lower limit (inclusive) of the valid range.
`upperLsimit`	number	<optional>	Number.MAX_VALUE	the upper limit (inclusive) of the valid range.
`allowEmpty`	boolean	<optional>	false	Indicates that an empty range string is valid.

See:

PCCViewer.Util.validatePageRange

Throws:

If pageRange does not conform to the supported format.

Type
Error
If pageRange specifies a range that is not within the bounds of options.lowerLimit and options.upperLimit.

Type
Error

Returns:

An array containing an element for each page number specified in the range.

Type: Array.<number>

Example

PCCViewer.Util.convertPageRangeToArray("1, 3-5"); // returns [1, 3, 4, 5]

PCCViewer.Util.convertPageRangeToArray("1, 3-5", {
    lowerLimit: 1,
    upperLimit: 6
}); // returns [1, 3, 4, 5]

PCCViewer.Util.convertPageRangeToArray("1, 3-100", {
    lowerLimit: 1,
    upperLimit: 6
}); // throws because the range goes beyond the upper limit

(static) layerColors(colors, backgroundColor) → {string}

This method takes an ordered list of colored layers, and calculates the flat color resulting from stacking all the layers.

Note: this stacking order calculation uses the W3C specification for simple alpha compositing, and is therefore not a complete color mixing solution. Instead, it calculates RGB color composition to browser specification.

Parameters:

Name Type Description

Name	Type	Description
`colors`	Array.<Object> \| Object	An array of objects or a single object that defines a color layer. Note that the first element in the array will be the topmost layer in the stacking order, and the last element will be the bottom-most layer. Each object has the following properties: color {string} - required Specifies the Hexadecimal color for the highlight. Valid values are any 7-character string representing a color. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color. opacity {number} - required Specifies the opacity of the highlight. Valid values are from 0 to 255 (inclusive).
`backgroundColor`	string	A valid 7-character Hexadecimal color string. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color.

colors

Array.<Object> | Object

An array of objects or a single object that defines a color layer. Note that the first element in the array will be the topmost layer in the stacking order, and the last element will be the bottom-most layer.

Each object has the following properties:

color {string} - required
- Specifies the Hexadecimal color for the highlight.
- Valid values are any 7-character string representing a color. The first letter must be a "#" symbol and the other six characters must be hexadecimal digits representing the red, green, and blue portions of the color.
opacity {number} - required
- Specifies the opacity of the highlight.
- Valid values are from 0 to 255 (inclusive).

backgroundColor

string

Throws:

If any of the color objects have an invalid color Hex string, or the value is undefined.

Type
Error
If any of the color objects have an invalid opacity number, or the value is undefined.

Type
Error
If the backgroundColor argument is not a valid Hex string, or the value is undefined.

Type
Error

Returns:

The resulting flat color produced by stacking all of the layers on top of the background color. This value will be a 7-character Hexadecimal color.

Type: string

(static) save(filename, stringValue)

Triggers file saving functionality with data generated on the client side. This method handles browser-specific differences in file generation. As such, it may have slightly different behavior in the various browsers. The end result provides a common interface for triggering a file save.

Parameters:

Name	Type	Description
`filename`	string	The desired name of the output file. This will be used as the name or suggested name in browsers that support it.
`stringValue`	string	The data, in string format, to be written to the file.

(static) validatePageRange(range, optionsopt) → {boolean}

Determines whether the range string is a valid page range of the format supported by the viewer. It will optionally validate that the range is within a specified set of limits.

Parameters:

Name Type Attributes Description

range

string

A string specifying page numbers or ranges.

Valid values are any string using this format (specified using EBNF):

range      = "all" | pageRange;
pageRange  = pageNumber, [",", range]
           | subRange, [",", range];
pageNumber = naturalNumber;
subRange   = pageNumber, "-", pageNumber;

For example: "all", "1,2,3", and "1, 5-10" are all valid ranges.

options

object

An object specifying validation options.

Properties

Name	Type	Attributes	Default	Description
`lowerLimit`	number	<optional>	1	the lower limit (inclusive) of the valid range.
`upperLsimit`	number	<optional>	Number.MAX_VALUE	the upper limit (inclusive) of the valid range.
`allowEmpty`	boolean	<optional>	false	Indicates that an empty range string is valid.

See:

PCCViewer.Util.convertPageRangeToArray

Returns:

A value indicating whether the specified page range is valid.

Type: boolean

Example

PCCViewer.Util.validatePageRange("1, 3-5", {
    lowerLimit: 1,
    upperLimit: 6
}); // returns true

PCCViewer.Util.validatePageRange("1, 3-5, 100", {
    lowerLimit: 1,
    upperLimit: 6
}); // returns false

PCCViewer.Util.validatePageRange("this is not a valid range", {
    lowerLimit: 1,
    upperLimit: 6
}); // returns false

PCCViewer.Util.validatePageRange("3", {
    lowerLimit: 1,
    upperLimit: myViewerControl.getPageCount() // assuming myViewerControl is a PCCViewer.ViewerControl
}); // returns true if the document has at least 3 pages

PCCViewer.Util.validatePageRange(""); // returns false

PCCViewer.Util.validatePageRange("", {
    allowEmpty: true
}); // returns true