uing

Crystal binding for libui

UIng

test Lines of Code Ask DeepWiki

UIng is a Crystal binding for libui-ng.

libui-ng uses the native APIs of each platform: Win32 API, Direct2D, and DirectWrite on Windows; Cocoa (AppKit) on macOS; and GTK+ 3.10+ and Pango on Linux/Unix. You get windows, buttons, text boxes, menus, dialogs, drawing areas, and other standard widgets with the look and feel of each OS. The binary size is small.

Windows Mac Linux

Quick Start

Clone the repository and try the examples:

git clone https://github.com/kojix2/uing
cd uing
crystal run download.cr
crystal run examples/control_gallery.cr

Windows MSVC Setup

For Windows users using MSVC, use Developer Command Prompt or add Windows Kits path:

$env:Path += ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64"

Installation

Add the dependency to your shard.yml:

dependencies:
  uing:
    github: kojix2/uing

The required libui-ng binary is automatically downloaded from the kojix2/libui-ng GitHub Releases via postinstall.

Supported Platforms

  • macOS: x86_64 (64-bit), ARM64 (Apple Silicon)
  • Linux: x86_64 (64-bit), ARM64
  • Windows: x86_64 (64-bit, MSVC and MinGW), x86 (32-bit, MSVC only)

Usage

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

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 basic_window-ubuntu basic_window-windows basic_window-macos

Control

Control Ubuntu Windows macOS
Button basic_button-ubuntu basic_button-windows basic_button-macos
Checkbox basic_checkbox-ubuntu basic_checkbox-windows basic_checkbox-macos
ColorButton basic_color_button-ubuntu basic_color_button-windows basic_color_button-macos
Combobox basic_combobox-ubuntu basic_combobox-windows basic_combobox-macos
DateTimePicker basic_date_time_picker-ubuntu basic_date_time_picker-windows basic_date_time_picker-macos
EditableCombobox basic_editable_combobox-ubuntu basic_editable_combobox-windows basic_editable_combobox-macos
Entry basic_entry-ubuntu basic_entry-windows basic_entry-macos
FontButton basic_font_button-ubuntu basic_font_button-windows basic_font_button-macos
Label basic_label-ubuntu basic_label-windows basic_label-macos
MultilineEntry basic_multiline_entry-ubuntu basic_multiline_entry-windows basic_multiline_entry-macos
Progressbar basic_progressbar-ubuntu basic_progressbar-windows basic_progressbar-macos
RadioButtons basic_radio_buttons-ubuntu basic_radio_buttons-windows basic_radio_buttons-macos
Separator basic_separator-ubuntu basic_separator-windows basic_separator-macos
Slider basic_slider-ubuntu basic_slider-windows basic_slider-macos
Spinbox basic_spinbox-ubuntu basic_spinbox-windows basic_spinbox-macos

Container Control

Container Ubuntu Windows macOS
Box (Horizontal) basic_box_horizontal-ubuntu basic_box_horizontal-windows basic_box_horizontal-macos
Box (Vertical) basic_box_vertical-ubuntu basic_box_vertical-windows basic_box_vertical-macos
Tab basic_tab-ubuntu basic_tab-windows basic_tab-macos
Form basic_form-ubuntu basic_form-windows basic_form-macos
Group basic_group-ubuntu basic_group-windows basic_group-macos
Grid basic_grid-ubuntu basic_grid-windows basic_grid-macos
Grid (Calculator) grid_calculator-ubuntu grid_calculator-windows grid_calculator-macos

Note: Grid Layout does not work as expected on macOS.

Table

Example Ubuntu Windows macOS
basic_table basic_table-ubuntu basic_table-windows basic_table-macos
advanced_table advanced_table-ubuntu advanced_table-windows advanced_table-macos

Area

Example Ubuntu Windows macOS
basic_area basic_area-ubuntu basic_area-windows basic_area-macos
area_basic_shapes area_basic_shapes-ubuntu area_basic_shapes-windows area_basic_shapes-macos
area_colors_and_brushes area_colors_and_brushes-ubuntu area_colors_and_brushes-windows area_colors_and_brushes-macos
area_analog_clock area_analog_clock-ubuntu area_analog_clock-windows area_analog_clock-macos
spirograph spirograph-ubuntu spirograph-windows spirograph-macos
basic_draw_text basic_draw_text-ubuntu basic_draw_text-windows basic_draw_text-macos
area_breakout area_breakout-ubuntu area_breakout-windows area_breakout-macos
boid3d boid3d-ubuntu boid3d-windows boid3d-macos

Menu

Example Ubuntu Windows macOS
basic_menu basic_menu-ubuntu basic_menu-windows basic_menu-macos

Dialog

Example Ubuntu Windows macOS
basic_msg_box basic_msg_box-ubuntu basic_msg_box-windows basic_msg_box-macos
basic_msg_box_error basic_msg_box_error-ubuntu basic_msg_box_error-windows basic_msg_box_error-macos

Image (experimental)

Example Ubuntu Windows macOS
area_draw_image area_draw_image-ubuntu area_draw_image-windows area_draw_image-macos
basic_image_view basic_image_view-ubuntu basic_image_view-windows basic_image_view-macos

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 Safety

  • Most callbacks are stored as instance variables of their respective controls, which protects them from garbage collection (GC). Some callbacks are stored as UIng class variables, which serves the same purpose.

  • Instances of a control are passed as arguments to a parent control's append or set_child method. This establishes a reference from the parent to the child, creating a reference chain such as Window -> Box -> Button. This chain prevents the Garbage Collector (GC) from collecting the Button object (and its callbacks), thus avoiding a segmentation fault as long as the Window is present.

  • Some root components, such as Window and Menu, are stored as class variables to ensure protection from GC. This may cause memory leaks, but is acceptable for now.

  • The use of finalize is intentionally avoided in certain cases because the non-deterministic timing of memory deallocation by the GC is often incompatible with libui. Instead, RAII-style API is provided that automatically calls the free method upon exiting a block, relieving users of the need to call free manually.

Limitations

libui-ng is an excellent library, but supporting three platforms comes with some notable limitations:

  1. Image display is not supported. While tables can display images, the image sizes vary across platforms. (It is possible to display videos in areas using libmpv though.)

  2. Grid layout is broken on macOS.

  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.

Windows Setup

Hide Console Window

MinGW:

crystal build app.cr --link-flags "-mwindows"

MSVC:

crystal build app.cr --link-flags=/SUBSYSTEM:WINDOWS

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.

Development

  • UIng::LibUI is the module for direct C bindings
  • Initially, 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 in the pre-build branch.

Note:
This project was developed with the assistance of generative AI.

In particular, AI is used entirely to create GitHub Actions for taking screenshots and generating complex Examples.

While kojix2 prefers Vibe Coding, I think this library is not a product of Vibe Coding. it has been created with a good amount of manual work and human review.

Contributing

  • Fork this repository
  • Report bugs and submit pull requests
  • Improve documentation
  • Test memory safety improvements

License

MIT License

Repository

uing

Owner
Statistic
  • 7
  • 0
  • 2
  • 0
  • 1
  • about 8 hours ago
  • April 20, 2024
License

MIT License

Links
Synced at

Tue, 26 Aug 2025 07:23:13 GMT

Languages