Fix Enter Actions section in State.

Author: munificent

book/state.markdown

@@ -359,36 +359,35 @@ The <a href="object-pool.html" class="pattern">Object Pool</a> pattern can help.
 ## Enter and Exit Actions
 
 The goal of the State pattern is to encapsulate all of the behavior and data for
-one state in a single class. We've done that pretty well, but there's still a
-loose end. We moved handling user input and updating the charge time into
-`DuckingState`, but there's a bit of ducking-specific code left outside. Over in
-the standing state, when we *start* ducking, it does some initialization:
+one state in a single class. We're partway there, but we still have
+some loose ends.
 
-^code start-ducking
+When the heroine changes state, we also switch her sprite. Right now, that code is owned by the state she's switching *from*. When she goes from ducking to standing, the ducking state sets her image:
 
-The ducking state should take care of resetting the charge time (after
-all, it's the object that has that field) and playing the animation. We can
+^code enter-standing-before
+
+What we really want is each state to control its own graphics. We can
 handle that by giving the state an *entry action*:
 
-^code ducking-with-enter
+^code standing-with-enter
 
-Back in `Heroine`, we wrap changing the state in a little convenience method
-that calls that on the new state:
+Back in `Heroine`, we modify the code for handling state changes to call that
+on the new state:
 
 ^code change-state
 
-In the standing code we use it like:
+This lets us simplify the ducking code to:
 
-^code enter-ducking
+^code enter-standing
 
-Now ducking really is encapsulated. One particularly nice thing about entry
-actions is that they run when you enter the state regardless of which state
-you're coming *from*.
+All it does is switch to standing and the standing state takes care of
+the graphics. Now our states really are encapsulated. One particularly nice thing
+about entry actions is that they run when you enter the state regardless of
+which state you're coming *from*.
 
 Most real-world state graphs have multiple transitions into the same state. For
-example, maybe our heroine can fire her weapon while standing, ducking, and
-jumping. That means you end up duplicating some code everywhere that transition
-occurs. Entry actions give you a place to consolidate that.
+example, our heroine will also end up standing after she lands a jump or dive. That means we would end up duplicating some code everywhere that transition
+occurs. Entry actions give us a place to consolidate that.
 
 We can, of course, also extend this to support an *exit action*. This is just a
 method we call on the state we're *leaving* right before we switch to the new

code/cpp/state.h

@@ -517,12 +517,14 @@ namespace State
       friend class JumpingState;
     public:
       void setGraphics(Animate animate) {}
+      void changeState(HeroineState* state) {}
     private:
       HeroineState* state_;
     };
 
     class StandingState : public HeroineState {};
     class DuckingState : public HeroineState {};
+
     class JumpingState : public HeroineState {
       void handleInput(Heroine& heroine, Input input)
       {
@@ -538,6 +540,42 @@ namespace State
     class DivingState : public HeroineState {};
   }
 
+  namespace EnterActionsBefore
+  {
+    class HeroineState {};
+
+    class Heroine
+    {
+      friend class JumpingState;
+    public:
+      void setGraphics(Animate animate) {}
+      void changeState(HeroineState* state) {}
+    };
+
+    class StandingState : public HeroineState {};
+    class DuckingState : public HeroineState {
+    public:
+      HeroineState* handleInput(Heroine& heroine, Input input);
+    };
+
+    //^enter-standing-before
+    HeroineState* DuckingState::handleInput(Heroine& heroine,
+                                            Input input)
+    {
+      if (input == RELEASE_DOWN)
+      {
+        heroine.setGraphics(IMAGE_STAND);
+        return new StandingState();
+      }
+
+      // Other code...
+      //^omit
+      return NULL;
+      //^omit
+    }
+    //^enter-standing-before
+  }
+
   namespace EnterActions
   {
     class Heroine;
@@ -547,67 +585,70 @@ namespace State
     public:
       virtual ~HeroineState() {}
       virtual void enter(Heroine& heroine) {}
-      virtual void handleInput(Heroine& heroine, Input input) {}
-      virtual void update(Heroine& heroine) {}
+      virtual HeroineState* handleInput(Heroine& heroine, Input input)
+      {
+        return NULL;
+      }
     };
 
     class Heroine
     {
     public:
+      void handleInput(Input input);
       void setGraphics(Animate animate) {}
-      void superBomb() {}
-      void changeState(HeroineState* state);
     private:
       HeroineState* state_;
-      double yVelocity_;
     };
 
-    //^ducking-with-enter
-    class DuckingState : public HeroineState
+    //^standing-with-enter
+    class StandingState : public HeroineState
     {
     public:
-      //^omit
-      DuckingState()
-      : chargeTime_(0)
-      {}
-
-      //^omit
       virtual void enter(Heroine& heroine)
       {
-        chargeTime_ = 0;
-        heroine.setGraphics(IMAGE_DUCK);
+        heroine.setGraphics(IMAGE_STAND);
       }
 
       // Other code...
-      //^omit
-    private:
-      int chargeTime_;
-      //^omit
     };
-    //^ducking-with-enter
+    //^standing-with-enter
 
     //^change-state
-    void Heroine::changeState(HeroineState* state)
+    void Heroine::handleInput(Input input)
     {
-      delete state_;
-      state_ = state;
-      state_->enter(*this);
+      HeroineState* state = state_->handleInput(*this, input);
+      if (state != NULL)
+      {
+        delete state_;
+        state_ = state;
+
+        // Call the enter action on the new state.
+        state_->enter(*this);
+      }
     }
     //^change-state
 
-    class StandingState : public HeroineState
+    class DuckingState : public HeroineState
     {
     public:
-      virtual void handleInput(Heroine& heroine, Input input)
+      virtual HeroineState* handleInput(Heroine& heroine, Input input);
+    };
+
+    //^enter-standing
+    HeroineState* DuckingState::handleInput(Heroine& heroine,
+                                            Input input)
+    {
+      if (input == RELEASE_DOWN)
       {
-        //^enter-ducking
-        if (input == PRESS_DOWN)
-        {
-          heroine.changeState(new DuckingState());
-        }
-        //^enter-ducking
+        return new StandingState();
       }
-    };
+
+      // Other code...
+      //^omit
+      return NULL;
+      //^omit
+    }
+    //^enter-standing
   }
 
   namespace Concurrent

html/state.html

@@ -592,63 +592,76 @@ <h3><a href="#instantiated-states" name="instantiated-states">Instantiated state
 
 <h2><a href="#enter-and-exit-actions" name="enter-and-exit-actions">Enter and Exit Actions</a></h2>
 <p>The goal of the State pattern is to encapsulate all of the behavior and data for
-one state in a single class. We&#8217;ve done that pretty well, but there&#8217;s still a
-loose end. We moved handling user input and updating the charge time into
-<code>DuckingState</code>, but there&#8217;s a bit of ducking-specific code left outside. Over in
-the standing state, when we <em>start</em> ducking, it does some initialization:</p>
-<div class="codehilite"><pre><span class="c1">// In standing state:</span>
-<span class="k">if</span> <span class="p">(</span><span class="n">input</span> <span class="o">==</span> <span class="n">PRESS_DOWN</span><span class="p">)</span>
+one state in a single class. We&#8217;re partway there, but we still have
+some loose ends.</p>
+<p>When the heroine changes state, we also switch her sprite. Right now, that code is owned by the state she&#8217;s switching <em>from</em>. When she goes from ducking to standing, the ducking state sets her image:</p>
+<div class="codehilite"><pre><span class="n">HeroineState</span><span class="o">*</span> <span class="n">DuckingState</span><span class="o">::</span><span class="n">handleInput</span><span class="p">(</span><span class="n">Heroine</span><span class="o">&amp;</span> <span class="n">heroine</span><span class="p">,</span>
+                                        <span class="n">Input</span> <span class="n">input</span><span class="p">)</span>
 <span class="p">{</span>
-  <span class="c1">// Change state...</span>
-  <span class="n">chargeTime_</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
-  <span class="n">setGraphics</span><span class="p">(</span><span class="n">IMAGE_DUCK</span><span class="p">);</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">input</span> <span class="o">==</span> <span class="n">RELEASE_DOWN</span><span class="p">)</span>
+  <span class="p">{</span>
+    <span class="n">heroine</span><span class="p">.</span><span class="n">setGraphics</span><span class="p">(</span><span class="n">IMAGE_STAND</span><span class="p">);</span>
+    <span class="k">return</span> <span class="k">new</span> <span class="nf">StandingState</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="c1">// Other code...</span>
 <span class="p">}</span>
 </pre></div>
 
 
-<p>The ducking state should take care of resetting the charge time (after
-all, it&#8217;s the object that has that field) and playing the animation. We can
+<p>What we really want is each state to control its own graphics. We can
 handle that by giving the state an <em>entry action</em>:</p>
-<div class="codehilite"><pre><span class="k">class</span> <span class="nc">DuckingState</span> <span class="o">:</span> <span class="k">public</span> <span class="n">HeroineState</span>
+<div class="codehilite"><pre><span class="k">class</span> <span class="nc">StandingState</span> <span class="o">:</span> <span class="k">public</span> <span class="n">HeroineState</span>
 <span class="p">{</span>
 <span class="nl">public:</span>
   <span class="k">virtual</span> <span class="kt">void</span> <span class="n">enter</span><span class="p">(</span><span class="n">Heroine</span><span class="o">&amp;</span> <span class="n">heroine</span><span class="p">)</span>
   <span class="p">{</span>
-    <span class="n">chargeTime_</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
-    <span class="n">heroine</span><span class="p">.</span><span class="n">setGraphics</span><span class="p">(</span><span class="n">IMAGE_DUCK</span><span class="p">);</span>
+    <span class="n">heroine</span><span class="p">.</span><span class="n">setGraphics</span><span class="p">(</span><span class="n">IMAGE_STAND</span><span class="p">);</span>
   <span class="p">}</span>
 
   <span class="c1">// Other code...</span>
 <span class="p">};</span>
 </pre></div>
 
 
-<p>Back in <code>Heroine</code>, we wrap changing the state in a little convenience method
-that calls that on the new state:</p>
-<div class="codehilite"><pre><span class="kt">void</span> <span class="n">Heroine</span><span class="o">::</span><span class="n">changeState</span><span class="p">(</span><span class="n">HeroineState</span><span class="o">*</span> <span class="n">state</span><span class="p">)</span>
+<p>Back in <code>Heroine</code>, we modify the code for handling state changes to call that
+on the new state:</p>
+<div class="codehilite"><pre><span class="kt">void</span> <span class="n">Heroine</span><span class="o">::</span><span class="n">handleInput</span><span class="p">(</span><span class="n">Input</span> <span class="n">input</span><span class="p">)</span>
 <span class="p">{</span>
-  <span class="k">delete</span> <span class="n">state_</span><span class="p">;</span>
-  <span class="n">state_</span> <span class="o">=</span> <span class="n">state</span><span class="p">;</span>
-  <span class="n">state_</span><span class="o">-&gt;</span><span class="n">enter</span><span class="p">(</span><span class="o">*</span><span class="k">this</span><span class="p">);</span>
+  <span class="n">HeroineState</span><span class="o">*</span> <span class="n">state</span> <span class="o">=</span> <span class="n">state_</span><span class="o">-&gt;</span><span class="n">handleInput</span><span class="p">(</span><span class="o">*</span><span class="k">this</span><span class="p">,</span> <span class="n">input</span><span class="p">);</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">state</span> <span class="o">!=</span> <span class="nb">NULL</span><span class="p">)</span>
+  <span class="p">{</span>
+    <span class="k">delete</span> <span class="n">state_</span><span class="p">;</span>
+    <span class="n">state_</span> <span class="o">=</span> <span class="n">state</span><span class="p">;</span>
+
+    <span class="c1">// Call the enter action on the new state.</span>
+    <span class="n">state_</span><span class="o">-&gt;</span><span class="n">enter</span><span class="p">(</span><span class="o">*</span><span class="k">this</span><span class="p">);</span>
+  <span class="p">}</span>
 <span class="p">}</span>
 </pre></div>
 
 
-<p>In the standing code we use it like:</p>
-<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="n">input</span> <span class="o">==</span> <span class="n">PRESS_DOWN</span><span class="p">)</span>
+<p>This lets us simplify the ducking code to:</p>
+<div class="codehilite"><pre><span class="n">HeroineState</span><span class="o">*</span> <span class="n">DuckingState</span><span class="o">::</span><span class="n">handleInput</span><span class="p">(</span><span class="n">Heroine</span><span class="o">&amp;</span> <span class="n">heroine</span><span class="p">,</span>
+                                        <span class="n">Input</span> <span class="n">input</span><span class="p">)</span>
 <span class="p">{</span>
-  <span class="n">heroine</span><span class="p">.</span><span class="n">changeState</span><span class="p">(</span><span class="k">new</span> <span class="n">DuckingState</span><span class="p">());</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">input</span> <span class="o">==</span> <span class="n">RELEASE_DOWN</span><span class="p">)</span>
+  <span class="p">{</span>
+    <span class="k">return</span> <span class="k">new</span> <span class="n">StandingState</span><span class="p">();</span>
+  <span class="p">}</span>
+
+  <span class="c1">// Other code...</span>
 <span class="p">}</span>
 </pre></div>
 
 
-<p>Now ducking really is encapsulated. One particularly nice thing about entry
-actions is that they run when you enter the state regardless of which state
-you&#8217;re coming <em>from</em>.</p>
+<p>All it does is switch to standing and the standing state takes care of
+the graphics. Now our states really are encapsulated. One particularly nice thing
+about entry actions is that they run when you enter the state regardless of
+which state you&#8217;re coming <em>from</em>.</p>
 <p>Most real-world state graphs have multiple transitions into the same state. For
-example, maybe our heroine can fire her weapon while standing, ducking, and
-jumping. That means you end up duplicating some code everywhere that transition
-occurs. Entry actions give you a place to consolidate that.</p>
+example, our heroine will also end up standing after she lands a jump or dive. That means we would end up duplicating some code everywhere that transition
+occurs. Entry actions give us a place to consolidate that.</p>
 <p>We can, of course, also extend this to support an <em>exit action</em>. This is just a
 method we call on the state we&#8217;re <em>leaving</em> right before we switch to the new
 state.</p>