diff --git a/README.md b/README.md index 9f09a4d..4f26852 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,14 @@ Pop.Box is a GUI library for use in the [LÖVE][2] engine, designed to be easy t use and require as little code as possible to set up. It is primarily designed to make it easy to experiment with GUIs during development. +Supports LÖVE versions 0.9.1 and higher. + ## Features - Quickly set up and align GUI elements. - Fully customizable alignment / styling. - Moving/resizing elements takes alignment into account. +- Mouse and key input handling. (**Note**: Work in progress.) - Extensible: Make your own elements, skins, extensions, and everything is automatically loaded. @@ -25,6 +28,9 @@ local window = pop.window():align("center"):setTitle("Welcome!") 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`. # Documentation diff --git a/demo/test.ogv b/demo/test.ogv new file mode 100644 index 0000000..1dcdf39 Binary files /dev/null and b/demo/test.ogv differ diff --git a/docs/Pop.md b/docs/Pop.md new file mode 100644 index 0000000..5874f0e --- /dev/null +++ b/docs/Pop.md @@ -0,0 +1,66 @@ +# Pop Module + +This is the main module that allows you to access everything else in Pop.Box. +Simply require it (`local pop = require "pop"`) and define LÖVE callbacks for: + +- `pop.update(dt)` +- `pop.draw()` +- `pop.mousemoved(x, y, dx, dy)` (when using LÖVE 0.10.0 or later) +- `pop.mousepressed(x, y, button)` +- `pop.mousereleased(x, y, button)` +- `pop.keypressed(key)` +- `pop.keyreleased(key)` +- `pop.textinput(text)` + +Every callback returns `true`/`false` for whether or not the event was handled. +For example, using the `mousepressed` event handler: + +```lua +function love.mousepressed(x, y, button) + local handled = pop.mousepressed(x, y, button) + if not handled then + -- do something useful + end +end +``` + +## Creating Elements + +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 +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 + +See the [Skins][2] documentation. + +## Custom Elements/Skins/Extensions + +Any `.lua` file placed in the `elements`, `skins`, and `extensions` directories +within the module will be loaded and available as appropriate. See the +documentation on each for how to make them: + +- [Elements][1] +- [Skins][2] +- [Extensions][3] + +Also of use, there is a separate set of docs about how Pop.Box works under the +surface: [Pop Module (dev)][4] + +[1]: ./Elements.md +[2]: ./Skins.md +[3]: ./Extensions.md +[4]: ./dev/Pop.md diff --git a/docs/Skins.md b/docs/Skins.md new file mode 100644 index 0000000..9fdcf04 --- /dev/null +++ b/docs/Skins.md @@ -0,0 +1,19 @@ +# Skins + +**Note**: This system is mostly an after-thought right now, and will probably +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. + +- `color` - A table of RGBA values (see [love.graphics.setColor][2]), used as a + foreground color (currently for `text` elements only). +- `background` - A [supported Drawable][4], used for backgrounds (currently + used on `box` elements only). +- `font` - A [Font][5]. + +[2]: https://love2d.org/wiki/love.graphics.setColor +[3]: ./Pop.md +[4]: ./Drawables.md +[5]: https://love2d.org/wiki/Font diff --git a/docs/dev/Pop.md b/docs/dev/Pop.md new file mode 100644 index 0000000..36602fc --- /dev/null +++ b/docs/dev/Pop.md @@ -0,0 +1,8 @@ +# Pop Module (dev) + +(This document focuses on the structure and code of Pop.Box, not how to use it. + See the [regular documentation][1] for that.) + +TODO: Write me. + +[1]: ../Pop.md diff --git a/src/pop/init.moon b/src/pop/init.moon index 4ebe1ae..ec2da29 100644 --- a/src/pop/init.moon +++ b/src/pop/init.moon @@ -157,6 +157,8 @@ pop.textinput = (text) -> print "textinput", text return false --TODO event handlers return if they have handled the event! +--TODO rewrite skin system to not rely on knowing internals of elements, +-- instead call functions like setColor and setBackground -- skins an element (and its children unless depth == true or 0) -- depth can be an integer for how many levels to go down when skinning -- defaults to pop.screen and the default skin diff --git a/src/pop/skins/default.moon b/src/pop/skins/default.moon index cb1aa5a..197849e 100644 --- a/src/pop/skins/default.moon +++ b/src/pop/skins/default.moon @@ -1,3 +1,6 @@ +-- Note that the "default" name is a bit of a misnomer, as this does not +-- specify the defaults used in Pop.Box elements (they define their own) + import graphics from love return {