src/framework/activity.hpp

   1 /*
   2  * Copyright (c) 2007-2013, Czirkos Zoltan http://code.google.com/p/gdash/
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  19  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  20  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  21  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22  */
  23
  24 #ifndef ACTIVITY_HPP_INCLUDED
  25 #define ACTIVITY_HPP_INCLUDED
  26
  27 #include "config.h"
  28
  29 class App;
  30
  31 /**
  32  * @ingroup Framework
  33  * @brief An activity object is a mini-application controlled by the user in the
  34  * game - for example the title screen, a file selection dialog or the game
  35  * playing.
  36  *
  37  * The activity objects are managed by an App object, which organizes them in
  38  * a stack. Every user event (keypress etc.) is always sent to the topmost activity,
  39  * which is an instance of a derived class of this Activity class.
  40  *
  41  * Activities are free to do just like anything to the screen. They can measure time
  42  * by overloading the Activity::timer_event() function; they can receive keypresses
  43  * by overloading the Activity::keypress_event() function. They are notified when
  44  * they become the topmost one by calling their Activity::shown_event() method,
  45  * and when occluded by a new activity, by their Activity::hidden_event() method.
  46  * Their redraw_event() is called by the App object, when they must redraw the screen.
  47  *
  48  * Activities can enqueue Command objects in the queue of the App. After calling any
  49  * of the event methods, the App will check if there are any commands enqueued. If so,
  50  * they are executed, and this way the activities can control the flow of the whole
  51  * application.
  52  */
  53 class Activity {
  54 public:
  55     /** The keycode given to an activity is either one of the
  56      * App::KeyCodeSpecialKey codes, or a Unicode encoded character. */
  57     typedef unsigned KeyCode;
  58     /** Construct an activity.
  59      * @param app The App, in which the activity will run. */
  60     Activity(App *app) : app(app), redraw_queued(false) {}
  61     /** Virtual destructor.
  62      * Pure virtual, but implemented in the cpp file: a trick to make
  63      * this an abstract base class. */
  64     virtual ~Activity() = 0;
  65
  66 private:
  67     /**
  68      * Inform the Activity object about time elapsing.
  69      * @param ms_elapsed The number of milliseconds elapsed. These are
  70      * usually not real milliseconds, but the interval of the timer used
  71      * by the App. */
  72     virtual void timer_event(int ms_elapsed);
  73     /**
  74      * This is another timer, which is seldom used. It is called only in
  75      * replay video saving mode, and implemented only by the
  76      * ReplaySaverActivity class. The timer2 events are generated there
  77      * by the SDL_Mixer library, to use the audio mixing routine for the
  78      * cave replay to be totally in sync with the framerate of the game. */
  79     virtual void timer2_event();
  80     /**
  81      * A key pressed, sent to the Activity.
  82      * @param keycode a unicode character code, or some special key (see KeyCodeSpecialKey)
  83      * @param gfxlib_keycode graphics library specific keycode (sdl/gtk/etc). This is
  84      * here so the Activity can know it and also catch it, to be able to configure the
  85      * GameInputHandler object.
  86      */
  87     virtual void keypress_event(KeyCode keycode, int gfxlib_keycode);
  88     /**
  89      * Called by the App to request the topmost Activity to redraw the screen.
  90      * The state of the Activity should not change, as it may be called any time.
  91      * When the Activity becomes the topmost one, this is called by the App
  92      * automatically. Activities should not call their own redraw_event() methods.
  93      */
  94     virtual void redraw_event(bool full) const = 0;
  95     /**
  96      * Called by the App when the Activity gets pushed into the stack of activities
  97      * of the App. The Activity can perform some post-initialization, it may even
  98      * pop itself. The Command
  99      * objects enqueued in this event will be executed when the Activity is already
 100      * in the stack, so new activities they may create will be above it in the stack.
 101      * An activity will only receive one pushed_event() in its lifetime. */
 102     virtual void pushed_event();
 103     /**
 104      * Called by the App when the activities occluding the current activities have
 105      * disappeared. May perform any actions, but it is not necessary to do a redraw,
 106      * because the redraw_event will also be called. An activity may receive many
 107      * shown_event()-s in its lifetime. */
 108     virtual void shown_event();
 109     /**
 110      * Called by the App when the Activity is occluded by a new one. May free some
 111      * resources, for example, to be reacquired later, when the Acitivity becomes
 112      * topmost again. An activity may be sent many shown_event()-s in its lifetime. */
 113     virtual void hidden_event();
 114
 115 protected:
 116     friend class App;
 117     /** The owner app. Used for enqueueing Command objects, for example. */
 118     App *app;
 119     /** There is something to draw. */
 120     bool redraw_queued;
 121     /** Event handlers can call this function to tell the App that a redraw should be done.
 122      * Redraws are processed after all events and commands. */
 123     void queue_redraw() {
 124         redraw_queued = true;
 125     }
 126
 127 private:
 128     Activity(Activity const &);       ///< Not meant to be copied.
 129     void operator=(Activity const &); ///< Not meant to be assigned.
 130
 131 };
 132
 133 #endif // GD_ACTIVITY_H