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 * @deprecated use @ref setNativeHandle
86 * @since 0.15 (KDE 4.9)
87 */
88 OKULARCORE_DEPRECATED 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 */
96 OKULARCORE_DEPRECATED QVariant nativeId() const;
97
98 /**
99 * Sets "native" handle for the action
100 *
101 * This is a opaque datapointer used for the action by the
102 * Generator. The generator is responsible for setting it
103 * to something sensible and also for interpreting it.
104 *
105 * The handle is deleted according to rules of the
106 * shared pointer.
107 *
108 * @note Okular (core/part/shell/...) itself makes no use of this
109 * @since 24.05.2
110 */
111 void setNativeHandle(std::shared_ptr<const void> handle);
112
113 /**
114 * @returns the native handle pointer
115 *
116 * @since 24.05.2
117 */
118 const void *nativeHandle() const;
119
120 /**
121 * Returns the next actions to be executed after.
122 *
123 * @since 1.5
124 */
125 QVector<Action *> nextActions() const;
126
127 /**
128 * Sets the next actions.
129 *
130 * Takes ownership of the objects in the actions vector.
131 * @since 1.5
132 */
133 void setNextActions(const QVector<Action *> &actions);
134
135protected:
136 /// @cond PRIVATE
137 explicit Action(ActionPrivate &dd);
138 Q_DECLARE_PRIVATE(Action)
139 ActionPrivate *d_ptr;
140 /// @endcond
141
142private:
143 Q_DISABLE_COPY(Action)
144};
145
146/**
147 * The Goto action changes the viewport to another page
148 * or loads an external document.
149 */
150class OKULARCORE_EXPORT GotoAction : public Action
151{
152public:
153 /**
154 * Creates a new goto action.
155 *
156 * @p fileName The name of an external file that shall be loaded.
157 * @p viewport The target viewport information of the current document.
158 */
159 GotoAction(const QString &fileName, const DocumentViewport &viewport);
160
161 /**
162 * Creates a new goto action.
163 *
164 * @p fileName The name of an external file that shall be loaded.
165 * @p namedDestination The target named destination for the target document.
166 *
167 * @since 0.9 (KDE 4.3)
168 */
169 GotoAction(const QString &fileName, const QString &namedDestination);
170
171 /**
172 * Destroys the goto action.
173 */
174 ~GotoAction() override;
175
176 /**
177 * Returns the action type.
178 */
179 ActionType actionType() const override;
180
181 /**
182 * Returns the action tip.
183 */
184 QString actionTip() const override;
185
186 /**
187 * Returns whether the goto action points to an external document.
188 */
189 bool isExternal() const;
190
191 /**
192 * Returns the filename of the external document.
193 */
194 QString fileName() const;
195
196 /**
197 * Returns the document viewport the goto action points to.
198 */
199 DocumentViewport destViewport() const;
200
201 /**
202 * Returns the document named destination the goto action points to.
203 *
204 * @since 0.9 (KDE 4.3)
205 */
206 QString destinationName() const;
207
208private:
209 Q_DECLARE_PRIVATE(GotoAction)
210 Q_DISABLE_COPY(GotoAction)
211};
212
213/**
214 * The Execute action executes an external application.
215 */
216class OKULARCORE_EXPORT ExecuteAction : public Action
217{
218public:
219 /**
220 * Creates a new execute action.
221 *
222 * @param fileName The file name of the application to execute.
223 * @param parameters The parameters of the application to execute.
224 */
225 ExecuteAction(const QString &fileName, const QString &parameters);
226
227 /**
228 * Destroys the execute action.
229 */
230 ~ExecuteAction() override;
231
232 /**
233 * Returns the action type.
234 */
235 ActionType actionType() const override;
236
237 /**
238 * Returns the action tip.
239 */
240 QString actionTip() const override;
241
242 /**
243 * Returns the file name of the application to execute.
244 */
245 QString fileName() const;
246
247 /**
248 * Returns the parameters of the application to execute.
249 */
250 QString parameters() const;
251
252private:
253 Q_DECLARE_PRIVATE(ExecuteAction)
254 Q_DISABLE_COPY(ExecuteAction)
255};
256
257/**
258 * The Browse action browses an url by opening a web browser or
259 * email client, depending on the url protocol (e.g. http, mailto, etc.).
260 */
261class OKULARCORE_EXPORT BrowseAction : public Action
262{
263public:
264 /**
265 * Creates a new browse action.
266 *
267 * @param url The url to browse.
268 */
269 explicit BrowseAction(const QUrl &url);
270
271 /**
272 * Destroys the browse action.
273 */
274 ~BrowseAction() override;
275
276 /**
277 * Returns the action type.
278 */
279 ActionType actionType() const override;
280
281 /**
282 * Returns the action tip.
283 */
284 QString actionTip() const override;
285
286 /**
287 * Returns the url to browse.
288 */
289 QUrl url() const;
290
291private:
292 Q_DECLARE_PRIVATE(BrowseAction)
293 Q_DISABLE_COPY(BrowseAction)
294};
295
296/**
297 * The DocumentAction action contains an action that is performed on
298 * the current document.
299 */
300class OKULARCORE_EXPORT DocumentAction : public Action
301{
302public:
303 /**
304 * Describes the possible action types.
305 */
307 PageFirst = 1, ///< Jump to first page
308 PagePrev = 2, ///< Jump to previous page
309 PageNext = 3, ///< Jump to next page
310 PageLast = 4, ///< Jump to last page
311 HistoryBack = 5, ///< Go back in page history
312 HistoryForward = 6, ///< Go forward in page history
313 Quit = 7, ///< Quit application
314 Presentation = 8, ///< Start presentation
315 EndPresentation = 9, ///< End presentation
316 Find = 10, ///< Open find dialog
317 GoToPage = 11, ///< Goto page
318 Close = 12, ///< Close document
319 Print = 13, ///< Print the document @since 22.04
320 SaveAs = 14 ///< SaveAs the document @since 22.04
321 };
322
323 /**
324 * Creates a new document action.
325 *
326 * @param documentActionType The type of document action.
327 */
328 explicit DocumentAction(enum DocumentActionType documentActionType);
329
330 /**
331 * Destroys the document action.
332 */
333 ~DocumentAction() override;
334
335 /**
336 * Returns the action type.
337 */
338 ActionType actionType() const override;
339
340 /**
341 * Returns the action tip.
342 */
343 QString actionTip() const override;
344
345 /**
346 * Returns the type of action.
347 */
348 DocumentActionType documentActionType() const;
349
350private:
351 Q_DECLARE_PRIVATE(DocumentAction)
352 Q_DISABLE_COPY(DocumentAction)
353};
354
355/**
356 * The Sound action plays a sound on activation.
357 */
358class OKULARCORE_EXPORT SoundAction : public Action
359{
360public:
361 /**
362 * Creates a new sound action.
363 *
364 * @param volume The volume of the sound.
365 * @param synchronous Whether the sound shall be played synchronous.
366 * @param repeat Whether the sound shall be repeated.
367 * @param mix Whether the sound shall be mixed.
368 * @param sound The sound object which contains the sound data.
369 */
370 SoundAction(double volume, bool synchronous, bool repeat, bool mix, Okular::Sound *sound);
371
372 /**
373 * Destroys the sound action.
374 */
375 ~SoundAction() override;
376
377 /**
378 * Returns the action type.
379 */
380 ActionType actionType() const override;
381
382 /**
383 * Returns the action tip.
384 */
385 QString actionTip() const override;
386
387 /**
388 * Returns the volume of the sound.
389 */
390 double volume() const;
391
392 /**
393 * Returns whether the sound shall be played synchronous.
394 */
395 bool synchronous() const;
396
397 /**
398 * Returns whether the sound shall be repeated.
399 */
400 bool repeat() const;
401
402 /**
403 * Returns whether the sound shall be mixed.
404 */
405 bool mix() const;
406
407 /**
408 * Returns the sound object which contains the sound data.
409 */
410 Okular::Sound *sound() const;
411
412private:
413 Q_DECLARE_PRIVATE(SoundAction)
414 Q_DISABLE_COPY(SoundAction)
415};
416
417/**
418 * The Script action executes a Script code.
419 *
420 * @since 0.7 (KDE 4.1)
421 */
422class OKULARCORE_EXPORT ScriptAction : public Action
423{
424public:
425 /**
426 * Creates a new Script action.
427 *
428 * @param type The type of the script (for now, only JavaScript = 0 is implemented).
429 * @param script The code to execute.
430 */
431 ScriptAction(enum ScriptType type, const QString &script);
432
433 /**
434 * Destroys the browse action.
435 */
436 ~ScriptAction() override;
437
438 /**
439 * Returns the action type.
440 */
441 ActionType actionType() const override;
442
443 /**
444 * Returns the action tip.
445 */
446 QString actionTip() const override;
447
448 /**
449 * Returns the type of action.
450 */
451 ScriptType scriptType() const;
452
453 /**
454 * Returns the code.
455 */
456 QString script() const;
457
458private:
459 Q_DECLARE_PRIVATE(ScriptAction)
460 Q_DISABLE_COPY(ScriptAction)
461};
462
463/**
464 * The Movie action executes an operation on a video on activation.
465 *
466 * @since 0.15 (KDE 4.9)
467 */
468class OKULARCORE_EXPORT MovieAction : public Action
469{
470public:
471 /**
472 * Describes the possible operation types.
473 */
474 enum OperationType { Play, Stop, Pause, Resume };
475
476 /**
477 * Creates a new movie action.
478 */
479 explicit MovieAction(OperationType operation);
480
481 /**
482 * Destroys the movie action.
483 */
484 ~MovieAction() override;
485
486 /**
487 * Returns the action type.
488 */
489 ActionType actionType() const override;
490
491 /**
492 * Returns the action tip.
493 */
494 QString actionTip() const override;
495
496 /**
497 * Returns the operation type.
498 */
499 OperationType operation() const;
500
501 /**
502 * Sets the @p annotation that is associated with the movie action.
503 */
504 void setAnnotation(MovieAnnotation *annotation);
505
506 /**
507 * Returns the annotation or @c 0 if no annotation has been set.
508 */
509 MovieAnnotation *annotation() const;
510
511private:
512 Q_DECLARE_PRIVATE(MovieAction)
513 Q_DISABLE_COPY(MovieAction)
514};
515
516/**
517 * The Rendition action executes an operation on a video or
518 * executes some JavaScript code on activation.
519 *
520 * @since 0.16 (KDE 4.10)
521 */
522class OKULARCORE_EXPORT RenditionAction : public Action
523{
524public:
525 /**
526 * Describes the possible operation types.
527 */
529 None, ///< Execute only the JavaScript
530 Play, ///< Start playing the video
531 Stop, ///< Stop playing the video
532 Pause, ///< Pause the video
533 Resume ///< Resume playing the video
534 };
535
536 /**
537 * Creates a new rendition action.
538 *
539 * @param operation The type of operation the action executes.
540 * @param movie The movie object the action references.
541 * @param scriptType The type of script the action executes.
542 * @param script The actual script the action executes.
543 */
544 RenditionAction(OperationType operation, Okular::Movie *movie, enum ScriptType scriptType, const QString &script);
545
546 /**
547 * Destroys the rendition action.
548 */
549 ~RenditionAction() override;
550
551 /**
552 * Returns the action type.
553 */
554 ActionType actionType() const override;
555
556 /**
557 * Returns the action tip.
558 */
559 QString actionTip() const override;
560
561 /**
562 * Returns the operation type.
563 */
564 OperationType operation() const;
565
566 /**
567 * Returns the movie object or @c 0 if no movie object was set on construction time.
568 */
569 Okular::Movie *movie() const;
570
571 /**
572 * Returns the type of script.
573 */
574 ScriptType scriptType() const;
575
576 /**
577 * Returns the script code.
578 */
579 QString script() const;
580
581 /**
582 * Sets the @p annotation that is associated with the rendition action.
583 */
584 void setAnnotation(ScreenAnnotation *annotation);
585
586 /**
587 * Returns the annotation or @c 0 if no annotation has been set.
588 */
589 ScreenAnnotation *annotation() const;
590
591private:
592 Q_DECLARE_PRIVATE(RenditionAction)
593 Q_DISABLE_COPY(RenditionAction)
594};
595
596class OKULARCORE_EXPORT BackendOpaqueAction : public Action
597{
598public:
599 enum OpaqueActionResult {
600 DoNothing = 0, ///< @since 24.12 No action needed
601 RefreshForms = 0x01 ///< @since 24.12 Forms need to be refreshed
602 };
603 Q_DECLARE_FLAGS(OpaqueActionResults, OpaqueActionResult)
604
605 BackendOpaqueAction();
606
607 /**
608 * Returns the action type.
609 */
610 ActionType actionType() const override;
611
612private:
613 Q_DISABLE_COPY(BackendOpaqueAction)
614};
615
616}
617
618#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:262
The DocumentAction action contains an action that is performed on the current document.
Definition action.h:301
DocumentActionType
Describes the possible action types.
Definition action.h:306
A view on the document.
Definition document.h:1450
The Execute action executes an external application.
Definition action.h:217
The Goto action changes the viewport to another page or loads an external document.
Definition action.h:151
The Movie action executes an operation on a video on activation.
Definition action.h:469
OperationType
Describes the possible operation types.
Definition action.h:474
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:523
OperationType
Describes the possible operation types.
Definition action.h:528
@ Stop
Stop playing the video.
Definition action.h:531
@ Pause
Pause the video.
Definition action.h:532
@ None
Execute only the JavaScript.
Definition action.h:529
@ Play
Start playing the video.
Definition action.h:530
Screen annotation.
The Script action executes a Script code.
Definition action.h:423
The Sound action plays a sound on activation.
Definition action.h:359
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 Fri Nov 22 2024 12:02:13 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.