Package com.ironsoftware.ironpdf.form

Class FormManager

    • Constructor Detail

      • FormManager

        public FormManager​(com.ironsoftware.ironpdf.internal.staticapi.InternalPdfDocument internalPdfDocument)
        Please get FormManager by PdfDocument.getForm() instead.
        Parameters:
        internalPdfDocument - the internal pdf document

    • Method Detail

      • flatten

        public final void flatten()
        Flattens a document (make all form fields non-editable).

      • flatten

        public final void flatten​(PageSelection pageSelection)
        Flattens a document (make all form fields non-editable).
        Parameters:
        pageSelection - Selected page indexes. Default is all pages.

      • getFields

        public FormFieldsSet getFields()
        Get a collection of the user-editable form fields within a PDF document
        Returns:
        FormFieldsSet

      • renameField

        public String renameField​(String currentFieldName,
                          String newFieldName)
        Rename a FormField
        Parameters:
        currentFieldName - Current fully qualified field name
        newFieldName - New partial field name Please use a fully qualified field name for CurrentFieldName, and a partial field name for NewFieldName
        Returns:
        New fully-qualified field name

      • setFieldValue

        public void setFieldValue​(String fieldName,
                          String value)
        Set the string value of a FormField
        Parameters:
        fieldName - Fully qualified field name
        value - New value

      • setFieldReadOnly

        public void setFieldReadOnly​(String fieldName,
                             boolean value)
        Set the is read only value of a FormField
        Parameters:
        fieldName - Fully qualified field name
        value - is read only

      • setTextFieldFont

        public void setTextFieldFont​(String textFieldName,
                             FontTypes font,
                             int fontSize)
        Deprecated.
        This method is deprecated and no longer has any effect. Set the font of a TextField
        Parameters:
        textFieldName - Fully qualified field name
        font - New font
        fontSize - New font size

      • setFormFont

        public void setFormFont​(String fontName,
                        byte[] fontData,
                        boolean forceEmbed)
        Sets the document-wide font for all subsequent form-field fills on this document.

        The engine only auto-embeds the Tahoma/Arial fallback when a form value containing non-ASCII characters is set. Every other field update (renaming, toggling read-only, etc.) leaves fonts untouched, so this method is only useful when at least one of your fills contains non-ASCII characters.

        If your form fields reference more than one font variant (e.g. Poppins-Regular and Poppins-Bold), call this method once per variant.

        File-size impact

        • Name-only mode (fontData is null/empty): zero bytes added; the font must already be in the document.
        • Bytes mode and the font is already embedded with usable glyph data: zero bytes added.
        • Bytes mode and the font is missing or has no glyph data: the full font is embedded.
        • Bytes mode with forceEmbed = true: a fresh font copy is added alongside any existing copy; the document grows by the size of the new font on every call. Use sparingly.
        Parameters:
        fontName - PDF font name to register (e.g. "Poppins-Regular"). Allowed characters: letters, digits, '-', '_', '.', '+'.
        fontData - Raw TrueType/OpenType bytes; pass null or empty for name-only mode (the font must already be in the document).
        forceEmbed - When true, embed fontData even if a font with the same name and usable glyph data is already present. Has no effect in name-only mode.
        Throws:
        IllegalArgumentException - when fontName or fontData fails validation

      • setFormFont

        public void setFormFont​(String fontName,
                        byte[] fontData)
        Sets the document-wide form font without forcing a re-embed. Equivalent to setFormFont(fontName, fontData, false).
        Parameters:
        fontName - PDF font name to register
        fontData - Raw font bytes, or null/empty for name-only mode
        Throws:
        IllegalArgumentException - when fontName or fontData fails validation

      • setFormFont

        public void setFormFont​(String fontName)
        Sets the document-wide form font by name only. The font must already be in the document (e.g. embedded by the template, or added via a previous call with bytes).
        Parameters:
        fontName - PDF font name as it appears in the document
        Throws:
        IllegalArgumentException - when fontName fails validation

      • setFormFontFromFile

        public void setFormFontFromFile​(Path fontFilePath)
                         throws IOException
        Loads a TrueType/OpenType font from disk and applies it as the document-wide form font. The PDF font name is derived from the file name (without extension).
        Parameters:
        fontFilePath - Path to a TTF/OTF/TTC font file
        Throws:
        IOException - when the font file cannot be read
        IllegalArgumentException - when the file or derived font name fails validation

      • setFormFontFromFile

        public void setFormFontFromFile​(Path fontFilePath,
                                String fontName,
                                boolean forceEmbed)
                         throws IOException
        Loads a TrueType/OpenType font from disk and applies it as the document-wide form font.
        Parameters:
        fontFilePath - Path to a TTF/OTF/TTC font file
        fontName - Optional PDF font name to register the font under. When null, the file name without extension is used.
        forceEmbed - When true, embed even if the font is already present.
        Throws:
        IOException - when the font file cannot be read
        IllegalArgumentException - when the file or derived font name fails validation

      • disableFormFontFallback

        public void disableFormFontFallback()
        Suppresses the automatic Tahoma/Arial fallback embed for non-ASCII form values without registering any replacement font. Use when zero file-size growth is required and the template's existing font references are sufficient for the values being filled.

        Rendering of non-ASCII characters then depends entirely on the viewer's font substitution — best for ASCII or Latin-Extended fills where the template already references suitable fonts. For broader character ranges, use setFormFont(String, byte[], boolean) instead.