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 A pü‰Ã @Ó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 x uè1 ¬@ Ö˜˛ä7∂√]ì´◊Î≠ ¡A 8à”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.

The Problem In the Preview app in macOS (or the Files app in iOS and iPadOS), when a user selects a radio button to "On", the radio button appears to behave as expected (with related radio buttons, sharing the same parent form field, appearing to turn "Off"). Also, as expected, the app indicates that the user has edited the PDF and, as such, is able to save and close the file as normal. On re-opening the file, the radio buttons seem to have been reset and user input lost. What is Happening Related radio button annotation widgets share the same parent form field. In the PDF 1.7 specification (ISO PDF32000-2008, s. 12.7.4.2.4), the parent form field object holds the field name property (T), the name object of the appearance state of the kid object currently selected (V), as well as an array of the references to the related radio button kid objects (Kids). Each kid object holds a reference to the parent object (Parent). When the user selects a radio button to be on, the V property is updated in the parent object accordingly. On saving the PDF, an incremental update to the file is made with an updated copy of the kid object, corresponding to the selected radio box, created. The kid object created for the updated radio box, however, is updated incorrectly with the Parent object reference removed and the properties that ought to reside with the parent object (for V, T, and FT), instead, incorrectly written/merged into the kid object itself. The original parent object (belonging to the shared field form) is not updated with the incremental update in any way. Impact on User Experience Radio buttons are not functional, with user-input not properly saved. As such, using Preview to complete a PDF form with radio buttons is not possible. On re-opening the PDF, user input to the state of radio buttons appear not to have been saved. Affected Apps/OSs: Preview (macOS 12 and above) and Files (iOS 16 and iPadOS 16) Related Sample of Code Radio button annotation widget object (11 0 obj) and form field parent object (16 0 obj) in original PDF file: 11 0 obj << /Border [ 0 0 0 ] /Rect [ 433 405 453 425 ] /F 4 /BS 13 0 R /Subtype /Widget /DA (/Helvetica 13 Tf 0 g) /MK 14 0 R /C [ 0 ] /AP 15 0 R /M (D:20230803164805Z00'00') /AS /Off /Parent 16 0 R /Type /Annot /Ff 32768 >> endobj 16 0 obj << /V / /Kids [ 10 0 R 11 0 R ] /T (button2) /FT /Btn >> endobj 15 0 obj << /N 17 0 R >> endobj 17 0 obj << /Ted 18 0 R /Off 20 0 R >> endobj Copy of object (11 0 obj) created with incremental update of PDF, included in saved file following user selection: 11 0 obj << /C [ 0 ] /FT /Btn /F 4 /BS << /W 0 >> /Subtype /Widget /DA (//Helvetica 13 Tf 0 g) /Type /Annot /Border [ 0 0 0 ] /M (D:20230803164805Z00'00') /Rect [ 433 405 453 425 ] /MK << /BG [ 0.75 ] >> /AP << /N << /Off 53 0 R /Ted 57 0 R >> >> /T (button2) /AS /Ted /Ff 32768 /V /Ted >> endobj A bug report, describing as much, was submitted to Apple (FB9978281).