diff options
Diffstat (limited to 'include/qpdf/QPDFFormFieldObjectHelper.hh')
| -rw-r--r-- | include/qpdf/QPDFFormFieldObjectHelper.hh | 154 |
1 files changed, 63 insertions, 91 deletions
diff --git a/include/qpdf/QPDFFormFieldObjectHelper.hh b/include/qpdf/QPDFFormFieldObjectHelper.hh index 2221684a..fbd5547f 100644 --- a/include/qpdf/QPDFFormFieldObjectHelper.hh +++ b/include/qpdf/QPDFFormFieldObjectHelper.hh @@ -2,29 +2,25 @@ // // 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 +// 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. +// 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. +// 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. +// This object helper helps with form fields for interactive forms. Please see comments in +// QPDFAcroFormDocumentHelper.hh for additional details. #include <qpdf/QPDFObjectHelper.hh> @@ -46,37 +42,32 @@ class QPDFFormFieldObjectHelper: public QPDFObjectHelper 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(). + // 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. + // 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. + // 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. + // 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. + // 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. + // Returns the value of /FT if present, otherwise returns the empty string. QPDF_DLL std::string getFieldType(); @@ -86,60 +77,53 @@ class QPDFFormFieldObjectHelper: public QPDFObjectHelper 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. + // 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. + // 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. + // 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. + // 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. + // 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. + // 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. + // 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 + // 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(); @@ -148,19 +132,16 @@ class QPDFFormFieldObjectHelper: public QPDFObjectHelper // 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. + // 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 + // 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 + // 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 @@ -170,45 +151,36 @@ class QPDFFormFieldObjectHelper: public QPDFObjectHelper QPDF_DLL std::vector<std::string> 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. + // 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. + // 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. + // 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. + // 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. + // 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&); |