FormField.h
1 //////////////////////////////////////////////////////////////////////////
2 // Copyright 2001-2019 Aspose Pty Ltd. All Rights Reserved.
3 //
4 // This file is part of Aspose.Words. The source code in this file
5 // is only intended as a supplement to the documentation, and is provided
6 // "as is", without warranty of any kind, either expressed or implied.
7 //////////////////////////////////////////////////////////////////////////
8 #pragma once
9 
10 
11 #include <system/string.h>
12 #include <system/shared_ptr.h>
13 #include <system/object.h>
14 #include <cstdint>
15 
16 #include "Aspose.Words.Cpp/Model/Text/SpecialChar.h"
17 #include "Aspose.Words.Cpp/Model/Nodes/NodeType.h"
18 #include "Aspose.Words.Cpp/Model/Fields/FormFields/TextFormFieldType.h"
19 #include "Aspose.Words.Cpp/Model/Fields/FieldType.h"
20 #include "Aspose.Words.Cpp/aspose_words_api_defs.h"
21 
22 namespace Aspose { namespace Words { namespace Comparison { class FieldComparer; } } }
23 namespace Aspose { namespace Words { namespace RW { namespace Docx { namespace Writer { class DocxFieldsWriter; } } } } }
24 namespace Aspose { namespace Words { namespace RW { namespace Html { namespace Reader { class HtmlControlAsFormFieldReader; } } } } }
25 namespace Aspose { namespace Words { namespace RW { namespace Wml { namespace Writer { class WmlFieldsWriter; } } } } }
26 namespace Aspose { namespace Words { namespace RW { namespace Nrx { namespace Reader { class NrxFldCharReaderBase; } } } } }
27 namespace Aspose { namespace Words { class RangeDocumentBuilder; } }
28 namespace Aspose { namespace Words { namespace Layout { namespace Core { class SpanFormField; } } } }
29 namespace Aspose { namespace Words { namespace Layout { namespace PreAps { class LayoutSpanFormFieldControl; } } } }
30 namespace Aspose { namespace Words { namespace Fields { class FieldFormText; } } }
31 namespace Aspose { namespace Words { class DocumentBuilder; } }
32 namespace Aspose { namespace Words { namespace RW { namespace Html { namespace Writer { class HtmlFieldWriter; } } } } }
33 namespace Aspose { namespace Words { namespace RW { namespace Odt { namespace Reader { class OdtFieldReader; } } } } }
34 namespace Aspose { namespace Words { namespace RW { namespace Odt { namespace Writer { class OdtFieldWriter; } } } } }
35 namespace Aspose { namespace Words { namespace RW { namespace Doc { namespace Reader { class ModelBuilder; } } } } }
36 namespace Aspose { namespace Words { namespace RW { namespace Doc { namespace Writer { class DocWriter; } } } } }
37 namespace Aspose { namespace Words { namespace RW { namespace Doc { class FfDataFiler; } } } }
38 namespace Aspose { namespace Words { namespace RW { namespace Odt { namespace Writer { class OdtTextBodyWriter; } } } } }
39 namespace Aspose { namespace Words { namespace RW { namespace Rtf { namespace Reader { class RtfModelBuilder; } } } } }
40 namespace Aspose { namespace Words { namespace RW { namespace Rtf { namespace Writer { class RtfFieldWriter; } } } } }
41 namespace Aspose { namespace Words { namespace Fields { enum class FormFieldType; } } }
42 namespace Aspose { namespace Words { namespace Fields { class Field; } } }
43 namespace Aspose { namespace Words { namespace Fields { class DropDownItemCollection; } } }
44 namespace Aspose { namespace Words { class BookmarkStart; } }
45 namespace Aspose { namespace Words { namespace Fields { class FormFieldPr; } } }
46 namespace Aspose { namespace Words { class DocumentBase; } }
47 namespace Aspose { namespace Words { class RunPr; } }
48 namespace Aspose { namespace Words { class Node; } }
49 namespace Aspose { namespace Words { class INodeCloningListener; } }
50 namespace Aspose { namespace Words { class DocumentVisitor; } }
51 namespace Aspose { enum class CharCase; }
52 namespace Aspose { namespace Words { namespace Fields { class FieldStart; } } }
53 
54 namespace Aspose {
55 
56 namespace Words {
57 
58 namespace Fields {
59 
60 
61 /// <summary>
62 /// Represents a single form field.
63 /// </summary>
64 /// <remarks>
65 /// <p>Microsoft Word provides the following form fields: checkbox, text input and dropdown (combobox).</p>
66 /// <p>
67 /// <b>FormField</b> is an inline-node and can only be a child of <b>Paragraph</b>.</p>
68 /// <p>
69 /// <b>FormField</b> is represented in a document by a special character and
70 /// positioned as a character within a line of text.</p>
71 /// <p>A complete form field in a Word document is a complex structure represented by several
72 /// nodes: field start, field code such as FORMTEXT, form field data, field separator,
73 /// field result, field end and a bookmark. To programmatically create form fields in a Word document use
74 /// <see cref="Aspose::Words::DocumentBuilder::InsertCheckBox(System::String, bool, int32_t)">DocumentBuilder.InsertCheckBox</see>,
75 /// <see cref="Aspose::Words::DocumentBuilder::InsertTextInput(System::String, Aspose::Words::Fields::TextFormFieldType, System::String, System::String, int32_t)">DocumentBuilder.InsertTextInput</see> and
76 /// <see cref="Aspose::Words::DocumentBuilder::InsertComboBox(System::String, System::ArrayPtr&lt;System::String&gt;, int32_t)">DocumentBuilder.InsertComboBox</see> which
77 /// make sure all of the form field nodes are created in a correct order and in a suitable state.</p>
78 /// </remarks>
79 class FormField : public Aspose::Words::SpecialChar
80 {
81  typedef FormField ThisType;
82  typedef Aspose::Words::SpecialChar BaseType;
83 
84  typedef ::System::BaseTypesInfo<BaseType> ThisTypeBaseTypesInfo;
85  ASPOSE_WORDS_SHARED_RTTI_INFO_DECL();
86 
88  friend class Aspose::Words::Comparison::FieldComparer;
89  friend class Aspose::Words::RW::Docx::Writer::DocxFieldsWriter;
90  friend class Aspose::Words::RW::Html::Reader::HtmlControlAsFormFieldReader;
91  friend class Aspose::Words::RW::Wml::Writer::WmlFieldsWriter;
92  friend class Aspose::Words::RW::Nrx::Reader::NrxFldCharReaderBase;
93  friend class Aspose::Words::RangeDocumentBuilder;
94  friend class Aspose::Words::Layout::Core::SpanFormField;
95  friend class Aspose::Words::Layout::PreAps::LayoutSpanFormFieldControl;
96  friend class Aspose::Words::Fields::FieldFormText;
97  friend class Aspose::Words::DocumentBuilder;
98  friend class Aspose::Words::RW::Html::Writer::HtmlFieldWriter;
99  friend class Aspose::Words::RW::Odt::Reader::OdtFieldReader;
100  friend class Aspose::Words::RW::Odt::Writer::OdtFieldWriter;
101  friend class Aspose::Words::RW::Doc::Reader::ModelBuilder;
102  friend class Aspose::Words::RW::Doc::Writer::DocWriter;
103  friend class Aspose::Words::RW::Doc::FfDataFiler;
104  friend class Aspose::Words::RW::Odt::Writer::OdtTextBodyWriter;
105  friend class Aspose::Words::RW::Rtf::Reader::RtfModelBuilder;
106  friend class Aspose::Words::RW::Rtf::Writer::RtfFieldWriter;
107 
108 public:
109  using Aspose::Words::SpecialChar::Clone;
110 
111 public:
112 
113  /// <summary>
114  /// Returns <b>NodeType.FormField</b>.
115  /// </summary>
116  virtual ASPOSE_WORDS_SHARED_API Aspose::Words::NodeType get_NodeType() const;
117  /// <summary>
118  /// Gets or sets the form field name.
119  /// </summary>
120  /// <remarks>
121  /// Microsoft Word allows strings with at most 20 characters.
122  /// </remarks>
123  ASPOSE_WORDS_SHARED_API System::String get_Name();
124  /// Setter for Aspose::Words::Fields::FormField::get_Name
125  ASPOSE_WORDS_SHARED_API void set_Name(System::String value);
126  /// <summary>
127  /// Returns the form field type.
128  /// </summary>
129  ASPOSE_WORDS_SHARED_API Aspose::Words::Fields::FieldType get_Type();
130  /// <summary>
131  /// Gets or sets a string that represents the result of this form field.
132  /// </summary>
133  /// <remarks>
134  /// <p>For a text form field the result is the text that is in the field.</p>
135  /// <p>For a checkbox form field the result can be "1" or "0" to indicate checked or unchecked.</p>
136  /// <p>For a dropdown form field the result is the string selected in the dropdown.</p>
137  /// <p>Setting <see cref="Aspose::Words::Fields::FormField::get_Result" /> for a text form field does not apply the text format
138  /// specified in <see cref="Aspose::Words::Fields::FormField::get_TextInputFormat" />. If you want to set a value and apply the
139  /// format, use the <see cref="Aspose::Words::Fields::FormField::SetTextInputValue(System::SharedPtr&lt;$System::Object&gt;)" /> method.</p>
140  /// </remarks>
141  ASPOSE_WORDS_SHARED_API System::String get_Result();
142  /// Setter for Aspose::Words::Fields::FormField::get_Result
143  ASPOSE_WORDS_SHARED_API void set_Result(System::String value);
144  /// <summary>
145  /// Returns or sets the text that's displayed in the status bar when a form field has the focus.
146  /// </summary>
147  /// <remarks>
148  /// <p>If the OwnStatus property is set to true, the StatusText property specifies the status bar text.
149  /// If the OwnStatus property is set to false, the StatusText property specifies the name of an AutoText
150  /// entry that contains status bar text for the form field.</p>
151  /// <p> Microsoft Word allows strings with at most 138 characters.</p>
152  /// </remarks>
153  ASPOSE_WORDS_SHARED_API System::String get_StatusText();
154  /// Setter for Aspose::Words::Fields::FormField::get_StatusText
155  ASPOSE_WORDS_SHARED_API void set_StatusText(System::String value);
156  /// <summary>
157  /// Specifies the source of the text that's displayed in the status bar when a form field has the focus.
158  /// </summary>
159  /// <remarks>
160  /// <p>If true, the text specified by the StatusText property is displayed.
161  /// If false, the text of the AutoText entry specified by the StatusText property is displayed.</p>
162  /// </remarks>
163  ASPOSE_WORDS_SHARED_API bool get_OwnStatus();
164  /// Setter for Aspose::Words::Fields::FormField::get_OwnStatus
165  ASPOSE_WORDS_SHARED_API void set_OwnStatus(bool value);
166  /// <summary>
167  /// Returns or sets the text that's displayed in a message box when the form field has the focus and the user presses F1.
168  /// </summary>
169  /// <remarks>
170  /// <p>If the OwnHelp property is set to True, HelpText specifies the text string value.
171  /// If OwnHelp is set to False, HelpText specifies the name of an AutoText entry that contains help
172  /// text for the form field.</p>
173  /// <p>Microsoft Word allows strings with at most 255 characters.</p>
174  /// </remarks>
175  ASPOSE_WORDS_SHARED_API System::String get_HelpText();
176  /// Setter for Aspose::Words::Fields::FormField::get_HelpText
177  ASPOSE_WORDS_SHARED_API void set_HelpText(System::String value);
178  /// <summary>
179  /// Specifies the source of the text that's displayed in a message box when a form field has the focus and the user presses F1.
180  /// </summary>
181  /// <remarks>
182  /// <p>If True, the text specified by the HelpText property is displayed.
183  /// If False, the text in the AutoText entry specified by the HelpText property is displayed.</p>
184  /// </remarks>
185  ASPOSE_WORDS_SHARED_API bool get_OwnHelp();
186  /// Setter for Aspose::Words::Fields::FormField::get_OwnHelp
187  ASPOSE_WORDS_SHARED_API void set_OwnHelp(bool value);
188  /// <summary>
189  /// True if references to the specified form field are automatically updated whenever the field is exited.
190  /// </summary>
191  /// <remarks>
192  /// <p>Setting <b>CalculateOnExit</b> only affects the behavior of the form field when
193  /// the document is opened in Microsoft Word. Aspose.Words never updates references
194  /// to the form field.</p>
195  /// </remarks>
196  ASPOSE_WORDS_SHARED_API bool get_CalculateOnExit();
197  /// Setter for Aspose::Words::Fields::FormField::get_CalculateOnExit
198  ASPOSE_WORDS_SHARED_API void set_CalculateOnExit(bool value);
199  /// <summary>
200  /// Returns or sets an entry macro name for the form field.
201  /// </summary>
202  /// <remarks>
203  /// <p>The entry macro runs when the form field gets the focus in Microsoft Word.</p>
204  /// <p>Microsoft Word allows strings with at most 32 characters.</p>
205  /// </remarks>
206  ASPOSE_WORDS_SHARED_API System::String get_EntryMacro();
207  /// Setter for Aspose::Words::Fields::FormField::get_EntryMacro
208  ASPOSE_WORDS_SHARED_API void set_EntryMacro(System::String value);
209  /// <summary>
210  /// Returns or sets an exit macro name for the form field.
211  /// </summary>
212  /// <remarks>
213  /// <p>The exit macro runs when the form field loses the focus in Microsoft Word.</p>
214  /// <p>Microsoft Word allows strings with at most 32 characters.</p>
215  /// </remarks>
216  ASPOSE_WORDS_SHARED_API System::String get_ExitMacro();
217  /// Setter for Aspose::Words::Fields::FormField::get_ExitMacro
218  ASPOSE_WORDS_SHARED_API void set_ExitMacro(System::String value);
219  /// <summary>
220  /// True if a form field is enabled.
221  /// </summary>
222  /// <remarks>
223  /// <p>If a form field is enabled, its contents can be changed as the form is filled in.</p>
224  /// </remarks>
225  ASPOSE_WORDS_SHARED_API bool get_Enabled();
226  /// Setter for Aspose::Words::Fields::FormField::get_Enabled
227  ASPOSE_WORDS_SHARED_API void set_Enabled(bool value);
228  /// <summary>
229  /// Returns or sets the text formatting for a text form field.
230  /// </summary>
231  /// <remarks>
232  /// <p>If the text form field contains regular text, then valid format strings are
233  /// "", "UPPERCASE", "LOWERCASE", "FIRST CAPITAL" and "TITLE CASE". The strings
234  /// are case-insensitive.</p>
235  /// <p>If the text form field contains a number or a date/time value, then valid
236  /// format strings are number or date and time format strings.</p>
237  /// <p>Microsoft Word allows strings with at most 64 characters.</p>
238  /// </remarks>
239  ASPOSE_WORDS_SHARED_API System::String get_TextInputFormat();
240  /// Setter for Aspose::Words::Fields::FormField::get_TextInputFormat
241  ASPOSE_WORDS_SHARED_API void set_TextInputFormat(System::String value);
242  /// <summary>
243  /// Gets or sets the type of a text form field.
244  /// </summary>
245  ASPOSE_WORDS_SHARED_API Aspose::Words::Fields::TextFormFieldType get_TextInputType();
246  /// Setter for Aspose::Words::Fields::FormField::get_TextInputType
247  ASPOSE_WORDS_SHARED_API void set_TextInputType(Aspose::Words::Fields::TextFormFieldType value);
248  /// <summary>
249  /// Gets or sets the default string or a calculation expression of a text form field.
250  /// </summary>
251  /// <remarks>
252  /// <para>The meaning of this property depends on the value of the <see cref="Aspose::Words::Fields::FormField::get_TextInputType" /> property.</para>
253  /// <para>When <see cref="Aspose::Words::Fields::FormField::get_TextInputType" /> is <see cref="Aspose::Words::Fields::TextFormFieldType::Regular" /> or
254  /// <see cref="Aspose::Words::Fields::TextFormFieldType::Number" />, this string specifies the default string for the text form field.
255  /// This string is the content that Microsoft Word will display in the document when the form field is empty.</para>
256  /// <para>When <see cref="Aspose::Words::Fields::FormField::get_TextInputType" /> is <see cref="Aspose::Words::Fields::TextFormFieldType::Calculated" />, then this string holds
257  /// the expression to be calculated. The expression needs to be a formula valid according to Microsoft Word formula field
258  /// requirements. When you set a new expression using this property, Aspose.Words calculates the formula result
259  /// automatically and inserts it into the form field.</para>
260  /// <para>Microsoft Word allows strings with at most 255 characters.</para>
261  /// </remarks>
262  ASPOSE_WORDS_SHARED_API System::String get_TextInputDefault();
263  /// Setter for Aspose::Words::Fields::FormField::get_TextInputDefault
264  ASPOSE_WORDS_SHARED_API void set_TextInputDefault(System::String value);
265  /// <summary>
266  /// Maximum length for the text field. Zero when the length is not limited.
267  /// </summary>
268  ASPOSE_WORDS_SHARED_API int32_t get_MaxLength();
269  /// Setter for Aspose::Words::Fields::FormField::get_MaxLength
270  ASPOSE_WORDS_SHARED_API void set_MaxLength(int32_t value);
271  /// <summary>
272  /// Provides access to the items of a dropdown form field.
273  /// </summary>
274  /// <remarks>
275  /// <p>Microsoft Word allows maximum 25 items in a dropdown form field.</p>
276  /// </remarks>
277  ASPOSE_WORDS_SHARED_API System::SharedPtr<Aspose::Words::Fields::DropDownItemCollection> get_DropDownItems();
278  /// <summary>
279  /// Gets or sets the index specifying the currently selected item in a dropdown form field.
280  /// </summary>
281  ASPOSE_WORDS_SHARED_API int32_t get_DropDownSelectedIndex();
282  /// Setter for Aspose::Words::Fields::FormField::get_DropDownSelectedIndex
283  ASPOSE_WORDS_SHARED_API void set_DropDownSelectedIndex(int32_t value);
284  /// <summary>
285  /// Gets or sets the checked status of the check box form field.
286  /// Default value for this property is <b>false</b>.
287  /// </summary>
288  /// <remarks>
289  /// <p>Applicable for a check box form field only.</p>
290  /// </remarks>
291  ASPOSE_WORDS_SHARED_API bool get_Checked();
292  /// Setter for Aspose::Words::Fields::FormField::get_Checked
293  ASPOSE_WORDS_SHARED_API void set_Checked(bool value);
294  /// <summary>
295  /// Gets or sets the default value of the check box form field.
296  /// Default value for this property is <b>false</b>.
297  /// </summary>
298  /// <remarks>
299  /// <p>Applicable for a check box form field only.</p>
300  /// </remarks>
301  ASPOSE_WORDS_SHARED_API bool get_Default();
302  /// Setter for Aspose::Words::Fields::FormField::get_Default
303  ASPOSE_WORDS_SHARED_API void set_Default(bool value);
304  /// <summary>
305  /// Gets or sets the boolean value that indicates whether the size of the textbox is automatic or specified explicitly.
306  /// </summary>
307  /// <remarks>
308  /// <p>Applicable for a check box form field only.</p>
309  /// <seealso cref="Aspose::Words::Fields::FormField::get_CheckBoxSize" />
310  /// </remarks>
311  ASPOSE_WORDS_SHARED_API bool get_IsCheckBoxExactSize();
312  /// Setter for Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize
313  ASPOSE_WORDS_SHARED_API void set_IsCheckBoxExactSize(bool value);
314  /// <summary>
315  /// Gets or sets the size of the checkbox in points. Has effect only when <see cref="Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize" /> is true.
316  /// </summary>
317  /// <remarks>
318  /// <p>Applicable for a check box form field only.</p>
319  /// <seealso cref="Aspose::Words::Fields::FormField::get_IsCheckBoxExactSize" />
320  /// </remarks>
321  ASPOSE_WORDS_SHARED_API double get_CheckBoxSize();
322  /// Setter for Aspose::Words::Fields::FormField::get_CheckBoxSize
323  ASPOSE_WORDS_SHARED_API void set_CheckBoxSize(double value);
324 
325  /// <summary>
326  /// Accepts a visitor.
327  /// </summary>
328  /// <remarks>
329  /// <p>Calls DocumentVisitor.VisitFormField.</p>
330  /// <p>For more info see the Visitor design pattern.</p>
331  /// </remarks>
332  /// <param name="visitor">The visitor that will visit the node.</param>
333  /// <returns>False if the visitor requested the enumeration to stop.</returns>
334  virtual ASPOSE_WORDS_SHARED_API bool Accept(System::SharedPtr<Aspose::Words::DocumentVisitor> visitor);
335  /// <summary>
336  /// Removes the complete form field, not just the form field special character.
337  /// </summary>
338  /// <remarks>
339  /// If there is a bookmark associated with the form field, the bookmark is not removed.
340  /// </remarks>
341  ASPOSE_WORDS_SHARED_API void RemoveField();
342  /// <summary>
343  /// Applies the text format specified in <see cref="Aspose::Words::Fields::FormField::get_TextInputFormat" /> and stores the value in <see cref="Aspose::Words::Fields::FormField::get_Result" />.
344  /// </summary>
345  /// <param name="newValue">Can be a string, number or a DateTime object.</param>
346  ASPOSE_WORDS_SHARED_API void SetTextInputValue(System::SharedPtr<System::Object> newValue);
347 
348 protected:
349 
350  Aspose::Words::Fields::FormFieldType get_FormFieldType();
351  System::SharedPtr<Aspose::Words::Fields::Field> get_Field();
352  System::String get_DropDownValue();
353  void set_DropDownValue(System::String value);
354  System::SharedPtr<Aspose::Words::BookmarkStart> get_BookmarkStart();
355  System::SharedPtr<Aspose::Words::Fields::FormFieldPr> get_FormFieldPr() const;
356 
357  static System::String& DefaultTextInputValue();
358 
359  FormField(System::SharedPtr<Aspose::Words::DocumentBase> doc, System::SharedPtr<Aspose::Words::Fields::FormFieldPr> formFieldPr, System::SharedPtr<Aspose::Words::RunPr> runPr);
360 
361  virtual ASPOSE_WORDS_SHARED_API System::SharedPtr<Aspose::Words::Node> Clone(bool isCloneChildren, System::SharedPtr<Aspose::Words::INodeCloningListener> cloningListener);
362  ASPOSE_WORDS_SHARED_API System::Object::shared_members_type GetSharedMembers() override;
363 
364 private:
365 
366  System::SharedPtr<Aspose::Words::Fields::FormFieldPr> mFormFieldPr;
367  System::SharedPtr<Aspose::Words::Fields::Field> mFieldCache;
368 
369  static Aspose::CharCase StringToCharCase(System::String charCase);
370  System::SharedPtr<Aspose::Words::Fields::FieldStart> GetFieldStart();
371  ThisType* CppMemberwiseClone() ASPOSE_CONST override { return new ThisType(*this); }
372 
373 };
374 
375 }
376 }
377 }
Definition: IFontData.h:19
Definition: CompareOptions.h:16
Definition: Hyphenation.h:18
Insert line breaks after every 76th character.
#define ASPOSE_CONST
Makes methods labelled as ASPOSE_CONST const.
Definition: defines.h:43
#define FRIEND_FUNCTION_System_MakeObject
Macro to befriend MakeObject function.
Definition: smart_ptr.h:1366