src/framework/activity.hpp

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