wip #5, docs updated, next commit has some code updates

README.md

@@ -31,11 +31,12 @@ window:addChild(pop.text("Welcome to Pop.Box()!"))
 **Note**: Due to this being so early in development...the above example doesn't
 actually work as expected. `window` is a very new element.
 
-For more examples, see the code in `demo`. For documentation, see `docs`.
+For more examples, see the code in `demo`. For documentation, see `docs` (and
+links to documentation below).
 
 # Documentation
 
-**Note**: Docs not written just yet. Will be soon.
+**Note**: Docs are a work in progress, sometimes lagging behind the actual code.
 
 - [Pop Module][3] (The main module/interface.)
 - [Elements][4] (Basic features of elements/types of elements.)

docs/Drawables.md

@@ -8,8 +8,8 @@ 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*.)
+(The alpha value is optional, but not using an alpha is likely to mess up your
+ rendering if an alpha is used *anywhere else*.)
 
 [1]: https://love2d.org/wiki/Drawable
 [2]: https://love2d.org/wiki/love.graphics.setColor

docs/Elements.md

@@ -2,7 +2,7 @@
 
 Elements are the core of Pop.Box.
 
-Once `pop` has been required, you can create Elements and interact with them.
+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
@@ -22,7 +22,7 @@ so check their documentation.)
 - [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.)
+- [Window][5] (A movable window. Has a title and area for other elements.)
 
 [1]: ./elements/element.md
 [2]: ./elements/box.md

docs/Excludes.md

@@ -0,0 +1,14 @@
+# Excludes
+
+Any element can have a few boolean values set to exclude it from normal
+operations for movement, rendering, and updating. Simply set the appropriate
+value to a true value.
+
+Note that any element using one of these excludes its children as well.
+
+- `excludeMovement` Excludes movement caused by a parent being moved.
+- `excludeUpdate` Excludes an element from being updated (by `pop.update()`).
+- `excludeDraw` Excludes being rendered (by `pop.draw()`).
+
+**Note**: `excludeDraw` also excludes an element from accepting events (it
+wouldn't make sense to have an invisible element capturing text input).

docs/Skins.md

@@ -4,8 +4,26 @@
 be replaced with something else entirely.
 
 Skins are simple tables containing information to style a variety of elements.
-Use `pop.skin()` to apply a skin to an element and its children (see
-[Pop Module][3] documentation). Skins are loaded from the `skins` directory.
+Use `pop.skin()` to apply a skin to an element and its children. Skins are
+loaded from the `skins` directory.
+
+**Note**: Skins are only applied on elements as-is. You can't change elements
+added in the future by setting a skin, or change a skin to modify elements that
+have had it applied. In the future, I might change this. (This skinning system
+is basically a placeholder.)
+
+Usage: `pop.skin(element, skin, depth)`
+
+- `element` is the element to start with.
+- `skin` is the skin (a table).
+- `depth` is how many levels of children of the element should be skinned.
+  Defaults to skinning as many levels of children as there are.
+
+Alternately, you can think of depth as a boolean for "don't recurse". By
+setting it to `true`, you can stop skinning children. `false` (and default
+behavior) will skin all levels of children.
+
+## What's inside a skin
 
 - `color` - A table of RGBA values (see [love.graphics.setColor][2]), used as a
   foreground color (currently for `text` elements only).

docs/dev/Pop.md

@@ -5,4 +5,11 @@
 
 TODO: Write me.
 
+## Notes
+
+- `pop.mousereleased()` Handling a click maybe should *not* check bounds.
+  Handling a mouse release should maybe *not* check for `excludeDraw`. If an
+  element was already selected and then went invisible, I'm probably breaking
+  things worse by doing this.
+
 [1]: ../Pop.md

docs/dev/elements/window.md

@@ -0,0 +1,4 @@
+- `addChild()` Adds children to `@window` instead of itself. This may cause
+  issues with expectation vs result. A user expects when using `addChild()` that
+  an element will be a direct child of `window`, not that it will end up in a
+  sub-element.

docs/elements/element.md

@@ -17,12 +17,19 @@ calling `getPosition()`.
 
 ## Methods
 
+Every method that does not return a value returns the element itself, so that
+you can chain method calls (ex: `box:setSize(100, 50):align("right")`).
+
 - `addChild(child)` Adds a child element.
+- `removeChild(child)` Removes child element by reference or index. If `child`
+  is a number, it will return the child at that index (after removing it).
 - `getChildren()` Returns a numerically indexed table of child elements.
 - `move(x, y)` Moves the element (and its children) by specified values.
-  Parameters optional.
+  Parameters optional. (Children can exclude being moved with their parent. See
+  [Excludes][1].)
 - `setPosition(x, y)` Sets position of the element (and its children) based on
-  the alignment of the element. Parameters optional.
+  the alignment of the element. Parameters optional. (Children can exclude being
+  moved with their parent. See [Excludes][1].)
 - `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
@@ -38,7 +45,7 @@ calling `getPosition()`.
   "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
+  `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.
@@ -51,3 +58,5 @@ calling `getPosition()`.
 - `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.
+
+[1]: ../Excludes.md