How to determine “Checked” value for Checkboxes (from GetAppearanceStates)

Question

I have a question about checkbox fields, and consistently figuring out which value to use for a checked state.

I have been searching, and shelled out $50 for the iText in Action book and scoured it as well. The book is great, but it didn’t answer this particular question.

I know to call GetAppearanceStates(fieldName) to get the domain of possible values for a particular field, and know to call SetField(fieldName, value) to check the box.

My question is: how do I definitively know WHICH of the values returned by GetAppearanceStates is the “Check” value, or the value I need to use to check the field?

To be fair, most forms I've seen use values like: True,False,On,Off,Yes,No... but if I understand things correctly, the creator of the PDF can specify any arbitrary value.

Is there a way to find out, for sure, WHICH of the values returned by GetAppearanceStates is the "check" value?

The examples I saw seemed to indicate the first element in the array would be the one to check it, but apparently that was just me reading too much into the example, because I’ve run into a document where the first element is “Off” (and the second is “Yes”). Before I dive in and write code that explicitly looks for string values like True,Yes,On,Oui,Yuppers,Check… or whatever, I thought I’d see if there is a better way! I really hope I’m missing something.

Again, I'm working only with checkbox fields here.

Thanks for any help at all!

Answer 1

ISO 32000-1:2008 ("PDF 1.7 spec") says in 12.7.4.2.3 ("Check Boxes"):

The appearance for the off state is optional but, if present, shall be stored in the appearance dictionary under the name Off. Yes should be used as the name for the on state.

So if there's an appearance for the unchecked state, it has to be Off. The Yes for the checked state is a recommendation; it can be named differently.

If 2 arbitrary names are used for checked and unchecked, you can't reliably determine which should be used for checked and which for unchecked.