From 1ee799e29e90a0734ee40153315409c7a320a6bc Mon Sep 17 00:00:00 2001
From: Robert Zubeck <robert@threerings.net>
Date: Tue, 20 Nov 2007 01:38:02 +0000
Subject: [PATCH] Helpful utility classes for game creators.

git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@505 c613c5cb-e716-0410-b11b-feb51c14d237
---
 src/as/com/threerings/ezgame/util/GameMode.as |  35 ++++++
 .../threerings/ezgame/util/GameModeStack.as   | 102 ++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 src/as/com/threerings/ezgame/util/GameMode.as
 create mode 100644 src/as/com/threerings/ezgame/util/GameModeStack.as

diff --git a/src/as/com/threerings/ezgame/util/GameMode.as b/src/as/com/threerings/ezgame/util/GameMode.as
new file mode 100644
index 00000000..44fd9839
--- /dev/null
+++ b/src/as/com/threerings/ezgame/util/GameMode.as
@@ -0,0 +1,35 @@
+//
+// $Id$
+
+package com.whirled.util
+{
+
+/**
+ * Interface for game modes, handled by the GameModeManager. Game modes are notified when they
+ * become activated and deactivated, so that they can adjust themselves accordingly.
+ */
+public interface GameMode
+{
+    /**
+     * Called when this instance of GameMode is added to the top of the stack.
+     */
+    function pushed () :void;
+
+    /**
+     * Called when this instance of GameMode is removed from the top of the stack.
+     */
+    function popped () :void;
+
+    /**
+     * Called when this instance of GameMode was the top of the stack, but another instance
+     * is being pushed on top of it.
+     */
+    function pushedOnto (mode :GameMode) :void;
+
+    /**
+     * Called when another instance is being removed from the top of the stack,
+     * making this instance the new top.
+     */
+    function poppedFrom (mode :GameMode) :void;
+}
+}
diff --git a/src/as/com/threerings/ezgame/util/GameModeStack.as b/src/as/com/threerings/ezgame/util/GameModeStack.as
new file mode 100644
index 00000000..ef29d3c0
--- /dev/null
+++ b/src/as/com/threerings/ezgame/util/GameModeStack.as
@@ -0,0 +1,102 @@
+//
+// $Id$
+
+package com.whirled.util {
+    
+import flash.display.DisplayObject;
+
+/**
+ * GameModeStack implements a stack of user-specific <i>game modes</i>. Modes can be pushed on to
+ * or popped off of the stack. Whenever a new mode is pushed on the stack, the old top is cleaned
+ * up, and the new one is initialized; vice versa for popping a mode off the stack.
+ *
+ * Usage example:
+ * <pre>
+ *   var mgr :GameModeStack = new GameModeStack(switchDisplayFn);
+ *   mgr.push(new MainMenu());
+ *   ...
+ *   // in the main menu, we decide to pick a level
+ *   mgr.push(new LevelSelectorScreen());
+ *   ...
+ *   // inside the level selector, we start the game:
+ *   mgr.push(new GameScreen());
+ *   ...
+ *   // inside the game screen, once it was won or lost:
+ *   mgr.pop();
+ * </pre>
+ */
+public class GameModeStack 
+{
+    /**
+     * Constructor, receives a function to be called whenever the top of the stack changes.
+     *
+     * @param callback Called whenever the top of the stack changes. Should be a function like:
+     *   function (previousTop :GameMode, newTop :GameMode) :void { }
+     *   - where previousTop is the mode previously selected, and newTop is the mode currently
+     *   selected (either can be null).
+     */
+    public function GameModeStack (callback :Function)
+    {
+        _callback = callback;
+    }
+
+    /** Returns the top of the mode stack. If the stack is empty, returns null. */
+    public function top () :GameMode
+    {
+        return (_stack.length > 0) ? _stack[0] : null; 
+    }
+
+    /** Pops all items off the stack. */
+    public function clear () :void
+    {
+        while (top() != null) {
+            pop();
+        }
+    }
+
+    /**
+     * Pushes a new game mode on top of the stack. 
+     */
+    public function push (newMode :GameMode) :void
+    {
+        var oldMode :GameMode = top();
+        if (oldMode != null) {
+            oldMode.pushedOnto(newMode);
+        }
+        
+        _stack.unshift(newMode);
+        newMode.pushed();
+
+        _callback(oldMode, newMode);
+    }
+
+    /**
+     * Pops and returns the current top game mode from the stack. Popping an empty stack is safe,
+     * it simply returns null.
+     */
+    public function pop () :GameMode
+    {
+        var oldMode :GameMode = top();
+        if (oldMode == null) {
+            return null;
+        }
+
+        _stack.shift();
+        oldMode.popped();
+
+        var newMode :GameMode = top();
+        if (newMode != null) {
+            newMode.poppedFrom(oldMode);
+        }
+
+        _callback(oldMode, newMode);
+        return oldMode;
+    }
+
+    /** Function that will be called every time the stack changes. */
+    protected var _callback :Function;
+    
+    /** Internal storage for the stack. */
+    protected var _stack :Array = new Array(); // of GameModes
+}
+}