PTMarkup

@interface PTMarkup : PTAnnot

Markup is a base class for a number of annotations types that are used to mark up PDF documents. These annotations have text that appears as part of the annotation and may be displayed in other ways by a conforming reader, such as in a Comments pane. Markup annotations may be divided into the following groups:

  • Free text annotations display text directly on the page. The annotation’s Contents entry specifies the displayed text.
  • Most other markup annotations have an associated pop-up window that may contain text. The annotation’s Contents entry specifies the text that shall be displayed when the pop-up window is opened. These include text, line, square, circle, polygon, polyline, highlight,underline, squiggly-underline, strikeout, rubber stamp, caret, ink, and file attachment annotations.
  • Sound annotations do not have a pop-up window but may also have associated text specified by the Contents entry.

  • A subset of markup annotations are intended to markup text of a document (e.g. highlight, strikeout, jagged, underline) and they are derived from TextMarkup base class.

Note

The pop-up annotation type must not appear by itself; it must be associated with a markup annotation that uses it to display text.

The meaning of an annotation’s Contents entry varies by annotation type. Typically, it is the text that shall be displayed for the annotation or, if the annotation does not display text, an alternate description of the annotation’s contents in human-readable form. When separating text into paragraphs, a CARRIAGE RETURN (0Dh) must be used.

  • Creates a markup annotation and initializes it using given Cos/SDF object.

    Note

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

    Declaration

    Objective-C

    - (instancetype)initWithD:(PTObj *)d;

    Swift

    init!(d: PTObj!)

    Parameters

    d

    The Cos/SDF object to initialze the annotation with.

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithAnn: (PTAnnot*)ann;

    Swift

    init!(ann: PTAnnot!)

  • Returns the title of the markup annotation.

    Note

    The title is The text label that is displayed in the title bar of the annotation’s pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the ‘T’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (NSString *)GetTitle;

    Swift

    func getTitle() -> String!

    Return Value

    A string representing the title of the markup annotation, or null is the title is not specified.

  • Sets the title of the markup annotation. (Optional; PDF 1.1)

    Note

    The title is The text label that is displayed in the title bar of the annotation’s pop-up window when open and active Markup annotation. This entry is also used to identify the user who added the annotation. It corresponds to the ‘T’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (void)SetTitle:(NSString *)title;

    Swift

    func setTitle(_ title: String!)

    Parameters

    title

    A string.

  • Returns the Popup object associated with this markup annotation.

    Note

    The Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

    Declaration

    Objective-C

    - (PTPopup *)GetPopup;

    Swift

    func getPopup() -> PTPopup!

    Return Value

    A Popup object that is associated with this markup annotation.

  • Sets the Popup object associated with this markup annotation. (Optional; PDF 1.3 )

    Note

    the Popup is An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation.

    Declaration

    Objective-C

    - (void)SetPopup:(PTPopup *)ppup;

    Swift

    func setPopup(_ ppup: PTPopup!)

    Parameters

    ppup

    A Popup object that is associated with this markup annotation.

  • Note

    This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation’s appearance stream, it may incorporate this Opacity entry into the stream’s content.)

    Note

    This corresponds to the ‘CA’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (double)GetOpacity;

    Swift

    func getOpacity() -> Double

    Return Value

    The opacity value. Default value: 1.0.

  • Sets the opacity value for the annotation. (Optional; PDF 1.4 )

    Note

    This value is applied to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. When an appearance stream is presented with the annotation, this entry is ignored.(However, if the compliant viewer regenerates the annotation’s appearance stream, it may incorporate this Opacity entry into the stream’s content.)

    Note

    This corresponds to the ‘CA’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (void)SetOpacity:(double)op;

    Swift

    func setOpacity(_ op: Double)

    Parameters

    op

    A number indicating the Markup annotation’s opacity value. Default value: 1.0.

  • Returns the subject of the Markup annotation. (PDF 1.5)

    Note

    The subject is a short piece of text description about the annotation.

    Note

    This corresponds to the ‘Subj’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (NSString *)GetSubject;

    Swift

    func getSubject() -> String!

    Return Value

    A string representing the subject of the Markup annotation.

  • Sets subject of the Markup annotation. (Optional; PDF 1.5 )

    Note

    The subject is a short piece of text description about the annotation.

    Note

    This corresponds to the ‘Subj’ field of the annotation’s dictionary.

    Declaration

    Objective-C

    - (void)SetSubject:(NSString *)contents;

    Swift

    func setSubject(_ contents: String!)

    Parameters

    contents

    A string representing the subject of the Markup annotation.

  • Note

    This corresponds to the ‘CreationDate’ field of the markup annotation’s dictionary.

    Declaration

    Objective-C

    - (PTDate *)GetCreationDates;

    Swift

    func getCreationDates() -> PTDate!

    Return Value

    The creation date for the markup annotation.

  • Sets the creation date for the markup annotation. (Optional; PDF 1.5 )

    Note

    This corresponds to the ‘CreationDate’ field of the markup annotation’s dictionary.

    Declaration

    Objective-C

    - (void)SetCreationDates:(PTDate *)dt;

    Swift

    func setCreationDates(_ dt: PTDate!)

    Parameters

    dt

    A Date object indicating the date the markup annotation is created.

  • Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

    Note

    When “e_Cloudy” is chosen,the width and dash array specified by the annotation’s BorderStyle entry needs to be taken into consideration.

    Declaration

    Objective-C

    - (PTBorderEffect)GetBorderEffect;

    Swift

    func getBorderEffect() -> PTBorderEffect

    Return Value

    the border effect of the markup annotation. Default value: e_None.

  • Sets the border effect of the markup annotation. (Optional; PDF 1.5 )

    Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

    Note

    When “e_Cloudy” is chosen,the width and dash array specified by the annotation’s BorderStyle entry needs to be taken into consideration.

    Declaration

    Objective-C

    - (void)SetBorderEffect:(PTBorderEffect)effect;

    Swift

    func setBorderEffect(_ effect: PTBorderEffect)

    Parameters

    effect

    An entry from the enum “BorderEffect” that represents the border effect of the Markup annotation. Default value: e_None.

  • Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

    Declaration

    Objective-C

    - (double)GetBorderEffectIntensity;

    Swift

    func getBorderEffectIntensity() -> Double

    Return Value

    A number describing the intensity of the border effect, in the range 0 to 2.

  • Sets the border effect intensity of the markup annotation. (Optional; valid only if Border effect is Cloudy)

    Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a ‘BE’ entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry.

    Note

    this parameter applies only if Border effect is e_Cloudy.

    Declaration

    Objective-C

    - (void)SetBorderEffectIntensity:(double)intensity;

    Swift

    func setBorderEffectIntensity(_ intensity: Double)

    Parameters

    intensity

    A number describing the intensity of the border effect, in the range 0 (which is default) to 2.

  • Returns the interior color of the annotation.

    Note

    The color can be in different color spaces: Gray, RGB, or CMYK. Call “GetInteriorColorCompNum” to access the color space information.

    Note

    According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotations (Line,Square,Circle,Polygon,PolyLine,Redaction) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color (‘IC’ entry), if present in their annotation dictionary. In case no color is specified, CMYK white is returned.

    Declaration

    Objective-C

    - (PTColorPt *)GetInteriorColor;

    Swift

    func getInteriorColor() -> PTColorPt!

    Return Value

    A ColorPt object that denotes the color of the annotation.

  • Returns the number indicating the interior color space of the annotation.

    Declaration

    Objective-C

    - (int)GetInteriorColorCompNum;

    Swift

    func getInteriorColorCompNum() -> Int32

    Return Value

    An integer indicating the number of channels forming the color space. 3 corresponds to RGB, 4 corresponds to CMYK, and 1 corresponds to Gray. If the interior is transparent, the return value is 0.

  • Sets the interior color of the Markup annotation.

    Note

    It is necessary to make sure the consistency between the type of parameter c and the value of parameter CompNum. RGB ColorPt corresponds to 3, CMYK ColorPt corresponds to 4, Gray ColorPt corresponds to 1, and transparent corresponds to 0.

    Note

    According to PDF Reference Manual interior color is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use interior color will ignore the interior color (‘IC’ entry), if present in their annotation dictionary.

    Entries out of the specified color space array length will be discarded. Missing entries for a specified color space will lead to potential exceptions.

    Declaration

    Objective-C

    - (void)SetInteriorColor:(PTColorPt *)c CompNum:(int)CompNum;

    Swift

    func setInteriorColor(_ c: PTColorPt!, compNum CompNum: Int32)

    Parameters

    c

    A ColorPt object that denotes the color of the Markup annotation.
    CompNum

    An integer indicating the number of channels forming the color space used. It also defines the length of the array to be allocated for storing the entries of c.

  • Returns the inner bounding rectangle of the Markup annotation.

    Note

    This rectangle can be same as or inside of the annotation’s rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed.

    Note

    According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle (‘RD’ entry), if present in their annotation dictionary.

    Declaration

    Objective-C

    - (PTPDFRect *)GetContentRect;

    Swift

    func getContentRect() -> PTPDFRect!

    Return Value

    A rectangle specifying the region where content should be displayed.

  • Sets the inner bounding rectangle of the Markup annotation. (Optional)

    Note

    This rectangle can be same as or inside of the annotation’s rectangle. If it is smaller, such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. For FreeText annotation with a callout, content rectangle specifies an inner region for the text to be displayed.

    Note

    According to PDF Reference Manual content rectangle is not the property that is expected for Markup annotations in general, but it applies to many derived annotation classes (FreeText,Square,Circle,Caret) and therefore get()/set() methods are provided in the base class Markup. Annotations that do not use this property will ignore the content rectangle (‘RD’ entry), if present in their annotation dictionary.

    Declaration

    Objective-C

    - (void)SetContentRect:(PTPDFRect *)cr;

    Swift

    func setContentRect(_ cr: PTPDFRect!)

    Parameters

    cr

    A Rect struct to be assign to the ‘RD’ entry of the annotation dictionary.

  • Returns the rectangle difference between overall annotation rectangle and content rectangle.

    Note

    The four numbers of the returning struct specify the difference between two rectangles: the Rect entry of the annotation and the actual bounding box of the underlying rectangle. Such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. The four numbers of the returning struct correspond to the differences in default user space, between the left, top, right, and bottom of the two above mentioned rectangles.

    Note

    GetPadding() and GetContentRectangle() both use ‘RD’ entry of the annotation dictionary, but represent it to user in different ways.

    See

    GetContentRect()

    Declaration

    Objective-C

    - (PTPDFRect *)GetPadding;

    Swift

    func getPadding() -> PTPDFRect!

    Return Value

    A set of four numbers represented as a Rect struct.

  • Sets the rectangle difference between overall annotation rectangle and content rectangle. (Optional)

    Note

    The four numbers of rd specify the difference between two rectangles: the Rect entry of the annotation and the actual bounding box of the underlying rectangle. Such a difference may occur in situations where a border effect causes the size of the annotation Rect entry to increase beyond that of the rectangle. The four numbers of the rd correspond to the differences in default user space, between the left, top, right, and bottom of the two above mentioned rectangles.

    Note

    SetPadding() and SetContentRectangle() both use ‘RD’ entry of the annotation dictionary. Two methods are provided to give users additional flexibility and ease of use in setting the values of the ‘RD’ field.

    See

    GetContentRect()

    Declaration

    Objective-C

    - (void)SetPaddingWithRect:(PTPDFRect *)rd;

    Swift

    func setPaddingWith(_ rd: PTPDFRect!)

    Parameters

    rd

    A set of four numbers represented as a Rect struct

  • Undocumented

    Declaration

    Objective-C

    - (void)SetPadding: (double)x;

    Swift

    func setPadding(_ x: Double)

  • Rotates the appearance of the Markup annotation.

    Note

    Apply a rotation to an existing appearance. This rotation will be reflected in the bounding rect of the annot (which will be updated), but not in any other part of the annotation dictionary. This will effectively create a custom appearance for the annotation, and any subsequent calls to RefreshAppearance will clear this transformation.

    Declaration

    Objective-C

    - (void)RotateAppearance:(double)angle;

    Swift

    func rotateAppearance(_ angle: Double)

    Parameters

    angle

    The new rotation