Loading...
Searching...
No Matches
pdftron::PDF::Page Class Reference

`#include <Page.h>`

## Public Types
enum | Box { e_media , e_crop , e_bleed , e_trim , e_art , e_user_crop }
enum | Rotate { e_0 , e_90 , e_180 , e_270 }
enum | ActionTriggerEvent { e_action_trigger_page_open = 11 , e_action_trigger_page_close = 12 }

## Public Member Functions
| Page (SDF::Obj page_dict=0)
| Page (const Page &p)
Page & | operator= (const Page &p)
bool | IsValid () const
int | GetIndex () const
Rect | GetBox (Box type) const
void | SetBox (Box type, const Rect &box) const
Rect | GetCropBox () const
void | SetCropBox (const Rect &box)
Rect | GetMediaBox () const
void | SetMediaBox (const Rect &box)
Rect | GetVisibleContentBox () const
Rotate | GetRotation () const
void | SetRotation (Rotate angle)
double | GetPageWidth (Box box_type=e_crop)
double | GetPageHeight (Box box_type=e_crop)
Common::Matrix2D | GetDefaultMatrix (bool flip_y=false, Box box_type=e_crop, Rotate angle=e_0) const
SDF::Obj | GetAnnots () const
UInt32 | GetNumAnnots () const
Annot | GetAnnot (UInt32 index) const
SDF::Obj | GetTriggerAction (Page::ActionTriggerEvent trigger)
void | AnnotInsert (UInt32 pos, Annot &annot)
void | AnnotInsertWithTagging (UInt32 pos, Annot &annot, SDF::Obj &tag_parent, const TaggingOptions &options)
void | AnnotPushBack (Annot &annot)
void | AnnotPushFront (Annot &annot)
void | AnnotRemove (Annot &annot)
void | AnnotRemove (UInt32 index)
void | Scale (double scale)
void | FlattenField (class Field field_to_flatten)
bool | HasTransition () const
double | GetUserUnitSize () const
void | SetUserUnitSize (double unit_size)
SDF::Obj | GetResourceDict () const
SDF::Obj | GetContents () const
SDF::Obj | GetSDFObj () const
SDF::Obj | FindInheritedAttribute (const char *attrib) const
| operator bool ()
SDF::Obj | GetThumb () const

## Static Public Member Functions
static Rotate | AddRotations (Rotate r0, Rotate r1)
static Rotate | SubtractRotations (Rotate r0, Rotate r1)
static int | RotationToDegree (Rotate r)
static Rotate | DegreeToRotation (int r)

## Detailed Description

Page is a high-level class representing PDF page object (see 'Page Objects' in Section 3.6.2, 'Page Tree,' in PDF Reference Manual).

Among other associated objects, a page object contains:

- A series of objects representing the objects drawn on the page (See Element and ElementReader class for examples of how to extract page content).
- A list of resources used in drawing the page
- Annotations
- Beads, private metadata, optional thumbnail image, etc.

Definition at line 31 of file Page.h.

## Member Enumeration Documentation

## ◆ ActionTriggerEvent

enum pdftron::PDF::Page::ActionTriggerEvent

Enumerator
e_action_trigger_page_open |
e_action_trigger_page_close |

Definition at line 307 of file Page.h.

## ◆ Box

enum pdftron::PDF::Page::Box

PDF page can define as many as five separate boundaries to control various aspects of the imaging process (for more details please refer to Section 10.10.1 'Page Boundaries' in PDF Reference Manual):

- The media box defines the boundaries of the physical medium on which the page is to be printed. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes. It may also include areas close to the edges of the medium that cannot be marked because of physical limitations of the output device. Content falling outside this boundary can safely be discarded without affecting the meaning of the PDF file.
- The crop box defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed. Unlike the other boxes, the crop box has no defined meaning in terms of physical page geometry or intended use; it merely imposes clipping on the page contents. The default value is the page's media box.
- The bleed box defines the region to which the contents of the page should be clipped when output in a production environment. This may include any extra bleed area needed to accommodate the physical limitations of cutting, folding, and trimming equipment. The default value is the page's crop box.
- The trim box defines the intended dimensions of the finished page after trimming. It may be smaller than the media box to allow for production related content, such as printing instructions, cut marks, or color bars. The default value is the page's crop box.
- The art box defines the extent of the page's meaningful content (including potential white space) as intended by the page's creator. The default value is the page's crop box.
- The user crop box defines a custom region to which the contents of the page are to be clipped (cropped) when displayed by PDFNet It must be fully contained within the e_crop box. The default value is the page's crop box.

Enumerator
e_media |
e_crop |
e_bleed |
e_trim |
e_art |
e_user_crop |

Definition at line 98 of file Page.h.

## ◆ Rotate

enum pdftron::PDF::Page::Rotate

Specifies page rotation, in degrees.

Enumerator
e_0 |
e_90 |
e_180 |
e_270 |

Definition at line 190 of file Page.h.

## Constructor & Destructor Documentation

## ◆ Page() [1/2]

pdftron::PDF::Page::Page | ( | SDF::Obj | page_dict = 0 | ) |

Initialize a page using an existing low-level Cos/SDF page object.

Parameters

  page_dict | - a low-level (SDF/Cos) page dictionary.

Note
  This constructor does not copy any data, but is instead the logical equivalent of a type cast.
  Because PDF::PDFDoc provides a complete high-level interface for Page creation and traversal this constructor is rarely used.

## ◆ Page() [2/2]

pdftron::PDF::Page::Page | ( | const Page & | p | ) |

## Member Function Documentation

## ◆ AddRotations()

Rotate pdftron::PDF::Page::AddRotations | ( | Rotate | r0,
|  | Rotate | r1 )
| static

Rotate r0 clockwise by r1

Parameters

  r0 | first rotation.
  r1 | second rotation.

Returns
  returns r0 + r1

## ◆ AnnotInsert()

void pdftron::PDF::Page::AnnotInsert | ( | UInt32 | pos,
|  | Annot & | annot )

Adds an annotation at the specified location in a page's annotation array.

Parameters

  pos | - The location in the array to insert the object. The object is inserted before the specified location. The first element in an array has a pos of zero. If pos >= GetNumAnnots(), the method appends the annotation to the array.
  annot | - The annotation to add.

## ◆ AnnotInsertWithTagging()

void pdftron::PDF::Page::AnnotInsertWithTagging | ( | UInt32 | pos,
|  | Annot & | annot,
|  | SDF::Obj & | tag_parent,
|  | const TaggingOptions & | options )

Adds an annotation at the specified location in a page's annotation array, as well as tag it in a specific place in the StructureTree.

Parameters

  pos | - The location in the array to insert the object. The object is inserted before the specified location. The first element in an array has a pos of zero. If pos >= GetNumAnnots(), the method appends the annotation to the array.
  annot | - The annotation to add.
  tag_parent | - The structure tree node under which to insert the Annot's new tag
  options | - Options for tag creation, allows specifying things such as tag insert location and alt desc

## ◆ AnnotPushBack()

void pdftron::PDF::Page::AnnotPushBack | ( | Annot & | annot | ) |

Adds an annotation to the end of a page's annotation array.

Parameters

  annot | - The annotation to prepend in a page's annotation array.

## ◆ AnnotPushFront()

void pdftron::PDF::Page::AnnotPushFront | ( | Annot & | annot | ) |

Adds an annotation to the beginning of a page's annotation array.

Parameters

  annot | - The annotation to append in a page's annotation array.

## ◆ AnnotRemove() [1/2]

void pdftron::PDF::Page::AnnotRemove | ( | Annot & | annot | ) |

Removes the given annotation from the page.

Note
  Removing the annotation invalidates the given Annot object.

Parameters

  annot | The annotation to remove.

## ◆ AnnotRemove() [2/2]

void pdftron::PDF::Page::AnnotRemove | ( | UInt32 | index | ) |

Removes the annotation at a given location.

Note
  Removing the annotation invalidates any associated Annot object.

Parameters

  index | - A zero based index of the annotation to remove.

## ◆ DegreeToRotation()

Rotate pdftron::PDF::Page::DegreeToRotation | ( | int | r | ) |
| static

Convert a number that represents rotation in degrees to a rotation enum.

Parameters

  r | degree to convert to rotation. Valid numbers are multiples of 90.

Returns
  one of four angles; e_0, e_90, e_180 or e_270. Returns e_0 if input is not a multiple 90.

## ◆ FindInheritedAttribute()

SDF::Obj pdftron::PDF::Page::FindInheritedAttribute | ( | const char * | attrib | ) | const

Some of the page attributes are designated as inheritable. If such an attribute is omitted from a page object, its value is inherited from an ancestor node in the page tree. If the attribute is a required one, a value must be supplied in an ancestor node; if it is optional and no inherited value is specified, the default value should be used.

The function walks up the page inheritance tree in search for specified attribute.

Parameters

  attrib | A string representing the attribute to search for.

Returns
  if the attribute was found return a pointer to the value. Otherwise the function return NULL.

Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)

## ◆ FlattenField()

void pdftron::PDF::Page::FlattenField | ( | class Field | field_to_flatten | ) |

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form 'flattening' refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Parameters

  field_to_flatten | field to flatten

Note
  An alternative approach to set the field as read only is using Field.SetFlag(Field::e_read_only, true) method. Unlike Field.SetFlag(...), the result of FlattenField() operation can not be programatically reversed.

## ◆ GetAnnot()

Annot pdftron::PDF::Page::GetAnnot | ( | UInt32 | index | ) | const

Returns the annotation on the page.

Returns
  Annotation object. If the index is out of range returned Annot object is not valid (i.e. annot.IsValid() returns false).

Parameters

  index | - The index of the annotation to get on a page. The first annotation on a page has an index of zero.

## ◆ GetAnnots()

SDF::Obj pdftron::PDF::Page::GetAnnots | ( |  | ) | const

Returns SDF/Cos array containing annotation dictionaries. See Section 8.4 in the PDF Reference for a description of the annotation array.

Returns
  an array of annotation dictionaries representing annotations associated with the page or NULL if page dictionary is not specified.

## ◆ GetBox()

Rect pdftron::PDF::Page::GetBox | ( | Box | type | ) | const

Returns
  the box specified for the page object intersected with the media box.

Parameters

  type | The type of the page bounding box. Possible values are: e_media, e_crop, e_bleed, e_trim, and e_art.

If the value for 'type' is e_crop, this call is equivalent to GetCropBox(). If the value for 'type' is e_media, this call is equivalent to GetMediaBox().

## ◆ GetContents()

SDF::Obj pdftron::PDF::Page::GetContents | ( |  | ) | const

Returns
  NULL if page is empty, otherwise a single stream or an array of streams.

## ◆ GetCropBox()

Rect pdftron::PDF::Page::GetCropBox | ( |  | ) | const

Returns
  the crop box for this page. The page dimensions are specified in user space coordinates.

The crop box is the region of the page to display and print.

Note
  this method is equivalent to GetBox(Page::e_crop)

## ◆ GetDefaultMatrix()

Common::Matrix2D pdftron::PDF::Page::GetDefaultMatrix | ( | bool | flip_y = false,
|  | Box | box_type = e_crop,
|  | Rotate | angle = e_0 ) const

Returns
  the matrix that transforms user space coordinates to rotated and cropped coordinates. The origin of this space is the bottom-left of the rotated, cropped page.

Parameters

  flip_y | this parameter can be used to mirror the page. if 'flip_y' is true the Y axis is not flipped and it is increasing, otherwise Y axis is decreasing.
  box_type | an optional parameter used to specify the page box/region that the matrix should map to. By default, the function transforms user space coordinates to cropped coordinates.
  angle | an optional parameter used to specify page rotation in addition to the rotation specified in the page dictionary. This parameter is usually used to rotate the page without modifying the document itself.

## ◆ GetIndex()

int pdftron::PDF::Page::GetIndex | ( |  | ) | const

Returns
  the Page number indication the position of this Page in document's page sequence. Document's page sequence is indexed from 1. Page number 0 means that the page is not part of document's page sequence or that the page is not valid.

## ◆ GetMediaBox()

Rect pdftron::PDF::Page::GetMediaBox | ( |  | ) | const

Returns
  the media box for this page. The page dimensions are specified in user space coordinates.

The media box defines the boundaries of the physical medium on which the page is to be printed. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes.

Note
  this method is equivalent to GetBox(Page::e_media)

Exceptions

  if | the page is missing media box the function throws Exception

## ◆ GetNumAnnots()

UInt32 pdftron::PDF::Page::GetNumAnnots | ( |  | ) | const

Returns the number of annotations on a page. Widget annotations (form fields) are included in the count.

Returns
  The number of annotations on a page.

## ◆ GetPageHeight()

double pdftron::PDF::Page::GetPageHeight | ( | Box | box_type = e_crop | ) |

Returns
  the height for the given page region/box taking into account page rotation attribute (i.e. /Rotate entry in page dictionary).

Parameters

  box_type | indicates the page box/region to query for height.

## ◆ GetPageWidth()

double pdftron::PDF::Page::GetPageWidth | ( | Box | box_type = e_crop | ) |

Returns
  the width for the given page region/box taking into account page rotation attribute (i.e. /Rotate entry in page dictionary).

Parameters

  box_type | indicates the page box/region to query for width.

## ◆ GetResourceDict()

SDF::Obj pdftron::PDF::Page::GetResourceDict | ( |  | ) | const

Returns
  a pointer to the page resource dictionary.

Exceptions

  if | the page is missing resource dictionary the function throws Exception

## ◆ GetRotation()

Rotate pdftron::PDF::Page::GetRotation | ( |  | ) | const

Returns
  the rotation value for this page.

## ◆ GetSDFObj()

SDF::Obj pdftron::PDF::Page::GetSDFObj | ( |  | ) | const

Returns the page dictionary.

Returns
  the object to the underlying SDF/Cos object.

## ◆ GetThumb()

SDF::Obj pdftron::PDF::Page::GetThumb | ( |  | ) | const

Returns
  Object representing the Image thumbnail.

## ◆ GetTriggerAction()

SDF::Obj pdftron::PDF::Page::GetTriggerAction | ( | Page::ActionTriggerEvent | trigger | ) |

Get the Action associated with the selected Page Trigger event.

Parameters

  trigger | the type of trigger event to get

Returns
  the Action Obj if present, otherwise NULL

## ◆ GetUserUnitSize()

double pdftron::PDF::Page::GetUserUnitSize | ( |  | ) | const

Returns the UserUnit value for the page. A UserUnit is a positive number giving the size of default user space units, in multiples of 1/72 inch.

Returns
  the UserUnit value for the page. If the key is not present in the page dictionary the default of 1.0 is returned.

## ◆ GetVisibleContentBox()

Rect pdftron::PDF::Page::GetVisibleContentBox | ( |  | ) | const

Returns
  the bounding box for this page. The page dimensions are specified in user space coordinates.

The bounding box is defined as the smallest rectangle that includes all the visible content on the page.

## ◆ HasTransition()

bool pdftron::PDF::Page::HasTransition | ( |  | ) | const

Tests whether this page has a transition.

## ◆ IsValid()

bool pdftron::PDF::Page::IsValid | ( |  | ) | const

Returns
  true if this is a valid (non-null) page, false otherwise. If the function returns false the underlying SDF/Cos object is null
  or is not valid.

## ◆ operator bool()

pdftron::PDF::Page::operator bool | ( |  | ) |
| inline

Returns
  true if the object is not null, false otherwise.

Definition at line 467 of file Page.h.

## ◆ operator=()

Page & pdftron::PDF::Page::operator= | ( | const Page & | p | ) |

## ◆ RotationToDegree()

int pdftron::PDF::Page::RotationToDegree | ( | Rotate | r | ) |
| static

Convert a rotation to a number.

Parameters

  r | rotation to convert to number

Returns
  one of four numbers; 0, 90, 180 or 270.

## ◆ Scale()

void pdftron::PDF::Page::Scale | ( | double | scale | ) |

A utility method used to scale physical dimensions of the page including all page content.

Parameters

  scale | A number greater than 0 which is used as a scale factor. For example, calling page.Scale(0.5) will reduce physical dimensions of the page to half its original size, whereas page.Scale(2) will double the physical dimensions of the page and will rescale all page content appropriately.

Note
  Unlike SetUserUnitSize(unit_size) which is only supported in PDF 1.6
  (i.e. Acrobat 7) and above, page.Scale(sc) supports all PDF versions.

## ◆ SetBox()

void pdftron::PDF::Page::SetBox | ( | Box | type,
|  | const Rect & | box ) const

Sets the page bounding box specified by 'page_region' for this page.

Parameters

  type | The type of the page bounding box. Possible values are: e_media, e_crop, e_bleed, e_trim, and e_art.
  box | A rectangle specifying the coordinates to set for the box. The coordinates are specified in user space units.

## ◆ SetCropBox()

void pdftron::PDF::Page::SetCropBox | ( | const Rect & | box | ) |

Sets the crop box for this page. The crop box is the region of the page to display and print.

Parameters

  box | the new crop box for this page. The page dimensions are specified in user space coordinates.

The crop box defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed.

Note
  this method is equivalent to SetBox(Page::e_crop)

## ◆ SetMediaBox()

void pdftron::PDF::Page::SetMediaBox | ( | const Rect & | box | ) |

Sets the media box for this page.

Parameters

  box | the new media box for this page. The page dimensions are specified in user space coordinates.

The media box defines the boundaries of the physical medium on which the page is to be printed. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes.

Note
  this method is equivalent to SetBox(Page::e_media)

## ◆ SetRotation()

void pdftron::PDF::Page::SetRotation | ( | Rotate | angle | ) |

Sets the rotation value for this page.

Parameters

  angle | Rotation value to be set for a given page. Must be one of the Page::Rotate values.

## ◆ SetUserUnitSize()

void pdftron::PDF::Page::SetUserUnitSize | ( | double | unit_size | ) |

Sets the UserUnit value for a page.

Parameters

  unit_size | A positive number giving the size of default user space units, in multiples of 1/72 inch.

Note
  This is a PDF 1.6 feature. See the implementation note 171 in PDF Reference for details.

## ◆ SubtractRotations()

Rotate pdftron::PDF::Page::SubtractRotations | ( | Rotate | r0,
|  | Rotate | r1 )
| static

Rotate r0 counter clockwise by r1.

Parameters

  r0 | first rotation.
  r1 | second rotation.

Returns
  returns r0 - r1

The documentation for this class was generated from the following file:

- PDF/Page.h