pdf-lib

import PDFDocument from "../PDFDocument"; import PDFPage from "../PDFPage"; import PDFField, { FieldAppearanceOptions } from "./PDFField"; import { AppearanceProviderFor } from "./appearances"; import { PDFRef, PDFAcroRadioButton } from "../../core"; /** * Represents a radio group field of a [[PDFForm]]. * * [[PDFRadioGroup]] fields are collections of radio buttons. The purpose of a * radio group is to enable users to select one option from a set of mutually * exclusive choices. Each choice in a radio group is represented by a radio * button. Radio buttons each have two states: `on` and `off`. At most one * radio button in a group may be in the `on` state at any time. Users can * click on a radio button to select it (and thereby automatically deselect any * other radio button that might have already been selected). Some radio * groups allow users to toggle a selected radio button `off` by clicking on * it (see [[PDFRadioGroup.isOffToggleable]]). * * Note that some radio groups allow multiple radio buttons to be in the `on` * state at the same type **if** they represent the same underlying value (see * [[PDFRadioGroup.isMutuallyExclusive]]). */ export default class PDFRadioGroup extends PDFField { /** * > **NOTE:** You probably don't want to call this method directly. Instead, * > consider using the [[PDFForm.getOptionList]] method, which will create an * > instance of [[PDFOptionList]] for you. * * Create an instance of [[PDFOptionList]] from an existing acroRadioButton * and ref * * @param acroRadioButton The underlying `PDFAcroRadioButton` for this * radio group. * @param ref The unique reference for this radio group. * @param doc The document to which this radio group will belong. */ static of: (acroRadioButton: PDFAcroRadioButton, ref: PDFRef, doc: PDFDocument) => PDFRadioGroup; /** The low-level PDFAcroRadioButton wrapped by this radio group. */ readonly acroField: PDFAcroRadioButton; private constructor(); /** * Get the list of available options for this radio group. Each option is * represented by a radio button. These radio buttons are displayed at * various locations in the document, potentially on different pages (though * typically they are stacked horizontally or vertically on the same page). * For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * const options = radioGroup.getOptions() * console.log('Radio Group options:', options) * ``` * @returns The options for this radio group. */ getOptions(): string[]; /** * Get the selected option for this radio group. The selected option is * represented by the radio button in this group that is turned on. At most * one radio button in a group can be selected. If no buttons in this group * are selected, `undefined` is returned. * For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * const selected = radioGroup.getSelected() * console.log('Selected radio button:', selected) * ``` * @returns The selected option for this radio group. */ getSelected(): string | undefined; /** * Select an option for this radio group. This operation is analogous to a * human user clicking one of the radio buttons in this group via a PDF * reader to toggle it on. This method will update the underlying state of * the radio group to indicate which option has been selected. PDF libraries * and readers will be able to extract this value from the saved document and * determine which option was selected. * * For example: * ```js * const radioGroup = form.getRadioGroup('best.superhero.radioGroup') * radioGroup.select('One Punch Man') * ``` * * This method will mark this radio group 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 dot inside the widget of this check box field * that represents the selected option. * * @param option The option to be selected. */ select(option: string): void; /** * Clear any selected option for this dropdown. This will result in all * radio buttons in this group being toggled off. This method will update * the underlying state of the dropdown to indicate that no radio buttons * have been selected. * For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.clear() * ``` * This method will mark this radio group as dirty. See * [[PDFRadioGroup.select]] for more details about what this means. */ clear(): void; /** * Returns `true` if users can click on radio buttons in this group to toggle * them off. The alternative is that once a user clicks on a radio button * to select it, the only way to deselect it is by selecting on another radio * button in the group. See [[PDFRadioGroup.enableOffToggling]] and * [[PDFRadioGroup.disableOffToggling]]. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * if (radioGroup.isOffToggleable()) console.log('Off toggling is enabled') * ``` */ isOffToggleable(): boolean; /** * Allow users to click on selected radio buttons in this group to toggle * them off. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.enableOffToggling() * ``` * > **NOTE:** This feature is documented in the PDF specification * > (Table 226). However, most PDF readers do not respect this option and * > prevent users from toggling radio buttons off even when it is enabled. * > At the time of this writing (9/6/2020) Mac's Preview software did * > respect the option. Adobe Acrobat, Foxit Reader, and Google Chrome did * > not. */ enableOffToggling(): void; /** * Prevent users from clicking on selected radio buttons in this group to * toggle them off. Clicking on a selected radio button will have no effect. * The only way to deselect a selected radio button is to click on a * different radio button in the group. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.disableOffToggling() * ``` */ disableOffToggling(): void; /** * Returns `true` if the radio buttons in this group are mutually exclusive. * This means that when the user selects a radio button, only that specific * button will be turned on. Even if other radio buttons in the group * represent the same value, they will not be enabled. The alternative to * this is that clicking a radio button will select that button along with * any other radio buttons in the group that share the same value. See * [[PDFRadioGroup.enableMutualExclusion]] and * [[PDFRadioGroup.disableMutualExclusion]]. * For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * if (radioGroup.isMutuallyExclusive()) console.log('Mutual exclusion is enabled') * ``` */ isMutuallyExclusive(): boolean; /** * When the user clicks a radio button in this group it will be selected. In * addition, any other radio buttons in this group that share the same * underlying value will also be selected. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.enableMutualExclusion() * ``` * Note that this option must be enabled prior to adding options to the * radio group. It does not currently apply retroactively to existing * radio buttons in the group. */ enableMutualExclusion(): void; /** * When the user clicks a radio button in this group only it will be selected. * No other radio buttons in the group will be selected, even if they share * the same underlying value. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.disableMutualExclusion() * ``` * Note that this option must be disabled prior to adding options to the * radio group. It does not currently apply retroactively to existing * radio buttons in the group. */ disableMutualExclusion(): void; /** * Add a new radio button to this group on the specified page. For example: * ```js * const page = pdfDoc.addPage() * * const form = pdfDoc.getForm() * const radioGroup = form.createRadioGroup('best.gundam') * * const options = { * x: 50, * width: 25, * height: 25, * textColor: rgb(1, 0, 0), * backgroundColor: rgb(0, 1, 0), * borderColor: rgb(0, 0, 1), * borderWidth: 2, * rotate: degrees(90), * } * * radioGroup.addOptionToPage('Exia', page, { ...options, y: 50 }) * radioGroup.addOptionToPage('Dynames', page, { ...options, y: 110 }) * ``` * This will create a new radio button widget for this radio group field. * @param option The option that the radio button widget represents. * @param page The page to which the radio button widget should be added. * @param options The options to be used when adding the radio button widget. */ addOptionToPage(option: string, page: PDFPage, options?: FieldAppearanceOptions): void; /** * Returns `true` if any of this group's radio button widgets do not have an * appearance stream for their current state. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * if (radioGroup.needsAppearancesUpdate()) console.log('Needs update') * ``` * @returns Whether or not this radio group needs an appearance update. */ needsAppearancesUpdate(): boolean; /** * Update the appearance streams for each of this group's radio button widgets * using the default appearance provider for radio groups. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.defaultUpdateAppearances() * ``` */ defaultUpdateAppearances(): void; /** * Update the appearance streams for each of this group's radio button widgets * using the given appearance provider. If no `provider` is passed, the * default appearance provider for radio groups will be used. For example: * ```js * const radioGroup = form.getRadioGroup('some.radioGroup.field') * radioGroup.updateAppearances((field, widget) => { * ... * return { * normal: { on: drawRadioButton(...), off: drawRadioButton(...) }, * down: { on: drawRadioButton(...), off: drawRadioButton(...) }, * } * }) * ``` * @param provider Optionally, the appearance provider to be used for * generating the contents of the appearance streams. */ updateAppearances(provider?: AppearanceProviderFor<PDFRadioGroup>): void; private updateWidgetAppearance; } //# sourceMappingURL=PDFRadioGroup.d.ts.map