Upate documentation

Author: rm-code

ScreenManager.lua

@@ -52,10 +52,14 @@ end
 -- ------------------------------------------------
 
 ---
--- 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.
+-- Initialise the ScreenManager.
+-- Sets up the ScreenManager and pushes the first screen.
+-- @param nscreens (table)  A table containing pointers to the different screen
+--                           classes. The keys will are used to call a specific
+--                           screen.
+-- @param screen   (string) The key of the first screen to push to the stack.
+--                           Use the key under which the screen in question is
+--                           stored in the nscreens table.
 --
 function ScreenManager.init( nscreens, screen )
     stack = {};
@@ -64,22 +68,24 @@ function ScreenManager.init( nscreens, screen )
 end
 
 ---
--- Clears the ScreenManager, creates a new screen and switches
--- to it. Use this if you don't want to stack onto other screens.
---
--- @param nscreen
+-- Switches to a screen.
+-- Removes all screens from the stack, creates a new screen and switches to it.
+-- Use this if you don't want to stack onto other screens.
+-- @param screen (string) The key of the screen to switch to.
+-- @param ...    (vararg) One or multiple arguments passed to the new screen.
 --
 function ScreenManager.switch( screen, ... )
     clear();
     ScreenManager.push( screen, ... );
 end
 
 ---
--- Creates a new screen and pushes it on the screen stack, where
--- it will overlay all the other screens.
--- Screens below the this new screen will be set inactive.
---
--- @param screen - The name of the screen to push on the stack.
+-- Pushes a new screen to the stack.
+-- Creates a new screen and pushes it on the screen stack, where it will overlay
+-- the other screens below it. Screens below the this new screen will be set
+-- inactive.
+-- @param screen (string) The key of the screen to push to the stack.
+-- @param ...    (vararg) One or multiple arguments passed to the new screen.
 --
 function ScreenManager.push( screen, ... )
     -- Deactivate the previous screen if there is one.
@@ -105,13 +111,15 @@ end
 
 ---
 -- Returns the screen on top of the screen stack without removing it.
+-- @return (table) The screen on top of the stack.
 --
 function ScreenManager.peek()
     return stack[#stack];
 end
 
 ---
--- Removes the topmost screen of the stack.
+-- Removes and returns the topmost screen of the stack.
+-- @return (table) The screen on top of the stack.
 --
 function ScreenManager.pop()
     if #stack > 1 then
@@ -136,16 +144,20 @@ end
 -- ------------------------------------------------
 
 ---
--- Callback function triggered when a directory is dragged and dropped onto the window.
--- @param file - The full platform-dependent path to the directory.
+-- Reroute the directorydropped callback to the currently active screen.
+-- @param path (string) The full platform-dependent path to the directory.
+--                       It can be used as an argument to love.filesystem.mount,
+--                       in order to gain read access to the directory with
+--                       love.filesystem.
 --
 function ScreenManager.directorydropped( path )
     ScreenManager.peek():directorydropped( path );
 end
 
 ---
--- Draw all screens on the stack. Screens that are higher on the stack
--- will overlay screens that are on the bottom.
+-- Reroute the draw callback to all screens on the stack.
+-- Screens that are higher on the stack will overlay screens that are below
+-- them.
 --
 function ScreenManager.draw()
     for i = 1, #stack do
@@ -154,104 +166,116 @@ function ScreenManager.draw()
 end
 
 ---
--- Callback function triggered when a file is dragged and dropped onto the window.
--- @param file - The unopened File object representing the file that was dropped.
+-- Reroute the filedropped callback to the currently active screen.
+-- @param file (File) The unopened File object representing the file that was
+--                     dropped.
 --
 function ScreenManager.filedropped( file )
     ScreenManager.peek():filedropped( file );
 end
 
 ---
--- Update all screens on the stack whenever the game window gains or
--- loses focus.
--- @param nfocus
+-- Reroute the focus callback to all screens on the stack.
+-- @param focus (boolean) True if the window gains focus, false if it loses focus.
 --
-function ScreenManager.focus( nfocus )
+function ScreenManager.focus( focus )
     for i = 1, #stack do
-        stack[i]:focus( nfocus );
+        stack[i]:focus( focus );
     end
 end
 
 ---
--- Callback function triggered when a key is pressed.
--- @param key - Character of the pressed key.
--- @param scancode - The scancode representing the pressed key.
--- @param isrepeat - Whether this keypress event is a repeat. The delay between key repeats depends on the user's system settings.
+-- Reroute the keypressed callback to the currently active screen.
+-- @param key      (KeyConstant) Character of the pressed key.
+-- @param scancode (Scancode)    The scancode representing the pressed key.
+-- @param isrepeat (boolean)     Whether this keypress event is a repeat. The
+--                                delay between key repeats depends on the
+--                                user's system settings.
 --
 function ScreenManager.keypressed(  key, scancode, isrepeat )
-    ScreenManager.peek():keypressed( key, scancode, isrepeat);
+    ScreenManager.peek():keypressed( key, scancode, isrepeat );
 end
 
 ---
--- Callback function triggered when a keyboard key is released.
--- @param key - Character of the released key.
--- @param scancode - The scancode representing the released key.
+-- Reroute the keyreleased callback to the currently active screen.
+-- @param key      (KeyConstant) Character of the released key.
+-- @param scancode (Scancode)    The scancode representing the released key.
 --
 function ScreenManager.keyreleased( key, scancode )
     ScreenManager.peek():keyreleased( key, scancode );
 end
 
 ---
--- Callback function triggered when the system is running out of memory on mobile devices.
+-- Reroute the lowmemory callback to the currently active screen.
+-- mobile devices.
 --
 function ScreenManager.lowmemory()
     ScreenManager.peek():lowmemory();
 end
 
 ---
 -- Reroute the mousefocus callback to the currently active screen.
--- @param focus - Wether the window has mouse focus or not.
+-- @param focus (boolean) Wether the window has mouse focus or not.
 --
 function ScreenManager.mousefocus( focus )
     ScreenManager.peek():mousefocus( focus );
 end
 
 ---
--- Callback function triggered when the mouse is moved.
--- @param x - Mouse x position.
--- @param y - Mouse y position.
--- @param dx - The amount moved along the x-axis since the last time love.mousemoved was called.
--- @param dy - The amount moved along the y-axis since the last time love.mousemoved was called.
+-- Reroute the mousemoved callback to the currently active screen.
+-- @param x  (number) Mouse x position.
+-- @param y  (number) Mouse y position.
+-- @param dx (number) The amount moved along the x-axis since the last time
+--                     love.mousemoved was called.
+-- @param dy (number) The amount moved along the y-axis since the last time
+--                     love.mousemoved was called.
 --
 function ScreenManager.mousemoved( x, y, dx, dy )
     ScreenManager.peek():mousemoved( x, y, dx, dy );
 end
 
 ---
--- Callback function triggered when a mouse button is pressed.
--- @param x - Mouse x position, in pixels.
--- @param y - Mouse y position, in pixels.
--- @param button - The button index that was pressed. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependant.
--- @param istouch - True if the mouse button press originated from a touchscreen touch-press.
+-- Reroute the mousepressed callback to the currently active screen.
+-- @param x       (number)  Mouse x position, in pixels.
+-- @param y       (number)  Mouse y position, in pixels.
+-- @param button  (number)  The button index that was pressed. 1 is the primary
+--                           mouse button, 2 is the secondary mouse button and 3
+--                           is the middle button. Further buttons are mouse
+--                           dependent.
+-- @param istouch (boolean) True if the mouse button press originated from a
+--                           touchscreen touch-press.
 --
 function ScreenManager.mousepressed( x, y, button, istouch )
     ScreenManager.peek():mousepressed( x, y, button, istouch );
 end
 
 ---
--- Callback function triggered when a mouse button is released.
--- @param x - Mouse x position, in pixels.
--- @param y - Mouse y position, in pixels.
--- @param button - The button index that was released. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependant.
--- @param istouch - True if the mouse button release originated from a touchscreen touch-release.
+-- Reroute the mousereleased callback to the currently active screen.
+-- @param x       (number)  Mouse x position, in pixels.
+-- @param y       (number)  Mouse y position, in pixels.
+-- @param button  (number)  The button index that was released. 1 is the primary
+--                           mouse button, 2 is the secondary mouse button and 3
+--                           is the middle button. Further buttons are mouse
+--                           dependent.
+-- @param istouch (boolean) True if the mouse button release originated from a
+--                           touchscreen touch-release.
 --
 function ScreenManager.mousereleased( x, y, button, istouch )
     ScreenManager.peek():mousereleased( x, y, button, istouch );
 end
 
 ---
 -- Reroute the quit callback to the currently active screen.
--- @param dquit - Abort quitting. If true, do not close the game.
+-- @return quit (boolean) Abort quitting. If true, do not close the game.
 --
-function ScreenManager.quit( dquit )
-    ScreenManager.peek():quit( dquit );
+function ScreenManager.quit()
+    ScreenManager.peek():quit();
 end
 
 ---
--- Called when the window is resized, for example if the user resizes the window, or if love.window.setMode is called with an unsupported width or height in fullscreen and the window chooses the closest appropriate size.
---
--- @param w - The new width, in pixels.
--- @param h - The new height, in pixels.
+-- Reroute the resize callback to all screens on the stack.
+-- @param w (number) The new width, in pixels.
+-- @param h (number) The new height, in pixels.
 --
 function ScreenManager.resize( w, h )
     for i = 1, #stack do
@@ -260,19 +284,18 @@ function ScreenManager.resize( w, h )
 end
 
 ---
--- Called when the candidate text for an IME (Input Method Editor) has changed.
--- The candidate text is not the final text that the user will eventually choose. Use love.textinput for that.
--- @param text - The UTF-8 encoded unicode candidate text.
--- @param start - The start cursor of the selected candidate text.
--- @param length - The length of the selected candidate text. May be 0.
+-- Reroute the textedited callback to the currently active screen.
+-- @param text   (string) The UTF-8 encoded unicode candidate text.
+-- @param start  (number) The start cursor of the selected candidate text.
+-- @param length (number) The length of the selected candidate text. May be 0.
 --
 function ScreenManager.textedited( text, start, length )
     ScreenManager.peek():textedited( text, start, length );
 end
 
 ---
 -- Reroute the textinput callback to the currently active screen.
--- @param input
+-- @param input (string) The UTF-8 encoded unicode text.
 --
 function ScreenManager.textinput( input )
     ScreenManager.peek():textinput( input );
@@ -291,40 +314,65 @@ end
 
 
 ---
--- Callback function triggered when a touch press moves inside the touch screen.
--- @param id - The identifier for the touch press.
--- @param x - The x-axis position of the touch press inside the window, in pixels.
--- @param y - The y-axis position of the touch press inside the window, in pixels.
--- @param pressure - The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.
+-- Reroute the touchmoved callback to the currently active screen.
+-- @param id       (light userdata) The identifier for the touch press.
+-- @param x        (number)         The x-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param y        (number)         The y-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param dx       (number)         The x-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param dy       (number)         The y-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param pressure (number)         The amount of pressure being applied. Most
+--                                   touch screens aren't pressure sensitive,
+--                                   in which case the pressure will be 1.
 --
-function ScreenManager.touchmoved( id, x, y, pressure )
-    ScreenManager.peek():touchmoved( id, x, y, pressure );
+function ScreenManager.touchmoved( id, x, y, dx, dy, pressure )
+    ScreenManager.peek():touchmoved( id, x, y, dx, dy, pressure );
 end
 
 ---
--- Callback function triggered when the touch screen is touched.
--- @param id - The identifier for the touch press.
--- @param x - The x-axis position of the touch press inside the window, in pixels.
--- @param y - The y-axis position of the touch press inside the window, in pixels.
--- @param pressure - The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.
+-- Reroute the touchpressed callback to the currently active screen.
+-- @param id       (light userdata) The identifier for the touch press.
+-- @param x        (number)         The x-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param y        (number)         The y-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param dx       (number)         The x-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param dy       (number)         The y-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param pressure (number)         The amount of pressure being applied. Most
+--                                   touch screens aren't pressure sensitive,
+--                                   in which case the pressure will be 1.
 --
-function ScreenManager.touchpressed( id, x, y, pressure )
-    ScreenManager.peek():touchpressed( id, x, y, pressure );
+function ScreenManager.touchpressed( id, x, y, dx, dy, pressure )
+    ScreenManager.peek():touchpressed( id, x, y, dx, dy, pressure );
 end
 
 ---
--- Callback function triggered when the touch screen stops being touched.
--- @param id - The identifier for the touch press.
--- @param x - The x-axis position of the touch press inside the window, in pixels.
--- @param y - The y-axis position of the touch press inside the window, in pixels.
--- @param pressure - The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.
+-- Reroute the touchreleased callback to the currently active screen.
+-- @param id       (light userdata) The identifier for the touch press.
+-- @param x        (number)         The x-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param y        (number)         The y-axis position of the touch press inside the
+--                                   window, in pixels.
+-- @param dx       (number)         The x-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param dy       (number)         The y-axis movement of the touch inside the
+--                                   window, in pixels.
+-- @param pressure (number)         The amount of pressure being applied. Most
+--                                   touch screens aren't pressure sensitive,
+--                                   in which case the pressure will be 1.
 --
-function ScreenManager.touchreleased( id, x, y, pressure )
-    ScreenManager.peek():touchreleased( id, x, y, pressure );
+function ScreenManager.touchreleased( id, x, y, dx, dy, pressure )
+    ScreenManager.peek():touchreleased( id, x, y, dx, dy, pressure );
 end
 
 ---
--- Update all screens on the stack.
+-- Reroute the update callback to all screens.
+-- @param dt (number) Time since the last update in seconds.
 --
 function ScreenManager.update( dt )
     for i = 1, #stack do
@@ -333,19 +381,22 @@ function ScreenManager.update( dt )
 end
 
 ---
--- Update all screens on the stack whenever the game window is minimized.
--- @param nvisible
+-- Reroute the visible callback to all screens.
+-- @param visible (boolean) True if the window is visible, false if it isn't.
 --
-function ScreenManager.visible( nvisible )
+function ScreenManager.visible( visible )
     for i = 1, #stack do
-        stack[i]:visible( nvisible );
+        stack[i]:visible( visible );
     end
 end
 
 ---
--- Callback function triggered when the mouse wheel is moved.
--- @param x - Amount of horizontal mouse wheel movement. Positive values indicate movement to the right.
--- @param y - Amount of vertical mouse wheel movement. Positive values indicate upward movement.
+-- Reroute the wheelmoved callback to the currently active screen.
+-- @param x (number) Amount of horizontal mouse wheel movement. Positive values
+--                    indicate movement to the right.
+-- @param y (number) Amount of vertical mouse wheel movement. Positive values
+--                    indicate upward movement.
+--
 function ScreenManager.wheelmoved( x, y )
     ScreenManager.peek():wheelmoved( x, y );
 end