mirror of
https://github.com/TangentFoxy/Pop.Box.git
synced 2024-12-15 12:44:20 +00:00
117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# Elements
|
|
|
|
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
|
|
set alignment.
|
|
- Elements are drawn from the top down (meaning child elements will always draw
|
|
on top of their parents).
|
|
|
|
The alignment stuff is much easier explained by experimenting or running the
|
|
demo, please check it out!
|
|
|
|
All elements have the following standard methods:
|
|
|
|
- `move(x, y)` - Moves the element by `x`/`y`.
|
|
- `setPosition(x, y)` - Sets the `x`/`y` position based on current alignment.
|
|
- `getPosition()` - Returns `x` and `y` position based on current alignment.
|
|
- `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`.
|
|
- `alignTo(element, horizontal, vertical)` - Sets alignment based on an
|
|
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()`
|
|
|
|
Events:
|
|
|
|
If any of these is set as a function, they will be called when the appropriate
|
|
event happens.
|
|
|
|
- `mousepressed(button, x, y)` - Called the moment a mouse click starts, uses
|
|
the same values for `button` as [love.mousepressed][4], but the `x`/`y` are
|
|
relative to the element.
|
|
- `mousereleased(button, x, y)` - Called the moment a mouse click stops, uses
|
|
the same values for `button` as [love.mousepressed][4], but the `x`/`y` are
|
|
relative to the element.
|
|
- `clicked(button, x, y)` - Called when a mouse click stops if it started on the
|
|
same element. Uses the same values for `button` as [love.mousepressed][4], but
|
|
the `x`/`y` are relative to the 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, background)`
|
|
If `parent` not specified, uses `pop.window` (the top level element).
|
|
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 background?
|
|
|
|
## Text Element
|
|
|
|
Text is used to draw text.
|
|
|
|
`pop.text(parent, text, color)`
|
|
If `parent` not specified, uses `pop.window` (the top level element).
|
|
If `color` is not specified, uses white.
|
|
|
|
Overwritten methods:
|
|
|
|
- `setSize()` - Does not allow you to set the size, instead, it fixes the size
|
|
if it is incorrect (mostly for internal use).
|
|
|
|
Additional methods:
|
|
|
|
- `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 color?
|
|
TODO Make it possible to use setting size on text to actually calculate what
|
|
font size will make that work?
|
|
|
|
# Excluding Movement/Rendering
|
|
|
|
If you set `excludeMovement` to `true` on any element, it and its children will
|
|
not be moved unless its own movement methods are used.
|
|
|
|
If you set `excludeRendering` to `true` on any element, it and its children will
|
|
not be rendered.
|
|
|
|
If you set `excludeUpdating` 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
|
|
[4]: https://love2d.org/wiki/love.mousepressed
|