diff --git a/Element.luadoc b/Element.luadoc new file mode 100644 index 0000000..33738b4 --- /dev/null +++ b/Element.luadoc @@ -0,0 +1,150 @@ +--- This is a description of what is expected in an element class. +--- +--- **IMPORTANT**: Your class should inherit from *the* element class. This +--- means that any methods defined on that class need to be compatible with or +--- overridden by your class! +--- @see element + + + +--- **Optional**: Called during `pop.load()` with a reference to Pop.Box. +--- @function load +--- @tparam module pop The Pop.Box module. + +--- **Optional**: Called during `pop.load()` to allow a custom wrapper function +--- to be created for your element class. +--- @function wrap +--- @tparam module pop The Pop.Box module. +--- @treturn function wrapper A function to be called to create an element of +--- this class instead of using `pop.create()`. + +--- **Optional**: Called from `pop.update()` if `data.update` and a child of +--- `pop.screen`. Use it for any time-based updates your element may need. +--- @function update +--- @tparam number dt The amount of time elapsed since `update` was last called. + +--- **Optional**: Called from `pop.draw()` if `data.draw` and a child of +--- `pop.screen`. Use it to draw your element. +--- @function draw + +--- **Optional**: Called from `pop.mousemoved()` if in LOVE >= 0.10.0 and your +--- element is focused. +--- @function mousemoved +--- @tparam integer x The x coordinate of the mouse. +--- @tparam integer y The y coordinate of the mouse. +--- @tparam number dx The distance on the x axis the mouse was moved. +--- @tparam number dy The distance on the y axis the mouse was moved. +--- @treturn boolean Was the event handled? + +--- **Optional**: Called from `pop.mousepressed()` if a mouse button was pressed +--- over your element. +--- +--- **Note**: Your element must be visible (`data.draw` is true) for this method +--- to be called. +--- @function mousepressed +--- @tparam integer x The x coordinate of the mouse press. +--- @tparam integer y The y coordinate of the mouse press. +--- @tparam ?string|integer button The mouse button pressed. (Type varies by +--- LÖVE version.) +--- @treturn boolean Was the event handled? + + + +--- The parent element of this element. +--- @tfield ?Element|false parent Parent element. + +--- The child elements of this element. +--- @tfield table child All child elements. + + + +--- Every object has a data field with pre-defined values. Any serializable data +--- should be saved in this field. Ideally, any Pop.Box element can be +--- reconstructed from its data field. +--- @table data +--- @tfield ?table|false parent The parent of this element's data field. This +--- will **not** be serialized. This is the *only* exception to all data being +--- serialized. +--- @tfield table child All child elements' data fields. +--- @tfield integer x The left edge of your element. +--- @tfield integer y The top edge of your element. +--- @tfield integer w The width of your element. +--- @tfield integer h The height of your element. +--- @tfield boolean update Whether or not to update this element (and its +--- children). +--- @tfield boolean draw Whether or not to draw this element (and its children). + + + +pop.mousereleased = (x, y, button, element) -> + if element.clicked and element.data.draw + clickedHandled = element\clicked x - element.data.x, y - element.data.y, button + if element.mousereleased + mousereleasedHandled = element\mousereleased x - element.data.x, y - element.data.y, button + + -- if we clicked, we're focused! + if clickedHandled + pop.focused = element + +pop.keypressed = (key) -> + print "keypressed", key + + -- keypressed events must be on visible elements + element = pop.focused + if element and element.keypressed and element.data.draw + return element.keypressed key + + return false + +pop.keyreleased = (key) -> + print "keyreleased", key + + -- keyreleased events are always called + element = pop.focused + if element and element.keyreleased + return element.keyreleased key + + return false + +pop.textinput = (text) -> + print "textinput", text + + -- textinput events must be on visible elements + element = pop.focused + if element and element.textinput and element.data.draw + return element.textinput text + + return false + +pop.debugDraw = (element=pop.screen) -> + if element.debugDraw + element\debugDraw! + else + graphics.setLineWidth 1 + graphics.setLineColor 0, 0, 0, 100 + graphics.rectangle "fill", element.x, element.y, element.w, element.h + graphics.setColor 150, 150, 150, 150 + graphics.rectangle "line", element.x, element.y, element.w, element.h + graphics.setColor 200, 200, 200, 255 + graphics.print ".", element.x, element.y + + for i = 1, #element.child + pop.debugDraw element.child[i] + +pop.printElementTree = (element=pop.screen, depth=0) -> + cls = element.__class.__name + + if cls == "text" + cls = cls .. " (\"#{element\getText!\gsub "\n", "\\n"}\")" + elseif cls == "box" + bg = element\getBackground! + + if type(bg) == "table" + bg = "#{bg[1]}, #{bg[2]}, #{bg[3]}, #{bg[4]}" + + cls = cls .. " (#{bg})" + + print string.rep("-", depth) .. " #{cls}" + + for i = 1, #element.child + pop.printElementTree element.child[i], depth + 1 diff --git a/config.ld b/config.ld index 71d505d..d15b0c8 100644 --- a/config.ld +++ b/config.ld @@ -1,7 +1,9 @@ file = { "init.moon", - --"main.moon", + "elements/element.moon", + "main.moon", "util.moon", + "Element.luadoc", } project = "Pop.Box()" diff --git a/docs/classes/element.html b/docs/classes/element.html new file mode 100644 index 0000000..1224fdf --- /dev/null +++ b/docs/classes/element.html @@ -0,0 +1,120 @@ + + + + + Documentation + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Class element

+

A generic element every element must inherit from.

+

+ +

+

Info:

+
    +
  • Copyright: Paul Liverman III (2016)
    • +
  • License: The MIT License (MIT)
    • +
+ + +

Methods

+ + + + + +
element.new (self, parent)Constructor expects nothing?
+ +
+
+ + +

Methods

+ +
+
+ + element.new (self, parent) +
+
+ Constructor expects nothing? + + +

Parameters:

+
    +
  • self + + + +
    • +
  • parent + + + +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.4.3 +Last updated 2016-08-21 00:47:30 +
+
+ + diff --git a/docs/index.html b/docs/index.html index a3a3e90..bd04f05 100644 --- a/docs/index.html +++ b/docs/index.html @@ -32,7 +32,13 @@

Modules

+

Classes

+ @@ -48,17 +54,32 @@ pop The Pop.Box GUI itself. + + main + A demo program for Pop.Box. + util Utility functions, intended for internal use only. + + Element + This is a description of what is expected in an element class. + + +

Classes

+ + + + +
elementA generic element every element must inherit from.
generated by LDoc 1.4.3 -Last updated 2016-08-20 21:29:17 +Last updated 2016-08-21 00:47:30
diff --git a/docs/modules/Element.html b/docs/modules/Element.html new file mode 100644 index 0000000..bc4788a --- /dev/null +++ b/docs/modules/Element.html @@ -0,0 +1,402 @@ + + + + + Documentation + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module Element

+

This is a description of what is expected in an element class.

+

IMPORTANT: Your class should inherit from the element class. This + means that any methods defined on that class need to be compatible with or + overridden by your class!

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
load (pop)Optional: Called during pop.load() with a reference to Pop.Box.
wrap (pop)Optional: Called during pop.load() to allow a custom wrapper function + to be created for your element class.
update (dt)Optional: Called from pop.update() if data.update and a child of + pop.screen.
draw ()Optional: Called from pop.draw() if data.draw and a child of + pop.screen.
mousemoved (x, y, dx, dy)Optional: Called from pop.mousemoved() if in LOVE >= 0.10.0 and your + element is focused.
mousepressed (x, y, button)Optional: Called from pop.mousepressed() if a mouse button was pressed + over your element.
+

Tables

+ + + + + +
dataEvery object has a data field with pre-defined values.
+

Fields

+ + + + + + + + + +
parentThe parent element of this element.
childThe child elements of this element.
+ +
+
+ + +

Functions

+ +
+
+ + load (pop) +
+
+ Optional: Called during pop.load() with a reference to Pop.Box. + + +

Parameters:

+
    +
  • pop + module + The Pop.Box module. +
    • +
+ + + + + +
+
+ + wrap (pop) +
+
+ Optional: Called during pop.load() to allow a custom wrapper function + to be created for your element class. + + +

Parameters:

+
    +
  • pop + module + The Pop.Box module. +
    • +
+ +

Returns:

+
    + + function + wrapper A function to be called to create an element of + this class instead of using pop.create(). +
+ + + + +
+
+ + update (dt) +
+
+ Optional: Called from pop.update() if data.update and a child of + pop.screen. Use it for any time-based updates your element may need. + + +

Parameters:

+
    +
  • dt + number + The amount of time elapsed since update was last called. +
    • +
+ + + + + +
+
+ + draw () +
+
+ Optional: Called from pop.draw() if data.draw and a child of + pop.screen. Use it to draw your element. + + + + + + + +
+
+ + mousemoved (x, y, dx, dy) +
+
+ Optional: Called from pop.mousemoved() if in LOVE >= 0.10.0 and your + element is focused. + + +

Parameters:

+
    +
  • x + integer + The x coordinate of the mouse. +
    • +
  • y + integer + The y coordinate of the mouse. +
    • +
  • dx + number + The distance on the x axis the mouse was moved. +
    • +
  • dy + number + The distance on the y axis the mouse was moved. +
    • +
+ +

Returns:

+
    + + boolean + Was the event handled? +
+ + + + +
+
+ + mousepressed (x, y, button) +
+
+ Optional: Called from pop.mousepressed() if a mouse button was pressed + over your element.

+ +

Note: Your element must be visible (data.draw is true) for this method + to be called. + + +

Parameters:

+
    +
  • x + integer + The x coordinate of the mouse press. +
    • +
  • y + integer + The y coordinate of the mouse press. +
    • +
  • button + string or integer + The mouse button pressed. (Type varies by + LÖVE version.) +
    • +
+ +

Returns:

+
    + + boolean + Was the event handled? +
+ + + + +
+
+

Tables

+ +
+
+ + data +
+
+ Every object has a data field with pre-defined values. Any serializable data + should be saved in this field. Ideally, any Pop.Box element can be + reconstructed from its data field. + + +

Fields:

+
    +
  • parent + table or false + The parent of this element's data field. This + will not be serialized. This is the only exception to all data being + serialized. +
    • +
  • child + table + All child elements' data fields. +
    • +
  • x + integer + The left edge of your element. +
    • +
  • y + integer + The top edge of your element. +
    • +
  • w + integer + The width of your element. +
    • +
  • h + integer + The height of your element. +
    • +
  • update + boolean + Whether or not to update this element (and its + children). +
    • +
  • draw + boolean + Whether or not to draw this element (and its children). +
    • +
+ + + + + +
+
+

Fields

+ +
+
+ + parent +
+
+ The parent element of this element. + + +
    +
  • parent + Element or false + Parent element. +
    • +
+ + + + + +
+
+ + child +
+
+ The child elements of this element. + + +
    +
  • child + table + All child elements. +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.4.3 +Last updated 2016-08-21 00:47:30 +
+
+ + diff --git a/docs/modules/main.html b/docs/modules/main.html index 9090cec..7f1d7ea 100644 --- a/docs/modules/main.html +++ b/docs/modules/main.html @@ -37,6 +37,11 @@
  • pop
  • main
  • util
    • +
  • Element
    • + +

    Classes

    + @@ -66,7 +71,7 @@
    generated by LDoc 1.4.3 -Last updated 2016-08-20 19:46:37 +Last updated 2016-08-21 00:47:30
    diff --git a/docs/modules/pop.html b/docs/modules/pop.html index 87cc2d7..06a1671 100644 --- a/docs/modules/pop.html +++ b/docs/modules/pop.html @@ -34,13 +34,20 @@

    Modules

    +

    Classes

    + @@ -103,10 +110,6 @@ Event handler for love.textinput(). - skin (element, skin, depth) - Applies skins to elements. - - debugDraw (element) Draws simple rectangle outlines to debug placement of elements. @@ -124,6 +127,31 @@ +

    Issues

    + + + + + + + + + + + + + + + + + +
    update-todo1Define Elements and @ see that documentation from here. Generic documentation, not specifically element! + data.update boolean controls an element and its children being updated
    mousemoved-todo2Implement a way for an element to attach itself to love.mousemoved() events?
    mousereleased-todo3 Figure out how to bring a focused element to the front of view (aka the first element in its parent's children). + (If I do it right here, the for loop above may break! I need to test/figure this out.) +NOTE this might cause an error in the above for loop! + basically, move focused element to front of its parent's child +element.parent\focusChild element +table.insert element.parent, element.parent\removeChild(element),
    printElementTree-todo4Correct this once elements are reimplemented if it needs correction.


    @@ -139,7 +167,8 @@
    Loads elements, skins, extensions, and initializes pop.screen.

    -

    IMPORTANT: Intended to only be called once, and is automatically called when you require Pop.Box. +

    IMPORTANT: Intended to only be called once, and is automatically called + when you require Pop.Box. @@ -147,7 +176,8 @@

    See also:

    @@ -163,15 +193,20 @@

    Parameters:

    @@ -179,7 +214,8 @@

    See also:

    @@ -195,15 +231,23 @@

    Parameters:

    +

    See also:

    +
    @@ -218,12 +262,18 @@

    Parameters:

    +

    See also:

    + @@ -232,21 +282,25 @@ mousemoved (x, y, dx, dy)
    - Event handler for love.mousemoved(). (*LÖVE >= 0.10.0*) + Event handler for love.mousemoved(). (LÖVE >= 0.10.0)

    Parameters:

    @@ -254,7 +308,8 @@

    Returns:

      - true / false: Was the event handled? + boolean + Was the event handled?
    @@ -272,26 +327,37 @@

    Parameters:

    Returns:

      - true / false: Was the event handled? + boolean + Was the event handled?
    +

    See also:

    +
    @@ -306,28 +372,40 @@

    Parameters:

    Returns:

    1. - true / false: Was a click handled?
      2. + boolean + Was a click handled?
    2. - true / false: Was a mouse release handled?
      3. + boolean + Was a mouse release handled?
    +

    See also:

    + @@ -342,6 +420,7 @@

    Parameters:

    @@ -349,7 +428,8 @@

    Returns:

      - true / false: Was the event handled? + boolean + Was the event handled?
    @@ -367,6 +447,7 @@

    Parameters:

    @@ -374,7 +455,8 @@

    Returns:

      - true / false: Was the event handled? + boolean + Was the event handled?
    @@ -392,6 +474,7 @@

    Parameters:

    @@ -399,38 +482,13 @@

    Returns:

      - true / false: Was the text input handled? + boolean + Was the text input handled?
    - -
    - - skin (element, skin, depth) -
    -
    - Applies skins to elements. (NOTE: This function will be rewritten and change at some point...) - - -

    Parameters:

    - - - - - -
    @@ -443,12 +501,18 @@

    Parameters:

    +

    See also:

    + @@ -463,12 +527,18 @@

    Parameters:

    +

    See also:

    + @@ -489,19 +559,26 @@

    Fields:

    @@ -509,10 +586,77 @@

    See also:

    + + +

    Issues

    + +
    +
    + + update-todo1 +
    +
    + Define Elements and @ see that documentation from here. Generic documentation, not specifically element! + data.update boolean controls an element and its children being updated + + + + + + + +
    +
    + + mousemoved-todo2 +
    +
    + Implement a way for an element to attach itself to love.mousemoved() events? + + + + + + + +
    +
    + + mousereleased-todo3 +
    +
    + Figure out how to bring a focused element to the front of view (aka the first element in its parent's children). + (If I do it right here, the for loop above may break! I need to test/figure this out.) +NOTE this might cause an error in the above for loop! + basically, move focused element to front of its parent's child +element.parent\focusChild element +table.insert element.parent, element.parent\removeChild(element), + + + + + + + +
    +
    + + printElementTree-todo4 +
    +
    + Correct this once elements are reimplemented if it needs correction. + + + + + + +
    @@ -521,7 +665,7 @@
    generated by LDoc 1.4.3 -Last updated 2016-08-20 21:29:17 +Last updated 2016-08-21 00:47:30
    diff --git a/docs/modules/util.html b/docs/modules/util.html index b9215b8..135a0fe 100644 --- a/docs/modules/util.html +++ b/docs/modules/util.html @@ -39,7 +39,13 @@

    Modules

    +

    Classes

    + @@ -54,7 +60,6 @@

    Info:

    @@ -89,19 +94,27 @@

    Parameters:

    Returns:

      - true / false: Is the table an object inherting from "element"? + boolean + Is the table an object inherting from "element"?

    Raises:

    - Can error if the table has a similar structure to a MoonScript object without being the same structure. + Can error if the table has a similar structure to a MoonScript object + without being the same structure. +

    See also:

    + @@ -112,7 +125,7 @@
    generated by LDoc 1.4.3 -Last updated 2016-08-20 21:29:17 +Last updated 2016-08-21 00:47:30
    diff --git a/elements/element.lua b/elements/element.lua index 5a14e82..0ace973 100644 --- a/elements/element.lua +++ b/elements/element.lua @@ -6,7 +6,7 @@ do } _base_0.__index = _base_0 _class_0 = setmetatable({ - __init = function(self) end, + __init = function(self, parent) end, __base = _base_0, __name = "element" }, { diff --git a/elements/element.moon b/elements/element.moon index bc18de5..2ce143f 100644 --- a/elements/element.moon +++ b/elements/element.moon @@ -1,11 +1,11 @@ --- A generic element every element must inherit from. ---- @module pop +--- @classmod element --- @copyright Paul Liverman III (2016) --- @license The MIT License (MIT) ---- @release 0.0.0 class element - new: => + --- Constructor expects nothing? + new: (parent) => --do stuff setSize: => diff --git a/init.lua b/init.lua index e0df5aa..4f11b88 100644 --- a/init.lua +++ b/init.lua @@ -111,12 +111,18 @@ pop.create = function(element, parent, ...) element = pop.elements[element](parent, ...) insert(parent.child, element) insert(parent.data.child, element.data) + element.parent = parent + element.data.parent = parent.data elseif parent == false then element = pop.elements[element](false, ...) + element.parent = false + element.data.parent = false else element = pop.elements[element](pop.screen, parent, ...) insert(pop.screen.child, element) insert(pop.screen.data.child, element.data) + element.parent = pop.screen + element.data.parent = pop.screen.data end return element end @@ -233,34 +239,6 @@ pop.textinput = function(text) end return false end -pop.skin = function(element, skin, depth) - if element == nil then - element = pop.screen - end - if skin == nil then - skin = pop.skins.default - end - if element.background and skin.background then - element.background = skin.background - end - if element.color and skin.color then - element.color = skin.color - end - if element.font and skin.font then - element.font = skin.font - end - if not (depth or (depth == 0)) then - if depth == tonumber(depth) then - for i = 1, #element.child do - pop.skin(element.child[i], skin, depth - 1) - end - else - for i = 1, #element.child do - pop.skin(element.child[i], skin, true) - end - end - end -end pop.debugDraw = function(element) if element == nil then element = pop.screen diff --git a/init.moon b/init.moon index c6d4806..95dfa1e 100644 --- a/init.moon +++ b/init.moon @@ -27,12 +27,15 @@ import insert from table import inheritsFromElement from require "#{path}/util" --- @table pop ---- @field elements All GUI classes are stored here. ---- @field skins All skins are stored here. ---- @field extensions All extensions are loaded here. ---- @field screen The top level GUI element. Represents the game screen. Initialized in `pop.load()` +--- @tfield table elements All GUI classes are stored here. +--- @tfield table skins All skins are stored here. +--- @tfield table extensions All extensions are loaded here. +--- @tfield Element screen The top level GUI element. Represents the game +--- screen. Initialized in `pop.load()` +--- @tfield ?Element|false focused The currently focused GUI element (or `false` +--- if none is focused). --- @see pop.load ---- @field focused The currently focused GUI element (or `false` if none is focused). +--- @see Element pop.elements = {} pop.skins = {} @@ -44,12 +47,13 @@ pop.focused = false --- Loads elements, skins, extensions, and initializes `pop.screen`. --- ---- **IMPORTANT**: Intended to only be called once, and is automatically called when you require Pop.Box. +--- **IMPORTANT**: Intended to only be called once, and is automatically called +--- when you require Pop.Box. --- @function load --- @see pop +--- @see Element pop.load = -> - --@todo @ see Elements --@todo @ see Skins --@todo @ see Extensions elements = filesystem.getDirectoryItems "#{path}/elements" @@ -121,28 +125,37 @@ pop.load = -> --- Creates an element. --- @function create ---- @param element A string naming the element class to use. ---- @param parent[opt] The parent element. If `false`, an element is created with no parent. If `nil`, defaults to `pop.screen`. ---- @param ...[opt] Any number of parameters can be passed to the constructor for the element. +--- @tparam string element The element class to use. +--- @tparam ?Element|false|nil parent[opt] The parent element. If `false`, an +--- element is created with no parent. If `nil`, defaults to `pop.screen`. +--- @param ...[opt] Any number of parameters can be passed to the constructor +--- for the element. --- ---- (**Note**: An element with no parent will not be handled by Pop.Box's event handlers unless you handle it explicitly.) +--- (**Note**: An element with no parent will not be handled by Pop.Box's event +--- handlers unless you handle it explicitly.) --- @see pop +--- @see Element pop.create = (element, parent=pop.screen, ...) -> - --@todo @ see Elements -- if valid parent element, use it if inheritsFromElement parent element = pop.elements[element](parent, ...) insert parent.child, element insert parent.data.child, element.data + element.parent = parent + element.data.parent = parent.data -- if explicitly no parent, just create the element elseif parent == false element = pop.elements[element](false, ...) + element.parent = false + element.data.parent = false -- else use pop.screen (and "parent" is actually the first argument) else element = pop.elements[element](pop.screen, parent, ...) insert pop.screen.child, element insert pop.screen.data.child, element.data + element.parent = pop.screen + element.data.parent = pop.screen.data return element @@ -150,11 +163,14 @@ pop.create = (element, parent=pop.screen, ...) -> --- Event handler for `love.update()`. --- @function update ---- @param dt The amount of time passed since the last call to update, in seconds. ---- @param element[opt] The element to update (will update all its children as well). Defaults to `pop.screen`. +--- @tparam number dt The amount of time passed since the last call to update, +--- in seconds. +--- @tparam Element element[opt] The element to update (will update all its +--- children as well). Defaults to `pop.screen`. +--- @see Element pop.update = (dt, element=pop.screen) -> - --@todo Define Elements and @ see that documentation from here. Generic documentation, not specifically element! + --- @todo Define Elements and @ see that documentation from here. Generic documentation, not specifically element! -- data.update boolean controls an element and its children being updated if element.data.update if element.update @@ -166,10 +182,11 @@ pop.update = (dt, element=pop.screen) -> --- Event handler for `love.draw()`. --- @function draw ---- @param element[opt] The element to draw (will draw all its children as well). Defaults to `pop.screen`. +--- @tparam Element element[opt] The element to draw (will draw all its children +--- as well). Defaults to `pop.screen`. +--- @see Element pop.draw = (element=pop.screen) -> - --@todo @ see Elements -- data.draw boolean controls an element and its children being drawn if element.data.draw if element.draw @@ -179,16 +196,16 @@ pop.draw = (element=pop.screen) -> ---- Event handler for `love.mousemoved()`. (*LÖVE >= 0.10.0*) +--- Event handler for `love.mousemoved()`. (LÖVE >= 0.10.0) --- @function mousemoved ---- @param x The x coordinate of the mouse. ---- @param y The y coordinate of the mouse. ---- @param dx The distance on the x axis the mouse was moved. ---- @param dy The distance on the y axis the mouse was moved. ---- @return `true` / `false`: Was the event handled? +--- @tparam integer x The x coordinate of the mouse. +--- @tparam integer y The y coordinate of the mouse. +--- @tparam number dx The distance on the x axis the mouse was moved. +--- @tparam number dy The distance on the y axis the mouse was moved. +--- @treturn boolean Was the event handled? pop.mousemoved = (x, y, dx, dy) -> - --@todo Implement a way for an element to attach itself to `love.mousemoved()` events? + --- @todo Implement a way for an element to attach itself to `love.mousemoved()` events? if pop.focused and pop.focused.mousemoved return pop.focused\mousemoved x, y, dx, dy @@ -198,11 +215,14 @@ pop.mousemoved = (x, y, dx, dy) -> --- Event handler for `love.mousepressed()`. --- @function mousepressed ---- @param x The x coordinate of the mouse press. ---- @param y The y coordinate of the mouse press. ---- @param button The mouse button pressed. ---- @param element[opt] The element to check for event handling (will check its children as well). Defaults to `pop.screen`. ---- @return `true` / `false`: Was the event handled? +--- @tparam integer x The x coordinate of the mouse press. +--- @tparam integer y The y coordinate of the mouse press. +--- @tparam ?string|integer button The mouse button pressed. (Type varies by +--- LÖVE version.) +--- @tparam Element element[opt] The element to check for event handling (will +--- check its children as well). Defaults to `pop.screen`. +--- @treturn boolean Was the event handled? +--- @see Element pop.mousepressed = (x, y, button, element) -> -- start at the screen, print that we received an event @@ -234,12 +254,15 @@ pop.mousepressed = (x, y, button, element) -> --- Event handler for `love.mousereleased()`. --- @function mousereleased ---- @param x The x coordinate of the mouse release. ---- @param y The y coordinate of the mouse release. ---- @param button The mouse button released. ---- @param element[opt] The element to check for event handling (will check its children as well). Defaults to `pop.screen`. ---- @return `true` / `false`: Was a click handled? ---- @return `true` / `false`: Was a mouse release handled? +--- @tparam integer x The x coordinate of the mouse release. +--- @tparam integer y The y coordinate of the mouse release. +--- @tparam ?string|integer button The mouse button released. (Type varies by +--- LÖVE version.) +--- @tparam Element element[opt] The element to check for event handling (will +--- check its children as well). Defaults to `pop.screen`. +--- @treturn boolean Was a click handled? +--- @treturn boolean Was a mouse release handled? +--- @see Element pop.mousereleased = (x, y, button, element) -> -- we are trying to handle a clicked or mousereleased event @@ -266,7 +289,7 @@ pop.mousereleased = (x, y, button, element) -> -- if we clicked, we're focused! if clickedHandled pop.focused = element - --@todo Figure out how to bring a focused element to the front of view (aka the first element in its parent's children). + --- @todo Figure out how to bring a focused element to the front of view (aka the first element in its parent's children). --- (If I do it right here, the for loop above may break! I need to test/figure this out.) --NOTE this might cause an error in the above for loop! -- basically, move focused element to front of its parent's child @@ -284,8 +307,8 @@ pop.mousereleased = (x, y, button, element) -> --- Event handler for `love.keypressed()`. --- @function keypressed ---- @param key The key that was pressed. ---- @return `true` / `false`: Was the event handled? +--- @tparam string key The key that was pressed. +--- @treturn boolean Was the event handled? pop.keypressed = (key) -> print "keypressed", key @@ -301,8 +324,8 @@ pop.keypressed = (key) -> --- Event handler for `love.keyreleased()`. --- @function keyreleased ---- @param key The key that was released. ---- @return `true` / `false`: Was the event handled? +--- @tparam string key The key that was released. +--- @treturn boolean Was the event handled? pop.keyreleased = (key) -> print "keyreleased", key @@ -318,8 +341,8 @@ pop.keyreleased = (key) -> --- Event handler for `love.textinput()`. --- @function textinput ---- @param text The text that was typed. ---- @return `true` / `false`: Was the text input handled? +--- @tparam string text The text that was typed. +--- @treturn boolean Was the text input handled? pop.textinput = (text) -> print "textinput", text @@ -333,39 +356,11 @@ pop.textinput = (text) -> ---- Applies skins to elements. (**NOTE**: This function will be rewritten and change at some point...) ---- @function skin ---- @param element The element to skin (will also be applied to children). Defaults to `pop.screen`. ---- @param skin The skin to use, can be a string or an actual skin object, defaults to the default skin included with Pop.Box. ---- @param depth[opt] An integer for how many child levels to skin, OR, if `true`, will skin all children. - ---TODO rewrite skin system to not rely on knowing internals of elements, --- instead call functions like setColor and setBackground --- skins an element (and its children unless depth == true or 0) --- depth can be an integer for how many levels to go down when skinning --- defaults to pop.screen and the default skin -pop.skin = (element=pop.screen, skin=pop.skins.default, depth) -> - --@todo Rewrite the skin function taking advantage of data block / whatever else is needed. - if element.background and skin.background - element.background = skin.background - if element.color and skin.color - element.color = skin.color - if element.font and skin.font - element.font = skin.font - - unless depth or (depth == 0) - if depth == tonumber depth - for i = 1, #element.child - pop.skin element.child[i], skin, depth - 1 - else - for i = 1, #element.child - pop.skin element.child[i], skin, true - - - --- Draws simple rectangle outlines to debug placement of elements. --- @function debugDraw ---- @param element The element to draw (will draw its children as well). Defaults to `pop.screen`. +--- @tparam Element element[opt] The element to draw (will draw its children as +--- well). Defaults to `pop.screen`. +--- @see Element pop.debugDraw = (element=pop.screen) -> --@todo Make this better in the future when different element types have been created and whatnot. @@ -387,10 +382,12 @@ pop.debugDraw = (element=pop.screen) -> --- Prints a basic structure of GUI elements with minimal info. --- @function printElementTree ---- @param element The element to start at. Defaults to `pop.screen`. +--- @tparam Element element[opt] The element to start at. Defaults to +--- `pop.screen`. +--- @see Element pop.printElementTree = (element=pop.screen, depth=0) -> - --@todo Correct this once elements are reimplemented if it needs correction. + --- @todo Correct this once elements are reimplemented if it needs correction. cls = element.__class.__name if cls == "text" diff --git a/util.moon b/util.moon index fd9bc5e..b939336 100644 --- a/util.moon +++ b/util.moon @@ -2,12 +2,15 @@ --- @module util --- @copyright Paul Liverman III (2015-2016) --- @license The MIT License (MIT) ---- @release 0.0.0 --- @function inheritsFromElement ---- @param object A table (MoonScript object expected) to be checked for inheritence from the "element" element. ---- @return `true` / `false`: Is the table an object inherting from "element"? ---- @raise Can error if the table has a similar structure to a MoonScript object without being the same structure. +--- @tparam table object MoonScript object to be checked for inheritence from +--- the "element" element. +--- @treturn boolean Is the table an object inherting from "element"? +--- @raise Can error if the table has a similar structure to a MoonScript object +--- without being the same structure. +--- @see Element + inheritsFromElement = (object) -> if object and object.__class cls = object.__class