simgear/structure/StateMachine.hxx

   1 /* -*-c++-*-
   2  *
   3  * Copyright (C) 2013 James Turner
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License as
   7  * published by the Free Software Foundation; either version 2 of the
   8  * License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  18  * MA 02110-1301, USA.
  19  *
  20  */
  21
  22 #ifndef SIMGEAR_STATE_MACHINE_H
  23 #define SIMGEAR_STATE_MACHINE_H
  24
  25 #include <memory>
  26 #include <string>
  27
  28 #include <simgear/structure/SGReferenced.hxx>
  29 #include <simgear/structure/SGSharedPtr.hxx>
  30
  31 // forward decls
  32 class SGPropertyNode;
  33 class SGBinding;
  34 class SGCondition;
  35
  36 namespace simgear
  37 {
  38
  39 class StateMachine : public SGReferenced
  40 {
  41 public:
  42     StateMachine();
  43     virtual ~StateMachine();
  44
  45     class State : public SGReferenced
  46     {
  47     public:
  48         virtual ~State();
  49
  50         std::string name() const;
  51
  52         void addUpdateBinding(SGBinding* aBinding);
  53         void addEntryBinding(SGBinding* aBinding);
  54         void addExitBinding(SGBinding* aBinding);
  55
  56     private:
  57         friend class StateMachine;
  58
  59         State(const std::string& name);
  60
  61         void fireExitBindings();
  62         void fireEntryBindings();
  63
  64         void update();
  65
  66         class StatePrivate;
  67         std::auto_ptr<StatePrivate> d;
  68     };
  69
  70     class Transition : public SGReferenced
  71     {
  72     public:
  73         virtual ~Transition();
  74
  75         std::string name() const;
  76
  77         /**
  78          * The state we end in, after this transition fires
  79          */
  80         State* target() const;
  81
  82         /**
  83          * Add a state in which this transition is eligible to fire
  84          */
  85         void addSourceState(State* aSource);
  86
  87         /**
  88          * Specify the transition trigger condition. Takes ownership
  89          */
  90         void setTriggerCondition(SGCondition* aCondition);
  91
  92
  93         void addBinding(SGBinding* aBinding);
  94     private:
  95         friend class StateMachine;
  96
  97         Transition(const std::string& aName, State* aTarget);
  98
  99         /**
 100          * predicate to determine if this transition can fire given a
 101          * current state.
 102          */
 103         bool applicableForState(State* aCurrent) const;
 104
 105         /**
 106         * test if the transition should fire, based on current state
 107         */
 108         bool evaluate() const;
 109
 110         void fireBindings();
 111
 112         class TransitionPrivate;
 113         std::auto_ptr<TransitionPrivate> d;
 114     };
 115
 116     typedef SGSharedPtr<State> State_ptr;
 117     typedef SGSharedPtr<Transition> Transition_ptr;
 118
 119     /**
 120      * create a state machine from a property list description
 121      */
 122     static StateMachine* createFromPlist(SGPropertyNode* desc, SGPropertyNode* root);
 123
 124     SGPropertyNode* root();
 125
 126     void init();
 127     void shutdown();
 128
 129     void update(double dt);
 130
 131     State_ptr state() const;
 132
 133     /**
 134      * public API to force a change to a particular state.
 135      * @param aOnlyIfDifferent - only make a transition if the new state is
 136      *   different from the current state. Otherwise, the existing state will
 137      * be exited and re-entered.
 138      */
 139     void changeToState(State_ptr aState, bool aOnlyIfDifferent=true);
 140
 141      /// wrapper to change state by looking up a name
 142     void changeToStateName(const std::string& aName, bool aOnlyIfDifferent=true);
 143
 144     State_ptr findStateByName(const std::string& aName) const;
 145
 146     State_ptr stateByIndex(unsigned int aIndex) const;
 147
 148     int indexOfState(State_ptr aState) const;
 149
 150     // programatic creation
 151     State_ptr createState(const std::string& aName);
 152     Transition_ptr createTransition(const std::string& aName, State_ptr aTarget);
 153 private:
 154     void addState(State_ptr aState);
 155     void addTransition(Transition_ptr aTrans);
 156
 157     void innerChangeState(State_ptr aState, Transition_ptr aTrans);
 158
 159     class StateMachinePrivate;
 160     std::auto_ptr<StateMachinePrivate> d;
 161 };
 162
 163 typedef SGSharedPtr<StateMachine> StateMachine_ptr;
 164
 165 } // of simgear namespace
 166
 167 #endif // of SIMGEAR_STATE_MACHINE_H