Okular

action.h
1 /*
2  SPDX-FileCopyrightText: 2004 Enrico Ros <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #ifndef _OKULAR_ACTION_H_
8 #define _OKULAR_ACTION_H_
9 
10 #include "global.h"
11 #include "okularcore_export.h"
12 
13 #include <QString>
14 #include <QVariant>
15 
16 namespace Okular
17 {
18 class ActionPrivate;
19 class GotoActionPrivate;
20 class ExecuteActionPrivate;
21 class BrowseActionPrivate;
22 class DocumentActionPrivate;
23 class SoundActionPrivate;
24 class ScriptActionPrivate;
25 class MovieActionPrivate;
26 class RenditionActionPrivate;
27 class MovieAnnotation;
28 class ScreenAnnotation;
29 class Movie;
30 class Sound;
31 class DocumentViewport;
32 
33 /**
34  * @short Encapsulates data that describes an action.
35  *
36  * This is the base class for actions. It makes mandatory for inherited
37  * widgets to reimplement the 'actionType' method and return the type of
38  * the action described by the reimplemented class.
39  */
40 class OKULARCORE_EXPORT Action
41 {
42 public:
43  /**
44  * Describes the type of action.
45  */
46  enum ActionType {
47  Goto, ///< Goto a given page or external document
48  Execute, ///< Execute a command or external application
49  Browse, ///< Browse a given website
50  DocAction, ///< Start a custom action
51  Sound, ///< Play a sound
52  Movie, ///< Play a movie
53  Script, ///< Executes a Script code
54  Rendition, ///< Play a movie and/or execute a Script code @since 0.16 (KDE 4.10)
55  BackendOpaque ///< Calls back to the backend with the action @since 1.1
56  };
57 
58  /**
59  * Destroys the action.
60  */
61  virtual ~Action();
62 
63  /**
64  * Returns the type of the action. Every inherited class must return
65  * an unique identifier.
66  *
67  * @see ActionType
68  */
69  virtual ActionType actionType() const = 0;
70 
71  /**
72  * Returns a i18n'ed tip of the action that is presented to
73  * the user.
74  */
75  virtual QString actionTip() const;
76 
77  /**
78  * Sets the "native" @p id of the action.
79  *
80  * This is for use of the Generator, that can optionally store an
81  * handle (a pointer, an identifier, etc) of the "native" action
82  * object, if any.
83  *
84  * @note Okular makes no use of this
85  *
86  * @since 0.15 (KDE 4.9)
87  */
88  void setNativeId(const QVariant &id);
89 
90  /**
91  * Returns the "native" id of the action.
92  *
93  * @since 0.15 (KDE 4.9)
94  */
95  QVariant nativeId() const;
96 
97  /**
98  * Returns the next actions to be executed after.
99  *
100  * @since 1.5
101  */
102  QVector<Action *> nextActions() const;
103 
104  /**
105  * Sets the next actions.
106  *
107  * Takes ownership of the objects in the actions vector.
108  * @since 1.5
109  */
110  void setNextActions(const QVector<Action *> &actions);
111 
112 protected:
113  /// @cond PRIVATE
114  Action(ActionPrivate &dd);
115  Q_DECLARE_PRIVATE(Action)
116  ActionPrivate *d_ptr;
117  /// @endcond
118 
119 private:
120  Q_DISABLE_COPY(Action)
121 };
122 
123 /**
124  * The Goto action changes the viewport to another page
125  * or loads an external document.
126  */
127 class OKULARCORE_EXPORT GotoAction : public Action
128 {
129 public:
130  /**
131  * Creates a new goto action.
132  *
133  * @p fileName The name of an external file that shall be loaded.
134  * @p viewport The target viewport information of the current document.
135  */
136  GotoAction(const QString &fileName, const DocumentViewport &viewport);
137 
138  /**
139  * Creates a new goto action.
140  *
141  * @p fileName The name of an external file that shall be loaded.
142  * @p namedDestination The target named destination for the target document.
143  *
144  * @since 0.9 (KDE 4.3)
145  */
146  GotoAction(const QString &fileName, const QString &namedDestination);
147 
148  /**
149  * Destroys the goto action.
150  */
151  ~GotoAction() override;
152 
153  /**
154  * Returns the action type.
155  */
156  ActionType actionType() const override;
157 
158  /**
159  * Returns the action tip.
160  */
161  QString actionTip() const override;
162 
163  /**
164  * Returns whether the goto action points to an external document.
165  */
166  bool isExternal() const;
167 
168  /**
169  * Returns the filename of the external document.
170  */
171  QString fileName() const;
172 
173  /**
174  * Returns the document viewport the goto action points to.
175  */
176  DocumentViewport destViewport() const;
177 
178  /**
179  * Returns the document named destination the goto action points to.
180  *
181  * @since 0.9 (KDE 4.3)
182  */
183  QString destinationName() const;
184 
185 private:
186  Q_DECLARE_PRIVATE(GotoAction)
187  Q_DISABLE_COPY(GotoAction)
188 };
189 
190 /**
191  * The Execute action executes an external application.
192  */
193 class OKULARCORE_EXPORT ExecuteAction : public Action
194 {
195 public:
196  /**
197  * Creates a new execute action.
198  *
199  * @param fileName The file name of the application to execute.
200  * @param parameters The parameters of the application to execute.
201  */
202  ExecuteAction(const QString &fileName, const QString &parameters);
203 
204  /**
205  * Destroys the execute action.
206  */
207  ~ExecuteAction() override;
208 
209  /**
210  * Returns the action type.
211  */
212  ActionType actionType() const override;
213 
214  /**
215  * Returns the action tip.
216  */
217  QString actionTip() const override;
218 
219  /**
220  * Returns the file name of the application to execute.
221  */
222  QString fileName() const;
223 
224  /**
225  * Returns the parameters of the application to execute.
226  */
227  QString parameters() const;
228 
229 private:
230  Q_DECLARE_PRIVATE(ExecuteAction)
231  Q_DISABLE_COPY(ExecuteAction)
232 };
233 
234 /**
235  * The Browse action browses an url by opening a web browser or
236  * email client, depending on the url protocol (e.g. http, mailto, etc.).
237  */
238 class OKULARCORE_EXPORT BrowseAction : public Action
239 {
240 public:
241  /**
242  * Creates a new browse action.
243  *
244  * @param url The url to browse.
245  */
246  explicit BrowseAction(const QUrl &url);
247 
248  /**
249  * Destroys the browse action.
250  */
251  ~BrowseAction() override;
252 
253  /**
254  * Returns the action type.
255  */
256  ActionType actionType() const override;
257 
258  /**
259  * Returns the action tip.
260  */
261  QString actionTip() const override;
262 
263  /**
264  * Returns the url to browse.
265  */
266  QUrl url() const;
267 
268 private:
269  Q_DECLARE_PRIVATE(BrowseAction)
270  Q_DISABLE_COPY(BrowseAction)
271 };
272 
273 /**
274  * The DocumentAction action contains an action that is performed on
275  * the current document.
276  */
277 class OKULARCORE_EXPORT DocumentAction : public Action
278 {
279 public:
280  /**
281  * Describes the possible action types.
282  *
283  * WARNING KEEP IN SYNC WITH POPPLER!
284  */
286  PageFirst = 1, ///< Jump to first page
287  PagePrev = 2, ///< Jump to previous page
288  PageNext = 3, ///< Jump to next page
289  PageLast = 4, ///< Jump to last page
290  HistoryBack = 5, ///< Go back in page history
291  HistoryForward = 6, ///< Go forward in page history
292  Quit = 7, ///< Quit application
293  Presentation = 8, ///< Start presentation
294  EndPresentation = 9, ///< End presentation
295  Find = 10, ///< Open find dialog
296  GoToPage = 11, ///< Goto page
297  Close = 12 ///< Close document
298  };
299 
300  /**
301  * Creates a new document action.
302  *
303  * @param documentActionType The type of document action.
304  */
305  explicit DocumentAction(enum DocumentActionType documentActionType);
306 
307  /**
308  * Destroys the document action.
309  */
310  ~DocumentAction() override;
311 
312  /**
313  * Returns the action type.
314  */
315  ActionType actionType() const override;
316 
317  /**
318  * Returns the action tip.
319  */
320  QString actionTip() const override;
321 
322  /**
323  * Returns the type of action.
324  */
325  DocumentActionType documentActionType() const;
326 
327 private:
328  Q_DECLARE_PRIVATE(DocumentAction)
329  Q_DISABLE_COPY(DocumentAction)
330 };
331 
332 /**
333  * The Sound action plays a sound on activation.
334  */
335 class OKULARCORE_EXPORT SoundAction : public Action
336 {
337 public:
338  /**
339  * Creates a new sound action.
340  *
341  * @param volume The volume of the sound.
342  * @param synchronous Whether the sound shall be played synchronous.
343  * @param repeat Whether the sound shall be repeated.
344  * @param mix Whether the sound shall be mixed.
345  * @param sound The sound object which contains the sound data.
346  */
347  SoundAction(double volume, bool synchronous, bool repeat, bool mix, Okular::Sound *sound);
348 
349  /**
350  * Destroys the sound action.
351  */
352  ~SoundAction() override;
353 
354  /**
355  * Returns the action type.
356  */
357  ActionType actionType() const override;
358 
359  /**
360  * Returns the action tip.
361  */
362  QString actionTip() const override;
363 
364  /**
365  * Returns the volume of the sound.
366  */
367  double volume() const;
368 
369  /**
370  * Returns whether the sound shall be played synchronous.
371  */
372  bool synchronous() const;
373 
374  /**
375  * Returns whether the sound shall be repeated.
376  */
377  bool repeat() const;
378 
379  /**
380  * Returns whether the sound shall be mixed.
381  */
382  bool mix() const;
383 
384  /**
385  * Returns the sound object which contains the sound data.
386  */
387  Okular::Sound *sound() const;
388 
389 private:
390  Q_DECLARE_PRIVATE(SoundAction)
391  Q_DISABLE_COPY(SoundAction)
392 };
393 
394 /**
395  * The Script action executes a Script code.
396  *
397  * @since 0.7 (KDE 4.1)
398  */
399 class OKULARCORE_EXPORT ScriptAction : public Action
400 {
401 public:
402  /**
403  * Creates a new Script action.
404  *
405  * @param type The type of the script (for now, only JavaScript = 0 is implemented).
406  * @param script The code to execute.
407  */
408  ScriptAction(enum ScriptType type, const QString &script);
409 
410  /**
411  * Destroys the browse action.
412  */
413  ~ScriptAction() override;
414 
415  /**
416  * Returns the action type.
417  */
418  ActionType actionType() const override;
419 
420  /**
421  * Returns the action tip.
422  */
423  QString actionTip() const override;
424 
425  /**
426  * Returns the type of action.
427  */
428  ScriptType scriptType() const;
429 
430  /**
431  * Returns the code.
432  */
433  QString script() const;
434 
435 private:
436  Q_DECLARE_PRIVATE(ScriptAction)
437  Q_DISABLE_COPY(ScriptAction)
438 };
439 
440 /**
441  * The Movie action executes an operation on a video on activation.
442  *
443  * @since 0.15 (KDE 4.9)
444  */
445 class OKULARCORE_EXPORT MovieAction : public Action
446 {
447 public:
448  /**
449  * Describes the possible operation types.
450  */
451  enum OperationType { Play, Stop, Pause, Resume };
452 
453  /**
454  * Creates a new movie action.
455  */
456  explicit MovieAction(OperationType operation);
457 
458  /**
459  * Destroys the movie action.
460  */
461  ~MovieAction() override;
462 
463  /**
464  * Returns the action type.
465  */
466  ActionType actionType() const override;
467 
468  /**
469  * Returns the action tip.
470  */
471  QString actionTip() const override;
472 
473  /**
474  * Returns the operation type.
475  */
476  OperationType operation() const;
477 
478  /**
479  * Sets the @p annotation that is associated with the movie action.
480  */
481  void setAnnotation(MovieAnnotation *annotation);
482 
483  /**
484  * Returns the annotation or @c 0 if no annotation has been set.
485  */
486  MovieAnnotation *annotation() const;
487 
488 private:
489  Q_DECLARE_PRIVATE(MovieAction)
490  Q_DISABLE_COPY(MovieAction)
491 };
492 
493 /**
494  * The Rendition action executes an operation on a video or
495  * executes some JavaScript code on activation.
496  *
497  * @since 0.16 (KDE 4.10)
498  */
499 class OKULARCORE_EXPORT RenditionAction : public Action
500 {
501 public:
502  /**
503  * Describes the possible operation types.
504  */
506  None, ///< Execute only the JavaScript
507  Play, ///< Start playing the video
508  Stop, ///< Stop playing the video
509  Pause, ///< Pause the video
510  Resume ///< Resume playing the video
511  };
512 
513  /**
514  * Creates a new rendition action.
515  *
516  * @param operation The type of operation the action executes.
517  * @param movie The movie object the action references.
518  * @param scriptType The type of script the action executes.
519  * @param script The actual script the action executes.
520  */
521  RenditionAction(OperationType operation, Okular::Movie *movie, enum ScriptType scriptType, const QString &script);
522 
523  /**
524  * Destroys the rendition action.
525  */
526  ~RenditionAction() override;
527 
528  /**
529  * Returns the action type.
530  */
531  ActionType actionType() const override;
532 
533  /**
534  * Returns the action tip.
535  */
536  QString actionTip() const override;
537 
538  /**
539  * Returns the operation type.
540  */
541  OperationType operation() const;
542 
543  /**
544  * Returns the movie object or @c 0 if no movie object was set on construction time.
545  */
546  Okular::Movie *movie() const;
547 
548  /**
549  * Returns the type of script.
550  */
551  ScriptType scriptType() const;
552 
553  /**
554  * Returns the script code.
555  */
556  QString script() const;
557 
558  /**
559  * Sets the @p annotation that is associated with the rendition action.
560  */
561  void setAnnotation(ScreenAnnotation *annotation);
562 
563  /**
564  * Returns the annotation or @c 0 if no annotation has been set.
565  */
566  ScreenAnnotation *annotation() const;
567 
568 private:
569  Q_DECLARE_PRIVATE(RenditionAction)
570  Q_DISABLE_COPY(RenditionAction)
571 };
572 
573 class OKULARCORE_EXPORT BackendOpaqueAction : public Action
574 {
575 public:
576  BackendOpaqueAction();
577 
578  /**
579  * Returns the action type.
580  */
581  ActionType actionType() const override;
582 
583 private:
584  Q_DISABLE_COPY(BackendOpaqueAction)
585 };
586 
587 }
588 
589 #endif
Start a custom action.
Definition: action.h:50
Pause the video.
Definition: action.h:509
Execute only the JavaScript.
Definition: action.h:506
OperationType
Describes the possible operation types.
Definition: action.h:451
The Script action executes a Script code.
Definition: action.h:399
global.h
Definition: action.h:16
The Execute action executes an external application.
Definition: action.h:193
The Movie action executes an operation on a video on activation.
Definition: action.h:445
ScriptType
Describes the possible script types.
Definition: global.h:74
The Goto action changes the viewport to another page or loads an external document.
Definition: action.h:127
Contains information about a sound object.
Definition: sound.h:23
Goto a given page or external document.
Definition: action.h:47
OperationType
Describes the possible operation types.
Definition: action.h:505
Encapsulates data that describes an action.
Definition: action.h:40
DocumentActionType
Describes the possible action types.
Definition: action.h:285
Play a movie.
Definition: action.h:52
Movie annotation.
Definition: annotations.h:1530
Executes a Script code.
Definition: action.h:53
Play a movie and/or execute a Script code.
Definition: action.h:54
The Browse action browses an url by opening a web browser or email client, depending on the url proto...
Definition: action.h:238
The DocumentAction action contains an action that is performed on the current document.
Definition: action.h:277
Start playing the video.
Definition: action.h:507
ActionType
Describes the type of action.
Definition: action.h:46
A view on the document.
Definition: document.h:1301
The Rendition action executes an operation on a video or executes some JavaScript code on activation...
Definition: action.h:499
Browse a given website.
Definition: action.h:49
Stop playing the video.
Definition: action.h:508
Screen annotation.
Definition: annotations.h:1576
Play a sound.
Definition: action.h:51
The Sound action plays a sound on activation.
Definition: action.h:335
Execute a command or external application.
Definition: action.h:48
Contains information about a movie object.
Definition: movie.h:25
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jun 18 2021 22:35:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.