LibUI

build Gem Version

:radio_button: libui - a portable GUI library - for Ruby

Installation

gem install libui
  • The gem package contains the official release of the libui shared library versions 4.1 for Windows, Mac, and Linux.
    • Namely libui.dll, libui.dylib, and libui.so (only 1.4MB in total).
  • No dependency
    • The libui gem uses the standard Ruby library Fiddle to call C functions.
Windows Mac Linux

Note: If you are using the 32-bit (x86) version of Ruby, you need to download the 32-bit (x86) native dll. See Development.

Usage

require 'libui'

UI = LibUI

UI.init

main_window = UI.new_window('hello world', 200, 100, 1)

button = UI.new_button('Button')

UI.button_on_clicked(button) do
  UI.msg_box(main_window, 'Information', 'You clicked the button')
end

UI.window_on_closing(main_window) do
  puts 'Bye Bye'
  UI.control_destroy(main_window)
  UI.quit
  0
end

UI.window_set_child(main_window, button)
UI.control_show(main_window)

UI.main
UI.quit

See examples directory.

General Rules

Compared to original libui written in C,

  • The method names are snake_case.
  • If the last argument is nil, it can be omitted.
  • You can pass a block as a callback.
    • The block will be converted to a Proc object and added to the last argument.
    • Even in that case, it is possible to omit the last argument nil.

You can use the documentation for libui's Go bindings as a reference.

Not object oriented?

  • At the moment, it is not object-oriented.
    • Instead of providing a half-baked object-oriented approach, leave it as is.

DSLs for LibUI

How to use fiddle pointers?

require 'libui'
UI = LibUI
UI.init

Convert a pointer to a string.

label = UI.new_label("Ruby")
p pointer = UI.label_text(label) # #<Fiddle::Pointer>
p pointer.to_s # Ruby

If you need to use C structs, you can do the following.

font_button = UI.new_font_button

# Allocate memory 
font_descriptor = UI::FFI::FontDescriptor.malloc
font_descriptor.to_ptr.free = Fiddle::RUBY_FREE

UI.font_button_on_changed(font_button) do
  UI.font_button_font(font_button, font_descriptor)
  p family:  font_descriptor.Family.to_s,
    size:    font_descriptor.Size,
    weight:  font_descriptor.Weight,
    italic:  font_descriptor.Italic,
    stretch: font_descriptor.Stretch
end
  • Callbacks
    • In Ruby/Fiddle, C callback function is written as an object of Fiddle::Closure::BlockCaller or Fiddle::Closure. In this case, you need to be careful about Ruby's garbage collection. If the function object is collected, memory will be freed and a segmentation violation will occur when the callback is invoked.
# to a local variable to prevent it from being collected by GC.
handler.MouseEvent   = (c1 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
handler.MouseCrossed = (c2 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
handler.DragBroken   = (c3 = Fiddle::Closure::BlockCaller.new(0, [0]) {})

How to create an executable (.exe) on Windows

OCRA (One-Click Ruby Application) builds Windows executables from Ruby source code.

In order to build a exe with Ocra, include 3 DLLs from ruby_builtin_dlls folder:

ocra examples/control_gallery.rb        ^
  --dll ruby_builtin_dlls/libssp-0.dll  ^
  --dll ruby_builtin_dlls/libgmp-10.dll ^
  --dll ruby_builtin_dlls/libffi-7.dll  ^
  --gem-all=fiddle                      ^

Add additional options below if necessary.

  --window                              ^
  --add-all-core                        ^
  --chdir-first                         ^
  --icon assets\app.ico                 ^
  --verbose                             ^
  --output out\gallery.exe

Development

git clone https://github.com/kojix2/libui
cd libui
bundle install
bundle exec rake vendor:all_x64 # download shared libraries for all platforms
bundle exec rake test

You can use the following rake tasks to download the shared library required for your platform.

rake -T

rake vendor:all_x64      # Download libui.so, libui.dylib, and libui.dll to...
rake vendor:linux_x64    # Download libui.so for Linux to vendor directory
rake vendor:linux_x86    # Download libui.so for Linux to vendor directory
rake vendor:mac_x64      # Download libui.dylib for Mac to vendor directory
rake vendor:windows_x64  # Download libui.dll for Windows to vendor directory
rake vendor:windows_x86  # Download libui.dll for Windows to vendor directory

For example, If you are using a 32-bit (x86) version of Ruby on Windows, type rake vendor:windows_x86.

Or Set environment variable LIBUIDIR to specify the path to the shared library.

Contributing

Would you like to add your commits to libui?

  • Please feel free to send us your pull requests.
    • Small corrections, such as typofixes, are appreciated.
  • Did you find any bugs?　Write it in the issues section!

Acknowledgement

This project is inspired by libui-ruby.

While libui-ruby uses Ruby-FFI, this gem uses Fiddle.

License

MIT License.