// Copyright (c) 2005-2022 Jay Berkenbilt // // This file is part of qpdf. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Versions of qpdf prior to version 7 were released under the terms // of version 2.0 of the Artistic License. At your option, you may // continue to consider qpdf to be licensed under those terms. Please // see the manual for additional information. #ifndef QPDFFORMFIELDOBJECTHELPER_HH #define QPDFFORMFIELDOBJECTHELPER_HH // This object helper helps with form fields for interactive forms. // Please see comments in QPDFAcroFormDocumentHelper.hh for additional // details. #include #include #include class QPDFAnnotationObjectHelper; class QPDFFormFieldObjectHelper: public QPDFObjectHelper { public: QPDF_DLL QPDFFormFieldObjectHelper(); QPDF_DLL QPDFFormFieldObjectHelper(QPDFObjectHandle); QPDF_DLL virtual ~QPDFFormFieldObjectHelper() { } QPDF_DLL bool isNull(); // Return the field's parent. A form field object helper whose // underlying object is null is returned if there is no parent. // This condition may be tested by calling isNull(). QPDF_DLL QPDFFormFieldObjectHelper getParent(); // Return the top-level field for this field. Typically this will // be the field itself or its parent. If is_different is provided, // it is set to true if the top-level field is different from the // field itself; otherwise it is set to false. QPDF_DLL QPDFFormFieldObjectHelper getTopLevelField(bool* is_different = nullptr); // Get a field value, possibly inheriting the value from an // ancestor node. QPDF_DLL QPDFObjectHandle getInheritableFieldValue(std::string const& name); // Get an inherited field value as a string. If it is not a // string, silently return the empty string. QPDF_DLL std::string getInheritableFieldValueAsString(std::string const& name); // Get an inherited field value of type name as a string // representing the name. If it is not a name, silently return // the empty string. QPDF_DLL std::string getInheritableFieldValueAsName(std::string const& name); // Returns the value of /FT if present, otherwise returns the // empty string. QPDF_DLL std::string getFieldType(); QPDF_DLL std::string getFullyQualifiedName(); QPDF_DLL std::string getPartialName(); // Return the alternative field name (/TU), which is the field // name intended to be presented to users. If not present, fall // back to the fully qualified name. QPDF_DLL std::string getAlternativeName(); // Return the mapping field name (/TM). If not present, fall back // to the alternative name, then to the partial name. QPDF_DLL std::string getMappingName(); QPDF_DLL QPDFObjectHandle getValue(); // Return the field's value as a string. If this is called with a // field whose value is not a string, the empty string will be // silently returned. QPDF_DLL std::string getValueAsString(); QPDF_DLL QPDFObjectHandle getDefaultValue(); // Return the field's default value as a string. If this is called // with a field whose value is not a string, the empty string will // be silently returned. QPDF_DLL std::string getDefaultValueAsString(); // Return the default appearance string, taking inheritance from // the field tree into account. Returns the empty string if the // default appearance string is not available (because it's // erroneously absent or because this is not a variable text // field). If not found in the field hierarchy, look in /AcroForm. QPDF_DLL std::string getDefaultAppearance(); // Return the default resource dictionary for the field. This // comes not from the field but from the document-level /AcroForm // dictionary. While several PDF generates put a /DR key in the // form field's dictionary, experimentation suggests that many // popular readers, including Adobe Acrobat and Acrobat Reader, // ignore any /DR item on the field. QPDF_DLL QPDFObjectHandle getDefaultResources(); // Return the quadding value, taking inheritance from the field // tree into account. Returns 0 if quadding is not specified. Look // in /AcroForm if not found in the field hierarchy. QPDF_DLL int getQuadding(); // Return field flags from /Ff. The value is a logical or of // pdf_form_field_flag_e as defined in qpdf/Constants.h QPDF_DLL int getFlags(); // Methods for testing for particular types of form fields // Returns true if field is of type /Tx QPDF_DLL bool isText(); // Returns true if field is of type /Btn and flags do not indicate // some other type of button. QPDF_DLL bool isCheckbox(); // Returns true if field is a checkbox and is checked. QPDF_DLL bool isChecked(); // Returns true if field is of type /Btn and flags indicate that // it is a radio button QPDF_DLL bool isRadioButton(); // Returns true if field is of type /Btn and flags indicate that // it is a pushbutton QPDF_DLL bool isPushbutton(); // Returns true if fields if of type /Ch QPDF_DLL bool isChoice(); // Returns choices as UTF-8 strings QPDF_DLL std::vector getChoices(); // Set an attribute to the given value. If you have a // QPDFAcroFormDocumentHelper and you want to set the name of a // field, use QPDFAcroFormDocumentHelper::setFormFieldName // instead. QPDF_DLL void setFieldAttribute(std::string const& key, QPDFObjectHandle value); // Set an attribute to the given value as a Unicode string (UTF-16 // BE encoded). The input string should be UTF-8 encoded. If you // have a QPDFAcroFormDocumentHelper and you want to set the name // of a field, use QPDFAcroFormDocumentHelper::setFormFieldName // instead. QPDF_DLL void setFieldAttribute(std::string const& key, std::string const& utf8_value); // Set /V (field value) to the given value. If need_appearances is // true and the field type is either /Tx (text) or /Ch (choice), // set /NeedAppearances to true. You can explicitly tell this // method not to set /NeedAppearances if you are going to generate // an appearance stream yourself. Starting with qpdf 8.3.0, this // method handles fields of type /Btn (checkboxes, radio buttons, // pushbuttons) specially. QPDF_DLL void setV(QPDFObjectHandle value, bool need_appearances = true); // Set /V (field value) to the given string value encoded as a // Unicode string. The input value should be UTF-8 encoded. See // comments above about /NeedAppearances. QPDF_DLL void setV(std::string const& utf8_value, bool need_appearances = true); // Update the appearance stream for this field. Note that qpdf's // ability to generate appearance streams is limited. We only // generate appearance streams for streams of type text or choice. // The appearance uses the default parameters provided in the // file, and it only supports ASCII characters. Quadding is // currently ignored. While this functionality is limited, it // should do a decent job on properly constructed PDF files when // field values are restricted to ASCII characters. QPDF_DLL void generateAppearance(QPDFAnnotationObjectHelper&); private: QPDFObjectHandle getFieldFromAcroForm(std::string const& name); void setRadioButtonValue(QPDFObjectHandle name); void setCheckBoxValue(bool value); void generateTextAppearance(QPDFAnnotationObjectHelper&); QPDFObjectHandle getFontFromResource( QPDFObjectHandle resources, std::string const& font_name); class Members { friend class QPDFFormFieldObjectHelper; public: QPDF_DLL ~Members(); private: Members(); Members(Members const&); }; PointerHolder m; }; #endif // QPDFFORMFIELDOBJECTHELPER_HH