PSPDFButtonFormField

Objective-C


@interface PSPDFButtonFormField : PSPDFFormField

Swift

class ButtonFormField : PDFFormField

Represents one button form field in a PDF form. They come in three variants:

  • A push button that can have a action attached to it.
  • A check box that can be independently checked or unchecked.
  • A radio button that are mutually exclusive.

A PSPDFButtonFormField can be the parent of multiple buttons, like a RadioButton group.

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Inserts a new PSPDFButtonFormField into the document.

    Note

    This new form field will automatically be added to the document.

    Note

    PSPDFFormFieldTypePushButton only supports one form element.

    Declaration

    Objective-C

    + (nullable instancetype)
    insertedButtonFieldWithType:(PSPDFFormFieldType)type
             fullyQualifiedName:(nonnull NSString *)fullyQualifiedName
               documentProvider:
                   (nonnull PSPDFDocumentProvider *)documentProvider
                   formElements:(nonnull NSArray<__kindof PSPDFFormElement *> *)
                                    formElements
                   buttonValues:(nonnull NSArray<NSString *> *)buttonValues
                          error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func insertedButtonField(with type: PDFFormField.Kind, fullyQualifiedName: String, documentProvider: PSPDFDocumentProvider, formElements: [PSPDFFormElement], buttonValues: [String]) throws -> Self

    Parameters

    type

    The type of the PSPDFButtonFormField. Can be PSPDFFormFieldTypePushButton, PSPDFFormFieldTypeRadioButton or PSPDFFormFieldTypeCheckBox.
    fullyQualifiedName

    Each form field is identifiable using its fully qualified name. You can specify any dot separated name.
    documentProvider

    The document the form field gets inserted in.
    formElements

    One or more PSPDFButtonFormElement that will be linked to this form field. The form elements are the visual representation of the form on the page. If the form elements aren’t yet added to the document provider, they will be added.
    buttonValues

    When creating radio buttons or checkboxes, you have to supply their on-state value. For each form element passed in, you have to supply one string value in the array. The value cannot be Off.
    error

    The error, if any happens.

    Return Value

    Either an instance of PSPDFButtonFormField or nil if an error occurs.

  • A push button is a purely interactive control that responds immediately to user input without retaining a permanent value (see 12.7.4.2.2, “Pushbuttons”).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPushButton;

    Swift

    var isPushButton: Bool { get }

  • A check box toggles between two states, on and off (see 12.7.4.2.3, “Check Boxes”).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isCheckBox;

    Swift

    var isCheckBox: Bool { get }

  • Radio button fields contain a set of related buttons that can each be on or off. Typically, at most one radio button in a set may be on at any given time, and selecting any one of the buttons automatically deselects all the others. (There are exceptions to this rule, as noted in “Radio Buttons.”)

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isRadioButton;

    Swift

    var isRadioButton: Bool { get }

  • A set of selected annotation object numbers.

    Declaration

    Objective-C

    @property (nonatomic) NSArray<NSNumber *> *_Nonnull selectedAnnotationObjectNumbers;

    Swift

    var selectedAnnotationObjectNumbers: [NSNumber] { get set }

  • (Optional) An array of options that shall be presented to the user.

    Declaration

    Objective-C

    @property (nonatomic, copy) NSArray<PSPDFFormOption *> *_Nonnull options;

    Swift

    var options: [PSPDFFormOption] { get set }

  • The appearance state to be used in the ‘on’ position. This will be a key in the dictionary of appearance streams for the different states. The off state is always “Off”.

    Note

    If the Key is in Non-ASCII format, this will convert it to be in UTF-8. If a key has been converted from another format (e.g. ISO9959-1) then you cannot use this value to set the state.

    Declaration

    Objective-C

    - (nullable NSString *)onStateForButton:
    (nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func onState(forButton annotation: PSPDFWidgetAnnotation) -> String?

  • Toggles the button state.

    Declaration

    Objective-C

    - (void)toggleButton:(nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func toggleButton(_ annotation: PSPDFWidgetAnnotation)

    Parameters

    annotation

    The annotation representing the button.

  • Checks if the given annotation is selected.

    Declaration

    Objective-C

    - (BOOL)isSelected:(nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func isSelected(_ annotation: PSPDFWidgetAnnotation) -> Bool

    Parameters

    annotation

    The annotation representing the button.

    Return Value

    YES if selected, NO otherwise.

  • Selects the button.

    Declaration

    Objective-C

    - (void)selectButton:(nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func selectButton(_ annotation: PSPDFWidgetAnnotation)

    Parameters

    annotation

    The annotation representing the button.

  • Deselects the button.

    Declaration

    Objective-C

    - (void)deselectButton:(nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func deselectButton(_ annotation: PSPDFWidgetAnnotation)

    Parameters

    annotation

    The annotation representing the button.

  • Gets the value of the button.

    Note

    If the Key is in Non-ASCII format, this will convert it to be in UTF-8. If a key has been converted from another format (e.g. ISO9959-1) then you cannot use this value to set the state.

    Declaration

    Objective-C

    - (nullable NSString *)valueForButton:
    (nonnull PSPDFWidgetAnnotation *)annotation;

    Swift

    func value(forButton annotation: PSPDFWidgetAnnotation) -> String?

    Parameters

    annotation

    The annotation representing the button.