src/StateObject.hh

   1 /*
   2  * Copyright (C) 2007,2008 Ronald Lamprecht
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  */
  19 #ifndef STATEOBJECT_HH
  20 #define STATEOBJECT_HH
  21
  22 #include "Object.hh"
  23
  24
  25 namespace enigma {
  26
  27     /**
  28      * The base class for all gaming objects that have different states that
  29      * can be toggled by means of messages, actions or attribute settings.
  30      * This class is the successor of the former OnOffStone and OnOffItem.
  31      * Being a superclass of all gaming objects it provides a common interface
  32      * for the handling of states. The state is not limited to 2 states like
  33      * the common on/off and open/close. Arbitrary number of external states
  34      * are supported. E.g. FourSwitches have 4 states that describe the current
  35      * direction.<p>
  36      * But the external state - the logical gaming state used in level lua code -
  37      * is often just a small subset of states that an object has to distinguish.
  38      * Additional display related states, timer related states and internal
  39      * gaming logic states require sometimes a much more complex state machine.
  40      * <p>
  41      * The maximum set of states that we call the internal state of a final
  42      * gaming object class should be stored in StateObjects state ivar. It is
  43      * the responsibility of StateObject to guarantee the persistence and
  44      * cloning of the internal state.<p>
  45      * StateObject provides the common interface for state management with hooks
  46      * for all needs like conversion of external to and from internal states,
  47      * common messages like toggle, signal, on, off, open, close and checked
  48      * setter and getter for the state as a pseudo attribute.<p>
  49      * Furtheron its default implementation suits the needs a simple 2 state
  50      * on/off or open/close object. More complex stated objects will need to
  51      * override the hook methods to their needs.
  52      */
  53     class StateObject : public Object {
  54     public:
  55         StateObject();
  56         StateObject(const char * kind);
  57
  58         // Object Interface
  59
  60         /**
  61          * Handle the messages "toggle", "signal", "on", "off", "open", "close".
  62          * Any subclass should forward these messages to its superclass without
  63          * interfering these messages. Per default these messages will be blocked
  64          * by SendMessage() if they are not explicitly declared for the final
  65          * subclass in objects.xml.
  66          */
  67         virtual Value message(const Message &m);
  68
  69         /**
  70          * Handle the attribute "state" by a pseudo implementation. Subclasses
  71          * shall not interfere with this attribute but override the method
  72          * "externalState()" on demand.
  73          */
  74         virtual Value getAttr(const string &key) const;
  75
  76         /**
  77          * Handle the attribute "state" by a pseudo implementation. Subclasses
  78          * shall not interfere with this attribute but override the method
  79          * "setState()". New state values are checked against min and max.
  80          */
  81         virtual void setAttr(const string& key, const Value &val);
  82
  83     protected:
  84         /**
  85          * The storage location of the internal state. This ivar is logically
  86          * owned by the final discrete object class which will define in most
  87          * cases an enum called iState that lists all states. All intermediate
  88          * classes between StateObject and the state owning subclass will just
  89          * be aware of the external state that they access via the setter and
  90          * getter methods. Just these two methods in their StateObject default
  91          * implementation will directly access this ivar (besides the gaming
  92          * logic indepent persistence and cloning methods).
  93          */
  94         int state;
  95
  96         /**
  97          * The maximum number of the external state. It defaults to 1, and
  98          * should be overridden by the final subclass just on demand.
  99          */
 100         virtual int maxState() const;
 101
 102         /**
 103          * The minimum number of the external state. It defaults to 0, and
 104          * should be overridden by the final subclass just on demand.
 105          */
 106         virtual int minState() const;
 107
 108         /**
 109          * The method that is called on toggle messages to switch the object
 110          * to the next external state. The default implementation is a round
 111          * robin of the external state from minState() to maxState() and returning
 112          * to minState() again. Override this method if the toggle operation
 113          * changes the states in another sequence..
 114          */
 115         virtual void toggleState();
 116
 117         /**
 118          * Access method that translates the internal state stored in "state" to
 119          * the external gaming logic state. The default implementation is a
 120          * direct return of the state which suits a one to one mapping between
 121          * internal and external states. If additional internal states or another
 122          * mapping is used this method needs to be overwritten. All access to
 123          * the external state by any other intermediate class has to use this
 124          * method.
 125          */
 126         virtual int externalState() const;
 127
 128         /**
 129          * Setter method for external state that switches the object to the
 130          * appropriate internal state. The default implementation is a direct
 131          * storage of the external state as the internal state. Most final
 132          * subclasses will have to override this method to cause some actions,
 133          * to send messages and to switch the display model.
 134          */
 135         virtual void setState(int extState);
 136     };
 137
 138 } // namespace enigma
 139
 140 #endif