[README] Improve project description and usage docs.

master
Lorenzo Cogotti 2 years ago
parent f098b1cbd5
commit 6b7b987940

@ -1,19 +1,106 @@
Yui - A Declarative UI library for LÖVE
=======================================
**Yui** - Yet another User Interface, is an attempt to ease the process of assembling trivial menu-like GUIs for your game using [LÖVE](https://love2d.org).
**Yui** - Yet another User Interface, is a library to create menu-like GUIs
for games using 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.
## 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 dependency 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,
along with any other dependency:
```sh
lua crush.lua
```
4. You may now use `yui` in your project by `require()`-ing it.
```lua
local yui = require 'lib.yui'
```
5. Any project depending on yours may now fetch your project's dependencies (including `yui`)
automatically using `crush`, following the above procedure.
## Documentation
...Ouch.
Documentation and examples are underway, however the source code is (IMHO) sufficiently
straightforward and disciplined to have sufficient overview of the functionality.
## Acknowledgement
@ -27,3 +114,11 @@ Widgets offered by **yui** are also inspired by **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.
## License
Zlib, see [LICENSE](LICENSE) for details.

Loading…
Cancel
Save