The Problem
Push buttons (created as a PDFAnnotation using PDFKit) do not properly write the associated caption's key-value pair (within the annotation's appearance characteristics dictionary) to a PDF document.
What is Happening
Push button widget annotations can have a caption that is displayed as the button’s label.
In the PDF 1.7 specification (ISO PDF32000-2008, s. 12.5.6.19), a widget annotation can have an ‘appearance characteristics dictionary’ (MK) with properties to construct the appearance of the widget. The caption property (CA) is used to construct a button’s caption/label.
PDFKit uses the PDFAnnotation .caption property to set the value of a push button’s caption as a string.
Observation 1:
In an open PDF document (using PDFView), a push button widget annotation can be created and added to a PDFPage using the following code:
let pushButton = PDFAnnotation(bounds: pushButtonBounds, forType: .widget, withProperties: nil) pushButton.widgetFieldType = .button pushButton.widgetControlType = .pushButtonControl pushButton.caption = "My Button" page.addAnnotation(pushButton)
The PDFAnnotation .caption property is used to set the caption to the required string. As a result, the push button is correctly displayed on the PDFPage with the correct label being display on the button.
While the PDF document remains open, the appearance characteristics dictionary (an PDFAppearanceCharacteristics object) retains a key-value pair for the caption with the correct value as expected.
On saving/writing to the PDF file, however, the key-value pair for the caption in the appearance characteristics dictionary is not written to the PDF document’s file.
Resulting PDF markup:
6 0 obj << /Rect [ 256 299.8977 356 399.8977 ] /Border [ 0 0 0 ] /T (button23) /F 4 /Subtype /Widget /DA (/.AppleSystemUIFont 13 Tf 0 g) /MK 8 0 R /C [ 0 ] /AP 9 0 R /V /Off /M (D:20250330154918Z00'00') /FT /Btn /Type /Annot /Ff 65536 >> endobj 9 0 obj << /N 10 0 R >> endobj 8 0 obj << /BG [ 0.75 ] >> endobj 10 0 obj << /Filter /FlateDecode /Type /XObject /Subtype /Form /FormType 1 /BBox [0 0 100 100] /Resources 11 0 R /Length 170 >> stream x}ê1Ç0Öw~≈ahÈKÈ q1q0\‚`úŸ¿ 8¯Ôm%u0óª‰.Ô{yπåP°H-}ª‡ày3¸%≠¡‰%›g¨$•µMVXø‡Hé†Ö”î“¿˜®BI•Lˆ†b Apü‰Ã@ÓpB∫†æœsãÙ:d8Éwÿr»/}”€∂I÷BõB;'+gmÔ˝„mÙ~L*>• endstream endobj
On closing the PDF document, the assigned value for the push button’s caption is not written to the file and is lost.
Observation 2:
On reopening the PDF document, and assigning a new value for the already-created push button’s caption, a key-value pair for the caption is again correctly added to the PDFAnnotation appearance characteristics dictionary.
On saving/writing to the PDF file, this time, the caption key-value pair in the appearance characteristics dictionary is correctly written/saved to the PDF document file.
Resulting PDF markup:
6 0 obj << /Border [ 0 0 0 ] /Rect [ 256 299.8977 356 399.8977 ] /T (button23) /F 4 /BS 8 0 R /Subtype /Widget /DA (/.AppleSystemUIFont 13 Tf 0 g) /MK 9 0 R /C [ 0 ] /AP 10 0 R /V /Off /M (D:20250330154918Z00'00') /FT /Btn /Type /Annot /Ff 65536 >> endobj 10 0 obj << /N 11 0 R >> endobj 9 0 obj << /BG [ 0.75 ] /CA (My Button) >> endobj 8 0 obj << /W 0 >> endobj 11 0 obj << /Filter /FlateDecode /Type /XObject /Subtype /Form /FormType 1 /BBox [0 0 100 100] /Resources 12 0 R /Length 163 >> stream xuè1¬@Ö˜˛ä7∂√]ì´◊Î≠¡A8à”a∑Vj·ø˜jë™ !ÅÑ|y/=ˆËA1òʺ]pDá|=0¬“Œbø+Õgùf2E≤∞Ê≈N`û·Xm©-BãZ†HŸ ¿≈ºPÄ=Ø míãp•¡ ÈÓÅ˙>é“kó·Ÿb#—¬Ûã¶2∂Ñ2fiÎ ;óDÌiÓ?ü>LÁûÊy;} endstream endobj
Impact on User Experience:
Push button captions may not be properly saved to the PDF document’s file. This may result in an application redrawing a push button without a caption/label. More so, an application that uses the caption value to “read” a button’s label (e.g., for accessibility purposes) will not be able to do so.
