PDFTron PDFNet SDK API Reference

List of all members.


Public Types
enum	Box { e_media, e_crop, e_bleed, e_trim, e_art }
	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):. More...
enum	Rotate { e_0, e_90, e_180, e_270 }
	Specifies page rotation, in degrees. More...
Public Member Functions
	Page (SDF::Obj page_dict=0)
	Initialize a page using an existing low-level Cos/SDF page object.
	Page (const Page &p)
Page &	operator= (const Page &p)
bool	IsValid () const
	Returns: true if this is a valid (non-null) page, false otherwise.
int	GetIndex () const
	Returns: the Page number indication the position of this Page in document's page sequence.
Rect	GetBox (Box type) const
	Returns: the box specified for the page object intersected with the media box.
void	SetBox (Box type, const Rect &box) const
	Sets the page bounding box specified by 'page_region' for this page.
Rect	GetCropBox () const
	Returns: the crop box for this page.
void	SetCropBox (const Rect &box)
	Sets the crop box for this page.
Rect	GetMediaBox () const
	Returns: the media box for this page.
void	SetMediaBox (const Rect &box)
	Sets the media box for this page.
Rotate	GetRotation () const
	Returns: the rotation value for this page.
void	SetRotation (Rotate angle)
	Sets the rotation value for this page.
double	GetPageWidth (Box box_type=e_crop)
	Returns: the width for the given page region/box taking into account page rotation attribute (i.e.
double	GetPageHeight (Box box_type=e_crop)
	Returns: the height for the given page region/box taking into account page rotation attribute (i.e.
Common::Matrix2D	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.
SDF::Obj	GetAnnots () const
	Gets SDF/Cos array containing annotation dictionaries.
UInt	GetNumAnnots () const
	Gets the number of annotations on a page.
Annot	GetAnnot (UInt index) const
	Gets the annotation on the page.
void	AnnotInsert (UInt pos, Annot &annot)
	Adds an annotation at the specified location in a page's annotation array.
void	AnnotPushBack (Annot &annot)
	Adds an annotation to the end of a page's annotation array.
void	AnnotPushFront (Annot &annot)
	Adds an annotation to the beginning of a page's annotation array.
void	AnnotRemove (Annot &annot)
	Removes the given annotation from the page.
void	AnnotRemove (UInt index)
	Removes the annotation at a given location.
void	Scale (double scale)
	A utility method used to scale physical dimensions of the page including all page content.
void	FlattenField (class Field filed)
	Flatten/Merge existing form field appearances with the page content and remove widget annotation.
bool	HasTransition () const
	Tests whether this page has a transition.
double	GetUserUnitSize () const
	Gets the UserUnit value for the page.
void	SetUserUnitSize (double unit_size)
	Sets the UserUnit value for a page.
SDF::Obj	GetResourceDict () const
	Returns: a pointer to the page resource dictionary.
SDF::Obj	GetContents () const
	Returns: NULL if page is empty, otherwise a single stream or an array of streams.
SDF::Obj	GetSDFObj () const
	Gets the page dictionary.
SDF::Obj	FindInheritedAttribute (const char *attrib) const
	Some of the page attributes are designated as inheritable.
	operator bool ()
	Returns: true if the object is not null, false otherwise.

Detailed Description

Member Enumeration Documentation

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.

Enumerator:

e_media
e_crop
e_bleed
e_trim
e_art

enum pdftron::PDF::Page::Rotate

Specifies page rotation, in degrees.

Enumerator:

e_0
e_90
e_180
e_270

Constructor & Destructor Documentation

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.

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

Member Function Documentation

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

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.

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.

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().

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.

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)

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)

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:

the page is missing media box the function throws Exception

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.

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

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

Returns:: the rotation value for this page.

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.

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.

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.

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.

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

Gets 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.

UInt pdftron::PDF::Page::GetNumAnnots ( ) const

Gets the number of annotations on a page.

Widget annotations (form fields) are included in the count.

Returns:: The number of annotations on a page.

Annot pdftron::PDF::Page::GetAnnot ( UInt index ) const

Gets 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 apage. The first annotation on a page has an index of zero.

void pdftron::PDF::Page::AnnotInsert	(	UInt	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.

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.

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.

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

Removes the given annotation from the page.

Note:: Removing the annotation invalidates the given Annot object.

Parameters:

index

- A zero based index of the annotation to remove.

void pdftron::PDF::Page::AnnotRemove ( UInt 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.

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.

void pdftron::PDF::Page::FlattenField ( class Field filed )

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.

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.

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

Tests whether this page has a transition.

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

Gets 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.

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.

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

Returns:: a pointer to the page resource dictionary.

Exceptions:

the page is missing resource dictionary the function throws Exception

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

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

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

Gets the page dictionary.

Returns:: the object to the underlying SDF/Cos object.

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 inhritance tree in search for specified attribute.

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)

pdftron::PDF::Page Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation