This is a read only mirror of yui's main repository
Go to file
Lorenzo Cogotti 3dd1a039e0 [choice] Update clamp import path 2024-01-26 16:30:45 +01:00
device [*] Initial commit. 2022-08-15 23:41:17 +02:00
.gitignore [*] add documentation 2022-09-12 09:36:03 +02:00
.lovedeps [.lovedeps] Update dependencies 2023-11-01 11:01:23 +01:00
LICENSE [*] Initial commit. 2022-08-15 23:41:17 +02:00
README.ACKNOWLEDGEMENT [*] Initial commit. 2022-08-15 23:41:17 +02:00
README.md [README] Update project links 2023-11-01 11:05:48 +01:00
button.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
checkbox.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
choice.lua [choice] Update clamp import path 2024-01-26 16:30:45 +01:00
columns.lua [*] Style improvements, make constructors callable by :. 2022-10-25 13:26:30 +02:00
config.ld [config.ld] Update links in config.ld too. 2022-11-06 17:46:53 +01:00
core.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
crush.lua [crush] Update crush.lua. 2022-11-06 17:45:16 +01:00
init.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
input.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
label.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
layout.lua [layout] Improve focus management 2023-09-19 18:17:22 +02:00
rows.lua [rows] Minor style improvement. 2023-09-19 18:16:18 +02:00
slider.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
spacer.lua [*] Style improvements, make constructors callable by :. 2022-10-25 13:26:30 +02:00
theme.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00
ui.lua [ui] Invoke Timer:new() as a method (API update for gear.timer) 2023-09-19 18:18:51 +02:00
widget.lua [*] Rework theme customization. 2022-10-25 19:06:57 +02:00

README.md

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

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

Hello, World!

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 for general algorithms.
  • 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 to do the work for you.

  1. Clone this repository.
git clone https://codeberg.org/1414codeforge/yui
  1. Move to repository root directory:
cd yui
  1. Resolve dependencies using crush.
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 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:

{
    yui = "https://codeberg.org/1414codeforge/yui",

    -- ...more dependencies, if necessary...
}
  1. Yui can now be downloaded directly by crush to the project's lib directory:
lua crush.lua
  1. Now yui can be require()d in your code, like this:
local yui = require 'lib.yui'
  1. Any project depending on yours will now fetch yui automatically when using crush, following the above procedure.

Documentation

Code is documented with LDoc.

Documentation may be generated running the command:

ldoc .

ldoc generates a doc directory, open doc/index.html with your favorite browser to read the documentation.

The source code is also (IMHO) sufficiently straightforward and disciplined to have a decent overview of the functionality.

Examples are available at: https://codeberg.org/1414codeforge/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. SUIT is licensed under the MIT license.

Widgets offered by yui and basic theme are also mostly taken from SUIT.

See ACKNOWLEDGEMENT for full SUIT license information and copyright notice.

Similar projects

  • SUIT an excellent, simple and flexible framework for immediate UIs.
  • Gspöt a stateful GUI lib for LÖVE, has similar aims, but different approach.

License

Zlib, see LICENSE for details.