Okular

action.h
1/*
2 SPDX-FileCopyrightText: 2004 Enrico Ros <eros.kde@email.it>
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
16namespace Okular
17{
18class ActionPrivate;
19class GotoActionPrivate;
20class ExecuteActionPrivate;
21class BrowseActionPrivate;
22class DocumentActionPrivate;
23class SoundActionPrivate;
24class ScriptActionPrivate;
25class MovieActionPrivate;
26class RenditionActionPrivate;
27class MovieAnnotation;
29class Movie;
30class Sound;
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 */
40class OKULARCORE_EXPORT Action
41{
42public:
43 /**
44 * Describes the type of action.
45 */
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
112protected:
113 /// @cond PRIVATE
114 explicit Action(ActionPrivate &dd);
115 Q_DECLARE_PRIVATE(Action)
116 ActionPrivate *d_ptr;
117 /// @endcond
118
119private:
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 */
127class OKULARCORE_EXPORT GotoAction : public Action
128{
129public:
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
185private:
186 Q_DECLARE_PRIVATE(GotoAction)
187 Q_DISABLE_COPY(GotoAction)
188};
189
190/**
191 * The Execute action executes an external application.
192 */
193class OKULARCORE_EXPORT ExecuteAction : public Action
194{
195public:
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
229private:
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 */
238class OKULARCORE_EXPORT BrowseAction : public Action
239{
240public:
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
268private:
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 */
277class OKULARCORE_EXPORT DocumentAction : public Action
278{
279public:
280 /**
281 * Describes the possible action types.
282 */
284 PageFirst = 1, ///< Jump to first page
285 PagePrev = 2, ///< Jump to previous page
286 PageNext = 3, ///< Jump to next page
287 PageLast = 4, ///< Jump to last page
288 HistoryBack = 5, ///< Go back in page history
289 HistoryForward = 6, ///< Go forward in page history
290 Quit = 7, ///< Quit application
291 Presentation = 8, ///< Start presentation
292 EndPresentation = 9, ///< End presentation
293 Find = 10, ///< Open find dialog
294 GoToPage = 11, ///< Goto page
295 Close = 12, ///< Close document
296 Print = 13, ///< Print the document @since 22.04
297 SaveAs = 14 ///< SaveAs the document @since 22.04
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
327private:
328 Q_DECLARE_PRIVATE(DocumentAction)
329 Q_DISABLE_COPY(DocumentAction)
330};
331
332/**
333 * The Sound action plays a sound on activation.
334 */
335class OKULARCORE_EXPORT SoundAction : public Action
336{
337public:
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
389private:
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 */
399class OKULARCORE_EXPORT ScriptAction : public Action
400{
401public:
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
435private:
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 */
445class OKULARCORE_EXPORT MovieAction : public Action
446{
447public:
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
488private:
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 */
499class OKULARCORE_EXPORT RenditionAction : public Action
500{
501public:
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
568private:
569 Q_DECLARE_PRIVATE(RenditionAction)
570 Q_DISABLE_COPY(RenditionAction)
571};
572
573class OKULARCORE_EXPORT BackendOpaqueAction : public Action
574{
575public:
576 BackendOpaqueAction();
577
578 /**
579 * Returns the action type.
580 */
581 ActionType actionType() const override;
582
583private:
584 Q_DISABLE_COPY(BackendOpaqueAction)
585};
586
587}
588
589#endif
Encapsulates data that describes an action.
Definition action.h:41
ActionType
Describes the type of action.
Definition action.h:46
@ Execute
Execute a command or external application.
Definition action.h:48
@ Goto
Goto a given page or external document.
Definition action.h:47
@ DocAction
Start a custom action.
Definition action.h:50
@ Movie
Play a movie.
Definition action.h:52
@ Browse
Browse a given website.
Definition action.h:49
@ Script
Executes a Script code.
Definition action.h:53
@ Rendition
Play a movie and/or execute a Script code.
Definition action.h:54
@ Sound
Play a sound.
Definition action.h:51
virtual ActionType actionType() const =0
Returns the type of the action.
The Browse action browses an url by opening a web browser or email client, depending on the url proto...
Definition action.h:239
The DocumentAction action contains an action that is performed on the current document.
Definition action.h:278
DocumentActionType
Describes the possible action types.
Definition action.h:283
A view on the document.
Definition document.h:1350
The Execute action executes an external application.
Definition action.h:194
The Goto action changes the viewport to another page or loads an external document.
Definition action.h:128
The Movie action executes an operation on a video on activation.
Definition action.h:446
OperationType
Describes the possible operation types.
Definition action.h:451
Movie annotation.
Contains information about a movie object.
Definition movie.h:26
The Rendition action executes an operation on a video or executes some JavaScript code on activation.
Definition action.h:500
OperationType
Describes the possible operation types.
Definition action.h:505
@ Stop
Stop playing the video.
Definition action.h:508
@ Pause
Pause the video.
Definition action.h:509
@ None
Execute only the JavaScript.
Definition action.h:506
@ Play
Start playing the video.
Definition action.h:507
Screen annotation.
The Script action executes a Script code.
Definition action.h:400
The Sound action plays a sound on activation.
Definition action.h:336
Contains information about a sound object.
Definition sound.h:24
global.h
Definition action.h:17
ScriptType
Describes the possible script types.
Definition global.h:75
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:44:05 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.