yui/README.md

Yui - A Declarative UI library for LÖVE
=======================================

**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

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** 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.