In the scope of the 8.0.0 release we've introduced several major breaking changes in the
forms module of the
List of breaking changes:
Form fields with the same fully qualified names are now merged with each other.
If these fields have a different field type, value or default value, a log will be displayed (in the reading mode or when reading the document) or an exception will be thrown (in cases when the user tries to add a field with the same name as an already existing one, but different
/DVvalues). Merge occurs when an acroform is created, when children are added to a field, when field is renamed, or when fields are added to an acroform.
PdfAcroForm.addField(PdfFormField, PdfPage, boolean)can be used to not throw an exception while adding a new field.
setValuemethod sets the value not only to the field
setValueis called on, but also to its siblings (children of the parent field) if they have the same fully qualified name. Such fields may present when it was not possible to merge them, or, for example, during acroform reading.
If there are 2 fields in the hierarchy of fields – a parent without /T entry and a child, and the child has all the values in its dictionary (except for
/Kids) that match the parent values, and child
/Kidscontain only annotations (no form fields), then this child will be merged with the parent, that is, the
/Kidsof the child will become the
/Kidsof the parent. This makes the document structure cleaner (field annotations become pure widgets). Parent should not have /T entry because we only want to perform such a merge if the field doesn't contain any name (even an empty one).
For radio groups, all of its child form fields are merged with it, since radio group should contain only annotation children according to the specification. This means that we force radio buttons to be pure widgets in order to match the PDF specification.
For fields with multiple widgets, all annotations are added to the page (previously only fields with one widget were supported).
PdfFormField.setValuedoesn't set the value to the child form fields any longer.
PdfAcroForm.replaceField– fields now get replaced in their parents, where previously they just would have been added to the main form dictionary.
Fields (including merged fields) that do not have
/Tkey are considered fields named
PdfFormFieldlogic to be able to add fields without partial name. In general we leave the field without changes and treat it's name as an empty string. This name is handled as any other name, since an empty string is still a string (e.g. fields merging, search, remove, etc...). Full name for field's children looks like
rootFieldName.parentFieldName.childNameIn this particular case parentFieldName will be an empty string. This behavior violates the PDF 2.0 specification, but it is valid for PDF 1.7.
Moved radio button, push button, checkbox, text field drawing logic from forms to renderers.
This led to some changes in the fields appearance, and now flattened and interactive fields are drawn in almost the same way.
Also fixed a bug related to fields stream data: it was written to the content stream of the page before, but now it is in the field normal appearance which is used for drawing the annotation.
Creating fields using model element became much more convenient. Currently we have two main ways to create form field in the acroform structure:
First one is the old one: through the usage of
Second one is much less complicated and easy for users. One needs to simply create a layout element related to form fields and add it to the
Documentobject like we usually do for other layout elements (such as
Div, etc...). After that, the form field will be automatically placed on the page and related elements will be added to the acroform if iterative mode is enabled. This is not yet supported for choice form fields.
Text form field drawing logic was moved to
Text drawing was moved to the related layout elements.
Text approximation is improved.
Border drawing bug with border being 2 times smaller was fixed.
Text no longer overlaps the border.
Some new classes were added for checkboxes drawing:
Model element can be passed to
public PdfFormAnnotation setFormFieldElement(IFormField element). Note that annotation properties will take precedence, so such properties cannot be overridden by using this method (e.g. background, text color, etc.), but it can be useful to take into account when drawing those properties that the annotation does not have (e.g. paddings). Also note that the model element won't be used for annotations for choice form fields.
Each model element is responsible for one annotation. We can add them to the document using
Document.addmethod. Elements with the same id will be responsible for the annotations of the field with the name equal to id. Note that fields with the same fully qualified field name shall have the same field type, value, and default value to merge it without problems.
Re-adding the same model element two or more times can lead to an undefined behavior since model element properties is changed in
Created builder classes for every different
Use builders instead of old creator methods and set appropriate properties, e.g. instead of
A few convenience getters were added into
Generating appearance was moved from
If you used to override some drawing methods in PdfFormField, from now on you have to subclass PdfFormAnnotation and override the corresponding drawing methods.
Model element classes and corresponding renderers were moved from
Changed radio buttons creation logic to make them pure widgets instead of form fields: radio buttons changed from a
For radio buttons use
More user friendly enums are introduced/used for check box types and fields justification.
Moved radio button, push button, checkbox, text field drawing logic from forms to renderers (
Drawing logic related to comb property and choice fields was moved to the new