@adnsistemas/pdf-lib 1.18.0

package/cjs/api/form/PDFCheckBox.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+var PDFPage_1 = tslib_1.__importDefault(require("../PDFPage"));
+var appearances_1 = require("./appearances");
+var colors_1 = require("../colors");
+var rotations_1 = require("../rotations");
+var PDFField_1 = tslib_1.__importStar(require("./PDFField"));
+var core_1 = require("../../core");
+var utils_1 = require("../../utils");
+/**
+ * Represents a check box field of a [[PDFForm]].
+ *
+ * [[PDFCheckBox]] fields are interactive boxes that users can click with their
+ * mouse. This type of [[PDFField]] has two states: `on` and `off`. The purpose
+ * of a check box is to enable users to select from one or more options, where
+ * each option is represented by a single check box. Check boxes are typically
+ * square in shape and display a check mark when they are in the `on` state.
+ */
+var PDFCheckBox = /** @class */ (function (_super) {
+    tslib_1.__extends(PDFCheckBox, _super);
+    function PDFCheckBox(acroCheckBox, ref, doc) {
+        var _this = _super.call(this, acroCheckBox, ref, doc) || this;
+        utils_1.assertIs(acroCheckBox, 'acroCheckBox', [
+            [core_1.PDFAcroCheckBox, 'PDFAcroCheckBox'],
+        ]);
+        _this.acroField = acroCheckBox;
+        return _this;
+    }
+    /**
+     * Mark this check box. This operation is analogous to a human user clicking
+     * a check box to fill it in a PDF reader. This method will update the
+     * underlying state of the check box field to indicate it has been selected.
+     * PDF libraries and readers will be able to extract this value from the
+     * saved document and determine that it was selected.
+     *
+     * For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.check()
+     * ```
+     *
+     * This method will mark this check box as dirty, causing its appearance
+     * streams to be updated when either [[PDFDocument.save]] or
+     * [[PDFForm.updateFieldAppearances]] is called. The updated appearance
+     * streams will display a check mark inside the widgets of this check box
+     * field.
+     */
+    PDFCheckBox.prototype.check = function () {
+        var _a;
+        var onValue = (_a = this.acroField.getOnValue()) !== null && _a !== void 0 ? _a : core_1.PDFName.of('Yes');
+        this.markAsDirty();
+        this.acroField.setValue(onValue);
+    };
+    /**
+     * Clears this check box. This operation is analogous to a human user clicking
+     * a check box to unmark it in a PDF reader. This method will update the
+     * underlying state of the check box field to indicate it has been deselected.
+     * PDF libraries and readers will be able to extract this value from the
+     * saved document and determine that it was not selected.
+     *
+     * For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.uncheck()
+     * ```
+     *
+     * This method will mark this check box as dirty. See [[PDFCheckBox.check]]
+     * for more details about what this means.
+     */
+    PDFCheckBox.prototype.uncheck = function () {
+        this.markAsDirty();
+        this.acroField.setValue(core_1.PDFName.of('Off'));
+    };
+    /**
+     * Returns `true` if this check box is selected (either by a human user via
+     * a PDF reader, or else programmatically via software). For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * if (checkBox.isChecked()) console.log('check box is selected')
+     * ```
+     * @returns Whether or not this check box is selected.
+     */
+    PDFCheckBox.prototype.isChecked = function () {
+        var onValue = this.acroField.getOnValue();
+        return !!onValue && onValue === this.acroField.getValue();
+    };
+    /**
+     * Show this check box on the specified page. For example:
+     * ```js
+     * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
+     * const page = pdfDoc.addPage()
+     *
+     * const form = pdfDoc.getForm()
+     * const checkBox = form.createCheckBox('some.checkBox.field')
+     *
+     * checkBox.addToPage(page, {
+     *   x: 50,
+     *   y: 75,
+     *   width: 25,
+     *   height: 25,
+     *   textColor: rgb(1, 0, 0),
+     *   backgroundColor: rgb(0, 1, 0),
+     *   borderColor: rgb(0, 0, 1),
+     *   borderWidth: 2,
+     *   rotate: degrees(90),
+     * })
+     * ```
+     * This will create a new widget for this check box field.
+     * @param page The page to which this check box widget should be added.
+     * @param options The options to be used when adding this check box widget.
+     */
+    PDFCheckBox.prototype.addToPage = function (page, options) {
+        var _a, _b, _c, _d, _e, _f;
+        utils_1.assertIs(page, 'page', [[PDFPage_1.default, 'PDFPage']]);
+        PDFField_1.assertFieldAppearanceOptions(options);
+        if (!options)
+            options = {};
+        if (!('textColor' in options))
+            options.textColor = colors_1.rgb(0, 0, 0);
+        if (!('backgroundColor' in options))
+            options.backgroundColor = colors_1.rgb(1, 1, 1);
+        if (!('borderColor' in options))
+            options.borderColor = colors_1.rgb(0, 0, 0);
+        if (!('borderWidth' in options))
+            options.borderWidth = 1;
+        // Create a widget for this check box
+        var widget = this.createWidget({
+            x: (_a = options.x) !== null && _a !== void 0 ? _a : 0,
+            y: (_b = options.y) !== null && _b !== void 0 ? _b : 0,
+            width: (_c = options.width) !== null && _c !== void 0 ? _c : 50,
+            height: (_d = options.height) !== null && _d !== void 0 ? _d : 50,
+            textColor: options.textColor,
+            backgroundColor: options.backgroundColor,
+            borderColor: options.borderColor,
+            borderWidth: (_e = options.borderWidth) !== null && _e !== void 0 ? _e : 0,
+            rotate: (_f = options.rotate) !== null && _f !== void 0 ? _f : rotations_1.degrees(0),
+            hidden: options.hidden,
+            page: page.ref,
+        });
+        var widgetRef = this.doc.context.register(widget.dict);
+        // Add widget to this field
+        this.acroField.addWidget(widgetRef);
+        // Set appearance streams for widget
+        widget.setAppearanceState(core_1.PDFName.of('Off'));
+        this.updateWidgetAppearance(widget, core_1.PDFName.of('Yes'));
+        // Add widget to the given page
+        page.node.addAnnot(widgetRef);
+    };
+    /**
+     * Returns `true` if any of this check box's widgets do not have an
+     * appearance stream for its current state. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * if (checkBox.needsAppearancesUpdate()) console.log('Needs update')
+     * ```
+     * @returns Whether or not this check box needs an appearance update.
+     */
+    PDFCheckBox.prototype.needsAppearancesUpdate = function () {
+        var _a;
+        var widgets = this.acroField.getWidgets();
+        for (var idx = 0, len = widgets.length; idx < len; idx++) {
+            var widget = widgets[idx];
+            var state = widget.getAppearanceState();
+            var normal = (_a = widget.getAppearances()) === null || _a === void 0 ? void 0 : _a.normal;
+            if (!(normal instanceof core_1.PDFDict))
+                return true;
+            if (state && !normal.has(state))
+                return true;
+        }
+        return false;
+    };
+    /**
+     * Update the appearance streams for each of this check box's widgets using
+     * the default appearance provider for check boxes. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.defaultUpdateAppearances()
+     * ```
+     */
+    PDFCheckBox.prototype.defaultUpdateAppearances = function () {
+        this.updateAppearances();
+    };
+    /**
+     * Update the appearance streams for each of this check box's widgets using
+     * the given appearance provider. If no `provider` is passed, the default
+     * appearance provider for check boxs will be used. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.updateAppearances((field, widget) => {
+     *   ...
+     *   return {
+     *     normal: { on: drawCheckBox(...), off: drawCheckBox(...) },
+     *     down: { on: drawCheckBox(...), off: drawCheckBox(...) },
+     *   }
+     * })
+     * ```
+     * @param provider Optionally, the appearance provider to be used for
+     *                 generating the contents of the appearance streams.
+     */
+    PDFCheckBox.prototype.updateAppearances = function (provider) {
+        var _a;
+        utils_1.assertOrUndefined(provider, 'provider', [Function]);
+        var widgets = this.acroField.getWidgets();
+        for (var idx = 0, len = widgets.length; idx < len; idx++) {
+            var widget = widgets[idx];
+            var onValue = (_a = widget.getOnValue()) !== null && _a !== void 0 ? _a : core_1.PDFName.of('Yes');
+            if (!onValue)
+                continue;
+            this.updateWidgetAppearance(widget, onValue, provider);
+        }
+        this.markAsClean();
+    };
+    PDFCheckBox.prototype.updateWidgetAppearance = function (widget, onValue, provider) {
+        var apProvider = provider !== null && provider !== void 0 ? provider : appearances_1.defaultCheckBoxAppearanceProvider;
+        var appearances = appearances_1.normalizeAppearance(apProvider(this, widget));
+        this.updateOnOffWidgetAppearance(widget, onValue, appearances);
+    };
+    /**
+     * > **NOTE:** You probably don't want to call this method directly. Instead,
+     * > consider using the [[PDFForm.getCheckBox]] method, which will create an
+     * > instance of [[PDFCheckBox]] for you.
+     *
+     * Create an instance of [[PDFCheckBox]] from an existing acroCheckBox and ref
+     *
+     * @param acroCheckBox The underlying `PDFAcroCheckBox` for this check box.
+     * @param ref The unique reference for this check box.
+     * @param doc The document to which this check box will belong.
+     */
+    PDFCheckBox.of = function (acroCheckBox, ref, doc) {
+        return new PDFCheckBox(acroCheckBox, ref, doc);
+    };
+    return PDFCheckBox;
+}(PDFField_1.default));
+exports.default = PDFCheckBox;
+//# sourceMappingURL=PDFCheckBox.js.map

package/cjs/api/form/PDFCheckBox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PDFCheckBox.js","sourceRoot":"","sources":["../../../src/api/form/PDFCheckBox.ts"],"names":[],"mappings":"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"}

package/cjs/api/form/PDFDropdown.d.ts

@@ -0,0 +1,403 @@
+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;
+}
+//# sourceMappingURL=PDFDropdown.d.ts.map

package/cjs/api/form/PDFDropdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PDFDropdown.d.ts","sourceRoot":"","sources":["../../../src/api/form/PDFDropdown.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,uBAA4B;AAC9C,OAAO,OAAO,mBAAwB;AACtC,OAAO,OAAO,mBAAwB;AACtC,OAAO,QAAQ,EAAE,EACf,sBAAsB,EAEvB,mBAA8B;AAC/B,OAAO,EACL,qBAAqB,EAGtB,sBAAiC;AAIlC,OAAO,EAEL,MAAM,EAIN,eAAe,EAEhB,mBAAiB;AAGlB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,QAAQ;IAC/C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,iBAAkB,eAAe,OAAO,MAAM,OAAO,WAAW,iBAC/B;IAE1C,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAEpC,OAAO;IAcP;;;;;;;;;;OAUG;IACH,UAAU,IAAI,MAAM,EAAE;IAYtB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,IAAI,MAAM,EAAE;IAWvB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE;IAU5B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAkBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,UAAQ;IA+BhD;;;;;;;;;;;OAWG;IACH,KAAK;IAKL;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM;IAM5B;;;;;;;;;;OAUG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;OAWG;IACH,aAAa;IAIb;;;;;;;;;;OAUG;IACH,cAAc;IAId;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;;OAQG;IACH,aAAa;IAIb;;;;;;;;OAQG;IACH,cAAc;IAId;;;;;;;;;OASG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;OAOG;IACH,iBAAiB;IAIjB;;;;;;;OAOG;IACH,kBAAkB;IAIlB;;;;;;;;;;;OAWG;IACH,cAAc,IAAI,OAAO;IAIzB;;;;;;;OAOG;IACH,mBAAmB;IAInB;;;;;;;OAOG;IACH,oBAAoB;IAIpB;;;;;;;;;;;;;OAaG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;;;;;OAQG;IACH,mBAAmB;IAInB;;;;;;;;OAQG;IACH,oBAAoB;IAIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAsCzD;;;;;;;;OAQG;IACH,sBAAsB,IAAI,OAAO;IAcjC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,IAAI,EAAE,OAAO;IAKtC;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CACf,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC;IAoB/C,OAAO,CAAC,sBAAsB;CAS/B"}