pdfium_render/pdf/document/page/field/
combo.rs

1//! Defines the [PdfFormComboBoxField] struct, exposing functionality related to a single
2//! form field of type [PdfFormFieldType::ComboBox].
3
4use std::marker::PhantomData;
5
6use crate::bindgen::{FPDF_ANNOTATION, FPDF_FORMHANDLE};
7use crate::pdf::document::page::field::options::PdfFormFieldOptions;
8use crate::pdf::document::page::field::private::internal::{
9    PdfFormFieldFlags, PdfFormFieldPrivate,
10};
11use crate::pdfium::PdfiumLibraryBindingsAccessor;
12
13#[cfg(any(
14    feature = "pdfium_future",
15    feature = "pdfium_7881",
16    feature = "pdfium_7763",
17    feature = "pdfium_7543",
18    feature = "pdfium_7350"
19))]
20use crate::error::PdfiumError;
21
22#[cfg(doc)]
23use {
24    crate::pdf::document::form::PdfForm,
25    crate::pdf::document::page::annotation::PdfPageAnnotationType,
26    crate::pdf::document::page::field::{PdfFormField, PdfFormFieldType},
27};
28
29/// A single [PdfFormField] of type [PdfFormFieldType::ComboBox]. The form field object defines
30/// an interactive drop-down list widget that allows the user to either select a value
31/// from a list of options or type a value into a text field.
32///
33/// Form fields in Pdfium are wrapped inside page annotations of type [PdfPageAnnotationType::Widget]
34/// or [PdfPageAnnotationType::XfaWidget]. User-specified values can be retrieved directly from
35/// each form field object by unwrapping the form field from the annotation, or in bulk from the
36/// [PdfForm::field_values()] function.
37pub struct PdfFormComboBoxField<'a> {
38    form_handle: FPDF_FORMHANDLE,
39    annotation_handle: FPDF_ANNOTATION,
40    options: PdfFormFieldOptions<'a>,
41    lifetime: PhantomData<&'a FPDF_ANNOTATION>,
42}
43
44impl<'a> PdfFormComboBoxField<'a> {
45    #[inline]
46    pub(crate) fn from_pdfium(
47        form_handle: FPDF_FORMHANDLE,
48        annotation_handle: FPDF_ANNOTATION,
49    ) -> Self {
50        PdfFormComboBoxField {
51            form_handle,
52            annotation_handle,
53            options: PdfFormFieldOptions::from_pdfium(form_handle, annotation_handle),
54            lifetime: PhantomData,
55        }
56    }
57
58    /// Returns the collection of selectable options in this [PdfFormComboBoxField].
59    pub fn options(&self) -> &PdfFormFieldOptions<'_> {
60        &self.options
61    }
62
63    /// Returns the displayed label for the currently selected option in this [PdfFormComboBoxField] object, if any.
64    #[inline]
65    pub fn value(&self) -> Option<String> {
66        self.options()
67            .iter()
68            .find(|option| option.is_set())
69            .and_then(|option| option.label().cloned())
70    }
71
72    /// Returns `true` if this [PdfFormComboBoxField] also includes an editable text box.
73    /// If `false`, this combo box field only includes a drop-down list.
74    #[inline]
75    pub fn has_editable_text_box(&self) -> bool {
76        self.get_flags_impl()
77            .contains(PdfFormFieldFlags::ChoiceEdit)
78    }
79
80    #[cfg(any(
81        feature = "pdfium_future",
82        feature = "pdfium_7881",
83        feature = "pdfium_7763",
84        feature = "pdfium_7543",
85        feature = "pdfium_7350"
86    ))]
87    /// Controls whether or not this [PdfFormComboBoxField] includes an editable text box
88    /// in addition to a drop-down list.
89    #[inline]
90    pub fn set_has_editable_text_box(
91        &mut self,
92        has_editable_text_box: bool,
93    ) -> Result<(), PdfiumError> {
94        self.update_one_flag_impl(PdfFormFieldFlags::ChoiceEdit, has_editable_text_box)
95    }
96
97    /// Returns `true` if the option items of this [PdfFormComboBoxField] should be sorted
98    /// alphabetically.
99    ///
100    /// This flag is intended for use by form authoring tools, not by PDF viewer applications.
101    #[inline]
102    pub fn is_sorted(&self) -> bool {
103        self.get_flags_impl()
104            .contains(PdfFormFieldFlags::ChoiceSort)
105    }
106
107    #[cfg(any(
108        feature = "pdfium_future",
109        feature = "pdfium_7881",
110        feature = "pdfium_7763",
111        feature = "pdfium_7543",
112        feature = "pdfium_7350"
113    ))]
114    /// Controls whether or not the option items of this [PdfFormComboBoxField] should be
115    /// sorted alphabetically.
116    ///
117    /// This flag is intended for use by form authoring tools, not by PDF viewer applications.
118    #[inline]
119    pub fn set_is_sorted(&mut self, is_sorted: bool) -> Result<(), PdfiumError> {
120        self.update_one_flag_impl(PdfFormFieldFlags::ChoiceSort, is_sorted)
121    }
122
123    /// Returns `true` if more than one of the option items in this [PdfFormComboBoxField]
124    /// may be selected simultaneously. If `false`, only one item at a time may be selected.
125    ///
126    /// This flag was added in PDF version 1.4.
127    pub fn is_multiselect(&self) -> bool {
128        self.get_flags_impl()
129            .contains(PdfFormFieldFlags::ChoiceMultiSelect)
130    }
131
132    #[cfg(any(
133        feature = "pdfium_future",
134        feature = "pdfium_7881",
135        feature = "pdfium_7763",
136        feature = "pdfium_7543",
137        feature = "pdfium_7350"
138    ))]
139    /// Controls whether more than one of the option items in this [PdfFormComboBoxField]
140    /// may be selected simultaneously.
141    ///
142    /// This flag was added in PDF version 1.4.
143    pub fn set_is_multiselect(&mut self, is_multiselect: bool) -> Result<(), PdfiumError> {
144        self.update_one_flag_impl(PdfFormFieldFlags::ChoiceMultiSelect, is_multiselect)
145    }
146
147    /// Returns `true` if text entered into the editable text box included in this
148    /// [PdfFormComboBoxField] should be spell checked.
149    ///
150    /// This flag is meaningful only if the [PdfFormComboBoxField::has_editable_text_box()]
151    /// flag is also `true`.
152    ///
153    /// This flag was added in PDF version 1.4.
154    pub fn is_spell_checked(&self) -> bool {
155        !self
156            .get_flags_impl()
157            .contains(PdfFormFieldFlags::TextDoNotSpellCheck)
158    }
159
160    #[cfg(any(
161        feature = "pdfium_future",
162        feature = "pdfium_7881",
163        feature = "pdfium_7763",
164        feature = "pdfium_7543",
165        feature = "pdfium_7350"
166    ))]
167    /// Controls whether or not text entered into the editable text box included in this
168    /// [PdfFormComboBoxField] should be spell checked.
169    ///
170    /// This flag was added in PDF version 1.4.
171    pub fn set_is_spell_checked(&mut self, is_spell_checked: bool) -> Result<(), PdfiumError> {
172        self.update_one_flag_impl(PdfFormFieldFlags::TextDoNotSpellCheck, !is_spell_checked)
173    }
174
175    /// Returns `true` if any new value is committed to this [PdfFormComboBoxField]
176    /// as soon as a selection is made with the pointing device. This option enables
177    /// applications to perform an action once a selection is made, without requiring
178    /// the user to exit the field. If `false`, any new value is not committed until the
179    /// user exits the field.
180    ///
181    /// This flag was added in PDF version 1.5.
182    pub fn is_commit_on_selection_change(&self) -> bool {
183        self.get_flags_impl()
184            .contains(PdfFormFieldFlags::ChoiceCommitOnSelectionChange)
185    }
186
187    #[cfg(any(
188        feature = "pdfium_future",
189        feature = "pdfium_7881",
190        feature = "pdfium_7763",
191        feature = "pdfium_7543",
192        feature = "pdfium_7350"
193    ))]
194    /// Controls whether or not any new value is committed to this [PdfFormComboBoxField]
195    /// as soon as a selection is made with the pointing device.
196    ///
197    /// This flag was added in PDF version 1.5.
198    pub fn set_is_commit_on_selection_change(
199        &mut self,
200        is_commit_on_selection_change: bool,
201    ) -> Result<(), PdfiumError> {
202        self.update_one_flag_impl(
203            PdfFormFieldFlags::ChoiceCommitOnSelectionChange,
204            is_commit_on_selection_change,
205        )
206    }
207}
208
209impl<'a> PdfFormFieldPrivate<'a> for PdfFormComboBoxField<'a> {
210    #[inline]
211    fn form_handle(&self) -> FPDF_FORMHANDLE {
212        self.form_handle
213    }
214
215    #[inline]
216    fn annotation_handle(&self) -> FPDF_ANNOTATION {
217        self.annotation_handle
218    }
219}
220
221impl<'a> PdfiumLibraryBindingsAccessor<'a> for PdfFormComboBoxField<'a> {}
222
223#[cfg(feature = "thread_safe")]
224unsafe impl<'a> Send for PdfFormComboBoxField<'a> {}
225
226#[cfg(feature = "thread_safe")]
227unsafe impl<'a> Sync for PdfFormComboBoxField<'a> {}
pdfium_render/pdf/document/page/field/combo.rs

pdfium_render/pdf/document/page/field/
combo.rs
