Okular

form.h
1/*
2 SPDX-FileCopyrightText: 2007 Pino Toscano <pino@kde.org>
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
20namespace Okular
21{
22class Action;
23class Page;
24class PagePrivate;
25class FormFieldPrivate;
26class FormFieldButtonPrivate;
27class FormFieldTextPrivate;
28class FormFieldChoicePrivate;
29class 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 */
39class OKULARCORE_EXPORT FormField
40{
41 /// @cond PRIVATE
42 friend class Page;
43 friend class PagePrivate;
44 /// @endcond
45
46public:
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 /**
133 Sets the @p value associated with the form field.
134
135 @since 24.08
136 */
137 virtual void setValue(const QVariant &value);
138
139 /**
140 Sets the appearance @p value associated with the form field.
141
142 @since 24.08
143 */
144 virtual void setAppearanceValue(const QVariant &value);
145
146 /**
147 Returns the value associated wit the form field.
148
149 @since 24.08
150 */
151 virtual QVariant value() const;
152
153 Action *activationAction() const;
154
155 /**
156 * Describes the type of form additional action.
157 *
158 * @since 1.1
159 */
161 FieldModified, ///< An action to be performed when the user modifies the field
162 FormatField, ///< An action to be performed before the field is formatted to display its value
163 ValidateField, ///< An action to be performed when the field value changes
164 CalculateField, ///< An action to be performed when the field needs to be recalculated
165 };
166
167 /**
168 * Returns the additional action of the given @p type or @c nullptr if no action has been defined.
169 *
170 * @since 1.1
171 */
172 Action *additionalAction(AdditionalActionType type) const;
173
174 /**
175 * Returns the additional action of the given @p type or @c nullptr if no action has been defined.
176 * This is for actions of annotation widgets associated with the FormField
177 *
178 * @since 1.5
179 */
180 Action *additionalAction(Annotation::AdditionalActionType type) const;
181
182 /**
183 * Returns all the additional actions for this form
184 * @since 22.04
185 */
186 QList<Action *> additionalActions() const;
187
188 /**
189 * Returns the page of this form field
190 *
191 * @since 21.12.2
192 */
193 Page *page() const;
194
195 /**
196 * Returns the value that was last committed in this form field.
197 *
198 * @since 24.08
199 */
200 QString committedValue() const;
201
202 /**
203 * Updates the value that was last committed in this form field.
204 *
205 * @since 24.08
206 */
207 void commitValue(const QString &value);
208
209 /**
210 * Returns the formatted value that was last committed in this form field.
211 *
212 * @since 24.08
213 */
214 QString committedFormattedValue() const;
215
216 /**
217 * Updates the value that was last committed in this form field.
218 *
219 * @since 24.08
220 */
221 void commitFormattedValue(const QString &value);
222
223protected:
224 /// @cond PRIVATE
225 explicit FormField(FormFieldPrivate &dd);
226 Q_DECLARE_PRIVATE(FormField)
227 FormFieldPrivate *d_ptr;
228 /// @endcond
229
230 void setActivationAction(Action *action);
231 void setAdditionalAction(AdditionalActionType type, Action *action);
232 void setAdditionalAction(Annotation::AdditionalActionType type, Action *action);
233
234private:
235 Q_DISABLE_COPY(FormField)
236};
237
238/**
239 * @short Interface of a button form field.
240 *
241 * This is the base interface to reimplement to represent a button field, like
242 * a push button, a check box or a radio button.
243 *
244 * @since 0.7 (KDE 4.1)
245 */
246class OKULARCORE_EXPORT FormFieldButton : public FormField
247{
248public:
249 /**
250 * The types of button field.
251 */
253 Push, ///< A simple push button.
254 CheckBox, ///< A check box.
255 Radio ///< A radio button.
256 };
257
258 ~FormFieldButton() override;
259
260 /**
261 The particular type of the button field.
262 */
263 virtual ButtonType buttonType() const = 0;
264
265 /**
266 * The caption to be used for the button.
267 */
268 virtual QString caption() const = 0;
269
270 /**
271 * The state of the button.
272 */
273 virtual bool state() const = 0;
274
275 /**
276 * Sets the state of the button to the new \p state .
277 */
278 virtual void setState(bool state);
279
280 /**
281 * The list with the IDs of siblings (ie, buttons belonging to the same
282 * group as the current one.
283 *
284 * Valid only for \ref Radio buttons, an empty list otherwise.
285 */
286 virtual QList<int> siblings() const = 0;
287
288 /**
289 * Sets the icon of the Button to the Icon of the field parameter.
290 *
291 * @since 1.9
292 */
293 virtual void setIcon(Okular::FormField *field);
294
295protected:
297
298private:
299 Q_DECLARE_PRIVATE(FormFieldButton)
300 Q_DISABLE_COPY(FormFieldButton)
301};
302
303/**
304 * @short Interface of a text form field.
305 *
306 * This is the base interface to reimplement to represent a text field, ie a
307 * field where the user insert text.
308 */
309class OKULARCORE_EXPORT FormFieldText : public FormField
310{
311public:
312 /**
313 * The types of text field.
314 */
315 enum TextType {
316 Normal, ///< A simple singleline text field.
317 Multiline, ///< A multiline text field.
318 FileSelect ///< An input field to select the path of a file on disk.
319 };
320
321 ~FormFieldText() override;
322
323 /**
324 * The particular type of the text field.
325 */
326 virtual TextType textType() const = 0;
327
328 /**
329 * The text of text field.
330 */
331 virtual QString text() const = 0;
332
333 /**
334 * Sets the new @p text in the text field.
335 *
336 * The default implementation does nothing.
337 *
338 * Reimplemented only if the setting of new text is supported.
339 */
340 virtual void setText(const QString &text);
341
342 /**
343 * Whether this text field is a password input, eg its text @b must be
344 * replaced with asterisks.
345 *
346 * Always false for @ref FileSelect text fields.
347 */
348 virtual bool isPassword() const;
349
350 /**
351 * Whether this text field should allow rich text.
352 */
353 virtual bool isRichText() const;
354
355 /**
356 * The maximum length allowed for the text of text field, or -1 if
357 * there is no limitation for the text.
358 */
359 virtual int maximumLength() const;
360
361 /**
362 * The alignment of the text within the field.
363 */
364 virtual Qt::Alignment textAlignment() const;
365
366 /**
367 * Whether the text inserted manually in the field (where possible)
368 * can be spell-checked.
369 *
370 * @note meaningful only if the field is editable.
371 */
372 virtual bool canBeSpellChecked() const;
373
374 /**
375 * Set the text which should be rendered by the PDF.
376 *
377 * @since 1.9
378 */
379 virtual void setAppearanceText(const QString &text) = 0;
380
381 /**
382 * Sets the @p value associated with the text form field.
383 * The value is of type string and this function internally @ref setText(const QString &text)
384 *
385 * @since 24.08
386 */
387 void setValue(const QVariant &value) override;
388
389 /**
390 * Returns the value associated with the text form field.
391 * Internally calls @ref text() method.
392 *
393 * @since 24.08
394 */
395 QVariant value() const override;
396
397 /**
398 * Sets the appearance value associated with the text form field.
399 * Internally calls @ref setAppearanceText(const QString &text) method.
400 *
401 * @since 24.08
402 */
403 void setAppearanceValue(const QVariant &value) override;
404
405protected:
407
408private:
409 Q_DECLARE_PRIVATE(FormFieldText)
410 Q_DISABLE_COPY(FormFieldText)
411};
412
413/**
414 * @short Interface of a choice form field.
415 *
416 * This is the base interface to reimplement to represent a choice field, ie a
417 * field where the user can select one (of more) element(s) among a set of
418 * choices.
419 */
420class OKULARCORE_EXPORT FormFieldChoice : public FormField
421{
422public:
423 /**
424 * The types of choice field.
425 */
427 ComboBox, ///< A combo box choice field.
428 ListBox ///< A list box choice field.
429 };
430
431 ~FormFieldChoice() override;
432
433 /**
434 * The particular type of the choice field.
435 */
436 virtual ChoiceType choiceType() const = 0;
437
438 /**
439 * The possible choices of the choice field.
440 */
441 virtual QStringList choices() const = 0;
442
443 /**
444 * Whether this ComboBox is editable, ie the user can type in a custom
445 * value.
446 *
447 * Always false for the other types of choices.
448 */
449 virtual bool isEditable() const;
450
451 /**
452 * Whether more than one choice of this ListBox can be selected at the
453 * same time.
454 *
455 * Always false for the other types of choices.
456 */
457 virtual bool multiSelect() const;
458
459 /**
460 * The currently selected choices.
461 *
462 * Always one element in the list in case of single choice elements.
463 */
464 virtual QList<int> currentChoices() const = 0;
465
466 /**
467 * Sets the selected choices to @p choices .
468 */
469 virtual void setCurrentChoices(const QList<int> &choices);
470
471 /**
472 The text entered into an editable combo box choice field
473
474 @since 0.16 (KDE 4.10)
475 */
476 virtual QString editChoice() const;
477
478 /**
479 Sets the text entered into an editable combo box choice field
480
481 @since 0.16 (KDE 4.10)
482 */
483 virtual void setEditChoice(const QString &text);
484
485 /**
486 * The alignment of the text within the field.
487 */
488 virtual Qt::Alignment textAlignment() const;
489
490 /**
491 * Whether the text inserted manually in the field (where possible)
492 * can be spell-checked.
493 *
494 * @note meaningful only if the field is editable.
495 */
496 virtual bool canBeSpellChecked() const;
497
498 /**
499 * Returns the export value for a given choice
500 *
501 * @since 1.11
502 */
503 QString exportValueForChoice(const QString &choice) const;
504
505 /**
506 * Sets the @p text which should be rendered by the PDF in the position of choice FormField.
507 *
508 * @since 24.12
509 */
510 virtual void setAppearanceChoiceText(const QString &text) = 0;
511
512 /**
513 * Sets the @p value asssociated with the choice form field.
514 * It does not set anything for ListBox for now, only for the ComboBox.
515 *
516 * Expected type of @p value is QString.
517 * @since 24.12
518 */
519 void setValue(const QVariant &value) override;
520
521 /**
522 * Returns the value associated with the choice form field.
523 * In case of ComboBox, if there is any selection, then the selected value is returned, else the value entered in editText of the comboBox.
524 * Returns empty string for ListBox for now.
525 *
526 * @since 24.12
527 */
528 QVariant value() const override;
529
530 /**
531 * Sets the appearance @p value associated with the form field.
532 *
533 * @since 24.12
534 */
535 void setAppearanceValue(const QVariant &value) override;
536
537protected:
539
540 /**
541 * The possible choices of the choice field.
542 * The key is the display name of the choice,
543 * The value is the export value (i.e. for use in javascript, etc) of the choice
544 *
545 * @since 1.11
546 */
547 void setExportValues(const QMap<QString, QString> &values);
548
549private:
550 Q_DECLARE_PRIVATE(FormFieldChoice)
551 Q_DISABLE_COPY(FormFieldChoice)
552};
553
554/**
555 * @short Interface of a signature form field.
556 *
557 * This is the base interface to reimplement to represent a signature field.
558 */
559class OKULARCORE_EXPORT FormFieldSignature : public FormField
560{
561public:
562 /**
563 * The types of signature.
564 */
566 AdbePkcs7sha1,
567 AdbePkcs7detached,
568 EtsiCAdESdetached,
569 UnknownType,
570 UnsignedSignature ///< The signature field has not been signed yet. @since 22.04
571 };
572
573 ~FormFieldSignature() override;
574
575 /**
576 * The signature type
577 */
578 virtual SignatureType signatureType() const = 0;
579
580 /**
581 * The signature info
582 * @since 23.08
583 */
584 virtual SignatureInfo signatureInfo() const = 0;
585
586 /**
587 Signs a field of UnsignedSignature type.
588
589 @since 22.04
590 */
591 virtual bool sign(const NewSignatureData &data, const QString &newPath) const = 0;
592
593 using SubscriptionHandle = uint64_t;
594 /**
595 * Subscribes to updates to signatureInfo
596 *
597 * Especially certificate validation can be a slow task and the
598 * underlying infrastructure might offload it to a background job.
599 *
600 * Whenever those background jobs finished, the callback(s) will be invoked
601 *
602 * @return handle to be able to be put back into \ref unsubscribeUpdates
603 *
604 * @since 24.08
605 */
606 virtual SubscriptionHandle subscribeUpdates(const std::function<void()> &callback) const = 0;
607 /**
608 * Unsubscribes a handle for updates. Handle must be acquired by
609 * the \ref subscribeUpdates function
610 *
611 * @return true if subscription succeeded and false if failed.
612 * The most likely reason for for failure is if the handle was
613 * already unsubscribed or for other reasons not existing
614 *
615 * @since 24.08
616 */
617 virtual bool unsubscribeUpdates(const SubscriptionHandle &) const = 0;
618
619protected:
621
622private:
623 Q_DECLARE_PRIVATE(FormFieldSignature)
624 Q_DISABLE_COPY(FormFieldSignature)
625};
626
627}
628
629Q_DECLARE_METATYPE(const Okular::FormFieldSignature *);
630
631#endif
Encapsulates data that describes an action.
Definition action.h:41
AdditionalActionType
Describes the type of additional actions.
Interface of a button form field.
Definition form.h:247
ButtonType
The types of button field.
Definition form.h:252
@ Push
A simple push button.
Definition form.h:253
@ CheckBox
A check box.
Definition form.h:254
virtual QString caption() const =0
The caption to be used for the button.
virtual QList< int > siblings() const =0
The list with the IDs of siblings (ie, buttons belonging to the same group as the current one.
virtual ButtonType buttonType() const =0
The particular type of the button field.
virtual bool state() const =0
The state of the button.
Interface of a choice form field.
Definition form.h:421
ChoiceType
The types of choice field.
Definition form.h:426
@ ComboBox
A combo box choice field.
Definition form.h:427
virtual QList< int > currentChoices() const =0
The currently selected choices.
virtual void setAppearanceChoiceText(const QString &text)=0
Sets the text which should be rendered by the PDF in the position of choice FormField.
virtual ChoiceType choiceType() const =0
The particular type of the choice field.
virtual QStringList choices() const =0
The possible choices of the choice field.
Interface of a signature form field.
Definition form.h:560
virtual bool sign(const NewSignatureData &data, const QString &newPath) const =0
Signs a field of UnsignedSignature type.
SignatureType
The types of signature.
Definition form.h:565
virtual bool unsubscribeUpdates(const SubscriptionHandle &) const =0
Unsubscribes a handle for updates.
virtual SignatureInfo signatureInfo() const =0
The signature info.
virtual SubscriptionHandle subscribeUpdates(const std::function< void()> &callback) const =0
Subscribes to updates to signatureInfo.
virtual SignatureType signatureType() const =0
The signature type.
Interface of a text form field.
Definition form.h:310
TextType
The types of text field.
Definition form.h:315
@ Multiline
A multiline text field.
Definition form.h:317
@ Normal
A simple singleline text field.
Definition form.h:316
virtual void setAppearanceText(const QString &text)=0
Set the text which should be rendered by the PDF.
virtual QString text() const =0
The text of text field.
virtual TextType textType() const =0
The particular type of the text field.
The base interface of a form field.
Definition form.h:40
AdditionalActionType
Describes the type of form additional action.
Definition form.h:160
@ FieldModified
An action to be performed when the user modifies the field.
Definition form.h:161
@ CalculateField
An action to be performed when the field needs to be recalculated.
Definition form.h:164
@ ValidateField
An action to be performed when the field value changes.
Definition form.h:163
@ FormatField
An action to be performed before the field is formatted to display its value.
Definition form.h:162
virtual QString uiName() const =0
The visible name of the field, to be used in the user interface (eg in error messages,...
FieldType
The types of form field.
Definition form.h:50
@ FormText
A field of variable text. See FormFieldText::TextType.
Definition form.h:52
@ FormChoice
A choice field. See FormFieldChoice::ChoiceType.
Definition form.h:53
@ FormButton
A "button". See FormFieldButton::ButtonType.
Definition form.h:51
virtual NormalizedRect rect() const =0
The bounding rect of the field, in normalized coordinates.
virtual int id() const =0
The ID of the field.
virtual QString name() const =0
The internal name of the field, to be used when referring to the field in eg scripts.
virtual QString fullyQualifiedName() const =0
The fully qualified name of the field, is used in the JavaScript scripts.
Data needed to create a new signature.
Definition document.h:1631
A NormalizedRect is a rectangle which can be defined by two NormalizedPoints.
Definition area.h:189
Collector for all the data belonging to a page.
Definition page.h:48
global.h
Definition action.h:17
typedef Alignment
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:08:40 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.