modules/menusystem: better comments

gamecore/modules/menusystem/flowbox.lua

@@ -1,10 +1,36 @@
-local cwd  = (...):gsub('%.flowbox$', '') .. "."
+-- flowbox :: flexible box menu, that handle in grid the widgets
-local Menu = require(cwd .. "parent")
 
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
+local cwd  = (...):gsub('%.flowbox$', '') .. "."
+
+local Menu = require(cwd .. "parent")
 local FlowBox = Menu:extend()
 
 local menuutils = require(cwd .. "widgets.utils")
 
+-- INIT FUNCTIONS
+-- Initialize and configure the flowbox
+
 function FlowBox:new(menusystem, name, x, y, w, h, slots_hor, slots_vert)
   self.view = {}
   self.view.slotNumber  = slots_hor * slots_vert
@@ -24,6 +50,9 @@ function FlowBox:updateWidgetSize()
   self.widget.w = math.floor( self.w / self.view.colNumber )
 end
 
+-- UPDATE FUNCTIONS
+-- Update the menu and its view
+
 function FlowBox:update(dt)
   self:updateView()
 end
@@ -150,6 +179,9 @@ function FlowBox:mousepressed(x, y, button, isTouch)
 
 end
 
+-- DRAW FUNCTIONS
+-- Draw the menu and its content
+
 function FlowBox:draw()
   self:updateView()
   local widgety = self.y

gamecore/modules/menusystem/grid.lua

@@ -1,10 +1,36 @@
-local cwd  = (...):gsub('%.grid$', '') .. "."
+-- grid :: a menu with arbitrary widget placement and size on a grid.
-local Menu = require(cwd .. "parent")
 
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
+local cwd  = (...):gsub('%.grid$', '') .. "."
+
+local Menu = require(cwd .. "parent")
 local GridBox = Menu:extend()
 
 local menuutils = require(cwd .. "widgets.utils")
 
+-- INIT FUNCTIONS
+-- Initialize and configure the menu
+
 function GridBox:new(menusystem, name, x, y, w, h, colNumber, lineNumber)
   self.view = {}
   self.view.slotNumber  = colNumber * lineNumber
@@ -40,6 +66,9 @@ function GridBox:updateWidgetSize()
   self.widget.w = math.floor( self.w / self.view.colNumber )
 end
 
+-- INFO FUNCTIONS
+-- Get the info of the widgets
+
 function GridBox:getWidgetSize(id)
   local slot = self:getWidgetSlot(id)
   if slot == 0 then
@@ -106,10 +135,16 @@ function GridBox:getWidgetAtPoint(x, y)
   return widgetID
 end
 
+-- UPDATE FUNCTIONS
+-- Update the Grid and its view
+
 function GridBox:update(dt)
   self.view.firstSlot = 1
 end
 
+-- KEYS FUNCTIONS
+-- Handle the keyboard/manette functions
+
 function GridBox:keyreleased(key, code)
   slotID = self:getWidgetSlot(self.widget.selected)
   local col, line = self.cursor.x, self.cursor.y
@@ -176,6 +211,9 @@ function GridBox:moveLine(direction)
   end
 end
 
+-- MOUSE FUNCTIONS
+-- Handle the mouse and activate the widgets with it
+
 function GridBox:mousemoved(x, y)
   local widgetID = self:getWidgetAtPoint(x, y)
 
@@ -206,6 +244,9 @@ function GridBox:mousepressed(x, y, button, isTouch)
   end
 end
 
+-- DRAW FUNCTIONS
+-- Draw the menu and its content
+
 function GridBox:draw()
 
   for i,v in ipairs(self.slots) do

gamecore/modules/menusystem/hlistbox.lua

@@ -1,9 +1,35 @@
+-- hlistbox : add an horizontal list of widgets.
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 local cwd  = (...):gsub('%.hlistbox$', '') .. "."
+
 local Menu = require(cwd .. "parent")
+local HListBox = Menu:extend()
 
 local menuutils = require(cwd .. "widgets.utils")
 
-local HListBox = Menu:extend()
+-- INIT FUNCTIONS
+-- Initialize and configure functions.
 
 function HListBox:new(menusystem, name, x, y, w, h, slotNumber)
   self.view = {}
@@ -14,6 +40,9 @@ function HListBox:new(menusystem, name, x, y, w, h, slotNumber)
   -- soit un multiple du nombre de slot et de leur hauteur
 end
 
+-- UPDATE FUNCTIONS
+-- Update the menu every step.
+
 function HListBox:updateWidgetSize()
   self.widget.h = self.h
   self.widget.w = math.floor( self.w / self.view.slotNumber )
@@ -36,6 +65,9 @@ function HListBox:updateView()
   end
 end
 
+-- KEYBOARD FUNCTIONS
+-- Handle key check.
+
 function HListBox:keyreleased(key, code)
 
   if key == 'left' then
@@ -60,6 +92,9 @@ function HListBox:keyreleased(key, code)
 
 end
 
+-- MOUSE FUNCTIONS
+-- Click and stuff like that.
+
 function HListBox:mousemoved(x, y)
   local widget_selected = self.view.firstSlot + math.floor(x / self.widget.w)
 
@@ -82,6 +117,9 @@ function HListBox:mousepressed(x, y, button, isTouch)
 
 end
 
+-- DRAW FUNCTIONS
+-- Draw the menu and its content
+
 function HListBox:draw()
   self:updateView()
   local widgetx = self.x

gamecore/modules/menusystem/init.lua

@@ -1,18 +1,47 @@
-local MenuSystem = Object:extend()
+-- menusystem :: the controller of the menu system. This object handle the
+-- different menu objects
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
 
 local cwd  = (...):gsub('%.init$', '') .. "."
 
+local MenuSystem = Object:extend()
+
+-- Load the differents menu object to get an easy access
 MenuSystem.Parent       = require(cwd .. "parent")
 MenuSystem.ListBox      = require(cwd .. "listbox")
 MenuSystem.FlowBox      = require(cwd .. "flowbox")
 MenuSystem.Grid         = require(cwd .. "grid")
 MenuSystem.TextMenu     = require(cwd .. "textmenu")
 
+-- load widgets object
 MenuSystem.Widget       = require(cwd .. "widgets")
 
 
 --local VirtualPad = require "modules.virtualpad"
 
+-- INIT FUNCTIONS
+-- Initialize and configure the menu controller
+
 function MenuSystem:new()
   self.menus = {}
   self.focusedMenu = ""
@@ -22,6 +51,9 @@ function MenuSystem:reset()
   self.menus = {}
 end
 
+-- MENUS FUNCTIONS
+-- Controle the menus of the menusystem
+
 function MenuSystem:addMenu(name, menu)
   self.menus[name] = menu
 end
@@ -30,6 +62,9 @@ function MenuSystem:menuExist(name)
   return (self.menus[name] ~= nil)
 end
 
+-- UPDATE FUNCTIONS
+-- Update the menus of the menusystem
+
 function MenuSystem:update(dt)
   self:removeDestroyedMenus()
   for k,v in pairs(self.menus) do
@@ -120,6 +155,9 @@ function MenuSystem:keyreleased(key, code)
   -- TODO:depreciated function
 end
 
+-- MOUSE FUNCTIONS
+-- Send mouse inputs to the menu
+
 function MenuSystem:mousemoved(x, y, dx, dy)
   for k,v in pairs(self.menus) do
     if v.isActive then
@@ -142,6 +180,9 @@ function MenuSystem:mousepressed( x, y, button, istouch )
   end
 end
 
+-- DRAW FUNCTIONS
+-- All functions to draw the menus of the menusystem
+
 function MenuSystem:getDrawList()
   local drawList = {}
   for k,v in pairs(self.menus) do

gamecore/modules/menusystem/listbox.lua

@@ -1,9 +1,35 @@
+-- listbox : add a vertical list of widgets.
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 local cwd  = (...):gsub('%.listbox$', '') .. "."
 local Menu = require(cwd .. "parent")
 
+local ListBox = Menu:extend()
+
 local menuutils = require(cwd .. "widgets.utils")
 
-local ListBox = Menu:extend()
+-- INIT FUNCTIONS
+-- Initialize and configure functions.
 
 function ListBox:new(menusystem, name, x, y, w, h, slotNumber)
   self.view = {}
@@ -14,6 +40,9 @@ function ListBox:new(menusystem, name, x, y, w, h, slotNumber)
   -- soit un multiple du nombre de slot et de leur hauteur
 end
 
+-- UPDATE FUNCTIONS
+-- Update the menu every step.
+
 function ListBox:updateWidgetSize()
   self.widget.h = math.floor( self.h / self.view.slotNumber )
   self.widget.w = self.w
@@ -36,6 +65,9 @@ function ListBox:updateView()
   end
 end
 
+-- KEYBOARD FUNCTIONS
+-- Handle input from keyboard/controllers.
+
 function ListBox:keyreleased(key, code)
 
   if key == 'up' then
@@ -60,6 +92,9 @@ function ListBox:keyreleased(key, code)
 
 end
 
+-- MOUSE FUNCTIONS
+-- Handle input from pointers.
+
 function ListBox:mousemoved(x, y)
   local widget_selected = self.view.firstSlot + math.floor(y / self.widget.h)
 
@@ -82,6 +117,9 @@ function ListBox:mousepressed(x, y, button, isTouch)
 
 end
 
+-- DRAW FUNCTIONS
+-- draw the menu and the rest of content.
+
 function ListBox:draw()
   self:updateView()
   local widgety = self.y

gamecore/modules/menusystem/parent.lua

@@ -1,5 +1,31 @@
+-- parent.lua : The parent of the functions.
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 local Menu = Object:extend()
 
+-- INIT FUNCTIONS
+-- Initialize and configure functions.
+
 function Menu:new(menusystem, name, x, y, w, h)
   self.menusystem = menusystem
   self.name       = name
@@ -86,12 +112,18 @@ function Menu:getWidgetSize(id)
   return self.widget.w, self.widget.h
 end
 
+-- ACTION FUNCTIONS
+-- Send actions to the widgets
+
 function Menu:cancelAction()
   if (self.widget.cancel ~= 0) then
     self.widget.list[self.widget.cancel]:action("key")
   end
 end
 
+-- UPDATE FUNCTIONS
+-- Update the menu every game update
+
 function Menu:update(dt)
   -- Cette fonction ne contient rien par défaut
 end
@@ -114,6 +146,9 @@ function Menu:destroy()
   self.destroyed = true
 end
 
+-- DRAW FUNCTIONS
+-- Draw the menu and its content
+
 function Menu:draw()
   -- nothing here
 end
@@ -126,10 +161,16 @@ function Menu:drawCanvas()
 
 end
 
+-- KEYBOARD FUNCTIONS
+-- Handle key press
+
 function Menu:keyreleased(key)
   -- Cette fonction ne contient rien par défaut
 end
 
+-- MOUSE FUNCTIONS
+-- Handle pointers (clic/touch)
+
 function Menu:mousemoved(x, y)
   -- Cette fonction ne contient rien par défaut
 end
@@ -138,6 +179,9 @@ function Menu:mousepressed( x, y, button, istouch )
   -- Cette fonction ne contient rien par défaut
 end
 
+-- WIDGET FUNCTIONS
+-- Handle widgets of the functions
+
 function Menu:addWidget(newwidget)
   if #self.widget.list == 0 then
     self.widget.selected = 1
@@ -168,6 +212,9 @@ function Menu:removeDestroyedWidgets() -- On retire les widgets marquées comme
   end
 end
 
+-- CURSOR FUNCTIONS
+-- Set or move the cursor of the menu
+
 function Menu:setCursor(cursorid)
   self.widget.selected = cursorid --math.max(1, math.min(cursorid, #self.widget.list))
 end
@@ -185,6 +232,9 @@ function Menu:moveCursor(new_selected)
   end
 end
 
+-- SOUND FUNCTION
+-- Handle SFX
+
 function Menu:setSound(soundasset)
   self.sound.active = true
   self.sound.asset = soundasset
@@ -198,6 +248,9 @@ function Menu:playSelectSound()
   end
 end
 
+-- VIEW FUNCTIONS
+-- Handle the view of the menu
+
 function Menu:resetView()
   -- ne sert à rien ici, c'est juste pour éviter des crash
 end

gamecore/modules/menusystem/widgets/init.lua

@@ -1,8 +1,34 @@
+-- widgets :: basic widget object
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 local Widget = {}
 
 BaseWidget  = Object:extend()
 TextWidget  = BaseWidget:extend()
 
+-- INIT FUNCTIONS
+-- Initialize and configure the widget
+
 function BaseWidget:new(menu)
   self.menu = menu
 
@@ -50,6 +76,9 @@ function BaseWidget:selectAction()
   -- Do nothing
 end
 
+-- DRAW WIDGETS
+-- Draw the widget
+
 function BaseWidget:draw(x, y)
   if self.canvas.texture ~= nil then
     utils.graphics.resetColor()
@@ -61,6 +90,9 @@ function BaseWidget:drawSelected(x,y,w,h)
     self:draw(x, y, w, h)
 end
 
+-- UPDATE FUNCTIONS
+-- Update the widget
+
 function BaseWidget:update(dt)
   if (self.canvas.needRedraw) then
     self:redrawCanvas()
@@ -68,6 +100,9 @@ function BaseWidget:update(dt)
  -- N/A
 end
 
+-- ACTION FUNCTION
+-- Functions to handle actions and selection.
+
 function BaseWidget:action(source)
   --self:destroy()
 end
@@ -76,6 +111,7 @@ function BaseWidget:destroy()
   self.destroyed = true
 end
 
+-- TEXT WIDGET
 -- Simple text widget
 
 function TextWidget:new(menu, font, label)
@@ -91,7 +127,7 @@ function TextWidget:drawCanvas()
   self.font:draw(self.label, w, h, -1, "center")
 end
 
-
+-- Add the widget as subvariable to the returned table
 Widget.Base   = BaseWidget
 Widget.Text   = TextWidget
 

gamecore/modules/menusystem/widgets/utils.lua

@@ -1,3 +1,26 @@
+-- widgets/utils :: basic utility functions for the widgets
+
+--[[
+  Copyright © 2019 Kazhnuz
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of
+  this software and associated documentation files (the "Software"), to deal in
+  the Software without restriction, including without limitation the rights to
+  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+  FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 local menuUtils = {}
 
 function menuUtils.drawCursor(x, y, w, h)