Foxit::PDF::Page Class Reference

Class to access PDF page. More...

Public Member Functions

Int32 GetIndex ()
 Get page index. More...
 
Size GetSize ()
 Get page size. More...
 
Int32 GetRotation ()
 Get page rotation. More...
 
RectFGetBox (PageBoxType boxType)
 Get page boundary which is a rectangle type value. More...
 
MatrixGetDisplayMatrix (Int32 x, Int32 y, Int32 width, Int32 height, Int32 rotation)
 Get page transformation matrix. More...
 
void Close ()
 Close current PDF page, and release all page contents and related resources. More...
 
TextPageLoadTextPage (UInt32 option)
 Prepare information of all characters in current page and return a PDF::TextPage object. More...
 
Int32 CountAnnots (const List< AnnotType >^typeFilter)
 Count annotations, by specific type filter. More...
 
IAnnotGetAnnot (const List< AnnotType >^typeFilter, Int32 index)
 Get an annotation with specified index, by specific type filter. More...
 
IAnnotGetAnnotAtPos (const List< AnnotType >^typeFilter, PointF^ position, float tolerance)
 Get an annotation at a specific position, by specific type filter. More...
 
Int32 GetAnnotIndex (IAnnot^ annot, const List< AnnotType >^typeFilter)
 Get the index of an annotation, within specific type filter. More...
 
IAnnotAddAnnot (RectF^ rect, AnnotType annotType, const List< AnnotType >^typeFilter, Int32 index)
 Add a new annotation with a specific index, within specific type filter. More...
 
Boolean RemoveAnnot (IAnnot^ annot)
 Remove the specific annotation from current page. More...
 
void SetAnnotGroup (const List< IMarkup^ >^annotArray, Int32 headerIndex)
 Group all the input markup annotations together. More...
 
SignatureGetSignatureAtPos (PointF^ position, float tolerance)
 Get a signature at a specific position. More...
 
Boolean RenderPage (PixelSource^ pxsrc, Matrix^ displayMatrix, UInt32 renderFlags, Pause^ pause)
 Render a PDF page. More...
 

Properties

Int64 pointer
 Pointer to a handle of PDF page object. This pointer is not useful outside this SDK. The application should not access the pointer to the handle of the PDF page object directly.
 

Detailed Description

Class to access PDF page.

PDF page can be loaded by function PDF::Document::LoadPage. After loading a PDF page, user can get some basic information, retrieve a text page, and render the PDF page. Function PDF::Page::Close should be called to close the loaded PDF page when no need to access it any more.

Member Function Documentation

IAnnot ^ Foxit::PDF::Page::AddAnnot ( RectF rect,
AnnotType  annotType,
const List< AnnotType >^  typeFilter,
Int32  index 
)

Add a new annotation with a specific index, within specific type filter.

This function can be used to add annotation of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::PSInk, Annotations::AnnotType::ThreeDimensional, Annotations::AnnotType::PrinterMark, Annotations::AnnotType::TrapNet, Annotations::AnnotType::Sound, Annotations::AnnotType::Movie, Annotations::AnnotType::Screen, Annotations::AnnotType::Watermark, Annotations::AnnotType::Widget, Annotations::AnnotType::Unknown, Annotations::AnnotType::Popup, Annotations::AnnotType::Caret.
Foxit PDF SDK does not treat popup annotation as a single annotation because typically popup annotation does not appear alone but is associated with a markup annotation – the parent annotation of popup annotation. So, pop-up annotation cannot be added alone by this function. But Foxit PDF SDK will add a default pop-up annotation when this function is called to add a new markup annotation.

Parameters
[in]rectA RectF object that specifies the rectangle of the new annotation, in PDF page coordinate system.
The value can be set as (0, 0, 0, 0), except following annotation types : Annotations::AnnotType::Note, Annotations::AnnotType::FreeText, Annotations::AnnotType::Square, Annotations::AnnotType::Circle, Annotations::AnnotType::FileAttachment, Annotations::AnnotType::Stamp.
[in]annotTypeAnnotation type of the new annotation. This should be in the type range defined by parameter typeFilter. Please refer to enumeration Annotations::AnnotType and this should be one of its values except
Annotations::AnnotType::PSInk, Annotations::AnnotType::ThreeDimensional, Annotations::AnnotType::PrinterMark, Annotations::AnnotType::TrapNet, Annotations::AnnotType::Sound, Annotations::AnnotType::Movie, Annotations::AnnotType::Screen, Annotations::AnnotType::Watermark, Annotations::AnnotType::Widget, Annotations::AnnotType::Unknown, Annotations::AnnotType::Popup, Annotations::AnnotType::Caret.
[in]typeFilterAn Annotations::AnnotType array that specifies the type filter used to count annotation. This can be nullptr or empty, it means this function should count all annotations. If this contains at least one valid Annotations::AnnotType, it means this function should only get annotation within this type filter. If Annotations::AnnotType::Unknown or Annotations::AnnotType::Popup is in this type filter, these two type will be ignored.
[in]indexThe index value that specifies where the new annotation is to be added. Range: 0 to (annotCount-1). annotCount is returned by function Paeg::CountAnnots with same typeFilter.
If input index is out of range, the new annotation will be added to the last within the range defined by parameter typeFilter.
Returns
An IAnnot object that receives the newly added annotation. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter rect is invalid for some types, or parameter annotType is invalid.
ErrorCode::Unsupported means not support to add annotation in type specified by parameter annotType.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
void Foxit::PDF::Page::Close ( )

Close current PDF page, and release all page contents and related resources.

Returns
None.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Int32 Foxit::PDF::Page::CountAnnots ( const List< AnnotType >^  typeFilter)

Count annotations, by specific type filter.

This function can be used to count annotations of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::Unknown and Annotations::AnnotType::Popup.

Parameters
[in]typeFilterAn Annotations::AnnotType array that specifies the type filter used to count annotation. This can be nullptr or empty, it means this function should count all annotations. If this contains at least one valid Annotations::AnnotType, it means this function should only count annotations within this type filter. If Annotations::AnnotType::Unknown or Annotations::AnnotType::Popup is in this type filter, these two type will be ignored.
Returns
Count of annotations with specific type filter. If there is any error, this function will return 0.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
IAnnot ^ Foxit::PDF::Page::GetAnnot ( const List< AnnotType >^  typeFilter,
Int32  index 
)

Get an annotation with specified index, by specific type filter.

This function can be used to get annotation of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::Unknown and Annotations::AnnotType::Popup. Typically, popup annotation does not appear alone but is associated with a markup annotation – the parent annotation of popup annotation. So, user can call function IMarkup::GetPopup to get the popup annotation of a markup annotation. In this function, if the retrieved annotation is a markup annotation but it does not have a popup annotation, this function will add a popup annotation to this markup annotation with rectangle [].

Parameters
[in]typeFilterAn Annotations::AnnotType array that specifies the type filter used to count annotation. This can be nullptr or empty, it means this function should count all annotations. If this contains at least one valid Annotations::AnnotType, it means this function should only get annotation within this type filter. If Annotations::AnnotType::Unknown or Annotations::AnnotType::Popup is in this type filter, these two type will be ignored.
[in]indexA zero-based index of annotation to be got. Range: 0 to (annotCount-1). annotCount is returned by function Page::CountAnnots with same typeFilter.
Returns
An IAnnot object that receives the specific annotation. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::NotFound means parameter index is out of range.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
IAnnot ^ Foxit::PDF::Page::GetAnnotAtPos ( const List< AnnotType >^  typeFilter,
PointF position,
float  tolerance 
)

Get an annotation at a specific position, by specific type filter.

This function can be used to get annotation of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::Unknown and Annotations::AnnotType::Popup. Typically, popup annotation does not appear alone but is associated with a markup annotation – the parent annotation of popup annotation. So, user can call function IMarkup::GetPopup to get the popup annotation of a markup annotation. In this function, if the retrieved annotation is a markup annotation but it does not have a popup annotation, this function will add a popup annotation to this markup annotation with rectangle [].

Parameters
[in]typeFilterAn Annotations::AnnotType array that specifies the type filter used to count annotation. This can be nullptr or empty, it means this function should count all annotations. If this contains at least one valid Annotations::AnnotType, it means this function should only get annotation within this type filter. If Annotations::AnnotType::Unknown or Annotations::AnnotType::Popup is in this type filter, these two type will be ignored.
[in]positionA Foxit::PointF object that specifies the position, in PDF page coordinate. It should not be nullptr.
[in]toleranceTolerance value for the position point. Valid value: from 0.0f to 30.0f.
Returns
An IAnnot object that receives the specific annotation. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter position is nullptr, or parameter tolerance is invalid.
ErrorCode::NotFound means no annotation can be found around the specified position.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Int32 Foxit::PDF::Page::GetAnnotIndex ( IAnnot annot,
const List< AnnotType >^  typeFilter 
)

Get the index of an annotation, within specific type filter.

This function can be used for annotations of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::Unknown and Annotations::AnnotType::Popup. Foxit PDF SDK does not treat popup annotation as a single annotation because typically popup annotation does not appear alone but is associated with a markup annotation – the parent annotation of popup annotation.

Parameters
[in]annotAn Annotations::IAnnot object that specifies the annotation which index is to be retreived. User should ensure that parameter annot is in current page.
[in]typeFilterAn Annotations::AnnotType array that specifies the type filter used to count annotation. This can be nullptr or empty, it means this function should count all annotations. If this contains at least one valid Annotations::AnnotType, it means this function should only get annotation index within this type filter. If Annotations::AnnotType::Unknown or Annotations::AnnotType::Popup is in this type filter, these two type will be ignored.
Returns
The index value. If there is any error, this function will return -1.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter annot is nullptr.
ErrorCode::NotFound means parameter annot cannot be found within the specified type filter.
ErrorCode::Conflict means parameter annot does not belong to current PDF page.
ErrorCode::Unsupported means not support to get the index of parameter annot.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
RectF ^ Foxit::PDF::Page::GetBox ( PageBoxType  boxType)

Get page boundary which is a rectangle type value.

In PDF, coordinates of page is upward to Y-axis and rightward to X-axis, therefore left is less than right and top is greater than bottom.
The origin of coordinate is at the corner of bottom-left of page and the page unit is 1/72 inch.

Parameters
[in]boxTypeA page boundary box type. Please refer to enumeration Foxit::PageBoxType and this should be one of its values.
Returns
A Foxit::RectF object that receives a rectangle value. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter boxType is invalid.
ErrorCode::NotFound means no suitable page boundary can be found.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Matrix ^ Foxit::PDF::Page::GetDisplayMatrix ( Int32  x,
Int32  y,
Int32  width,
Int32  height,
Int32  rotation 
)

Get page transformation matrix.

The origin of coordinate is at the corner of bottom-left of page and the page unit is 1/72 inch.
Transformation matrix is used to transform PDF page coordinate to device coordinate. Call function Matrix::GetReverse to get a reversed matrix to transform to opposite direction.

Parameters
[in]xLeft position of the transformation area in device coordinate, commonly in pixels.
[in]yTop position of the transformation area in device coordinate, commonly in pixels.
[in]widthWidth of the transformation area in device coordinate, commonly in pixels.
[in]heightHeight of the transformation area in device coordinate, commonly in pixels.
[in]rotationPage rotation value. It should be one of following values:
  • 0: No rotation.
  • 1: Rotate 90 degrees in clockwise direction.
  • 2: Rotate 180 degrees in clockwise direction.
  • 3: Rotate 270 degrees in clockwise direction.
Returns
A Foxit::Matrix object that receives the transformation matrix. If there is any error, this function will return a matrix with value [1 0 0 1 0 0].
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter rotation is an invalid value.
ErrorCode::NotParsed means the page hasn't been parsed.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Int32 Foxit::PDF::Page::GetIndex ( )

Get page index.

Returns
The page index, starting from 0. If there is any error, this function will return -1.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Int32 Foxit::PDF::Page::GetRotation ( )

Get page rotation.

Page width and height are just the size of a PDF page when value of "/Rotate" in page dictionary is 0.

Returns
The page rotation.
  • 0: No rotation.
  • 1: Rotate 90 degrees in clockwise direction.
  • 2: Rotate 180 degrees in clockwise direction.
  • 3: Rotate 270 degrees in clockwise direction.
Default value is 0. If there is any error, this function will return -1.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Signature ^ Foxit::PDF::Page::GetSignatureAtPos ( PointF position,
float  tolerance 
)

Get a signature at a specific position.

Parameters
[in]positionA Foxit::PointF object that specifies the position, in PDF page coordinate.
[in]toleranceTolerance value for the position point. Valid value: from 0.0f to 30.0f.
Returns
A PDF::Signature object that receives the specific signature object. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter tolerance is invalid.
ErrorCode::NotFound means no signature can be found around the specified position.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Size Foxit::PDF::Page::GetSize ( )

Get page size.

Returns
Size unit of a page is 1/72 inch. If there is any error, width and height will be set 0.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success for success.
For more error code values, please refer to enumeration Foxit::ErrorCode.
TextPage ^ Foxit::PDF::Page::LoadTextPage ( UInt32  option)

Prepare information of all characters in current page and return a PDF::TextPage object.

Parameters
[in]optionAn unsigned integer value that specifies the parsing option.
If set to 0, this function will load text page normally. For other options, please refer to enumeration PDF::TextParseOption and this could be one or a combination of its values.
Returns
A PDF::TextPage object that receives a new PDF text page if successful.
Application should release this PDF::TextPage object if this object is not in use, by calling function TextPage::Release.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::NotParsed means current page is not parsed.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Boolean Foxit::PDF::Page::RemoveAnnot ( IAnnot annot)

Remove the specific annotation from current page.

This function can be used to remove annotations of all types defined in enumeration Annotations::AnnotType except Annotations::AnnotType::Watermark, Annotations::AnnotType::Unknown, Annotations::AnnotType::Popup.
Foxit PDF SDK does not treat popup annotation as a single annotation because typically popup annotation does not appear alone but is associated with a markup annotation – the parent annotation of popup annotation. So popup annotation cannot be removed directly. Popup annotation will be removed with its parent markup annotation.

Parameters
[in]annotAn Annotations::IAnnot object that specifies the annotation which is to be removed. User should ensure that parameter annot is in current page.
Returns
A boolean value: true means success, while false means failure.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter annot is nullptr.
ErrorCode::Unsupported means not support to remove the type of parameter annot.
ErrorCode::Conflict means parameter annot does not belong to current PDF page.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
Boolean Foxit::PDF::Page::RenderPage ( PixelSource pxsrc,
Matrix displayMatrix,
UInt32  renderFlags,
Pause pause 
)

Render a PDF page.

Rendering can be started over and over again for the same page, but there can be only one rendering procedure for a page at any time. If one page rendering is already active and another rendering is started, the previous rendering will be canceled.
When rendering a page, application can specify the color of background for rendering by parameter pxsrc. If application does not specify the background color, Foxit PDF SDK will use white background by default.
There is no need to parse the page before rendering the page. The engine will parse the page along with the rendering process. With this technique, by using RenderFlags::DropObjects with this function, it can render very complicated pages without much memory consumption.

Parameters
[in,out]pxsrcA Foxit::PixelSource object.
[in]displayMatrixA Foxit::Matrix that receives the transformation matrix which is returned by function Page::GetDisplayMatrix.
[in]renderFlagsRenderer flags. All undefined bits are omitted. 0 is default and means to display normally. For other render flags, please refer to enumeration Foxit::RenderFlags and this could be one or combination of its values.
[in]pause(Reserved, should be nullptr currently) A Foxit::Pause object that specifies the pause control for rendering page in progressive process.
Returns
A boolean value: true means success, while false means failure.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter pxsrc is nullptr, or rotation or pageRenderFlag is invalid.
ErrorCode::NotParsed means the page hasn't been parsed.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.
void Foxit::PDF::Page::SetAnnotGroup ( const List< IMarkup^ >^  annotArray,
Int32  headerIndex 
)

Group all the input markup annotations together.

Parameters
[in]annotArrayA markup annotation array that specifies markup annotations which are to be grouped together. The count of annotations in this array should be at least 2. All the markup annotations in this array should be in current page.
[in]headerIndexThe index that specifies a markup annotation in parameter annotArray to be the header of the group.
Returns
An IAnnot object that receives the newly added annotation. If there is any error, this function will return nullptr.
Call function Library::GetLastError after this function returns, to get the error code.
ErrorCode::Success means success.
ErrorCode::Param means parameter annotArray is nullptr or count of elements is less than 2, or parameter headerIndex is out of the range of the count of annotArray, or any markup annotation object in annotArray is nullptr or invalid.
ErrorCode::Conflict means markup annotations in parameter annotArray do not all belong to current page.
ErrorCode::OutOfMemory means there is not enough memory or if the memory access is wrong.
ErrorCode::Error means the function fails because of any other reasons.
For more error code values, please refer to enumeration Foxit::ErrorCode.

Foxit Corporation