Page Class Documentation
classPageNamespace:datalogics_interface
Detailed Description
The page is the basic object used for organizing content in a PDF document.
Threading: single-thread use. A Page is bound to its owning Document's thread; do not share it across threads. See datalogics_interface.hpp for the full threading model.
Lifetime: a Page must not outlive the Document that produced it.
Referenced by
Constructor & Destructor Documentation
Member Function Documentation
add_qr_barcode
voidadd_qr_barcode(const std::string &text, doublex, doubley, doublewidth, doubleheight)Parameters
text: const std::string &The Text to be encoded in the barcode
x: doubleThe horizontal location on the page in points
y: doubleThe vertical location on the page in points
width: doubleThe width of the barcode image in points
height: doubleThe height of the barcode image in points
Returns:
voidAdd a QR Two-Dimensional Barcode encoded with the specified Text to the page as an image.
NOTE: The Error Correction Level is set to Medium.
add_qr_barcode
booladd_qr_barcode(QREncodeParams ¶ms)Parameters
params: QREncodeParams &The Text to be encoded in the barcode
Returns:
boolAdd a QR Two-Dimensional Barcode encoded with the specified Text to the page as an image.
NOTE: The Error Correction Level is set to Medium.
as_pdf_object
PDFObjectas_pdf_object()Returns:
PDFObjectReturns a non-owning PDFObject handle to this page's underlying dict. Page dicts are always indirect, so the returned object's get_indirect() will be true; putting it into another PDFDict/PDFArray will therefore store an indirect reference.
Suitable for storing in dicts/arrays as an indirect reference.
create_annotation
std::unique_ptr< Annotation >create_annotation(const std::string &sub_type, const Rect &rect)Parameters
sub_type: const std::string &rect: const Rect &
Returns:
The newly created annotation.(Deprecated, function may be removed in the future. Instead, use the constructor for Annotation or a subclass of Annotation.)
Creates a new annotation, associated with the specified page's Document, but not added to the page. Use AddAnnotation to add the annotation to the page.
draw_contents
std::vector< unsigned char >draw_contents(const DrawParams ¶ms)Parameters
params: const DrawParams &vector of pointers to a memory that we need to fill
Returns:
std::vector< unsigned char >Drawing separations to colorants' buffers of an image
get_annotation
std::unique_ptr< Annotation >get_annotation(intindex)Parameters
index: intThe index of the annotation to get on a page. The first annotation on a page has an index of zero.
Returns:
The indexed annotation object.Gets the annotIndex annotation on the page.
get_art_box
Rectget_art_box()Returns:
The ArtBox rectangle in user space coordinates.Get the page's ArtBox.
The ArtBox defines the extent of the page's meaningful content (including potential white space) as intended by the page's creator.
get_bbox
Rectget_bbox()Returns:
The bounding box rectangle in user space coordinates.Get the page's Bounding Box.
The BBox is the smallest rectangle that encloses all of the page's visible content. Unlike the other page boxes, it is calculated from the page content and cannot be set directly.
get_bleed_box
Rectget_bleed_box()Returns:
The BleedBox rectangle in user space coordinates.Get the page's BleedBox.
The BleedBox defines the region to which the contents of the page shall be clipped when output in a production environment. It includes any extra bleed area needed to account for limitations of cutting, folding, and trimming equipment.
get_content
Contentget_content()Returns:
The content for the page.Retrieve the page's content for inspection or editing.
Repeated calls without an intervening update_content() return the same cached content. After update_content(), the next call returns a fresh content that reflects the committed state.
Creates a Content from the Page object's contents and resources.
Calls to GetContent without an intervening UpdateContent return the same cached Content object, so edits made through earlier handles are visible. After a call to UpdateContent, a subsequent GetContent returns a fresh Content that reflects the committed state.
get_crop_box
Rectget_crop_box()Returns:
The CropBox rectangle in user space coordinates.Get the page's CropBox.
The CropBox defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed. The default value is the page's MediaBox.
get_image
Imageget_image(const Rect &export_rect)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
Returns:
An Image containing the rendered page region.Export a region of a PDF page to an Image object.
This version of GetImage can be used to specify a particular size in pixels for the exported image by setting ImageParams.PixelWidth and/or ImageParams.PixelHeight.
If the exportRect is smaller than the PDF page and ImageParams.PixelWidth and ImageParams.PixelHeight are set, then the resulting image will be of the size ImageParams.PixelWidth x ImageParams.PixelHeight and contain the area of the page inside the exportRect, scaled to fit.
It is also possible to use this function by specifying only ImageParams.PixelWidth or only ImageParams.PixelHeight. When only one is specified, the function will calculate the other.
get_image
Imageget_image(const Rect &export_rect, const PageImageParams ¶ms)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
params: const PageImageParams &A PageImageParams containing additional parameters for the exported image, including the exported image's pixel width, pixel height, and resolution. If these parameters are not specified, the pixel width and pixel height of the image are calculated using the exportRect and a resolution of 300.0.
Returns:
An Image containing the rendered page region.Export a region of a PDF page to an Image object.
This version of GetImage can be used to specify a particular size in pixels for the exported image by setting ImageParams.PixelWidth and/or ImageParams.PixelHeight.
If the exportRect is smaller than the PDF page and ImageParams.PixelWidth and ImageParams.PixelHeight are set, then the resulting image will be of the size ImageParams.PixelWidth x ImageParams.PixelHeight and contain the area of the page inside the exportRect, scaled to fit.
It is also possible to use this function by specifying only ImageParams.PixelWidth or only ImageParams.PixelHeight. When only one is specified, the function will calculate the other.
get_image
Imageget_image(const Rect &export_rect, const PageImageParams ¶ms, const std::vector< std::shared_ptr< SeparationColorSpace > > &separations)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
params: const PageImageParams &A PageImageParams containing additional parameters for the exported image, including the exported image's pixel width, pixel height, and resolution. If these parameters are not specified, the pixel width and pixel height of the image are calculated using the exportRect and a resolution of 300.0.
Returns:
An Image containing the rendered page region.Export a region of a PDF page to an Image object.
This version of GetImage can be used to specify a particular size in pixels for the exported image by setting ImageParams.PixelWidth and/or ImageParams.PixelHeight.
If the exportRect is smaller than the PDF page and ImageParams.PixelWidth and ImageParams.PixelHeight are set, then the resulting image will be of the size ImageParams.PixelWidth x ImageParams.PixelHeight and contain the area of the page inside the exportRect, scaled to fit.
It is also possible to use this function by specifying only ImageParams.PixelWidth or only ImageParams.PixelHeight. When only one is specified, the function will calculate the other.
get_image_separations
ImageCollectionget_image_separations(const Rect &export_rect, const PageImageParams ¶ms)Parameters
export_rect: const Rect ¶ms: const PageImageParams &
Returns:
ImageCollectionGet per-ink grayscale separation images for all inks on the page. Discovers inks via list_inks() and builds SeparationColorSpaces internally.
get_image_separations
ImageCollectionget_image_separations(const Rect &export_rect, const PageImageParams ¶ms, const std::vector< std::shared_ptr< SeparationColorSpace > > &separations)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
params: const PageImageParams &A PageImageParams containing additional parameters for the exported image, including the exported image's pixel width, pixel height, and resolution. If these parameters are not specified, the pixel width and pixel height of the image are calculated using the exportRect and a resolution of 300.0.
separations: const std::vector< std::shared_ptr< SeparationColorSpace > > &A collection of SeparationColorSpace class additional parameter for specifying colorants for bitmap rendering. Each SeparationColorSpace must be constructed from an ink and a page. Their tint transforms and alternates will be ignored.
Returns:
An ImageCollection containing one Image per separation colorant.Export a region of a PDF page using the specified Separation ColorSpaces to an Image Collection object.
This version of GetImage can be used to specify a particular size in pixels for the exported image by setting ImageParams.PixelWidth and/or ImageParams.PixelHeight.
If the exportRect is smaller than the PDF page and ImageParams.PixelWidth and ImageParams.PixelHeight are set, then the resulting image will be of the size ImageParams.PixelWidth x ImageParams.PixelHeight and contain the area of the page inside the exportRect, scaled to fit.
It is also possible to use this function by specifying only ImageParams.PixelWidth or only ImageParams.PixelHeight. When only one is specified, the function will calculate the other.
NOTE: By default if Separation Colorants are only Process (CMYK), rasterization is done using DeviceCMYK. When PageImageParams.UseDeviceNForImageSeparations is set, rasterization is done using DeviceN regardless.
get_media_box
Rectget_media_box()Returns:
The MediaBox rectangle in user space coordinates.Get the page's MediaBox.
The MediaBox defines the boundaries of the physical medium on which the page is intended to be displayed or printed. It is the largest of the page boxes and serves as the default for the CropBox.
get_num_annotations
intget_num_annotations()Returns:
The number of annotations on this page.Gets the number of annotations on a page. Annotations associated with pop-up windows (such as strikeouts) are counted as two annotations. Widget annotations (form fields) are included in the count.
get_output_preview_image
Imageget_output_preview_image(const Rect &export_rect, const PageImageParams ¶ms)Parameters
export_rect: const Rect ¶ms: const PageImageParams &
Returns:
ImageGet a soft-proof composite image for all inks on the page. Overprint simulation is off.
get_output_preview_image
Imageget_output_preview_image(const Rect &export_rect, const PageImageParams ¶ms, boolsimulate_overprint)Parameters
export_rect: const Rect ¶ms: const PageImageParams &simulate_overprint: bool
Returns:
ImageGet a soft-proof composite image for all inks with overprint control.
get_output_preview_image
Imageget_output_preview_image(const Rect &export_rect, const PageImageParams ¶ms, const std::vector< std::shared_ptr< SeparationColorSpace > > &separations)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
params: const PageImageParams &A PageImageParams containing additional parameters for the exported image, including the exported image's pixel width, pixel height, and resolution. If these parameters are not specified, the pixel width and pixel height of the image are calculated using the exportRect and a resolution of 300.0.
separations: const std::vector< std::shared_ptr< SeparationColorSpace > > &A collection of SeparationColorSpace class additional parameter for specifying colorants for bitmap rendering. Each SeparationColorSpace must be constructed from an ink and a page.
Returns:
An Image representing the output preview of the page region.Create an Output Preview image used when Soft Proofing a document prior to actual printing.
get_output_preview_image
Imageget_output_preview_image(const Rect &export_rect, const PageImageParams ¶ms, const std::vector< std::shared_ptr< SeparationColorSpace > > &separations, boolsimulate_overprint)Parameters
export_rect: const Rect &A Rect describing the region of the page to export, specified in user space coordinates. One user unit corresponds to 1/72 inch. To export the entire page, set this parameter to the page's CropBox. User space coordinates correspond to the unrotated page; the rotation specified in Page.Rotation is not taken into account with these coordinates.
params: const PageImageParams &A PageImageParams containing additional parameters for the exported image, including the exported image's pixel width, pixel height, and resolution. If these parameters are not specified, the pixel width and pixel height of the image are calculated using the exportRect and a resolution of 300.0.
separations: const std::vector< std::shared_ptr< SeparationColorSpace > > &A collection of SeparationColorSpace class additional parameter for specifying colorants for bitmap rendering. Each SeparationColorSpace must be constructed from an ink and a page.
simulate_overprint: bool
Returns:
An Image representing the output preview of the page region.Create an Output Preview image used when Soft Proofing a document prior to actual printing.
get_page_number
intget_page_number()Returns:
the number of this page in the Document.Retrieve the page number for this PDF page.
Page numbers always start at zero.
get_pdf_dict
PDFDictget_pdf_dict()Returns:
PDFDictRetrieve the underlying PDF dictionary for this page. Needed to set StructParents, Tabs, or other page-level entries that do not yet have dedicated accessors. Retrieve the PDFObject representation of this object.
get_render_warnings
intget_render_warnings()Returns:
A bitfield to be compared against PageRenderWarning Enum values.Reports possible page rendering problems.
get_rotation
PageRotationget_rotation()Returns:
PageRotationThe number of degrees by which the page is rotated clockwise when displayed or printed.
get_trim_box
Rectget_trim_box()Returns:
The TrimBox rectangle in user space coordinates.Get the page's TrimBox.
The TrimBox defines the intended dimensions of the finished page after trimming. It may be smaller than the MediaBox to account for production- related content such as printing instructions or cut marks.
get_user_unit
floatget_user_unit()Returns:
the size of default user space units.Gets the size of default user space units for the page.
has_transparency
boolhas_transparency(boolinclude_annot_appearances)Parameters
include_annot_appearances: boolIf true, annotation appearances are included in the check; if false, annotation appearances will be ignored.
Returns:
true if the page uses transparency features, false otherwise.Checks whether a page uses any transparency features.
Note: To determine whether a page uses transparency, the resources of the page must be enumerated (though the page contents do not need to be parsed). The page resources may not be optimized for slow (browser- based) connections, so calling Page.HasTransparency() before the page has been downloaded may cause unpleasant read behavior and performance problems.
list_inks
std::vector< Ink >list_inks()Returns:
A list of Ink objects representing the inks used on this page.Retrieve a list of all inks present on a page.
list_inks
std::vector< Ink >list_inks(boolinclude_opi)Parameters
include_opi: bool
Returns:
A list of Ink objects representing the inks used on this page.Retrieve a list of all inks present on a page.
make_separations
voidmake_separations(const SeparationParams ¶ms)Parameters
params: const SeparationParams &Parameters for the separation generation, including a list of plates.
Returns:
voidGenerate print color separations for a page.
operator=
Parameters
: Page &&
Returns:
Page &remove_annotation
voidremove_annotation(intindex)Parameters
index: intThe index (into the page's annotation array) of the annotation to remove.
Returns:
voidRemoves an annotation from the specified page. Annotations are stored in arrays, which are automatically compressed when an annotation is removed. For this reason, if you use a loop in which you remove annotations, structure the code so the loop processes from the highest to the lowest index. If you loop the other direction, you will skip over annotations immediately following ones you remove.
set_art_box
voidset_art_box(const Rect &r)Parameters
r: const Rect &The rectangle specifying the ArtBox in user space coordinates, or null to remove the ArtBox.
Returns:
voidSet the page's ArtBox.
The ArtBox defines the extent of the page's meaningful content (including potential white space) as intended by the page's creator.
set_bleed_box
voidset_bleed_box(const Rect &r)Parameters
r: const Rect &The rectangle specifying the BleedBox in user space coordinates, or null to remove the BleedBox.
Returns:
voidSet the page's BleedBox.
The BleedBox defines the region to which the contents of the page shall be clipped when output in a production environment. It includes any extra bleed area needed to account for limitations of cutting, folding, and trimming equipment.
set_crop_box
voidset_crop_box(const Rect &r)Parameters
r: const Rect &The rectangle specifying the CropBox in user space coordinates, or null to remove the CropBox.
Returns:
voidSet the page's CropBox.
The CropBox defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed. The default value is the page's MediaBox.
set_media_box
voidset_media_box(const Rect &r)Parameters
r: const Rect &The rectangle specifying the MediaBox in user space coordinates.
Returns:
voidSet the page's MediaBox.
The MediaBox defines the boundaries of the physical medium on which the page is intended to be displayed or printed. It is the largest of the page boxes and serves as the default for the CropBox.
set_rotation
voidset_rotation(PageRotationrotation)Parameters
rotation: PageRotationthe number of degrees by which the page is rotated clockwise when displayed or printed
Returns:
voidThe number of degrees by which the page is rotated clockwise when displayed or printed.
set_trim_box
voidset_trim_box(const Rect &r)Parameters
r: const Rect &The rectangle specifying the TrimBox in user space coordinates, or null to remove the TrimBox.
Returns:
voidSet the page's TrimBox.
The TrimBox defines the intended dimensions of the finished page after trimming. It may be smaller than the MediaBox to account for production- related content such as printing instructions or cut marks.
set_user_unit
voidset_user_unit(floatunit)Parameters
unit: floatthe size of default user space units.
Returns:
voidSets the size of default user space units for the page.
update_content
voidupdate_content()Returns:
voidCommit in-memory content edits back to the page dictionary.
Edits made through the Content returned by get_content() are held in memory until this method is called. Document::save() does not implicitly commit content edits.
Commits in-memory edits to the Page's Content back into the Page, using the same compression filters the content was previously encoded with.
Edits made through the Content object returned by GetContent are held in memory until UpdateContent is called. Document::Save does not implicitly commit content edits; a Page that has been edited but not committed will be saved in its pre-edit state.