@pdfme/pdf-lib 5.5.9 → 5.5.10-dev.125

package/dist/types/src/api/form/PDFDropdown.d.ts

@@ -1,402 +0,0 @@
-import PDFDocument from '../PDFDocument';
-import PDFPage from '../PDFPage';
-import PDFFont from '../PDFFont';
-import PDFField, { FieldAppearanceOptions } from './PDFField';
-import { AppearanceProviderFor } from './appearances';
-import { PDFRef, PDFAcroComboBox } from '../../core';
-/**
- * Represents a dropdown field of a [[PDFForm]].
- *
- * [[PDFDropdown]] fields are interactive text boxes that display a single
- * element (the currently selected value). The purpose of a dropdown is to
- * enable users to select a single option from a set of possible options. Users
- * can click on a dropdown to view the full list of options it provides.
- * Clicking on an option in the list will cause it to be selected and displayed
- * in the dropdown's text box. Some dropdowns allow users to enter text
- * directly into the box from their keyboard, rather than only being allowed to
- * choose an option from the list (see [[PDFDropdown.isEditable]]).
- */
-export default class PDFDropdown extends PDFField {
-    /**
-     * > **NOTE:** You probably don't want to call this method directly. Instead,
-     * > consider using the [[PDFForm.getDropdown]] method, which will create an
-     * > instance of [[PDFDropdown]] for you.
-     *
-     * Create an instance of [[PDFDropdown]] from an existing acroComboBox and ref
-     *
-     * @param acroComboBox The underlying `PDFAcroComboBox` for this dropdown.
-     * @param ref The unique reference for this dropdown.
-     * @param doc The document to which this dropdown will belong.
-     */
-    static of: (acroComboBox: PDFAcroComboBox, ref: PDFRef, doc: PDFDocument) => PDFDropdown;
-    /** The low-level PDFAcroComboBox wrapped by this dropdown. */
-    readonly acroField: PDFAcroComboBox;
-    private constructor();
-    /**
-     * Get the list of available options for this dropdown. These options will be
-     * displayed to users who click on this dropdown in a PDF reader.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * const options = dropdown.getOptions()
-     * console.log('Dropdown options:', options)
-     * ```
-     * @returns The options for this dropdown.
-     */
-    getOptions(): string[];
-    /**
-     * Get the selected options for this dropdown. These are the values that were
-     * selected by a human user via a PDF reader, or programatically via
-     * software.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * const selections = dropdown.getSelected()
-     * console.log('Dropdown selections:', selections)
-     * ```
-     * > **NOTE:** Note that PDF readers only display one selected option when
-     * > rendering dropdowns. However, the PDF specification does allow for
-     * > multiple values to be selected in a dropdown. As such, the `pdf-lib`
-     * > API supports this. However, in most cases the array returned by this
-     * > method will contain only a single element (or no elements).
-     * @returns The selected options in this dropdown.
-     */
-    getSelected(): string[];
-    /**
-     * Set the list of options that are available for this dropdown. These are
-     * the values that will be available for users to select when they view this
-     * dropdown in a PDF reader. Note that preexisting options for this dropdown
-     * will be removed. Only the values passed as `options` will be available to
-     * select.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('planets.dropdown')
-     * dropdown.setOptions(['Earth', 'Mars', 'Pluto', 'Venus'])
-     * ```
-     * @param options The options that should be available in this dropdown.
-     */
-    setOptions(options: string[]): void;
-    /**
-     * Add to the list of options that are available for this dropdown. Users
-     * will be able to select these values in a PDF reader. In addition to the
-     * values passed as `options`, any preexisting options for this dropdown will
-     * still be available for users to select.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('rockets.dropdown')
-     * dropdown.addOptions(['Saturn IV', 'Falcon Heavy'])
-     * ```
-     * @param options New options that should be available in this dropdown.
-     */
-    addOptions(options: string | string[]): void;
-    /**
-     * Select one or more values for this dropdown. This operation is analogous
-     * to a human user opening the dropdown in a PDF reader and clicking on a
-     * value to select it. This method will update the underlying state of the
-     * dropdown to indicate which values have been selected. PDF libraries and
-     * readers will be able to extract these values from the saved document and
-     * determine which values were selected.
-     *
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('best.superhero.dropdown')
-     * dropdown.select('One Punch Man')
-     * ```
-     *
-     * This method will mark this dropdown as dirty, causing its appearance
-     * streams to be updated when either [[PDFDocument.save]] or
-     * [[PDFForm.updateFieldAppearances]] is called. The updated streams will
-     * display the selected option inside the widgets of this dropdown.
-     *
-     * **IMPORTANT:** The default font used to update appearance streams is
-     * [[StandardFonts.Helvetica]]. Note that this is a WinAnsi font. This means
-     * that encoding errors will be thrown if the selected option for this field
-     * contains characters outside the WinAnsi character set (the latin alphabet).
-     *
-     * Embedding a custom font and passing it to
-     * [[PDFForm.updateFieldAppearances]] or [[PDFDropdown.updateAppearances]]
-     * allows you to generate appearance streams with characters outside the
-     * latin alphabet (assuming the custom font supports them).
-     *
-     * Selecting an option that does not exist in this dropdown's option list
-     * (see [[PDFDropdown.getOptions]]) will enable editing on this dropdown
-     * (see [[PDFDropdown.enableEditing]]).
-     *
-     * > **NOTE:** PDF readers only display one selected option when rendering
-     * > dropdowns. However, the PDF specification does allow for multiple values
-     * > to be selected in a dropdown. As such, the `pdf-lib` API supports this.
-     * > However, it is not recommended to select more than one value with this
-     * > method, as only one will be visible. [[PDFOptionList]] fields are better
-     * > suited for displaying multiple selected values.
-     *
-     * @param options The options to be selected.
-     * @param merge Whether or not existing selections should be preserved.
-     */
-    select(options: string | string[], merge?: boolean): void;
-    /**
-     * Clear all selected values for this dropdown. This operation is equivalent
-     * to selecting an empty list. This method will update the underlying state
-     * of the dropdown to indicate that no values have been selected.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.clear()
-     * ```
-     * This method will mark this text field as dirty. See [[PDFDropdown.select]]
-     * for more details about what this means.
-     */
-    clear(): void;
-    /**
-     * Set the font size for this field. Larger font sizes will result in larger
-     * text being displayed when PDF readers render this dropdown. Font sizes may
-     * be integer or floating point numbers. Supplying a negative font size will
-     * cause this method to throw an error.
-     *
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.setFontSize(4)
-     * dropdown.setFontSize(15.7)
-     * ```
-     *
-     * > This method depends upon the existence of a default appearance
-     * > (`/DA`) string. If this field does not have a default appearance string,
-     * > or that string does not contain a font size (via the `Tf` operator),
-     * > then this method will throw an error.
-     *
-     * @param fontSize The font size to be used when rendering text in this field.
-     */
-    setFontSize(fontSize: number): void;
-    /**
-     * Returns `true` if users are allowed to edit the selected value of this
-     * dropdown directly and are not constrained by the list of available
-     * options. See [[PDFDropdown.enableEditing]] and
-     * [[PDFDropdown.disableEditing]]. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.isEditable()) console.log('Editing is enabled')
-     * ```
-     * @returns Whether or not this dropdown is editable.
-     */
-    isEditable(): boolean;
-    /**
-     * Allow users to edit the selected value of this dropdown in PDF readers
-     * with their keyboard. This means that the selected value of this dropdown
-     * will not be constrained by the list of available options. However, if this
-     * dropdown has any available options, users will still be allowed to select
-     * from that list.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.enableEditing()
-     * ```
-     */
-    enableEditing(): void;
-    /**
-     * Do not allow users to edit the selected value of this dropdown in PDF
-     * readers with their keyboard. This will constrain the selected value of
-     * this dropdown to the list of available options. Users will only be able
-     * to select an option from that list.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.disableEditing()
-     * ```
-     */
-    disableEditing(): void;
-    /**
-     * Returns `true` if the option list of this dropdown is always displayed
-     * in alphabetical order, irrespective of the order in which the options
-     * were added to the dropdown. See [[PDFDropdown.enableSorting]] and
-     * [[PDFDropdown.disableSorting]]. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.isSorted()) console.log('Sorting is enabled')
-     * ```
-     * @returns Whether or not this dropdown's options are sorted.
-     */
-    isSorted(): boolean;
-    /**
-     * Always display the option list of this dropdown in alphabetical order,
-     * irrespective of the order in which the options were added to this dropdown.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.enableSorting()
-     * ```
-     */
-    enableSorting(): void;
-    /**
-     * Do not always display the option list of this dropdown in alphabetical
-     * order. Instead, display the options in whichever order they were added
-     * to the list. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.disableSorting()
-     * ```
-     */
-    disableSorting(): void;
-    /**
-     * Returns `true` if multiple options can be selected from this dropdown's
-     * option list. See [[PDFDropdown.enableMultiselect]] and
-     * [[PDFDropdown.disableMultiselect]]. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.isMultiselect()) console.log('Multiselect is enabled')
-     * ```
-     * @returns Whether or not multiple options can be selected.
-     */
-    isMultiselect(): boolean;
-    /**
-     * Allow users to select more than one option from this dropdown's option
-     * list. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.enableMultiselect()
-     * ```
-     */
-    enableMultiselect(): void;
-    /**
-     * Do not allow users to select more than one option from this dropdown's
-     * option list. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.disableMultiselect()
-     * ```
-     */
-    disableMultiselect(): void;
-    /**
-     * Returns `true` if the selected option should be spell checked by PDF
-     * readers. Spell checking will only be performed if this dropdown allows
-     * editing (see [[PDFDropdown.isEditable]]). See
-     * [[PDFDropdown.enableSpellChecking]] and
-     * [[PDFDropdown.disableSpellChecking]]. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.isSpellChecked()) console.log('Spell checking is enabled')
-     * ```
-     * @returns Whether or not this dropdown can be spell checked.
-     */
-    isSpellChecked(): boolean;
-    /**
-     * Allow PDF readers to spell check the selected option of this dropdown.
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.enableSpellChecking()
-     * ```
-     */
-    enableSpellChecking(): void;
-    /**
-     * Do not allow PDF readers to spell check the selected option of this
-     * dropdown. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.disableSpellChecking()
-     * ```
-     */
-    disableSpellChecking(): void;
-    /**
-     * Returns `true` if the option selected by a user is stored, or "committed",
-     * when the user clicks the option. The alternative is that the user's
-     * selection is stored when the user leaves this dropdown field (by clicking
-     * outside of it - on another field, for example). See
-     * [[PDFDropdown.enableSelectOnClick]] and
-     * [[PDFDropdown.disableSelectOnClick]]. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.isSelectOnClick()) console.log('Select on click is enabled')
-     * ```
-     * @returns Whether or not options are selected immediately after they are
-     *          clicked.
-     */
-    isSelectOnClick(): boolean;
-    /**
-     * Store the option selected by a user immediately after the user clicks the
-     * option. Do not wait for the user to leave this dropdown field (by clicking
-     * outside of it - on another field, for example). For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.enableSelectOnClick()
-     * ```
-     */
-    enableSelectOnClick(): void;
-    /**
-     * Wait to store the option selected by a user until they leave this dropdown
-     * field (by clicking outside of it - on another field, for example).
-     * For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.disableSelectOnClick()
-     * ```
-     */
-    disableSelectOnClick(): void;
-    /**
-     * Show this dropdown on the specified page. For example:
-     * ```js
-     * const ubuntuFont = await pdfDoc.embedFont(ubuntuFontBytes)
-     * const page = pdfDoc.addPage()
-     *
-     * const form = pdfDoc.getForm()
-     * const dropdown = form.createDropdown('best.gundam')
-     * dropdown.setOptions(['Exia', 'Dynames'])
-     * dropdown.select('Exia')
-     *
-     * dropdown.addToPage(page, {
-     *   x: 50,
-     *   y: 75,
-     *   width: 200,
-     *   height: 100,
-     *   textColor: rgb(1, 0, 0),
-     *   backgroundColor: rgb(0, 1, 0),
-     *   borderColor: rgb(0, 0, 1),
-     *   borderWidth: 2,
-     *   rotate: degrees(90),
-     *   font: ubuntuFont,
-     * })
-     * ```
-     * This will create a new widget for this dropdown field.
-     * @param page The page to which this dropdown widget should be added.
-     * @param options The options to be used when adding this dropdown widget.
-     */
-    addToPage(page: PDFPage, options?: FieldAppearanceOptions): void;
-    /**
-     * Returns `true` if this dropdown has been marked as dirty, or if any of
-     * this dropdown's widgets do not have an appearance stream. For example:
-     * ```js
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * if (dropdown.needsAppearancesUpdate()) console.log('Needs update')
-     * ```
-     * @returns Whether or not this dropdown needs an appearance update.
-     */
-    needsAppearancesUpdate(): boolean;
-    /**
-     * Update the appearance streams for each of this dropdown's widgets using
-     * the default appearance provider for dropdowns. For example:
-     * ```js
-     * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.defaultUpdateAppearances(helvetica)
-     * ```
-     * @param font The font to be used for creating the appearance streams.
-     */
-    defaultUpdateAppearances(font: PDFFont): void;
-    /**
-     * Update the appearance streams for each of this dropdown's widgets using
-     * the given appearance provider. If no `provider` is passed, the default
-     * appearance provider for dropdowns will be used. For example:
-     * ```js
-     * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
-     * const dropdown = form.getDropdown('some.dropdown.field')
-     * dropdown.updateAppearances(helvetica, (field, widget, font) => {
-     *   ...
-     *   return drawTextField(...)
-     * })
-     * ```
-     * @param font The font to be used for creating the appearance streams.
-     * @param provider Optionally, the appearance provider to be used for
-     *                 generating the contents of the appearance streams.
-     */
-    updateAppearances(font: PDFFont, provider?: AppearanceProviderFor<PDFDropdown>): void;
-    private updateWidgetAppearance;
-}

package/dist/types/src/api/form/PDFField.d.ts

@@ -1,203 +0,0 @@
-import PDFDocument from '../PDFDocument';
-import PDFFont from '../PDFFont';
-import { AppearanceMapping } from './appearances';
-import { Color } from '../colors';
-import { Rotation } from '../rotations';
-import { PDFRef, PDFWidgetAnnotation, PDFOperator, PDFName, PDFDict, PDFAcroTerminal } from '../../core';
-import { ImageAlignment } from '../image';
-import PDFImage from '../PDFImage';
-export interface FieldAppearanceOptions {
-    x?: number;
-    y?: number;
-    width?: number;
-    height?: number;
-    textColor?: Color;
-    backgroundColor?: Color;
-    borderColor?: Color;
-    borderWidth?: number;
-    rotate?: Rotation;
-    font?: PDFFont;
-    hidden?: boolean;
-}
-export declare const assertFieldAppearanceOptions: (options?: FieldAppearanceOptions) => void;
-/**
- * Represents a field of a [[PDFForm]].
- *
- * This class is effectively abstract. All fields in a [[PDFForm]] will
- * actually be an instance of a subclass of this class.
- *
- * Note that each field in a PDF is represented by a single field object.
- * However, a given field object may be rendered at multiple locations within
- * the document (across one or more pages). The rendering of a field is
- * controlled by its widgets. Each widget causes its field to be displayed at a
- * particular location in the document.
- *
- * Most of the time each field in a PDF has only a single widget, and thus is
- * only rendered once. However, if a field is rendered multiple times, it will
- * have multiple widgets - one for each location it is rendered.
- *
- * This abstraction of field objects and widgets is defined in the PDF
- * specification and dictates how PDF files store fields and where they are
- * to be rendered.
- */
-export default class PDFField {
-    /** The low-level PDFAcroTerminal wrapped by this field. */
-    readonly acroField: PDFAcroTerminal;
-    /** The unique reference assigned to this field within the document. */
-    readonly ref: PDFRef;
-    /** The document to which this field belongs. */
-    readonly doc: PDFDocument;
-    protected constructor(acroField: PDFAcroTerminal, ref: PDFRef, doc: PDFDocument);
-    /**
-     * Get the fully qualified name of this field. For example:
-     * ```js
-     * const fields = form.getFields()
-     * fields.forEach(field => {
-     *   const name = field.getName()
-     *   console.log('Field name:', name)
-     * })
-     * ```
-     * Note that PDF fields are structured as a tree. Each field is the
-     * descendent of a series of ancestor nodes all the way up to the form node,
-     * which is always the root of the tree. Each node in the tree (except for
-     * the form node) has a partial name. Partial names can be composed of any
-     * unicode characters except a period (`.`). The fully qualified name of a
-     * field is composed of the partial names of all its ancestors joined
-     * with periods. This means that splitting the fully qualified name on
-     * periods and taking the last element of the resulting array will give you
-     * the partial name of a specific field.
-     * @returns The fully qualified name of this field.
-     */
-    getName(): string;
-    /**
-     * Returns `true` if this field is read only. This means that PDF readers
-     * will not allow users to interact with the field or change its value. See
-     * [[PDFField.enableReadOnly]] and [[PDFField.disableReadOnly]].
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * if (field.isReadOnly()) console.log('Read only is enabled')
-     * ```
-     * @returns Whether or not this is a read only field.
-     */
-    isReadOnly(): boolean;
-    /**
-     * Prevent PDF readers from allowing users to interact with this field or
-     * change its value. The field will not respond to mouse or keyboard input.
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.enableReadOnly()
-     * ```
-     * Useful for fields whose values are computed, imported from a database, or
-     * prefilled by software before being displayed to the user.
-     */
-    enableReadOnly(): void;
-    /**
-     * Allow users to interact with this field and change its value in PDF
-     * readers via mouse and keyboard input. For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.disableReadOnly()
-     * ```
-     */
-    disableReadOnly(): void;
-    /**
-     * Returns `true` if this field must have a value when the form is submitted.
-     * See [[PDFField.enableRequired]] and [[PDFField.disableRequired]].
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * if (field.isRequired()) console.log('Field is required')
-     * ```
-     * @returns Whether or not this field is required.
-     */
-    isRequired(): boolean;
-    /**
-     * Require this field to have a value when the form is submitted.
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.enableRequired()
-     * ```
-     */
-    enableRequired(): void;
-    /**
-     * Do not require this field to have a value when the form is submitted.
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.disableRequired()
-     * ```
-     */
-    disableRequired(): void;
-    /**
-     * Returns `true` if this field's value should be exported when the form is
-     * submitted. See [[PDFField.enableExporting]] and
-     * [[PDFField.disableExporting]].
-     * For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * if (field.isExported()) console.log('Exporting is enabled')
-     * ```
-     * @returns Whether or not this field's value should be exported.
-     */
-    isExported(): boolean;
-    /**
-     * Indicate that this field's value should be exported when the form is
-     * submitted in a PDF reader. For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.enableExporting()
-     * ```
-     */
-    enableExporting(): void;
-    /**
-     * Indicate that this field's value should **not** be exported when the form
-     * is submitted in a PDF reader. For example:
-     * ```js
-     * const field = form.getField('some.field')
-     * field.disableExporting()
-     * ```
-     */
-    disableExporting(): void;
-    /** @ignore */
-    needsAppearancesUpdate(): boolean;
-    /** @ignore */
-    defaultUpdateAppearances(_font: PDFFont): void;
-    protected markAsDirty(): void;
-    protected markAsClean(): void;
-    protected isDirty(): boolean;
-    protected createWidget(options: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        textColor?: Color;
-        backgroundColor?: Color;
-        borderColor?: Color;
-        borderWidth: number;
-        rotate: Rotation;
-        caption?: string;
-        hidden?: boolean;
-        page?: PDFRef;
-    }): PDFWidgetAnnotation;
-    protected updateWidgetAppearanceWithFont(widget: PDFWidgetAnnotation, font: PDFFont, { normal, rollover, down }: AppearanceMapping<PDFOperator[]>): void;
-    protected updateOnOffWidgetAppearance(widget: PDFWidgetAnnotation, onValue: PDFName, { normal, rollover, down }: AppearanceMapping<{
-        on: PDFOperator[];
-        off: PDFOperator[];
-    }>): void;
-    protected updateWidgetAppearances(widget: PDFWidgetAnnotation, { normal, rollover, down }: AppearanceMapping<PDFRef | PDFDict>): void;
-    private createAppearanceStream;
-    /**
-     * Create a FormXObject of the supplied image and add it to context.
-     * The FormXObject size is calculated based on the widget (including
-     * the alignment).
-     * @param widget The widget that should display the image.
-     * @param alignment The alignment of the image.
-     * @param image The image that should be displayed.
-     * @returns The ref for the FormXObject that was added to the context.
-     */
-    protected createImageAppearanceStream(widget: PDFWidgetAnnotation, image: PDFImage, alignment: ImageAlignment): PDFRef;
-    private createAppearanceDict;
-}