wip docs + small modifications

docs/Drawables.md

@@ -0,0 +1,15 @@
+# Supported Drawables
+
+Pop.Box supports three [Drawables][1]: Canvas, Image, and Video.
+
+**Note**: Video and Canvas support are untested.
+
+Additionally, in the place of a Drawable, you can use `false` to not render
+anything, or a table of color values. The color values should be in the format
+LÖVE uses (`{red, green, blue, alpha}`, see [love.graphics.setColor][2]).
+
+(The alpha value is optional and will default to `255`, but not using an alpha
+ is likely to mess up your rendering if an alpha value is used *anywhere else*.)
+
+[1]: https://love2d.org/wiki/Drawable
+[2]: https://love2d.org/wiki/love.graphics.setColor

docs/Elements.md

@@ -0,0 +1,31 @@
+# Elements
+
+Elements are the core of Pop.Box.
+
+Once `pop` has been required, you can create Elements and interact with them.
+Most elements can be created like this: `local box = pop.box(...)`
+
+However, if an element's name clashes with a function name used in Pop.Box, you
+will have to use `pop.create(type, ...)` where `type` is a string naming the
+element type. (No standard elements do this.)
+
+When creating an element, the first argument is its parent element. If the first
+argument is not an element, it will be treated as the second argument. If it is
+`false`, then an element with no parent will be created.
+
+When no parent is specified, an element's parent is `pop.screen`, which is the
+top-level element of Pop.Box. (This behavior can be modified by custom elements,
+so check their documentation.)
+
+## Available Elements
+
+- [Element][1] (The base of all elements, and useful for alignment.)
+- [Box][2] (A box, can be colored, or display a [supported Drawable][3].)
+- [Text][4] (Plain text, no special features. Useful for basic labels and such.)
+- [Window][5] (A moveable window. Has a title and area for other elements.)
+
+[1]: ./elements/element.md
+[2]: ./elements/box.md
+[3]: ./Drawables.md
+[4]: ./elements/text.md
+[5]: ./elements/window.md

docs/Extensions.md

@@ -0,0 +1,14 @@
+# Extensions
+
+Extensions are simply a way for custom code to be run after loading elements and
+skins. Simply place a `.lua` file in the `extensions` directory, and it will be
+required.
+
+## Standard Extensions
+
+There is only one standard extension, which modifies element classes to add a
+more convenient getter/setter method to most get/set methods. For example,
+instead of `element:getSize()`, just call `element:size()`. Instead of
+`element:setSize(w, h)`, call `element:size(w, h)`.
+
+This is mostly for a demo of what can be possible, but also might be useful.

docs/Pop.md

@@ -29,19 +29,7 @@ end
 Once `pop` has been required, you can create [Elements][1] and interact with
 them. Most elements can be created like this: `local box = pop.box(...)`
 
-However, if an element's name clashes with a function name used in Pop.Box, you
+For more information, see the [Elements documentation][1].
-will have to use `pop.create(type, ...)` where `type` is a string naming the
-element type.
-
-When creating an element, the first argument is its parent element. If the first
-argument is not an element, it will be treated as the second argument. If it is
-`false`, then an element with no parent will be created. When no parent is
-specified, an element's parent is `pop.screen`, which is the top-level element
-of Pop.Box.
-
-(This behavior can be modified by elements themselves. No standard element does
- this, but if you use an element created by someone else, check its
- documentation first.)
 
 ## Skinning Elements
 

docs/elements/element.md

@@ -0,0 +1,53 @@
+# element
+
+This is the base of all elements, and useful for alignment purposes. It is also
+the element type used for `pop.screen` (the top-level element of Pop.Box). All
+methods here are available on all other elements (any differences are noted on
+their documentation pages).
+
+## Alignment
+
+All elements have a `horizontal` and `vertical` alignment property. These modify
+how elements are aligned and how positions are handled. For example, an element
+aligned to the top-right will return the position of the top-right corner when
+calling `getPosition()`.
+
+- `horizontal` can be `left`, `center`, or `right`. Defaults to `left`.
+- `vertical` can be `top`, `center`, or `bottom`. Defaults to `top`.
+
+## Methods
+
+- `addChild(child)` Adds a child element.
+- `getChildren()` Returns a numerically indexed table of child elements.
+- `move(x, y)` Moves the element (and its children) by specified values.
+  Parameters optional.
+- `setPosition(x, y)` Sets position of the element (and its children) based on
+  the alignment of the element. Parameters optional.
+- `getPosition()` Returns x/y position of the element based on its alignment.
+- `setSize(w, h)` Sets the width/height of the element, element keeps "in-place"
+  based on its alignment. (For example, a right-aligned element will grow to the
+  left.) Parameters optional.
+- `getSize()` Returns the width/height of the element.
+- `setWidth(w)` Sets the width of the element. Element stays "in-place" based on
+  its alignment.
+- `getWidth()` Returns the width of the element.
+- `setHeight(h)` Sets the height of the element. Element stays "in-place" based
+  on its alignment.
+- `getHeight()` Returns the height of the element.
+- `adjustSize(w, h)` Grows the element by a relative width/height. Element stays
+  "in-place" based on its alignment.
+- `align(horizontal, vertical, toPixel)` Aligns the element based on its margin
+  and parent. `toPixel` is a boolean for pixel-perfect alignment, defaulting to
+  true. See above section about alignment for valid values of `horizontal` and
+  `vertical`. A parent element is required for this method.
+- `alignTo(element, horizontal, vertical, toPixel)` Works just like `align()`,
+  except that alignment is based on a specific element instead of the parent.
+  Does not require a parent element.
+- `setAlignment(horizontal, vertical)` Sets alignment values on the element
+  *without* moving the element.
+- `getAlignment()` Returns the `horizontal` and `vertical` alignment of the
+  element.
+- `setMargin(m)` Sets a margin to be used when aligning the element.
+- `getMargin()` Returns the current margin value.
+- `fill()` Resizes and aligns the element to fill its parent's area, with the
+  element's margin taken into account on all sides.

src/pop/elements/element.moon

@@ -173,7 +173,7 @@ class element
         return @
 
     --TODO note that align requires a parent!
-    align: (horizontal, vertical, toPixel) =>
+    align: (horizontal, vertical, toPixel=true) =>
         @setAlignment horizontal, vertical
 
         @x = @parent.x
@@ -195,17 +195,17 @@ class element
             when "bottom"
                 @y += @parent.h - @h - @margin
 
-        if toPixel or (toPixel == nil)
+        if toPixel
             @x = floor @x
             @y = floor @y
 
         return @
 
-    alignTo: (element, horizontal, vertical) =>
+    alignTo: (element, horizontal, vertical, toPixel=true) =>
         parent = @parent
         @parent = element
 
-        @align horizontal, vertical
+        @align horizontal, vertical, toPixel
 
         @parent = parent
 

src/pop/elements/window.moon

@@ -19,8 +19,8 @@ do
         if revision == 1
             mousemoved_event = false
     else
-        print "elements/window: unrecognized LÖVE version: #{major}.#{minor}.#{revision}"
+        print "elements/window: unrecognized LOVE version: #{major}.#{minor}.#{revision}"
-        print "                 assuming LÖVE version > 0.10.1  (there may be bugs)"
+        print "                 assuming LOVE version > 0.10.1  (there may be bugs)"
 
 pop_ref = false -- reference to pop, loaded by pop.load!
 

src/pop/init.moon

@@ -1,5 +1,5 @@
 unless love.getVersion
-    error "Pop.Box only supports LÖVE versions >= 0.9.1"
+    error "Pop.Box only supports LOVE versions >= 0.9.1"
 
 import filesystem, graphics from love
 import insert from table