IPage methods reference

Draw(context, scale, offsetX, offsetY)

Draws the page onto the device context. This method is highly dependent on the state of the device context and there are a few interaction pitfalls to lookout for. See below for details.

Note: This method is not available in all scripting environments.

Syntax

VOID Draw (
HDC context,
FLOAT scale,
LONG offsetX,
LONG offsetY
)

context

Device context on which to draw the page.

scale

Scale at which to draw. To draw at the 100% size, use a scale of device_dpi / 72. Do not use the DC to do the scaling; this will result in scaling artifacts being drawn.

offsetX

Horizontal offset from the left edge of the DC surface, in *device* units, at which to start the drawing.

offsetY

Vertical offset from the top edge of the DC surface, in *device* units, at which to start the drawing.

The drawing is done in PDF user space units (72th of an inch). In order to have a smooth drawing of the page, the device context must have its mapping mode set to MM_TEXT with a 1:1 mapping between logical space (SetWindowExtEx) and device space (SetViewportExtEx). Since MM_TEXT has its origin at the top instead of the bottom, the drawing is done vertically mirrored; this means that the other mapping modes may not work because they are based at the bottom. A 100% zoom is obtained by setting the scale to the ratio of the device dpi divided by 72.

The Acrobat library automatically clips the drawing based on the viewable portion of the DC. If the DC is translated or scaled, either by a world transform (SetWorldTransform) or a logical-to-device space transform (SetWindowOrgEx or SetViewportOrgEx ), the *untransformed* space is used. As a result, all scaling and translation operation must be done by the library itself to work correctly. Otherwise, unwanted scaling artifacts or clipping will occur.

As such, the drawing code of the caller should look similar to this to obtain the same result as what Acrobat does:

  1. Fill the entire drawing area with gray.

  2. Determine the origin (orgx, orgy) (for example, at (0, 0), or as indicated by scroll bars).

  3. Draw a white rectangle of size (CropBox.width * zoom, CropBox.height * zoom) at (orgx, orgy) representing the page (optional; Acrobat does not do that, and this method already draws the white page background).

  4. Call the IPage.Draw() method to draw the page at (orgx, orgy).

Note that extra care must be taken when filling rectangles as to whether the boundary pixel will be inside or outside the region.

ExtractText(left, bottom, right, top)

Returns the text located inside the region bounded by the left, bottom, right and top parameters. If multiple lines are found, they are separated by a CR-LF pair.

This method is subject to many limitations (see below) and exists for backward-compatibility and debugging purposes only. For production purposes, use ExtractText2() instead.

Syntax

VOID ExtractText (
FLOAT left,
FLOAT bottom,
FLOAT right,
FLOAT top
)

left

Distance in inches of the left limit of the region from the left edge of the /CropBox.

bottom

Distance in inches of the bottom limit of the region from the bottom edge of the /CropBox.

right

Distance in inches of the right limit of the region from the left edge of the /CropBox.

top

Distance in inches of the top limit of the region from the bottom edge of the /CropBox.

Return value

A string containing the text extracted from the specified region.

Limitations

  • No Unicode support.

  • A word is extracted only if it fits entirely in the region.

  • Empty lines are not supported.

  • A maximum of 4096 chars is returned.

  • A word can contain a maximum of 128 chars.

  • Horizontal moveto is not considered as a space.

  • /CropBox size is not taken into account (an object whose left is at 144 is considered to be 2 inches from the edge even if the /CropBox starts at 72).

  • Only horizontal text is supported; vertical or rotated text is undefined.

  • Rotated pages are unsupported.

  • /UserUnit is not supported.

ExtractText2(left, top, right, bottom)

Returns the text located inside the region bounded by the left, top, right and bottom parameters. If multiple lines are found, they are separated by a CR-LF pair.

Syntax

VOID ExtractText2 (
FLOAT left,
FLOAT top,
FLOAT right,
FLOAT bottom
)

left

Distance in inches of the left limit of the region from the left edge of the /CropBox. Must be between 0 and 5000.

top

Distance in inches of the top limit of the region from the top edge of the /CropBox. Must be between 0 and 5000.

right

Distance in inches of the right limit of the region from the left edge of the /CropBox. Must be between 0 and 5000.

bottom

Distance in inches of the bottom limit of the region from the top edge of the /CropBox. Must be between 0 and 5000.

Return value

A string containing the text extracted from the specified region.

MediaSize()

Returns the size of the physical medium on which the page is intended to be placed, in points. This corresponds to the /MediaBox entry of the /Page object in the PDF. See also: Size().

Syntax

IPdfRect MediaSize ( )

Return value

An IPdfRect structure containing the dimensions, in points, of the media size. Cannot be NULL.

setIncludeBorders(pbIncludeBorders)

Sets whether or not borders are included for IPage.ExtractText2(). If true, a character is considered to be inside the region using the 30% rule (i.e. at least 30% of the character must be enclosed in the region). Otherwise, the character must be entirely enclosed in the region to be returned. See also: ExtractText2(left, top, right, bottom).

Syntax

VOID setIncludeBorders ( LONG pbIncludeBorders )

pbIncludeBorders

If zero, the char must be completely inside the region. Otherwise, the 30% rule applies.

setTolerances(tolerableDeltaWidth, tolerableDeltaHeight, tolerableDeltaFontHeight, tolerableGap)

Sets the floating point values for the tolerable factors.

Syntax

VOID setTolerances (
FLOAT tolerableDeltaWidth,
FLOAT tolerableDeltaHeight,
FLOAT tolerableDeltaFontHeight,
FLOAT tolerableGap
)

tolerableDeltaWidth

Tolerable delta width factor value.

tolerableDeltaHeight

Tolerable delta height factor value.

tolerableDeltaFontHeight

Tolerable delta font height factor value.

tolerableGap

Tolerable gap between words factor value.

Merge(imageFile, left, top, rotateAngle, scaleFactor)

Inserts an image file and places it on the page at a specific location.
Supported image types are: JPG and PNG. It calls MergeToLayer internally.

Syntax

VOID Merge (
STRING imageFile,
FLOAT left,
FLOAT top,
FLOAT rotateAngle,
FLOAT scaleFactor
)

imageFile

Full name of the image to insert on the current page.

left

Coordinate at which to place the left edge of the image from the left edge of the page, in points.

top

Coordinate at which to place the top edge of the image from the top of the page, in points.

rotateAngle

Angle at which to rotate counter-clockwise the inserted image, in degrees. The rotation is done after the image is placed at (left, top) and centered around that point.

scaleFactor

Scale at which to display the image. For bitmaps, this is based on a 72 dpi resolution. Use 1.0 for the nominal size.

Merge2(srcPage, left, top, rotateAngle, scaleFactor)

Transparently places a PDF page on top of the current page at a specific location. The source page can be either from the same PDF or another opened file. If the source is from the same PDF file, the source page is not modified. This allows to have the same behavior as IPDF.MergeWith() by first inserting the pages from an external file, merging them and then deleting them, but with more flexibility.

Syntax

VOID Merge2 (
IPage srcPage,
FLOAT left,
FLOAT top,
FLOAT rotateAngle,
FLOAT scaleFactor
)

srcPage

IPage object to overlay on the current page.

left

Coordinate at which to place the left edge of the image from the left edge of the page, in points.

top

Coordinate at which to place the top edge of the image from the top of the page, in points.

rotateAngle

Angle at which to rotate counter-clockwise the inserted image, in degrees. The rotation is done after the image is placed at (left, top) and centered around that point.

scaleFactor

Scale at which to display the image. For bitmaps, this is based on a 72 dpi resolution. Use 1.0 for the nominal size.

MergeToLayer(imageFile, left, top, rotateAngle, scaleFactor, layerName)

This method behaves the same as Merge() but allows to insert the image as a layer (aka an Optional Content Group).

Supported image types are JPG and PNG. If the input file is a PNG with an alpha channel, the PNG is alpha blended with the page underneath. Monochrome PNG files are drawn transparently, with the white used as the transparent color.

Syntax

VOID MergeToLayer (
STRING imageFile,
FLOAT left,
FLOAT top,
FLOAT rotateAngle,
FLOAT scaleFactor,
STRING layerName
)

imageFile

Full name of the image to insert on the current page.

left

Coordinate at which to place the left edge of the image from the left edge of the page, in points.

top

Coordinate at which to place the top edge of the image from the top of the page, in points.

rotateAngle

Angle at which to rotate counter-clockwise the inserted image, in degrees. The rotation is done after the image is placed at (left, top) and centered around that point.

scaleFactor

Scale at which to display the image. For bitmaps, this is based on a 72 dpi resolution. Use 1.0 for the nominal size.

layerName

Name of an Optional Content Group in which to put the layer containing the image. The string cannot be empty but can be NULL if no layer is required.

MergeToLayer2(srcPage, left, top, rotateAngle, scaleFactor, layerName)

This method behaves the same as Merge2() but allows to put the source page as a layer (aka an Optional Content Group).

Syntax

VOID MergeToLayer2 (
IPage srcPage,
FLOAT left,
FLOAT top,
FLOAT rotateAngle,
FLOAT scaleFactor,
BSTRlayerName
)

srcPage

IPage object to overlay on the current page.

left

Coordinate at which to place the left edge of the image from the left edge of the page, in points.

top

Coordinate at which to place the top edge of the image from the top of the page, in points.

otateAngle

Angle at which to rotate counter-clockwise the inserted image, in degrees. The rotation is done after the image is placed at (left, top) and centered around that point.

scaleFactor

Scale at which to display the image. For bitmaps, this is based on a 72 dpi resolution. Use 1.0 for the nominal size.

layerName

Name of an Optional Content Group in which to put the layer created from the source page. The string cannot be empty but can be NULL if no layer is required.

layerName

Name of an Optional Content Group in which to put the layer created from the source page. The string cannot be empty but can be NULL if no layer is required.

Size()

Returns the size of the rectangle that is used to clip (crop) the content of the page before applying it to the medium, in points. This corresponds to the /CropBox entry of the /Page PDF object. It can be seen as the bounding box of the page since by definition, anything outside of it should be left out of the drawing, although there may be empty areas within it.
See also: MediaSize().

Syntax

IPdfRect Size ( )

Return value

An IPdfRect structure containing the dimensions, in points, of the page size. Cannot be NULL.