Merge branch 'release/1.2.0'

Author: rm-code

Readme.md

@@ -1 +1,73 @@
-#ScreenManager
+#ScreenManager
+
+The ScreenManager library is a state manager at heart which allows some nifty things, like stacking multiple screens on top of each other.
+
+It also offers hooks for most of LÖVE's callback functions. Based on the type of callback the calls are rerouted to either only the active screen (love.keypressed, love.quit, ...) or to all screens (love.resize, love.visible, ...).
+
+## Example
+
+This is a simple example of how the ScreenManager should be used (note: You will have to change the paths in the example to fit your setup). 
+
+```
+#!lua
+-- main.lua
+
+local ScreenManager = require('lib/ScreenManager');
+
+function love.load()
+    local screens = {
+        main = require('src/screens/MainScreen');
+    };
+
+    ScreenManager.init(screens, 'main');
+end
+
+function love.draw()
+    ScreenManager.draw();
+end
+
+function love.update(dt)
+    ScreenManager.update(dt);
+end
+```
+Note how MainScreen inherits from Screen.lua. This isn't mandatory, but recommended since Screen.lua already has templates for most of the callback functions.
+
+```
+#!lua
+-- MainScreen.lua
+
+local Screen = require('lib/Screen');
+
+local MainScreen = {};
+
+function MainScreen.new()
+    local self = Screen.new();
+
+    local x, y, w, h = 20, 20, 40, 20;
+
+    function self:draw()
+        love.graphics.rectangle('fill', x, y, w, h);
+    end
+
+    function self:update(dt)
+        w = w + 2;
+        h = h + 1;
+    end
+
+    return self;
+end
+
+return MainScreen;
+```
+
+## License
+
+Copyright (c) 2014 - 2015 Robert Machmer                                          
+                                                                           
+This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:                             
+                                           
+ 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.                                      
+ 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.                        
+ 3. This notice may not be removed or altered from any source distribution.

Screen.lua

@@ -1,6 +1,6 @@
 --===============================================================================--
 --                                                                               --
--- Copyright (c) 2014 Robert Machmer                                             --
+-- Copyright (c) 2014 - 2015 Robert Machmer                                      --
 --                                                                               --
 -- This software is provided 'as-is', without any express or implied             --
 -- warranty. In no event will the authors be held liable for any damages         --
@@ -61,6 +61,8 @@ function Screen.new()
 
     function self:mousefocus(focus) end
 
+    function self:quit(dquit) end
+
     function self:isActive()
         return active;
     end

ScreenManager.lua

@@ -1,6 +1,6 @@
 --===============================================================================--
 --                                                                               --
--- Copyright (c) 2014 Robert Machmer                                             --
+-- Copyright (c) 2014 - 2015 Robert Machmer                                      --
 --                                                                               --
 -- This software is provided 'as-is', without any express or implied             --
 -- warranty. In no event will the authors be held liable for any damages         --
@@ -22,18 +22,26 @@
 
 local ScreenManager = {};
 
+-- ------------------------------------------------
+-- Local Variables
+-- ------------------------------------------------
+
 local stack = {};
+local screens = {};
 
 -- ------------------------------------------------
 -- Module Functions
 -- ------------------------------------------------
 
 ---
--- Initialise the ScreenManager and
--- @param screen
+-- Initialise the ScreenManager. This pushes the first
+-- screen to the stack.
+-- @param nscreens - The list of possible screens.
+-- @param screen - The first screen to push to the stack.
 --
-function ScreenManager.init(screen)
+function ScreenManager.init(nscreens, screen)
     stack = {};
+    ScreenManager.setScreens(nscreens);
     ScreenManager.push(screen);
 end
 
@@ -53,19 +61,28 @@ end
 -- it will overlay all the other screens.
 -- Screens below the this new screen will be set inactive.
 --
--- @param nscreen
+-- @param screen - The name of the screen to push on the stack.
 --
-function ScreenManager.push(nscreen)
+function ScreenManager.push(screen)
     -- Deactivate the previous screen if there is one.
     if ScreenManager.peek() then
         ScreenManager.peek():setActive(false);
     end
 
     -- Push the new screen onto the stack.
-    stack[#stack + 1] = nscreen;
+    if screens[screen] then
+        stack[#stack + 1] = screens[screen].new();
+    else
+        local str = "{";
+        for i, v in pairs(screens) do
+            str = str .. i .. ', ';
+        end
+        str = str .. "}";
+        error('"' .. screen .. '" is not a valid screen. You will have to add a new one to your screen list or use one of the existing screens: ' .. str);
+    end
 
     -- Create the new screen and initialise it.
-    nscreen:init();
+    stack[#stack]:init();
 end
 
 ---
@@ -76,7 +93,7 @@ function ScreenManager.peek()
 end
 
 ---
--- Removes the topmost screen of the stack
+-- Removes the topmost screen of the stack.
 --
 function ScreenManager.pop()
     if #stack > 1 then
@@ -139,21 +156,21 @@ end
 ---
 -- Update all screens on the stack whenever the game window gains or
 -- loses focus.
--- @param dfocus
+-- @param nfocus
 --
-function ScreenManager.focus(dfocus)
+function ScreenManager.focus(nfocus)
     for i = 1, #stack do
-        stack[i]:focus(dfocus);
+        stack[i]:focus(nfocus);
     end
 end
 
 ---
 -- Update all screens on the stack whenever the game window is minimized.
--- @param dvisible
+-- @param nvisible
 --
-function ScreenManager.visible(dvisible)
+function ScreenManager.visible(nvisible)
     for i = 1, #stack do
-        stack[i]:visible(dvisible);
+        stack[i]:visible(nvisible);
     end
 end
 
@@ -211,6 +228,27 @@ function ScreenManager.mousefocus(focus)
     ScreenManager.peek():mousefocus(focus);
 end
 
+---
+-- Reroute the quit callback to the currently active screen.
+-- @param dquit
+--
+function ScreenManager.quit(dquit)
+    ScreenManager.peek():quit(dquit);
+end
+
+-- ------------------------------------------------
+-- Setters
+-- ------------------------------------------------
+
+---
+-- Set a new table of screens from which to pick a new screen when
+-- pushing / switching.
+-- @param nscreens
+--
+function ScreenManager.setScreens(nscreens)
+    screens = nscreens;
+end
+
 -- ------------------------------------------------
 -- Return Module
 -- ------------------------------------------------