okular/core/action.h

   1 /***************************************************************************
   2  *   Copyright (C) 2004 by Enrico Ros <eros.kde@email.it>                  *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  ***************************************************************************/
   9
  10 #ifndef _OKULAR_ACTION_H_
  11 #define _OKULAR_ACTION_H_
  12
  13 #include <okular/core/global.h>
  14 #include <okular/core/okular_export.h>
  15
  16 #include <QtCore/QString>
  17
  18 namespace Okular {
  19
  20 class ActionPrivate;
  21 class GotoActionPrivate;
  22 class ExecuteActionPrivate;
  23 class BrowseActionPrivate;
  24 class DocumentActionPrivate;
  25 class SoundActionPrivate;
  26 class ScriptActionPrivate;
  27 class MovieActionPrivate;
  28 class Sound;
  29 class DocumentViewport;
  30
  31 /**
  32  * @short Encapsulates data that describes an action.
  33  *
  34  * This is the base class for actions. It makes mandatory for inherited
  35  * widgets to reimplement the 'actionType' method and return the type of
  36  * the action described by the reimplemented class.
  37  */
  38 class OKULAR_EXPORT Action
  39 {
  40     public:
  41         /**
  42          * Describes the type of action.
  43          */
  44         enum ActionType {
  45             Goto,       ///< Goto a given page or external document
  46             Execute,    ///< Execute a command or external application
  47             Browse,     ///< Browse a given website
  48             DocAction,  ///< Start a custom action
  49             Sound,      ///< Play a sound
  50             Movie,      ///< Play a movie
  51             Script      ///< Executes a Script code
  52         };
  53
  54         /**
  55          * Destroys the action.
  56          */
  57         virtual ~Action();
  58
  59         /**
  60          * Returns the type of the action. Every inherited class must return
  61          * an unique identifier.
  62          *
  63          * @see ActionType
  64          */
  65         virtual ActionType actionType() const = 0;
  66
  67         /**
  68          * Returns a i18n'ed tip of the action that is presented to
  69          * the user.
  70          */
  71         virtual QString actionTip() const;
  72
  73     protected:
  74         /// @cond PRIVATE
  75         Action( ActionPrivate &dd );
  76         Q_DECLARE_PRIVATE( Action )
  77         ActionPrivate *d_ptr;
  78         /// @endcond
  79
  80     private:
  81         Q_DISABLE_COPY( Action )
  82 };
  83
  84
  85 /**
  86  * The Goto action changes the viewport to another page
  87  * or loads an external document.
  88  */
  89 class OKULAR_EXPORT GotoAction : public Action
  90 {
  91     public:
  92         /**
  93          * Creates a new goto action.
  94          *
  95          * @p fileName The name of an external file that shall be loaded.
  96          * @p viewport The target viewport information of the current document.
  97          */
  98         GotoAction( const QString& fileName, const DocumentViewport & viewport );
  99
 100         /**
 101          * Destroys the goto action.
 102          */
 103         virtual ~GotoAction();
 104
 105         /**
 106          * Returns the action type.
 107          */
 108         ActionType actionType() const;
 109
 110         /**
 111          * Returns the action tip.
 112          */
 113         QString actionTip() const;
 114
 115         /**
 116          * Returns whether the goto action points to an external document.
 117          */
 118         bool isExternal() const;
 119
 120         /**
 121          * Returns the filename of the external document.
 122          */
 123         QString fileName() const;
 124
 125         /**
 126          * Returns the document viewport the goto action points to.
 127          */
 128         DocumentViewport destViewport() const;
 129
 130     private:
 131         Q_DECLARE_PRIVATE( GotoAction )
 132         Q_DISABLE_COPY( GotoAction )
 133 };
 134
 135 /**
 136  * The Execute action executes an external application.
 137  */
 138 class OKULAR_EXPORT ExecuteAction : public Action
 139 {
 140     public:
 141         /**
 142          * Creates a new execute action.
 143          *
 144          * @param fileName The file name of the application to execute.
 145          * @param parameters The parameters of the application to execute.
 146          */
 147         ExecuteAction( const QString &fileName, const QString &parameters );
 148
 149         /**
 150          * Destroys the execute action.
 151          */
 152         virtual ~ExecuteAction();
 153
 154         /**
 155          * Returns the action type.
 156          */
 157         ActionType actionType() const;
 158
 159         /**
 160          * Returns the action tip.
 161          */
 162         QString actionTip() const;
 163
 164         /**
 165          * Returns the file name of the application to execute.
 166          */
 167         QString fileName() const;
 168
 169         /**
 170          * Returns the parameters of the application to execute.
 171          */
 172         QString parameters() const;
 173
 174     private:
 175         Q_DECLARE_PRIVATE( ExecuteAction )
 176         Q_DISABLE_COPY( ExecuteAction )
 177 };
 178
 179 /**
 180  * The Browse action browses an url by opening a web browser or
 181  * email client, depedning on the url protocol (e.g. http, mailto, etc.).
 182  */
 183 class OKULAR_EXPORT BrowseAction : public Action
 184 {
 185     public:
 186         /**
 187          * Creates a new browse action.
 188          *
 189          * @param url The url to browse.
 190          */
 191         BrowseAction( const QString &url );
 192
 193         /**
 194          * Destroys the browse action.
 195          */
 196         virtual ~BrowseAction();
 197
 198         /**
 199          * Returns the action type.
 200          */
 201         ActionType actionType() const;
 202
 203         /**
 204          * Returns the action tip.
 205          */
 206         QString actionTip() const;
 207
 208         /**
 209          * Returns the url to browse.
 210          */
 211         QString url() const;
 212
 213     private:
 214         Q_DECLARE_PRIVATE( BrowseAction )
 215         Q_DISABLE_COPY( BrowseAction )
 216 };
 217
 218 /**
 219  * The DocumentAction action contains an action that is performed on
 220  * the current document.
 221  */
 222 class OKULAR_EXPORT DocumentAction : public Action
 223 {
 224     public:
 225         /**
 226          * Describes the possible action types.
 227          *
 228          * WARNING KEEP IN SYNC WITH POPPLER!
 229          */
 230         enum DocumentActionType {
 231             PageFirst = 1,        ///< Jump to first page
 232             PagePrev = 2,         ///< Jump to previous page
 233             PageNext = 3,         ///< Jump to next page
 234             PageLast = 4,         ///< Jump to last page
 235             HistoryBack = 5,      ///< Go back in page history
 236             HistoryForward = 6,   ///< Go forward in page history
 237             Quit = 7,             ///< Quit application
 238             Presentation = 8,     ///< Start presentation
 239             EndPresentation = 9,  ///< End presentation
 240             Find = 10,            ///< Open find dialog
 241             GoToPage = 11,        ///< Goto page
 242             Close = 12            ///< Close document
 243         };
 244
 245         /**
 246          * Creates a new document action.
 247          *
 248          * @param documentActionType The type of document action.
 249          */
 250         explicit DocumentAction( enum DocumentActionType documentActionType );
 251
 252         /**
 253          * Destroys the document action.
 254          */
 255         virtual ~DocumentAction();
 256
 257         /**
 258          * Returns the action type.
 259          */
 260         ActionType actionType() const;
 261
 262         /**
 263          * Returns the action tip.
 264          */
 265         QString actionTip() const;
 266
 267         /**
 268          * Returns the type of action.
 269          */
 270         DocumentActionType documentActionType() const;
 271
 272     private:
 273         Q_DECLARE_PRIVATE( DocumentAction )
 274         Q_DISABLE_COPY( DocumentAction )
 275 };
 276
 277 /**
 278  * The Sound action plays a sound on activation.
 279  */
 280 class OKULAR_EXPORT SoundAction : public Action
 281 {
 282     public:
 283         /**
 284          * Creates a new sound action.
 285          *
 286          * @param volume The volume of the sound.
 287          * @param synchronous Whether the sound shall be played synchronous.
 288          * @param repeat Whether the sound shall be repeated.
 289          * @param mix Whether the sound shall be mixed.
 290          * @param sound The sound object which contains the sound data.
 291          */
 292         SoundAction( double volume, bool synchronous, bool repeat, bool mix, Okular::Sound *sound );
 293
 294         /**
 295          * Destroys the sound action.
 296          */
 297         virtual ~SoundAction();
 298
 299         /**
 300          * Returns the action type.
 301          */
 302         ActionType actionType() const;
 303
 304         /**
 305          * Returns the action tip.
 306          */
 307         QString actionTip() const;
 308
 309         /**
 310          * Returns the volume of the sound.
 311          */
 312         double volume() const;
 313
 314         /**
 315          * Returns whether the sound shall be played synchronous.
 316          */
 317         bool synchronous() const;
 318
 319         /**
 320          * Returns whether the sound shall be repeated.
 321          */
 322         bool repeat() const;
 323
 324         /**
 325          * Returns whether the sound shall be mixed.
 326          */
 327         bool mix() const;
 328
 329         /**
 330          * Returns the sound object which contains the sound data.
 331          */
 332         Okular::Sound *sound() const;
 333
 334     private:
 335         Q_DECLARE_PRIVATE( SoundAction )
 336         Q_DISABLE_COPY( SoundAction )
 337 };
 338
 339 /**
 340  * The Script action executes a Script code.
 341  *
 342  * @since 0.7 (KDE 4.1)
 343  */
 344 class OKULAR_EXPORT ScriptAction : public Action
 345 {
 346     public:
 347         /**
 348          * Creates a new Script action.
 349          *
 350          * @param script The code to execute.
 351          */
 352         ScriptAction( enum ScriptType type, const QString &script );
 353
 354         /**
 355          * Destroys the browse action.
 356          */
 357         virtual ~ScriptAction();
 358
 359         /**
 360          * Returns the action type.
 361          */
 362         ActionType actionType() const;
 363
 364         /**
 365          * Returns the action tip.
 366          */
 367         QString actionTip() const;
 368
 369         /**
 370          * Returns the type of action.
 371          */
 372         ScriptType scriptType() const;
 373
 374         /**
 375          * Returns the code.
 376          */
 377         QString script() const;
 378
 379     private:
 380         Q_DECLARE_PRIVATE( ScriptAction )
 381         Q_DISABLE_COPY( ScriptAction )
 382 };
 383
 384 #if 0
 385 /**
 386  * The Movie action plays a video on activation.
 387  */
 388 class MovieAction : public Action
 389 {
 390     public:
 391         /**
 392          * Creates a new movie action.
 393          */
 394         MovieAction();
 395
 396         /**
 397          * Destroys the movie action.
 398          */
 399         virtual ~MovieAction();
 400
 401         /**
 402          * Returns the action type.
 403          */
 404         ActionType actionType() const;
 405
 406         /**
 407          * Returns the action tip.
 408          */
 409         QString actionTip() const;
 410
 411     private:
 412         Q_DECLARE_PRIVATE( MovieAction )
 413         Q_DISABLE_COPY( MovieAction )
 414 };
 415 #endif
 416
 417 }
 418
 419 #endif