From d031150cd222a2d3e2b6a2ff01df40d9c5a9e59a Mon Sep 17 00:00:00 2001
From: Fox <paul.liverman.iii@gmail.com>
Date: Fri, 22 Jan 2016 05:33:46 -0800
Subject: [PATCH] updated docs, added new skinning system

---
 README.md                |  5 ++++-
 docs/Drawables.md        | 13 ++++++++++++
 docs/Elements.md         | 44 ++++++++++++++++++++++++++++++++--------
 docs/Pop.md              |  8 ++++----
 docs/Skins.md            | 23 +++++++++------------
 docs/Text.md             |  3 ---
 pop/elements/element.lua |  7 +++++++
 pop/elements/text.lua    | 14 +++++++++++++
 pop/init.lua             | 18 ++++++++++++++++
 pop/skins/clear.lua      |  7 +++++++
 10 files changed, 113 insertions(+), 29 deletions(-)
 create mode 100644 docs/Drawables.md
 delete mode 100644 docs/Text.md
 create mode 100644 pop/skins/clear.lua

diff --git a/README.md b/README.md
index eb83a85..dfd6f04 100644
--- a/README.md
+++ b/README.md
@@ -23,10 +23,13 @@ local pop = require "pop"
 local box = pop.box()
 ```
 
-Docs: [pop Module][3], [Elements][4], [Skins][5]
+Docs: [pop Module][3], [Elements][4], [Skins][5], [Drawables][6]
+
+TODO Support rotation?
 
 [1]: https://en.wikipedia.org/wiki/Cola_(programming_language)
 [2]: https://love2d.org/
 [3]: ./docs/Pop.md
 [4]: ./docs/Elements.md
 [5]: ./docs/Skins.md
+[6]: ./docs/Drawables.md
diff --git a/docs/Drawables.md b/docs/Drawables.md
new file mode 100644
index 0000000..a7575b6
--- /dev/null
+++ b/docs/Drawables.md
@@ -0,0 +1,13 @@
+# Supported Drawables
+
+Pop.Box supports three [Drawables][1]: Canvas, Image, Video
+
+Additionally, you can use in the place of any Drawable `false` to stop rendering
+of whatever is using a Drawable, or a table of color values.
+
+Color values are in the form `{r, g, b, a}` where `r` is 0 to 255 red, `g` is
+the same range for green, `b` is the same range for blue, and `a` is the same
+range for alpha. `a` is optional, but in the event that any element uses
+transparency, could screw up your rendering.
+
+[1]: https://love2d.org/wiki/Drawable
diff --git a/docs/Elements.md b/docs/Elements.md
index 2f0647a..43e1d93 100644
--- a/docs/Elements.md
+++ b/docs/Elements.md
@@ -5,9 +5,9 @@ Elements are the core of Pop.Box.
 - Elements are arranged hierarchically.
 - When an element is moved, its child elements move with it.
 - When an element is resized, it resizes in a way that makes sense based on its
-  alignment.
+  set alignment.
 - Elements are drawn from the top down (meaning child elements will always draw
-  on top of their parents.)
+  on top of their parents).
 
 The alignment stuff is much easier explained by experimenting or running the
 demo, please check it out!
@@ -20,6 +20,7 @@ All elements have the following standard methods:
 - `setSize(x, y)` - Sets the witdh/height of the element. Will stretch based on
   alignment (run the demo to see an example).
 - `getSize()` - Returns width and height of the element.
+- `adjustSize(x, y)` - Adjusts element size by `x`/`y`.
 - `align(horizontal, vertical)` - Sets alignment based on the parent's position
   and size. Valid `horizontal` strings: `left`, `center`, `right`. Valid
   `vertical` strings: `top`, `center`, `bottom`.
@@ -27,29 +28,54 @@ All elements have the following standard methods:
   element's position and size. Same `horizontal`/`vertical` strings as `align()`
 - `setAlignment(horizontal, vertical)` - Sets alignment *values* to this, but
   does not move the element. Same `horizontal`/`vertical` strings as `align()`
-- `setSkin(skin)` - Sets the skin (see [Skins.md][1]) used for this element.
 
 **Note**! Calls to `align()`, `alignTo()`, and `setAlignment()` change what
 positions will be returned, and how positioning and resizing will work. Run the
 demo to see how these affect things.
 
+(Elements are loaded from the `elements` directory, so place any custom ones in
+there.)
+
 ## Box Element
 
 Box is the simplest element, a rectangular area.
 
-`pop.box(parent, skin)`
+`pop.box(parent, background)`
 If `parent` not specified, uses `pop.window` (the top level element).
-If `skin` is not specified, uses `pop.currentSkin` (see [Skins.md][1]).
+If `background` is not specified, doesn't draw anything.
+
+Additional methods:
+
+- `setBackground()` - Sets background, you can use any [supported Drawable][3].
+- `getBackground()` - Returns current background, which may be any
+  [supported Drawable][3].
+- `setColor(r, g, b, a)` - Sets background based on colors (`a` is alpha, and
+  optional).
+- `getColor()` - Returns background color, or errors if the background is not a
+  color.
 
 TODO Make it possible to just specify skin?
 
-## Text Element (NOT DEFINED YET!)
+## Text Element
 
 Text is used to draw text.
 
-`pop.text(parent, text, skin)`
+`pop.text(parent, text, color)`
 If `parent` not specified, uses `pop.window` (the top level element).
-If `skin` is not specified, uses `pop.currentSkin` (see [Skins.md][1]).
+If `color` is not specified, uses white.
+
+Additional methods:
+
+- `setSize()` - Does not allow you to set the size, instead, it fixes the size
+  if it is incorrect (mostly for internal use).
+- `setText(text)` - Sets text and modifies size to fit.
+- `getText()` - Returns text.
+- `setFont()` - Sets [Font][2] and modifies size to fit. Note: Empty text will
+  have the height of the font (and presumably, a 0 width, size is based on
+  [Font][2] objects).
+- `getFont()` - Returns the [Font][2] in use.
+- `setColor(r, g, b, a)` - Sets text color (`a` is alpha, and optional).
+- `getColor()` - Returns text color.
 
 TODO Make it possible to just specify text, or just text and skin?
 TODO Make it possible to use setting size on text to actually calculate what
@@ -64,3 +90,5 @@ If you set `excludeRendering` to `true` on any element, it and its children will
 not be rendered.
 
 [1]: ./Skins.md
+[2]: https://love2d.org/wiki/Font
+[3]: ./Drawables.md
diff --git a/docs/Pop.md b/docs/Pop.md
index 95b3a50..53357df 100644
--- a/docs/Pop.md
+++ b/docs/Pop.md
@@ -9,15 +9,13 @@ Once that has been done (or at the very least, `pop` has been required and a
 callback is set up for `pop.draw`), you can start creating [Elements][1] and
 drawing them.
 
-Also look into [Skins][2], which control how elements are rendered.
+Also look into [Skins][2], which can make it easy to apply styles to many
+elements at once.
 
 ## `pop` Values / Methods
 
 - `pop.window` is the top level element. It essentially represents the game
   window.
-- `pop.currentSkin` holds a string specifying the currently in-use skin.
-  Basically, it's a shortcut so you don't have to specify a skin with every
-  call to construct an element.
 - `pop.create(element, parent, ...)` is how elements are actually created,
   `element` is a string naming the desired element. There are wrappers around
   any element that doesn't conflict with a key in the `pop` module so that you
@@ -25,6 +23,8 @@ Also look into [Skins][2], which control how elements are rendered.
 - `pop.load()` loads elements and skins, and sets up `pop.window`. This is used
   internally, and will probably lead to issues if you use it (namely, destroying
   Pop.Box's access to any existing GUI).
+- `pop.skin(element, skin, stop)` will apply the specified [skin][2] to the
+  specified `element` and its children (unless `stop` is set).
 
 ## `pop` Callbacks
 
diff --git a/docs/Skins.md b/docs/Skins.md
index 8fcedeb..cabd80f 100644
--- a/docs/Skins.md
+++ b/docs/Skins.md
@@ -1,19 +1,16 @@
 # Skins
 
-Skins are simply tables containing information on how to draw elements that have
-been assigned them. Skins are loaded from Pop's `skins` directory when you
-require it.
+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]). Skins are loaded from the `skins` directory.
 
-- `background` - A [Drawable][1] drawn before the `foreground`, or if a table,
-  assumed to be a [color][2] and that color is used (if `false`, is ignored).
-- `foreground` - A [Drawable][1] drawn after the `background`, or if a table,
-  assumed to be a [color][2] and that color is used (if `false`, is ignored).
-- `draw(element)` - If defined, will be used to render an element instead of the
-  standard drawing method.
-
-**Note**: Supported Drawables: Canvas, Image, Video
-
-TODO various text style infos!
+- `color` - [Color][2], used on text elements currently.
+- `background` - A [supported Drawable][4], used for backgrounds (or `false` or
+  a color).
+- `font` - For text elements, what [Font][5] to use.
 
 [1]: https://love2d.org/wiki/Drawable
 [2]: https://love2d.org/wiki/love.graphics.setColor
+[3]: ./Pop.md
+[4]: ./Drawables.md
+[5]: https://love2d.org/wiki/Font
diff --git a/docs/Text.md b/docs/Text.md
deleted file mode 100644
index 29ee295..0000000
--- a/docs/Text.md
+++ /dev/null
@@ -1,3 +0,0 @@
-- set text will modify size
-- set font will modify size
-- set size just fixes the size, you cannot manually set text size
diff --git a/pop/elements/element.lua b/pop/elements/element.lua
index a77a402..cde5378 100644
--- a/pop/elements/element.lua
+++ b/pop/elements/element.lua
@@ -100,6 +100,13 @@ function element:getSize()
     return self.w, self.h
 end
 
+function element:adjustSize(x, y)
+    local X, Y = self:getSize()
+    self:setSize(X + x, Y + y)
+
+    return self
+end
+
 function element:align(horizontal, vertical)
     self:setAlignment(horizontal, vertical)
 
diff --git a/pop/elements/text.lua b/pop/elements/text.lua
index beee56e..f581a49 100644
--- a/pop/elements/text.lua
+++ b/pop/elements/text.lua
@@ -67,4 +67,18 @@ function text:getFont()
     return self.font
 end
 
+function text:setColor(r, g, b, a)
+    self.color = {r, g, b, a}
+
+    if not a then
+        self.color[4] = 255
+    end
+
+    return self
+end
+
+function text:getColor()
+    return self.color[1], self.color[1], self.color[3], self.color[4]
+end
+
 return text
diff --git a/pop/init.lua b/pop/init.lua
index e40c906..f6fd611 100644
--- a/pop/init.lua
+++ b/pop/init.lua
@@ -87,6 +87,24 @@ function pop.keyreleased(key)
     --TODO no idea what to do with this
 end
 
+function pop.skin(element, skin, stop)
+    if element.background then
+        element.background = skin.background
+    end
+    if element.color then
+        element.color = skin.color
+    end
+    if element.font then
+        element.font = skin.font
+    end
+
+    if not stop then
+        for i=1,#element.child do
+            pop.skin(element.child[i], skin)
+        end
+    end
+end
+
 pop.load()
 
 return pop
diff --git a/pop/skins/clear.lua b/pop/skins/clear.lua
new file mode 100644
index 0000000..3c863a9
--- /dev/null
+++ b/pop/skins/clear.lua
@@ -0,0 +1,7 @@
+local skin = {}
+
+skin.color = {255, 255, 255, 255}
+skin.background = false
+skin.font = love.graphics.newFont(14)
+
+return skin