docs updates + element wip

This commit is contained in:
Paul Liverman III 2016-09-07 21:42:19 -07:00
parent 0f6c10a226
commit fda0a340c9
12 changed files with 350 additions and 42 deletions

View File

@ -3,6 +3,10 @@
--- **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!
---
--- **Note**: The event handling functions only know about children of
--- `pop.screen` or children of an element *you* have called Pop.Box's event
--- handlers on.
--- @see element
@ -18,20 +22,20 @@
--- @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.
--- **Optional**: Called from `pop.update()` if `data.update`. 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.
--- **Optional**: Called from `pop.draw()` if `data.draw`. 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 integer x The x coordinate of the mouse relative to the element.
--- @tparam integer y The y coordinate of the mouse relative to the element.
--- @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?
@ -42,8 +46,10 @@
--- **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 integer x The x coordinate of the mouse press relative to the
--- element.
--- @tparam integer y The y coordinate of the mouse press relative to the
--- element.
--- @tparam ?string|integer button The mouse button pressed. (Type varies by
--- LÖVE version.)
--- @treturn boolean Was the event handled?
@ -78,7 +84,7 @@
--- The parent element of this element.
--- @tfield ?Element|false parent Parent element.
--- The child elements of this element.
--- The child element(s) of this element.
--- @tfield table child All child elements.
@ -87,7 +93,7 @@
--- 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
--- @tfield ?table|false|nil 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.

View File

@ -67,9 +67,33 @@
<h2><a href="#Methods">Methods</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#element.new">element.new (self, @, @)</a></td>
<td class="name" nowrap><a href="#element.new">element.new (parent, data)</a></td>
<td class="summary">Constructor expects nothing, or a data table describing it.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.setSize">element.setSize (w, h)</a></td>
<td class="summary">Sets an element's width/height.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.getSize">element.getSize (self)</a></td>
<td class="summary">Returns an element's width and height.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.setWidth">element.setWidth (w)</a></td>
<td class="summary">Sets an element's width.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.getWidth">element.getWidth (self)</a></td>
<td class="summary">Returns an element's width.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.setHeight">element.setHeight (h)</a></td>
<td class="summary">Sets an element's height.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#element.getHeight">element.getHeight (self)</a></td>
<td class="summary">Returns an element's height.</td>
</tr>
</table>
<br/>
@ -81,12 +105,74 @@
<dl class="function">
<dt>
<a name = "element.new"></a>
<strong>element.new (self, @, @)</strong>
<strong>element.new (parent, data)</strong>
</dt>
<dd>
Constructor expects nothing, or a data table describing it.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">parent</span>
<span class="types"><span class="type">Element</span> or <span class="type">false</span></span>
The parent element.
</li>
<li><span class="parameter">data</span>
<span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
[opt] The data (state) for this element.
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../classes/element.html#">element</a></span>
self
</ol>
</dd>
<dt>
<a name = "element.setSize"></a>
<strong>element.setSize (w, h)</strong>
</dt>
<dd>
Sets an element's width/height.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">w</span>
<span class="types"><span class="type">integer</span></span>
[opt] Width.
</li>
<li><span class="parameter">h</span>
<span class="types"><span class="type">integer</span></span>
[opt] Height.
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../classes/element.html#">element</a></span>
self
</ol>
</dd>
<dt>
<a name = "element.getSize"></a>
<strong>element.getSize (self)</strong>
</dt>
<dd>
Returns an element's width and height.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
@ -94,18 +180,127 @@
</li>
<li><span class="parameter">@</span>
</ul>
<h3>Returns:</h3>
<ol>
<li>
<span class="types"><span class="type">integer</span></span>
Width.</li>
<li>
<span class="types"><span class="type">integer</span></span>
Height.</li>
</ol>
</dd>
<dt>
<a name = "element.setWidth"></a>
<strong>element.setWidth (w)</strong>
</dt>
<dd>
Sets an element's width.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">w</span>
<span class="types"><span class="type">integer</span></span>
Width.
</li>
<li><span class="parameter">@</span>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../classes/element.html#">element</a></span>
self
</ol>
</dd>
<dt>
<a name = "element.getWidth"></a>
<strong>element.getWidth (self)</strong>
</dt>
<dd>
Returns an element's width.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">integer</span></span>
Width.
</ol>
</dd>
<dt>
<a name = "element.setHeight"></a>
<strong>element.setHeight (h)</strong>
</dt>
<dd>
Sets an element's height.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">h</span>
<span class="types"><span class="type">integer</span></span>
Height.
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../classes/element.html#">element</a></span>
self
</ol>
</dd>
<dt>
<a name = "element.getHeight"></a>
<strong>element.getHeight (self)</strong>
</dt>
<dd>
Returns an element's height.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">integer</span></span>
Height.
</ol>
@ -118,7 +313,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -79,7 +79,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -60,6 +60,10 @@
means that any methods defined on that class need to be compatible with or
overridden by your class!</p>
<p> <strong>Note</strong>: The event handling functions only know about children of
<code>pop.screen</code> or children of an element <em>you</em> have called Pop.Box's event
handlers on.</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
@ -74,13 +78,11 @@
</tr>
<tr>
<td class="name" nowrap><a href="#update">update (dt)</a></td>
<td class="summary"><strong>Optional</strong>: Called from <code>pop.update()</code> if <code>data.update</code> and a child of
<code>pop.screen</code>.</td>
<td class="summary"><strong>Optional</strong>: Called from <code>pop.update()</code> if <code>data.update</code>.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#draw">draw ()</a></td>
<td class="summary"><strong>Optional</strong>: Called from <code>pop.draw()</code> if <code>data.draw</code> and a child of
<code>pop.screen</code>.</td>
<td class="summary"><strong>Optional</strong>: Called from <code>pop.draw()</code> if <code>data.draw</code>.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mousemoved">mousemoved (x, y, dx, dy)</a></td>
@ -118,7 +120,7 @@
</tr>
<tr>
<td class="name" nowrap><a href="#child">child</a></td>
<td class="summary">The child elements of this element.</td>
<td class="summary">The child element(s) of this element.</td>
</tr>
</table>
@ -184,8 +186,8 @@
<strong>update (dt)</strong>
</dt>
<dd>
<strong>Optional</strong>: Called from <code>pop.update()</code> if <code>data.update</code> and a child of
<code>pop.screen</code>. Use it for any time-based updates your element may need.
<strong>Optional</strong>: Called from <code>pop.update()</code> if <code>data.update</code>. Use it for any
time-based updates your element may need.
<h3>Parameters:</h3>
@ -206,8 +208,8 @@
<strong>draw ()</strong>
</dt>
<dd>
<strong>Optional</strong>: Called from <code>pop.draw()</code> if <code>data.draw</code> and a child of
<code>pop.screen</code>. Use it to draw your element.
<strong>Optional</strong>: Called from <code>pop.draw()</code> if <code>data.draw</code>. Use it to draw your
element.
@ -229,11 +231,11 @@
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">integer</span></span>
The x coordinate of the mouse.
The x coordinate of the mouse relative to the element.
</li>
<li><span class="parameter">y</span>
<span class="types"><span class="type">integer</span></span>
The y coordinate of the mouse.
The y coordinate of the mouse relative to the element.
</li>
<li><span class="parameter">dx</span>
<span class="types"><span class="type">number</span></span>
@ -272,11 +274,13 @@
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">integer</span></span>
The x coordinate of the mouse press.
The x coordinate of the mouse press relative to the
element.
</li>
<li><span class="parameter">y</span>
<span class="types"><span class="type">integer</span></span>
The y coordinate of the mouse press.
The y coordinate of the mouse press relative to the
element.
</li>
<li><span class="parameter">button</span>
<span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a> or <span class="type">integer</span></span>
@ -394,7 +398,7 @@
<h3>Fields:</h3>
<ul>
<li><span class="parameter">parent</span>
<span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a> or <span class="type">false</span></span>
<span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a>, <span class="type">false</span> or <span class="type">nil</span></span>
The parent of this element's data field. This
will <strong>not</strong> be serialized. This is the <em>only</em> exception to all data being
serialized.
@ -464,7 +468,7 @@
<strong>child</strong>
</dt>
<dd>
The child elements of this element.
The child element(s) of this element.
<ul>
@ -486,7 +490,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -71,7 +71,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -665,7 +665,7 @@ table.insert element.parent, element.parent\removeChild(element),
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -125,7 +125,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-09-07 20:53:10 </i>
<i style="float:right;">Last updated 2016-09-07 21:37:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

View File

@ -2,7 +2,32 @@ local element
do
local _class_0
local _base_0 = {
setSize = function(self) end
setSize = function(self, w, h)
if w then
self.data.w = w
end
if h then
self.data.h = h
end
return self
end,
getSize = function(self)
return self.data.w, self.data.h
end,
setWidth = function(self, w)
self.data.w = w
return self
end,
getWidth = function(self)
return self.data.w
end,
setHeight = function(self, h)
self.data.h = h
return self
end,
getHeight = function(self)
return self.data.h
end
}
_base_0.__index = _base_0
_class_0 = setmetatable({
@ -14,6 +39,30 @@ do
if type(self.data ~= "table") then
self.data = { }
end
if not (self.data.parent) then
self.data.parent = false
end
if not (self.data.child) then
self.data.child = { }
end
if not (self.data.x) then
self.data.x = 0
end
if not (self.data.y) then
self.data.y = 0
end
if not (self.data.w) then
self.data.w = 0
end
if not (self.data.h) then
self.data.h = 0
end
if self.data.update == nil then
self.data.update = false
end
if self.data.draw == nil then
self.data.draw = true
end
end,
__base = _base_0,
__name = "element"

View File

@ -5,9 +5,60 @@
class element
--- Constructor expects nothing, or a data table describing it.
--- @tparam ?Element|false parent The parent element.
--- @tparam table data[opt] The data (state) for this element.
--- @treturn element self
new: (@parent, @data={}) =>
if type @data != "table"
@data = {}
setSize: =>
--do more stuff!
@data.parent = false unless @data.parent --included for correctness
@data.child = {} unless @data.child
@data.x = 0 unless @data.x
@data.y = 0 unless @data.y
@data.w = 0 unless @data.w
@data.h = 0 unless @data.h
@data.update = false if @data.update == nil
@data.draw = true if @data.draw == nil
--- Sets an element's width/height.
--- @tparam integer w[opt] Width.
--- @tparam integer h[opt] Height.
--- @treturn element self
setSize: (w, h) =>
if w
@data.w = w
if h
@data.h = h
return @
--- Returns an element's width and height.
--- @treturn integer Width.
--- @treturn integer Height.
getSize: =>
return @data.w, @data.h
--- Sets an element's width.
--- @tparam integer w Width.
--- @treturn element self
setWidth: (w) =>
@data.w = w
return @
--- Returns an element's width.
--- @treturn integer Width.
getWidth: =>
return @data.w
--- Sets an element's height.
--- @tparam integer h Height.
--- @treturn element self
setHeight: (h) =>
@data.h = h
return @
--- Returns an element's height.
--- @treturn integer Height.
getHeight: =>
return @data.h

View File

@ -154,7 +154,7 @@ pop.draw = function(element)
end
pop.mousemoved = function(x, y, dx, dy)
if pop.focused and pop.focused.mousemoved then
return pop.focused:mousemoved(x, y, dx, dy)
return pop.focused:mousemoved(x - pop.focused.data.x, y - pop.focused.data.y, dx, dy)
end
return false
end

View File

@ -207,7 +207,7 @@ pop.draw = (element=pop.screen) ->
pop.mousemoved = (x, y, dx, dy) ->
--- @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
return pop.focused\mousemoved x - pop.focused.data.x, y - pop.focused.data.y, dx, dy
return false

View File

@ -27,8 +27,11 @@ describe "Pop.Box", ->
pending "loads all extensions", ->
-- see checks for loading all elements
pending "creates an element the size of the game window", ->
-- use our shim's width/height, check the size of the element, check that it actually is an element class object, make sure it is stored in pop.screen
it "creates an element the size of the game window", ->
pop = require "init"
w, h = pop.screen\getSize!
assert.are.equal love.graphics.getWidth!, w
assert.are.equal love.graphics.getHeight!, h
pending "check inherit checker", ->