Okular

form.h
1 /*
2  SPDX-FileCopyrightText: 2007 Pino Toscano <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #ifndef _OKULAR_FORM_H_
8 #define _OKULAR_FORM_H_
9 
10 #include "annotations.h"
11 #include "area.h"
12 #include "okularcore_export.h"
13 #include "signatureutils.h"
14 
15 #include <QStringList>
16 
17 #include <memory>
18 
19 namespace Okular
20 {
21 class Action;
22 class Page;
23 class PagePrivate;
24 class FormFieldPrivate;
25 class FormFieldButtonPrivate;
26 class FormFieldTextPrivate;
27 class FormFieldChoicePrivate;
28 class FormFieldSignaturePrivate;
29 
30 /**
31  * @short The base interface of a form field.
32  *
33  * This is the very basic interface to represent a field in a form.
34  *
35  * This is not meant to be used as a direct base for the form fields in a
36  * document, but its abstract subclasses are.
37  */
38 class OKULARCORE_EXPORT FormField
39 {
40  /// @cond PRIVATE
41  friend class Page;
42  friend class PagePrivate;
43  /// @endcond
44 
45 public:
46  /**
47  * The types of form field.
48  */
49  enum FieldType {
50  FormButton, ///< A "button". See @ref FormFieldButton::ButtonType.
51  FormText, ///< A field of variable text. See @ref FormFieldText::TextType.
52  FormChoice, ///< A choice field. See @ref FormFieldChoice::ChoiceType.
53  FormSignature ///< A signature.
54  };
55 
56  virtual ~FormField();
57 
58  /**
59  * The type of the field.
60  */
61  FieldType type() const;
62 
63  /**
64  * The bounding rect of the field, in normalized coordinates.
65  */
66  virtual NormalizedRect rect() const = 0;
67 
68  /**
69  * The ID of the field.
70  */
71  virtual int id() const = 0;
72 
73  /**
74  * The internal name of the field, to be used when referring to the
75  * field in eg scripts.
76  */
77  virtual QString name() const = 0;
78 
79  /**
80  * The visible name of the field, to be used in the user interface
81  * (eg in error messages, etc).
82  */
83  virtual QString uiName() const = 0;
84 
85  /**
86  * The fully qualified name of the field, is used in the JavaScript
87  * scripts.
88  *
89  * @since 1.9
90  */
91  virtual QString fullyQualifiedName() const = 0;
92 
93  /**
94  * Whether the field is read-only.
95  */
96  virtual bool isReadOnly() const;
97 
98  /**
99  * Whether the field is read-only.
100  *
101  * @since 1.4
102  */
103  virtual void setReadOnly(bool value);
104 
105  /**
106  * Whether this form field is visible.
107  */
108  virtual bool isVisible() const;
109 
110  /**
111  * Whether the field is visible.
112  *
113  * @since 1.5
114  */
115  virtual void setVisible(bool value);
116 
117  /**
118  Whether this field is printable.
119 
120  @since 1.9
121  */
122  virtual bool isPrintable() const;
123 
124  /**
125  Set this field printable
126 
127  @since 1.9
128  */
129  virtual void setPrintable(bool value);
130 
131  Action *activationAction() const;
132 
133  /**
134  * Describes the type of form additional action.
135  *
136  * @since 1.1
137  */
139  FieldModified, ///< An action to be performed when the user modifies the field
140  FormatField, ///< An action to be performed before the field is formatted to display its value
141  ValidateField, ///< An action to be performed when the field value changes
142  CalculateField, ///< An action to be performed when the field needs to be recalculated
143  };
144 
145  /**
146  * Returns the additional action of the given @p type or @c nullptr if no action has been defined.
147  *
148  * @since 1.1
149  */
150  Action *additionalAction(AdditionalActionType type) const;
151 
152  /* Returns the additional action of the given @p type or @c nullptr if no action has been defined.
153  *
154  * This is for actions of annotation widgets associated with the FormField
155  *
156  * @since 1.5
157  */
158  Action *additionalAction(Annotation::AdditionalActionType type) const;
159 
160 protected:
161  /// @cond PRIVATE
162  explicit FormField(FormFieldPrivate &dd);
163  Q_DECLARE_PRIVATE(FormField)
164  FormFieldPrivate *d_ptr;
165  /// @endcond
166 
167  void setActivationAction(Action *action);
168  void setAdditionalAction(AdditionalActionType type, Action *action);
169  void setAdditionalAction(Annotation::AdditionalActionType type, Action *action);
170 
171 private:
172  Q_DISABLE_COPY(FormField)
173 };
174 
175 /**
176  * @short Interface of a button form field.
177  *
178  * This is the base interface to reimplement to represent a button field, like
179  * a push button, a check box or a radio button.
180  *
181  * @since 0.7 (KDE 4.1)
182  */
183 class OKULARCORE_EXPORT FormFieldButton : public FormField
184 {
185 public:
186  /**
187  * The types of button field.
188  */
189  enum ButtonType {
190  Push, ///< A simple push button.
191  CheckBox, ///< A check box.
192  Radio ///< A radio button.
193  };
194 
195  ~FormFieldButton() override;
196 
197  /**
198  The particular type of the button field.
199  */
200  virtual ButtonType buttonType() const = 0;
201 
202  /**
203  * The caption to be used for the button.
204  */
205  virtual QString caption() const = 0;
206 
207  /**
208  * The state of the button.
209  */
210  virtual bool state() const = 0;
211 
212  /**
213  * Sets the state of the button to the new \p state .
214  */
215  virtual void setState(bool state);
216 
217  /**
218  * The list with the IDs of siblings (ie, buttons belonging to the same
219  * group as the current one.
220  *
221  * Valid only for \ref Radio buttons, an empty list otherwise.
222  */
223  virtual QList<int> siblings() const = 0;
224 
225  /**
226  * Sets the icon of the Button to the Icon of the field parameter.
227  *
228  * @since 1.9
229  */
230  virtual void setIcon(Okular::FormField *field);
231 
232 protected:
233  FormFieldButton();
234 
235 private:
236  Q_DECLARE_PRIVATE(FormFieldButton)
237  Q_DISABLE_COPY(FormFieldButton)
238 };
239 
240 /**
241  * @short Interface of a text form field.
242  *
243  * This is the base interface to reimplement to represent a text field, ie a
244  * field where the user insert text.
245  */
246 class OKULARCORE_EXPORT FormFieldText : public FormField
247 {
248 public:
249  /**
250  * The types of text field.
251  */
252  enum TextType {
253  Normal, ///< A simple singleline text field.
254  Multiline, ///< A multiline text field.
255  FileSelect ///< An input field to select the path of a file on disk.
256  };
257 
258  ~FormFieldText() override;
259 
260  /**
261  * The particular type of the text field.
262  */
263  virtual TextType textType() const = 0;
264 
265  /**
266  * The text of text field.
267  */
268  virtual QString text() const = 0;
269 
270  /**
271  * Sets the new @p text in the text field.
272  *
273  * The default implementation does nothing.
274  *
275  * Reimplemented only if the setting of new text is supported.
276  */
277  virtual void setText(const QString &text);
278 
279  /**
280  * Whether this text field is a password input, eg its text @b must be
281  * replaced with asterisks.
282  *
283  * Always false for @ref FileSelect text fields.
284  */
285  virtual bool isPassword() const;
286 
287  /**
288  * Whether this text field should allow rich text.
289  */
290  virtual bool isRichText() const;
291 
292  /**
293  * The maximum length allowed for the text of text field, or -1 if
294  * there is no limitation for the text.
295  */
296  virtual int maximumLength() const;
297 
298  /**
299  * The alignment of the text within the field.
300  */
301  virtual Qt::Alignment textAlignment() const;
302 
303  /**
304  * Whether the text inserted manually in the field (where possible)
305  * can be spell-checked.
306  *
307  * @note meaningful only if the field is editable.
308  */
309  virtual bool canBeSpellChecked() const;
310 
311  /**
312  * Set the text which should be rendered by the PDF.
313  *
314  * @since 1.9
315  */
316  virtual void setAppearanceText(const QString &text) = 0;
317 
318 protected:
319  FormFieldText();
320 
321 private:
322  Q_DECLARE_PRIVATE(FormFieldText)
323  Q_DISABLE_COPY(FormFieldText)
324 };
325 
326 /**
327  * @short Interface of a choice form field.
328  *
329  * This is the base interface to reimplement to represent a choice field, ie a
330  * field where the user can select one (of more) element(s) among a set of
331  * choices.
332  */
333 class OKULARCORE_EXPORT FormFieldChoice : public FormField
334 {
335 public:
336  /**
337  * The types of choice field.
338  */
339  enum ChoiceType {
340  ComboBox, ///< A combo box choice field.
341  ListBox ///< A list box choice field.
342  };
343 
344  ~FormFieldChoice() override;
345 
346  /**
347  * The particular type of the choice field.
348  */
349  virtual ChoiceType choiceType() const = 0;
350 
351  /**
352  * The possible choices of the choice field.
353  */
354  virtual QStringList choices() const = 0;
355 
356  /**
357  * Whether this ComboBox is editable, ie the user can type in a custom
358  * value.
359  *
360  * Always false for the other types of choices.
361  */
362  virtual bool isEditable() const;
363 
364  /**
365  * Whether more than one choice of this ListBox can be selected at the
366  * same time.
367  *
368  * Always false for the other types of choices.
369  */
370  virtual bool multiSelect() const;
371 
372  /**
373  * The currently selected choices.
374  *
375  * Always one element in the list in case of single choice elements.
376  */
377  virtual QList<int> currentChoices() const = 0;
378 
379  /**
380  * Sets the selected choices to @p choices .
381  */
382  virtual void setCurrentChoices(const QList<int> &choices);
383 
384  /**
385  The text entered into an editable combo box choice field
386 
387  @since 0.16 (KDE 4.10)
388  */
389  virtual QString editChoice() const;
390 
391  /**
392  Sets the text entered into an editable combo box choice field
393 
394  @since 0.16 (KDE 4.10)
395  */
396  virtual void setEditChoice(const QString &text);
397 
398  /**
399  * The alignment of the text within the field.
400  */
401  virtual Qt::Alignment textAlignment() const;
402 
403  /**
404  * Whether the text inserted manually in the field (where possible)
405  * can be spell-checked.
406  *
407  * @note meaningful only if the field is editable.
408  */
409  virtual bool canBeSpellChecked() const;
410 
411  /**
412  * Returns the export value for a given choice
413  *
414  * @since 1.11
415  */
416  QString exportValueForChoice(const QString &choice) const;
417 
418 protected:
419  FormFieldChoice();
420 
421  /**
422  * The possible choices of the choice field.
423  * The key is the display name of the choice,
424  * The value is the export value (i.e. for use in javascript, etc) of the choice
425  *
426  * @since 1.11
427  */
428  void setExportValues(const QMap<QString, QString> &values);
429 
430 private:
431  Q_DECLARE_PRIVATE(FormFieldChoice)
432  Q_DISABLE_COPY(FormFieldChoice)
433 };
434 
435 /**
436  * @short Interface of a signature form field.
437  *
438  * This is the base interface to reimplement to represent a signature field.
439  */
440 class OKULARCORE_EXPORT FormFieldSignature : public FormField
441 {
442 public:
443  /**
444  * The types of signature.
445  */
446  enum SignatureType { AdbePkcs7sha1, AdbePkcs7detached, EtsiCAdESdetached, UnknownType };
447 
448  ~FormFieldSignature() override;
449 
450  /**
451  * The signature type
452  */
453  virtual SignatureType signatureType() const = 0;
454 
455  /**
456  * The signature info
457  */
458  virtual const SignatureInfo &signatureInfo() const = 0;
459 
460 protected:
462 
463 private:
464  Q_DECLARE_PRIVATE(FormFieldSignature)
465  Q_DISABLE_COPY(FormFieldSignature)
466 };
467 
468 }
469 
470 Q_DECLARE_METATYPE(const Okular::FormFieldSignature *);
471 
472 #endif
TextType
The types of text field.
Definition: form.h:252
A choice field. See FormFieldChoice::ChoiceType.
Definition: form.h:52
A NormalizedRect is a rectangle which can be defined by two NormalizedPoints.
Definition: area.h:189
FieldType
The types of form field.
Definition: form.h:49
A field of variable text. See FormFieldText::TextType.
Definition: form.h:51
A combo box choice field.
Definition: form.h:340
const QLatin1String name
global.h
Definition: action.h:16
A "button". See FormFieldButton::ButtonType.
Definition: form.h:50
typedef Alignment
An action to be performed when the field needs to be recalculated.
Definition: form.h:142
Interface of a text form field.
Definition: form.h:246
ButtonType
The types of button field.
Definition: form.h:189
An action to be performed when the user modifies the field.
Definition: form.h:139
A simple singleline text field.
Definition: form.h:253
AdditionalActionType
Describes the type of form additional action.
Definition: form.h:138
PartitionTable::TableType type
An action to be performed before the field is formatted to display its value.
Definition: form.h:140
Interface of a choice form field.
Definition: form.h:333
Collector for all the data belonging to a page.
Definition: page.h:49
Interface of a signature form field.
Definition: form.h:440
A helper class to store information about digital signature.
A simple push button.
Definition: form.h:190
ChoiceType
The types of choice field.
Definition: form.h:339
AdditionalActionType
Describes the type of additional actions.
Definition: annotations.h:191
Encapsulates data that describes an action.
Definition: action.h:40
SignatureType
The types of signature.
Definition: form.h:446
Annotation struct holds properties shared by all annotations.
Definition: annotations.h:96
A multiline text field.
Definition: form.h:254
An action to be performed when the field value changes.
Definition: form.h:141
bool isReadOnly
Interface of a button form field.
Definition: form.h:183
The base interface of a form field.
Definition: form.h:38
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Nov 30 2021 22:32:42 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.