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

KDE's Doxygen guidelines are available online.