From 8b4375b38c93d87083451fdf6bd157dbb17deeb8 Mon Sep 17 00:00:00 2001 From: Paul Liverman III Date: Sat, 16 Apr 2016 23:57:21 -0700 Subject: [PATCH] wip #5, docs updated, next commit has some code updates --- README.md | 5 +++-- docs/Drawables.md | 4 ++-- docs/Elements.md | 4 ++-- docs/Excludes.md | 14 ++++++++++++++ docs/Skins.md | 22 ++++++++++++++++++++-- docs/dev/Pop.md | 7 +++++++ docs/dev/elements/window.md | 4 ++++ docs/elements/element.md | 15 ++++++++++++--- 8 files changed, 64 insertions(+), 11 deletions(-) create mode 100644 docs/Excludes.md create mode 100644 docs/dev/elements/window.md diff --git a/README.md b/README.md index 4f26852..d5bc7f2 100644 --- a/README.md +++ b/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.) diff --git a/docs/Drawables.md b/docs/Drawables.md index b1ed96e..3db65da 100644 --- a/docs/Drawables.md +++ b/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 diff --git a/docs/Elements.md b/docs/Elements.md index cc38df4..20be594 100644 --- a/docs/Elements.md +++ b/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 diff --git a/docs/Excludes.md b/docs/Excludes.md new file mode 100644 index 0000000..1460964 --- /dev/null +++ b/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). diff --git a/docs/Skins.md b/docs/Skins.md index 9fdcf04..9b3bae4 100644 --- a/docs/Skins.md +++ b/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). diff --git a/docs/dev/Pop.md b/docs/dev/Pop.md index 36602fc..55ea328 100644 --- a/docs/dev/Pop.md +++ b/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 diff --git a/docs/dev/elements/window.md b/docs/dev/elements/window.md new file mode 100644 index 0000000..354df90 --- /dev/null +++ b/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. diff --git a/docs/elements/element.md b/docs/elements/element.md index eb87609..e6e67a6 100644 --- a/docs/elements/element.md +++ b/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