- iOS 11.0+
- Xcode 9.3+
The PDF file format allows for annotations to be associated with a page and a location on that page. One powerful annotation type is the widget, which represents interactive form elements. PDFKit supports three widget types: text, button, and choice widgets. Text widgets are basic text fields. Button widgets consist of three subtypes: radio buttons, checkboxes, and push buttons. Choice widgets consist of two subtypes: list (a table view) and combo box (a drop-down). This sample includes text and button widgets.
Create Widget Annotations
All widget annotations are instantiated using the
PDFAnnotation constructor with subtype
widget. To inform PDFKit which type of interactive element to add to the document, the
widget property is set for each widget:
Set Widget Control Types
Similarly, when creating a button widget annotation, the
widget property is set to inform PDFKit which type of button to add:
Choose Widget Control Properties
Toggles for the two kinds of choice widgets are set using the
is property (list is the default):
Add Widgets to the PDF Page
View first loads a URL to the
My file through the app’s main bundle. This URL is then used to instantiate a
PDFDocument. On success, the document is assigned to the
PDFView that was set up in Interface Builder. Once the document has been successfully loaded, The first page can be extracted so that widget annotations can be added.
View adds the following widgets to the extracted
PDFPage: three text fields, two radio buttons, three checkboxes, and one push button.
In addition to basic widget creation,
View includes a few extra widget-specific properties:
Text widget properties. The
text text widget annotation sets two extra properties:
maximum property sets the maximum number of characters a user can enter into the text field. The
has property, if set, divides the text field into as many equally spaced positions, or combs, as the value of the maximum length of the field. The
has property only works in conjunction with the
text text widget annotation sets one extra property:
is. By default, all text widget annotations are single line, meaning they don’t include word wrapping. If you want to create a large, multiline text widget with word wrapping, set this property to
Radio widget properties. The
radio button widget annotations set two extra properties:
button. All widgets have their own unique identifier, which is determined by the
field property. To group widgets—in this case the radio buttons—the buttons must have the same field name, which is set in
View. To give radio buttons of the same field name their own unique subidentifier, the
button property must be set on each, which is also done in
View. When the radio buttons are grouped by field name, and each has its own unique
button, they behave like normal radio buttons (where selecting one deselects others in the group).
Button widget properties. The
reset button widget annotation sets one extra property:
PDFAction. With this property set, the given action is performed when the user clicks (or taps) this button. The
PDFAction action is special in that it clears all widgets associated with it.
PDFAction takes an array of strings that represent widget field names. The default behavior is to clear all fields included in that array. This behavior can be changed to clear all widgets not included in the array, by setting the
fields property to false. Because the behavior to clear all widgets isn’t included in the list, and no field names were set, this action clears all widgets in the document.