PTPage

@interface PTPage : NSObject

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.

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

    Note

    This constructor does not copy any data, but is instead the logical equivalent of a type cast.

    Note

    Because PDF::PDFDoc provides a complete high-level interface for Page creation and traversal this constructor is rarely used.

    Declaration

    Objective-C

    - (instancetype)initWithPage_dict:(PTObj *)page_dict;

    Swift

    init!(page_dict: PTObj!)

    Parameters

    page_dict

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

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    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.

  • Declaration

    Objective-C

    - (int)GetIndex;

    Swift

    func getIndex() -> Int32

    Return Value

    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.

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

    Declaration

    Objective-C

    - (PTPDFRect *)GetBox:(PTBox)type;

    Swift

    func getBox(_ type: PTBox) -> PTPDFRect!

    Parameters

    type

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

    Return Value

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

  • Sets the page bounding box specified by ‘page_region’ for this page.

    Declaration

    Objective-C

    - (void)SetBox:(PTBox)type box:(PTPDFRect *)box;

    Swift

    func setBox(_ type: PTBox, box: PTPDFRect!)

    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.

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

    Note

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

    Declaration

    Objective-C

    - (PTPDFRect *)GetCropBox;

    Swift

    func getCropBox() -> PTPDFRect!

    Return Value

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

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

    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)

    Declaration

    Objective-C

    - (void)SetCropBox:(PTPDFRect *)box;

    Swift

    func setCropBox(_ box: PTPDFRect!)

    Parameters

    box

    the new crop 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) @exception if the page is missing media box the function throws Exception

    Declaration

    Objective-C

    - (PTPDFRect *)GetMediaBox;

    Swift

    func getMediaBox() -> PTPDFRect!

    Return Value

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

  • Sets the media box for this page.

    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)

    Declaration

    Objective-C

    - (void)SetMediaBox:(PTPDFRect *)box;

    Swift

    func setMediaBox(_ box: PTPDFRect!)

    Parameters

    box

    the new media 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.

    Declaration

    Objective-C

    - (PTPDFRect *)GetVisibleContentBox;

    Swift

    func getVisibleContentBox() -> PTPDFRect!

    Return Value

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

  • Rotate r0 clockwise by r1

    Declaration

    Objective-C

    + (PTRotate)AddRotations:(PTRotate)r0 r1:(PTRotate)r1;

    Swift

    class func addRotations(_ r0: PTRotate, r1: PTRotate) -> PTRotate

    Parameters

    r0

    first rotation.
    r1

    second rotation.

    Return Value

    returns r0 + r1

  • Rotate r0 counter clockwise by r1.

    Declaration

    Objective-C

    + (PTRotate)SubtractRotations:(PTRotate)r0 r1:(PTRotate)r1;

    Swift

    class func subtractRotations(_ r0: PTRotate, r1: PTRotate) -> PTRotate

    Parameters

    r0

    first rotation.
    r1

    second rotation.

    Return Value

    returns r0 - r1

  • Convert a rotation to a number.

    Declaration

    Objective-C

    + (int)RotationToDegree:(PTRotate)r;

    Swift

    class func rotation(toDegree r: PTRotate) -> Int32

    Parameters

    r

    rotation to convert to number

    Return Value

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

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

    Declaration

    Objective-C

    + (PTRotate)DegreeToRotation:(int)r;

    Swift

    class func degree(toRotation r: Int32) -> PTRotate

    Parameters

    r

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

    Return Value

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

  • Declaration

    Objective-C

    - (PTRotate)GetRotation;

    Swift

    func getRotation() -> PTRotate

    Return Value

    the rotation value for this page.

  • Sets the rotation value for this page.

    Declaration

    Objective-C

    - (void)SetRotation:(PTRotate)angle;

    Swift

    func setRotation(_ angle: PTRotate)

    Parameters

    angle

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

  • Declaration

    Objective-C

    - (double)GetPageWidth:(PTBox)box_type;

    Swift

    func getWidth(_ box_type: PTBox) -> Double

    Parameters

    box_type

    indicates the page box/region to query for width.

    Return Value

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

  • Declaration

    Objective-C

    - (double)GetPageHeight:(PTBox)box_type;

    Swift

    func getHeight(_ box_type: PTBox) -> Double

    Parameters

    box_type

    indicates the page box/region to query for height.

    Return Value

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

  • Declaration

    Objective-C

    - (PTMatrix2D *)GetDefaultMatrix:(BOOL)flip_y
                        box_type:(PTBox)box_type
                           angle:(PTRotate)angle;

    Swift

    func getDefaultMatrix(_ flip_y: Bool, box_type: PTBox, angle: PTRotate) -> PTMatrix2D!

    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.

    Return Value

    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.

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

    Declaration

    Objective-C

    - (PTObj *)GetAnnots;

    Swift

    func getAnnots() -> PTObj!

    Return Value

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

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

    Declaration

    Objective-C

    - (unsigned int)GetNumAnnots;

    Swift

    func getNumAnnots() -> UInt32

    Return Value

    The number of annotations on a page.

  • Returns the annotation on the page.

    Declaration

    Objective-C

    - (PTAnnot *)GetAnnot:(unsigned int)index;

    Swift

    func getAnnot(_ index: UInt32) -> PTAnnot!

    Parameters

    index

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

    Return Value

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

  • Get the Action associated with the selected Page Trigger event.

    Declaration

    Objective-C

    - (PTObj *)GetTriggerAction:(PTPageActionTriggerEvent)trigger;

    Swift

    func getTriggerAction(_ trigger: PTPageActionTriggerEvent) -> PTObj!

    Parameters

    trigger

    the type of trigger event to get

    Return Value

    the Action Obj if present, otherwise NULL

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

    Declaration

    Objective-C

    - (void)AnnotInsert:(unsigned int)pos annot:(PTAnnot *)annot;

    Swift

    func annotInsert(_ pos: UInt32, annot: PTAnnot!)

    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.

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

    Declaration

    Objective-C

    - (void)AnnotPushBack:(PTAnnot *)annot;

    Swift

    func annotPushBack(_ annot: PTAnnot!)

    Parameters

    annot

    - The annotation to prepend in a page’s annotation array.

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

    Declaration

    Objective-C

    - (void)AnnotPushFront:(PTAnnot *)annot;

    Swift

    func annotPushFront(_ annot: PTAnnot!)

    Parameters

    annot

    - The annotation to append in a page’s annotation array.

  • Removes the given annotation from the page.

    Note

    Removing the annotation invalidates the given Annot object.

    Declaration

    Objective-C

    - (void)AnnotRemoveWithAnnot:(PTAnnot *)annot;

    Swift

    func annotRemove(with annot: PTAnnot!)

    Parameters

    annot

    The annotation to remove.

  • Removes the annotation at a given location.

    Note

    Removing the annotation invalidates any associated Annot object.

    Declaration

    Objective-C

    - (void)AnnotRemoveWithIndex:(unsigned int)index;

    Swift

    func annotRemove(with index: UInt32)

    Parameters

    index

    - A zero based index of the annotation to remove.

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

    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.

    Declaration

    Objective-C

    - (void)Scale:(double)scale;

    Swift

    func scale(_ scale: Double)

    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.

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

    Declaration

    Objective-C

    - (void)FlattenField:(PTField *)field_to_flatten;

    Swift

    func flatten(_ field_to_flatten: PTField!)

    Parameters

    field_to_flatten

    field to flatten

  • Tests whether this page has a transition.

    Declaration

    Objective-C

    - (BOOL)HasTransition;

    Swift

    func hasTransition() -> Bool

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

    Declaration

    Objective-C

    - (double)GetUserUnitSize;

    Swift

    func getUserUnitSize() -> Double

    Return Value

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

  • Sets the UserUnit value for a page.

    Note

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

    Declaration

    Objective-C

    - (void)SetUserUnitSize:(double)unit_size;

    Swift

    func setUserUnitSize(_ unit_size: Double)

    Parameters

    unit_size

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

  • Declaration

    Objective-C

    - (PTObj *)GetResourceDict;

    Swift

    func getResourceDict() -> PTObj!

    Return Value

    a pointer to the page resource dictionary. @exception if the page is missing resource dictionary the function throws Exception

  • Declaration

    Objective-C

    - (PTObj *)GetContents;

    Swift

    func getContents() -> PTObj!

    Return Value

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

  • Returns the page dictionary.

    Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    the object to the underlying SDF/Cos object.

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

    Declaration

    Objective-C

    - (PTObj *)FindInheritedAttribute:(NSString *)attrib;

    Swift

    func findInheritedAttribute(_ attrib: String!) -> PTObj!

    Parameters

    attrib

    A string representing the attribute to search for.

    Return Value

    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)

  • Declaration

    Objective-C

    - (PTObj *)GetThumb;

    Swift

    func getThumb() -> PTObj!

    Return Value

    Object representing the Image thumbnail.

Additions

  • Returns a thumbnail image for the page that fits within the specified maximum size, in points. This method is equivalent to calling -thumbnailWithMaximumSize:scale: with a scale parameter equal to 0.0.

    Declaration

    Objective-C

    - (nullable UIImage *)thumbnailWithMaximumSize:(CGSize)maximumSize;

    Swift

    func thumbnail(withMaximumSize maximumSize: CGSize) -> UIImage?

    Parameters

    maximumSize

    The maximum dimensions of the thumbnail image, in points. The scale of the main UIScreen is used.

    Return Value

    a thumbnail image for the page, or nil if a thumbnail could not be created

  • Returns a thumbnail image for the page that fits within the specified maximum size, in points.

    Declaration

    Objective-C

    - (nullable UIImage *)thumbnailWithMaximumSize:(CGSize)maximumSize
                                         scale:(CGFloat)scale;

    Swift

    func thumbnail(withMaximumSize maximumSize: CGSize, scale: CGFloat) -> UIImage?

    Parameters

    maximumSize

    The maximum dimensions of the thumbnail image, in points.
    scale

    The screen scale to use to convert points to pixels. If you specify a value of 0.0, the scale factor is set to the scale factor of the device’s main screen.

    Return Value

    a thumbnail image for the page, or nil if a thumbnail could not be created

  • Append a string to the name of each field on the page.

    Declaration

    Objective-C

    - (void)appendStringToAllFieldNames:(nonnull NSString *)string;

    Swift

    func appendString(toAllFieldNames string: String)

    Parameters

    string

    The string to append to the name of each field on the page.