166 lines
4.7 KiB
Markdown
166 lines
4.7 KiB
Markdown
Yui - A Declarative UI library for LÖVE
|
|
=======================================
|
|
|
|
**Yui** - Yet another User Interface, is a library to create menu-like GUIs
|
|
for the [LÖVE](https://love2d.org) engine.
|
|
|
|
## Why is that?
|
|
|
|
Because I'm spending so much time tweaking and customizing existing libraries,
|
|
I might as well make my own.
|
|
|
|
## Hello, World!
|
|
|
|
```lua
|
|
local yui = require 'lib.yui'
|
|
|
|
function love.load()
|
|
local w, h = 300, 80
|
|
local x = math.floor((love.graphics.getWidth() - w) / 2)
|
|
local y = math.floor((love.graphics.getHeight() - h) / 2)
|
|
|
|
ui = yui.Ui.new {
|
|
x = x, y = y,
|
|
|
|
yui.Rows {
|
|
yui.Label {
|
|
w = w, h = h / 2,
|
|
text = "Hello, World!"
|
|
},
|
|
yui.Button {
|
|
text = "Close",
|
|
|
|
onHit = function() love.event.quit() end
|
|
}
|
|
}
|
|
}
|
|
end
|
|
|
|
function love.update(dt)
|
|
ui:update(dt)
|
|
end
|
|
|
|
function love.draw()
|
|
ui:draw()
|
|
end
|
|
```
|
|
|
|
|
|
|
|
## Features
|
|
|
|
**Yui** fills the following gaps:
|
|
|
|
* Immediate mode UIs tend to clutter LÖVE `update()` code a lot, using a declarative approach - that is:
|
|
describing how the UI should look upfront, and then letting the UI code `update()` and `draw()` itself accordingly,
|
|
makes for a cleaner code.
|
|
* Adapt to different sources of input easily (keyboard, mouse, touch, gamepad).
|
|
* Out of the box internationalization.
|
|
* Out of the box keyboard navigation across widgets.
|
|
* Simple layouts (place widget in columns or rows, or possibly build rows made of several columns - grids).
|
|
* Custom widgets support.
|
|
* Custom theme support.
|
|
* Custom input sources support.
|
|
* Sufficiently compact, straightforward and hackable code.
|
|
|
|
**Yui** does have some downsides:
|
|
|
|
* The declarative approach makes UIs harder to change drastically from frame to frame.
|
|
* **Yui** tries to ameliorate this, allowing widgets property tweening, it's still less powerful
|
|
compared to an all out immediate UI approach.
|
|
* Features come with a price, **Yui**'s code tries to be small and simple, but there are definitely smaller
|
|
(and less featureful) frameworks out there.
|
|
|
|
## Dependencies
|
|
|
|
**Yui** depends on:
|
|
|
|
* [gear](https://git.doublefourteen.io/lua/gear) for general algorithms.
|
|
* [moonspeak](https://git.doublefourteen.io/lua/moonspeak) for its localization functionality.
|
|
* ...and any of their dependencies.
|
|
|
|
You may either download each of them manually and place them inside a `lib` subdirectory, or use
|
|
[crush](https://git.doublefourteen.io/lua/crush) to do the work for you.
|
|
|
|
1. Clone this repository.
|
|
|
|
```sh
|
|
git clone https://git.doublefourteen.io/lua/yui
|
|
```
|
|
|
|
2. Move to repository root directory:
|
|
|
|
```sh
|
|
cd yui
|
|
```
|
|
|
|
3. Resolve dependencies using **crush**.
|
|
|
|
```sh
|
|
lua crush.lua
|
|
```
|
|
|
|
You should now see a `lib` subdirectory containing the necessary dependencies.
|
|
|
|
## Integrating yui in my project using crush
|
|
|
|
1. Download the latest [crush.lua](https://git.doublefourteen.io/lua/crush/src/branch/master/crush.lua) file and
|
|
place it in your project's root directory.
|
|
|
|
2. Create a `.lovedeps` text file in your project's root with the following entry:
|
|
|
|
```lua
|
|
{
|
|
yui = "https://git.doublefourteen.io/lua/yui",
|
|
|
|
-- ...more dependencies, if necessary...
|
|
}
|
|
```
|
|
|
|
3. **Yui** can now be downloaded directly by `crush` to the project's `lib` directory:
|
|
|
|
```sh
|
|
lua crush.lua
|
|
```
|
|
|
|
4. Now `yui` can be `require()`d in your code, like this:
|
|
|
|
```lua
|
|
local yui = require 'lib.yui'
|
|
```
|
|
|
|
5. Any project depending on yours will now fetch `yui`
|
|
automatically when using `crush`, following the above procedure.
|
|
|
|
## Documentation
|
|
|
|
...Ouch.
|
|
|
|
Documentation is underway, however the source code is (IMHO) sufficiently
|
|
straightforward and disciplined to have a decent overview of the functionality.
|
|
|
|
Examples are available at:
|
|
[https://git.doublefourteen.io/lua/yui-examples](https://git.doublefourteen.io/lua/yui-examples)
|
|
|
|
## Acknowledgement
|
|
|
|
Portions of this library's widget rendering code are taken from the
|
|
Simple User Interface Toolkit (**SUIT**) for LÖVE by Matthias Richter.
|
|
|
|
SUIT's source code is available at: [vrld/SUIT](https://github.com/vrld/SUIT).
|
|
SUIT is licensed under the [MIT license](https://github.com/vrld/suit/blob/master/license.txt).
|
|
|
|
Widgets offered by **yui** and basic theme are also mostly taken from SUIT.
|
|
|
|
See [ACKNOWLEDGEMENT](README.ACKNOWLEDGEMENT) for full SUIT license
|
|
information and copyright notice.
|
|
|
|
## Similar projects
|
|
|
|
* [SUIT](https://github.com/vrld/SUIT) an excellent, simple and flexible framework for immediate UIs.
|
|
* [Gspöt](https://notabug.org/pgimeno/Gspot) a stateful GUI lib for LÖVE, has similar aims, but different approach.
|
|
|
|
## License
|
|
|
|
Zlib, see [LICENSE](LICENSE) for details.
|