PTWidget

@interface PTWidget : PTAnnot

Interactive forms use widget annotations (PDF 1.2) to represent the appearance of fields and to manage user interactions. As a convenience, when a field has only a single associated widget annotation, the contents of the field dictionary and the annotation dictionary may be merged into a single dictionary containing entries that pertain to both a field and an annotation. NOTE This presents no ambiguity, since the contents of the two kinds of dictionaries do not conflict.

  • Creates a widget 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!)

  • Creates a new widget annotation in the specified document.

    Declaration

    Objective-C

    + (PTWidget *)Create:(PTSDFDoc *)doc
                 pos:(PTPDFRect *)pos
               field:(PTField *)field;

    Swift

    class func create(_ doc: PTSDFDoc!, pos: PTPDFRect!, field: PTField!) -> PTWidget!

    Parameters

    doc

    A document to which the annotation is added.
    pos

    A rectangle specifying the annotation’s bounds in default user space units.
    field

    A form field associated with this widget.

    Return Value

    A newly created blank widget annotation.

  • Returns the field associated with the Widget.

    Declaration

    Objective-C

    - (PTField *)GetField;

    Swift

    func getField() -> PTField!

    Return Value

    A Field object.

  • Note

    The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area

    Note

    A highlighting mode other than e_push will override any down appearance defined for the annotation. @default e_invert.

    Declaration

    Objective-C

    - (PTWidgetHighlightingMode)GetHighlightingMode;

    Swift

    func getHighlightingMode() -> PTWidgetHighlightingMode

    Return Value

    the HighlightingMode of the widget annotation.

  • Sets the HighlightingMode for the widget annotation.

    Note

    The annotation’s highlighting mode is the visual effect that shall be used when the mouse button is pressed or held down inside its active area

    Note

    A highlighting mode other than e_push shall override any down appearance defined for the annotation. Default value: e_invert.

    Declaration

    Objective-C

    - (void)SetHighlightingMode:(PTWidgetHighlightingMode)mode;

    Swift

    func setHighlightingMode(_ mode: PTWidgetHighlightingMode)

    Parameters

    mode

    - New highlighting mode for the widget.

  • Returns the action of the widget annotation

    Declaration

    Objective-C

    - (PTAction *)GetAction;

    Swift

    func getAction() -> PTAction!

    Return Value

    An action object representing the action of the widget annotation that should be performed when the annotation is activated.

  • Sets the action of the widget annotation (Optional; PDF 1.2 )

    Declaration

    Objective-C

    - (void)SetAction:(PTAction *)action;

    Swift

    func setAction(_ action: PTAction!)

    Parameters

    action

    An action object representing the action of the widget annotation that should be performed when the annotation is activated.

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

    Declaration

    Objective-C

    - (int)GetBorderColorCompNum;

    Swift

    func getBorderColorCompNum() -> Int32

    Return Value

    An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk”. 0 means this annotation had no color assigned.

  • Returns the border color of the annotation.

    Note

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

    Declaration

    Objective-C

    - (PTColorPt *)GetBorderColor;

    Swift

    func getBorderColor() -> PTColorPt!

    Return Value

    A color object that denotes the color of the Screen border.

  • Sets the border color of the annotation. (Optional)

    Declaration

    Objective-C

    - (void)SetBorderColor:(PTColorPt *)col compnum:(int)compnum;

    Swift

    func setBorderColor(_ col: PTColorPt!, compnum: Int32)

    Parameters

    col

    A color object that denotes the color of the screen border.
    compnum

    An integer which value indicates the color space used for the parameter c.

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

    Declaration

    Objective-C

    - (int)GetBackgroundColorCompNum;

    Swift

    func getBackgroundColorCompNum() -> Int32

    Return Value

    An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk” if color space is applicable, 0 means no background color was assigned.

  • Returns the background color of the annotation.

    Note

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

    Declaration

    Objective-C

    - (PTColorPt *)GetBackgroundColor;

    Swift

    func getBackgroundColor() -> PTColorPt!

    Return Value

    A color object that denotes the color of the Screen background.

  • Sets the background color of the annotation. (Optional)

    Declaration

    Objective-C

    - (void)SetBackgroundColor:(PTColorPt *)c compnum:(int)compnum;

    Swift

    func setBackgroundColor(_ c: PTColorPt!, compnum: Int32)

    Parameters

    col

    A color point that denotes the color of the screen background.
    compnum

    An integer which value indicates the color space used for the parameter c.

  • Returns static caption text of the annotation.

    Note

    The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes.

    Note

    This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

    Declaration

    Objective-C

    - (NSString *)GetStaticCaptionText;

    Swift

    func getStaticCaptionText() -> String!

    Return Value

    A string containing the static caption text of the annotation.

  • Sets static caption text of the annotation. (Optional; button fields only)

    Note

    The static caption is the annotation’s normal caption, which shall be displayed when it is not interacting with the user. Unlike the remaining entries with the captions, which apply only to widget annotations associated with pushbutton fields, the Static Caption(CA) entry may be used with any type of button field, including check boxes.

    Note

    This property is part of the Widget appearance characteristics dictionary, this dictionary that shall be used in constructing a dynamic appearance stream specifying the annotation’s visual presentation on the page.

    Declaration

    Objective-C

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

    Swift

    func setStaticCaptionText(_ contents: String!)

    Parameters

    contents

    A string containing the static caption text of the annotation.

  • Returns the rollover caption text of the annotation.

    Note

    The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

    Declaration

    Objective-C

    - (NSString *)GetRolloverCaptionText;

    Swift

    func getRolloverCaptionText() -> String!

    Return Value

    A string containing the rollover caption text of the annotation.

  • Sets the roll over caption text of the annotation. (Optional; button fields only)

    Note

    The rollover caption shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

    Declaration

    Objective-C

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

    Swift

    func setRolloverCaptionText(_ contents: String!)

    Parameters

    contents

    A string containing the roll over caption text of the annotation.

  • Returns the button down caption text of the annotation.

    Note

    The button down caption shall be displayed when the mouse button is pressed within its active area.

    Declaration

    Objective-C

    - (NSString *)GetMouseDownCaptionText;

    Swift

    func getMouseDownCaptionText() -> String!

    Return Value

    A string containing the button down text of the annotation.

  • Sets the button down caption text of the annotation. (Optional; button fields only)

    Note

    The button down caption shall be displayed when the mouse button is pressed within its active area.

    Declaration

    Objective-C

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

    Swift

    func setMouseDownCaptionText(_ contents: String!)

    Parameters

    contents

    A string containing the button down text of the annotation.

  • Returns the static icon associated with the annotation.

    Note

    The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

    Declaration

    Objective-C

    - (PTObj *)GetStaticIcon;

    Swift

    func getStaticIcon() -> PTObj!

    Return Value

    An SDF object that represents the static icon associated with the annotation.

  • Sets the static icon associated with the annotation. (Optional; button fields only)

    Note

    The static icon object is a form XObject defining the annotation’s normal icon, which shall be displayed when it is not interacting with the user.

    Declaration

    Objective-C

    - (void)SetStaticIcon:(PTObj *)icon;

    Swift

    func setStaticIcon(_ icon: PTObj!)

    Parameters

    icon

    An SDF object that represents the static icon associated with the annotation.

  • Returns the rollover icon associated with the annotation.

    Note

    The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

    Declaration

    Objective-C

    - (PTObj *)GetRolloverIcon;

    Swift

    func getRolloverIcon() -> PTObj!

    Return Value

    An SDF object that represents the rollover icon associated with the annotation.

  • Sets the rollover icon associated with the annotation. (Optional; button fields only)

    Note

    The rollover icon object is a form XObject defining the annotation’s rollover icon, which shall be displayed when the user rolls the cursor into its active area without pressing the mouse button.

    Declaration

    Objective-C

    - (void)SetRolloverIcon:(PTObj *)icon;

    Swift

    func setRolloverIcon(_ icon: PTObj!)

    Parameters

    icon

    An SDF object that represents the rollover icon associated with the annotation.

  • Returns the Mouse Down icon associated with the annotation.

    Note

    The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

    Declaration

    Objective-C

    - (PTObj *)GetMouseDownIcon;

    Swift

    func getMouseDownIcon() -> PTObj!

    Return Value

    An SDF object that represents the Mouse Down icon associated with the annotation.

  • Sets the Mouse Down icon associated with the annotation. (Optional; button fields only)

    Note

    The Mouse Down icon object is a form XObject defining the annotation’s alternate (down) icon, which shall be displayed when the mouse button is pressed within its active area.

    Declaration

    Objective-C

    - (void)SetMouseDownIcon:(PTObj *)icon;

    Swift

    func setMouseDownIcon(_ icon: PTObj!)

    Parameters

    icon

    An SDF object that represents the Mouse Down icon associated with the annotation.

  • Returns the Icon and caption relationship of the annotation.

    See

    IconCaptionRelation

    Declaration

    Objective-C

    - (PTWidgetIconCaptionRelation)GetIconCaptionRelation;

    Swift

    func getIconCaptionRelation() -> PTWidgetIconCaptionRelation

    Return Value

    A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

  • Sets the Icon and caption relationship of the annotation. (Optional; pushbutton fields only)

    See

    IconCaptionRelation

    Declaration

    Objective-C

    - (void)SetIconCaptionRelation:(PTWidgetIconCaptionRelation)icr;

    Swift

    func setIconCaptionRelation(_ icr: PTWidgetIconCaptionRelation)

    Parameters

    icr

    A value of the “IconCaptionRelation” enum type. Default value: e_NoIcon.

  • Returns the condition under which the icon should be scaled.

    See

    ScaleCondition

    Declaration

    Objective-C

    - (PTWidgetScaleCondition)GetScaleCondition;

    Swift

    func getScaleCondition() -> PTWidgetScaleCondition

    Return Value

    A value of the “ScaleCondition” enum type. Default value: e_Always.

  • Sets the condition under which the icon should be scaled. (Optional)

    Declaration

    Objective-C

    - (void)SetScaleCondition:(PTWidgetScaleCondition)sd;

    Swift

    func setScaleCondition(_ sd: PTWidgetScaleCondition)

    Parameters

    sd

    A value of the “ScaleCondition” enum type. Default value: e_Always.

  • Returns the Scale Type of the annotation.

    See

    ScaleType

    Declaration

    Objective-C

    - (PTWidgetScaleType)GetScaleType;

    Swift

    func getScaleType() -> PTWidgetScaleType

    Return Value

    A value of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

  • Sets the Scale Type of the annotation. (Optional)

    See

    ScaleType

    Declaration

    Objective-C

    - (void)SetScaleType:(PTWidgetScaleType)st;

    Swift

    func setScaleType(_ st: PTWidgetScaleType)

    Parameters

    st

    An entry of the “ScaleType” enum which represents the Scale Type of the annotation. Default value: P.

  • Returns the horizontal leftover space of the icon within the annotation.

    Note

    the horizontal leftover is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

    Declaration

    Objective-C

    - (double)GetHIconLeftOver;

    Swift

    func getHIconLeftOver() -> Double

    Return Value

    A number indicating the horizontal leftover space of the icon within the annotation.

  • Sets the horizontal leftover space of the icon within the annotation. (Optional)

    Note

    the horizontal leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the left. A value of 0.0 shall position the icon at the left of the annotation rectangle. A value of 0.5 shall center it in the horizontal direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

    Declaration

    Objective-C

    - (void)SetHIconLeftOver:(double)hl;

    Swift

    func setHIconLeftOver(_ hl: Double)

    Parameters

    hl

    A number indicating the horizontal leftover space of the icon within the annotation.

  • Returns the vertical leftover space of the icon within the annotation.

    Note

    the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

    Declaration

    Objective-C

    - (double)GetVIconLeftOver;

    Swift

    func getVIconLeftOver() -> Double

    Return Value

    a number indicating the vertical leftover space of the icon within the annotation.

  • Sets the vertical leftover space of the icon within the annotation. (Optional)

    Note

    the vertical leftover space is a number that shall be between 0.0 and 1.0 indicating the fraction of leftover space to allocate at the bottom of the icon. A value of 0.0 shall position the icon at the bottom of the annotation rectangle. A value of 0.5 shall center it in the vertical direction within the rectangle. This entry shall be used only if the icon is scaled proportionally. Default value: 0.5.

    Declaration

    Objective-C

    - (void)SetVIconLeftOver:(double)vl;

    Swift

    func setVIconLeftOver(_ vl: Double)

    Parameters

    vl

    A number indicating the vertical leftover space of the icon within the annotation.

  • Returns the “fit full” flag.

    Note

    the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

    Declaration

    Objective-C

    - (BOOL)GetFitFull;

    Swift

    func getFitFull() -> Bool

    Return Value

    A boolean value indicating the “fit full” flag value.

  • Sets the “fit full” flag. (Optional)

    Note

    the fit full flag, if true, indicates that the button appearance shall be scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. Default value: false.

    Declaration

    Objective-C

    - (void)SetFitFull:(BOOL)ff;

    Swift

    func setFitFull(_ ff: Bool)

    Parameters

    ff

    A boolean value indicating the “fit full” flag value.

  • Returns the text color of the Widget Annotation.

    Note

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

    Declaration

    Objective-C

    - (PTColorPt *)GetTextColor;

    Swift

    func getTextColor() -> PTColorPt!

    Return Value

    the text color.

  • Returns the number of color components in the text color of the Widget Annotation.

    Declaration

    Objective-C

    - (int)GetTextColorCompNum;

    Swift

    func getTextColorCompNum() -> Int32

    Return Value

    An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk” if color space is applicable.

  • Sets the text color of the Widget Annotation.

    Declaration

    Objective-C

    - (void)SetTextColor:(PTColorPt *)color col_comp:(int)col_comp;

    Swift

    func setTextColor(_ color: PTColorPt!, col_comp: Int32)

    Parameters

    color

    ColorPt object representing the color.
    col_comp

    An integer indicating a color space value from the ColorSpace::Type enum. That is, 1 corresponding to “e_device_gray”, 3 corresponding to “e_device_rgb”, and 4 corresponding to “e_device_cmyk”.

  • Returns the font size used in this Widget Annotation.

    Note

    A font size of 0 specifies that the text should be autosized to fit in the Widget.

    Declaration

    Objective-C

    - (double)GetFontSize;

    Swift

    func getFontSize() -> Double

    Return Value

    the font size

  • Sets the font size of the Widget Annotation.

    Note

    A font size of 0 specifies that the text should be autosized to fit in the Widget.

    Declaration

    Objective-C

    - (void)SetFontSize:(double)font_size;

    Swift

    func setFontSize(_ font_size: Double)

    Parameters

    font_size

    the new font size

  • Retrieves the font used for displaying text in this Widget.

    Declaration

    Objective-C

    - (PTFont *)GetFont;

    Swift

    func getFont() -> PTFont!

    Return Value

    the font used by this Widget.

  • Specifies a font to be used for text in this Widget.

    Declaration

    Objective-C

    - (void)SetFont:(PTFont *)font;

    Swift

    func setFont(_ font: PTFont!)

    Parameters

    font

    the font to use.