https://github.com/kojix2/uing
Crystal binding for libui
https://github.com/kojix2/uing
crystal libui libui-ng
Last synced: 7 days ago
JSON representation
Crystal binding for libui
- Host: GitHub
- URL: https://github.com/kojix2/uing
- Owner: kojix2
- License: mit
- Created: 2024-04-20T14:13:04.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-07T06:49:40.000Z (16 days ago)
- Last Synced: 2026-03-07T14:32:14.975Z (16 days ago)
- Topics: crystal, libui, libui-ng
- Language: Crystal
- Homepage: https://kojix2.github.io/uing/
- Size: 17.1 MB
- Stars: 26
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# UIng
[](https://github.com/kojix2/uing/actions/workflows/screenshot.yml)
[](https://tokei.kojix2.net/github/kojix2/uing)
[](https://deepwiki.com/kojix2/uing)
[](https://github.com/kojix2/uing/actions/workflows/ci-linux-x64.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-linux-arm64.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-macos-arm64.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-macos-intel.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-windows-msvc.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-windows-mingw64.yml)
[](https://github.com/kojix2/uing/actions/workflows/ci-windows-ucrt64.yml)
UIng is a [Crystal](https://crystal-lang.org/) binding for [libui-ng](https://github.com/libui-ng/libui-ng).
libui-ng uses the native APIs of each platform: Win32 API, [Direct2D](https://learn.microsoft.com/windows/win32/Direct2D/), and [DirectWrite](https://learn.microsoft.com/windows/win32/directwrite/) on Windows; [Cocoa]() (AppKit) on macOS; and [GTK+ 3.10+](https://docs.gtk.org/gtk3/) and [Pango](https://docs.gtk.org/Pango/) on Linux/Unix.
You get windows, buttons, text boxes, menus, dialogs, drawing areas, and other standard widgets.
Windows
Mac
Linux
📸 **Live Documentation**: All screenshots in the README are automatically generated by [GitHub Actions](https://github.com/kojix2/uing/blob/main/.github/workflows/screenshot.yml) on every push, ensuring cross-platform compatibility (Linux, Windows, macOS).
## Supported Platforms
- macOS: x86_64 (64-bit), ARM64 (Apple Silicon)
- Linux: x86_64 (64-bit), ARM64
- Windows: x86_64 (64-bit, MSVC, MinGW, and UCRT), x86 (32-bit, MSVC only)
## Installation
Add the dependency to your `shard.yml`:
```yaml
dependencies:
uing:
github: kojix2/uing
```
- The required libui-ng binary is automatically downloaded from [kojix2/libui-ng GitHub Releases](https://github.com/kojix2/libui-ng/releases) via [postinstall](https://github.com/kojix2/uing/blob/main/shard.yml).
- The UIng project is not just a binding; it provides unofficial patched builds of libui-ng for platforms. For more details, see the [README.md](https://github.com/kojix2/libui-ng/blob/main/README.md) and commits on the [`dev` branch](https://github.com/kojix2/libui-ng/commits/dev).
## Quick Start
Clone the repository:
```sh
git clone https://github.com/kojix2/uing
cd uing
```
Create the `libui` directory and download the static library for your platform:
```sh
crystal run download.cr
```
To run the `control_gallery` example, use the following command:
```sh
crystal run examples/control_gallery.cr
```
### Windows MSVC Setup
For Windows users using MSVC, use Developer Command Prompt or add Windows Kits path:
```powershell
$env:Path += ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64"
```
## Usage
```crystal
require "uing"
UIng.init
window = UIng::Window.new("Hello World", 300, 200)
window.on_closing do
UIng.quit
true
end
button = UIng::Button.new("Click me")
button.on_clicked do
window.msg_box("Info", "Button clicked!")
end
window.set_child(button)
window.show
UIng.main
UIng.uninit
```
### DSL style
```crystal
require "uing"
UIng.init do
UIng::Window.new("Hello World", 300, 200) { |win|
on_closing { UIng.quit; true }
set_child {
UIng::Button.new("Click me") {
on_clicked {
win.msg_box("Info", "Button clicked!")
}
}
}
show
}
UIng.main
end
```
Note: The DSL style is implemented using Crystal's `with ... yield` syntax internally.
## Examples Gallery
This gallery shows screenshots of example on three platforms (Ubuntu, Windows, macOS).
Images are automatically generated and stored in the `screenshots` branch.
### Window
Control
Ubuntu
Windows
macOS
Window
### Control
Control
Ubuntu
Windows
macOS
Button
Checkbox
ColorButton
Combobox
DateTimePicker
EditableCombobox
Entry
FontButton
Label
MultilineEntry
Progressbar
RadioButtons
Separator
Slider
Spinbox
### Container Control
Container
Ubuntu
Windows
macOS
Box (Horizontal)
Box (Vertical)
Tab
Form
Group
Grid
Grid (Calculator)
Note: Grid Layout does not work as expected on macOS.
### Table
Example
Ubuntu
Windows
macOS
basic_table
csv_viewer
advanced_table
Note: The Table API has quirks. For example, you must manually free memory as [instructed](https://github.com/kojix2/uing/issues/6) when the program terminates.
### Area
Example
Ubuntu
Windows
macOS
basic_area
area_basic_shapes
area_colors_and_brushes
area_analog_clock
spirograph
area_matrix
basic_draw_text
reversi
area_breakout
boid3d
### Menu
Example
Ubuntu
Windows
macOS
basic_menu
### Dialog
Example
Ubuntu
Windows
macOS
basic_msg_box
basic_msg_box_error
### Image (experimental)
Example
Ubuntu
Windows
macOS
area_draw_image
basic_image_view
Note: Image display is a feature introduced experimentally in a fork of libui-ng. Please be aware that this feature is not present in the original libui-ng.
## API Levels
Level
Defined in
Example
Description
High-Level
src/uing/*.cr
button.on_clicked { }, etc.
Object-oriented API
Low-Level
src/uing/lib_ui/lib_ui.cr
UIng::LibUI.new_button, etc.
Direct bindings to libui
- Almost all basic control functions such as `Window`, `Label`, and `Button` are covered.
- APIs for advanced controls such as `Table` and `Area` are also provided. However, these are still under development and there may still be memory management issues.
## Memory Management Policy
libui-ng is a C library, so normally the user is expected to manage memory manually.
However, it also provides some automatic memory management. The basic rule is: when a parent control is destroyed, all of its child controls are automatically destroyed as well.
For example, when destroy is called on controls such as Window, Box, Grid, Group, or Tab, it first destroys all child controls and then destroys itself.
In the case of a Window, there are two common situations:
When the user clicks the close (×) button on the title bar
In this case, on_closing is triggered, and Window#destroy is called automatically.
When on_should_quit is triggered
This means the entire program is about to quit. But here, Window#destroy is not called automatically, so the user needs to call it explicitly.
Crystal has garbage collection (GC) and provides a finalize hook when objects are freed. However, GC timing is non-deterministic, and libui-ng controls often require deterministic destruction order.
Therefore, UIng's primary policy is:
- Control objects (`Window`, `Box`, `Grid`, `Tab`, etc.) are managed with explicit `destroy`.
- C resources that require strict ordering (for example `Table::Model`) are managed with explicit `free`.
- `finalize` is never treated as a primary cleanup mechanism for order-sensitive resources.
Some lightweight wrappers include idempotent cleanup in `finalize` as a fallback, but this is best-effort only and not a correctness guarantee.
It may seem a bit tricky, but understanding how libui-ng handles memory will help you avoid problems when building applications.
Some controls require specific destruction order for proper memory cleanup
- [#6](https://github.com/kojix2/uing/issues/6)
- Table
- [#19](https://github.com/kojix2/uing/issues/19)
- MultilineEntry
- Tab
- Grid
- Area
## Limitations
libui-ng is cross-platform, but comes with some limitations:
1. The original libui-ng does not provide image display functionality. A patch has been applied in this project to add experimental support, which is available in the main branch.
2. The grid layout system is known to be broken on macOS. A patch has been applied to improve the behavior, though it still does not fully match the expected design.
3. Precise widget positioning is not possible. Control placement is intentionally coarse and cannot be specified numerically. This is likely an intentional constraint to ensure consistent behavior across all three platforms.
4. There is no function to delete columns from the table.
## Windows Setup
### Hide Console Window
MinGW:
```
crystal build app.cr --link-flags "-mwindows"
```
MSVC:
```
crystal build app.cr --link-flags=/SUBSYSTEM:WINDOWS
```
## Packaging Your Application
To learn how to package your UIng-based application for distribution, refer to the [md5_checker](examples/md5_checker) example.
This example demonstrates a simple way to bundle your Crystal app with the required native libraries, making it easy to share with others.
## Development
- `UIng::LibUI` is the module for direct C bindings
- Initially, [crystal_lib](https://github.com/crystal-lang/crystal_lib) was used to generate low-level bindings
- However, it required many manual conversions, such as changing LibC::Int to Bool. Currently, it is better to use AI.
- When adding new UI components, follow the established callback management patterns
- libui libraries are generated using GitHub Actions at [kojix2/libui-ng](https://github.com/kojix2/libui-ng) in the pre-build branch.
- Enhancement patches such as image display functionality are provided on the dev branch.
### Sustainability
From experience, maintaining a GUI library is harder than it looks, often requiring two to three times more effort than expected.
Rather than chasing new features, we should prioritize **sustainability**.
### Memory Safety
UIng applies several strategies to ensure safe interoperation between Crystal’s garbage-collected runtime and native C code:
- Callback Protection: Most callbacks are stored as instance variables of their controls, preventing them from being collected by the GC. Closures are additionally protected using `::Box.box()`, allowing Crystal blocks that capture external variables to be safely used as C callbacks.
- Reference Chains: Controls are passed to parent containers (e.g., `Window -> Box -> Button`), ensuring that children remain referenced as long as the parent exists. Root components such as `Window` and `Menu` are stored as class variables to avoid premature collection.
- Extended Handler Structures: For complex controls like `Area` and `Table`, extended C structs embed the base handler along with extra fields for boxed callbacks. Static C-compatible trampolines cast back to these extended structs and invoke the stored closures safely.
- Resource Management rules are defined in [Memory Management Policy](#memory-management-policy). In short, UIng prioritizes explicit ownership and explicit release (`destroy` / `free`), while RAII-style APIs are provided where possible.
### Closures in Low-Level Contexts
- Many methods support Crystal closures because the underlying libui-ng functions accept a `data` parameter.
- In some low-level APIs, such as function pointers assigned to struct members, no `data` can be passed. UIng works around this by using struct inheritance and boxed data to support closures in these cases.
- This approach is used in controls like `Table` and `Area`.
### Use of AI Coding
This project was developed with the assistance of generative AI.
In particular, AI was extensively used for:
- Creating GitHub Actions workflows for screenshot automation
- Generating complex example programs
- Producing patches for libui-ng
While kojix2 enjoys code generation and “Vibe Coding,” UIng is not a library created purely with that approach. In reality, it was built through substantial manual work, iterative design, and human review of AI-generated code.
I also maintain several projects that are based purely on the Vibe Coding style, but I do not consider this library to be one of them.
## Contributing
- Fork this repository
- Report bugs and submit pull requests
- Improve documentation
- Test memory safety improvements
## License
MIT License