glimmer-dsl-libui

Glimmer DSL for LibUI 0.13.1

Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library (Fukuoka Award Winning)

The Quickest Way From Zero To GUI

If You Liked Shoes, You'll Love Glimmer!

(Fukuoka Ruby Award Competition 2022 Special Award Winner)

(RubyConf 2024 Workshop - How To Build Basic Desktop Applications in Ruby)

(RubyConf 2023 Workshop - How To Build Desktop Applications in Ruby)

(RubyConf 2022 Talk - Building Native GUI Apps in Ruby)

(Ruby Rogues Podcast Interview - Desktop Apps in Ruby ft. Andy)

Glimmer DSL for LibUI is a Fukuoka Award Winning prerequisite-free MRI Ruby desktop development cross-platform native GUI (Graphical User Interface) library. No need to pre-install any prerequisites. Just install the gem and have cross-platform native GUI that just works on Mac, Windows, and Linux!

LibUI is a relatively new C GUI library that renders native controls on every platform (similar to SWT, but without the heavy weight of the Java Virtual Machine). Applications built with Glimmer DSL for LibUI will provide the familiar native look, feel, and behavior of GUI on Mac, Windows, and Linux.

The main trade-off in using Glimmer DSL for LibUI as opposed to Glimmer DSL for SWT or Glimmer DSL for Tk is the fact that SWT and Tk are more mature than mid-alpha libui as GUI toolkits. Still, if there is only a need to build a small simple application, Glimmer DSL for LibUI could be a good convenient choice due to having zero prerequisites (beyond Ruby and the dependencies included in the Ruby gem). Also, just like Glimmer DSL for Tk, its apps start instantly and have a small memory footprint. LibUI is a promising new GUI toolkit that might prove quite worthy in the future.

Note that the new Glimmer DSL for WX is supporting the new wxruby3 binding for wxWidgets, which offers native GUI support just like LibUI, but with a mature toolkit. If you need to build more serious native GUI apps and prefer CRuby over JRuby, then Glimmer DSL for WX could be the best option for that.

Glimmer DSL for LibUI aims to provide a DSL similar to the Glimmer DSL for SWT to enable more productive desktop development in Ruby with:

• Declarative DSL syntax that visually maps to the GUI control hierarchy
• Convention over configuration via smart defaults and automation of low-level details
• Requiring the least amount of syntax possible to build GUI
• Custom Component support (Custom Controls, Custom Windows, and Custom Shapes), including Component Slots and external Ruby gems (e.g. Graphs and Charts)
• Bidirectional/Unidirectional Data-Binding to declaratively wire and automatically synchronize GUI Views with Models
• Scaffolding for new custom windows/controls, apps, and gems
• [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.

Hello, World!

require 'glimmer-dsl-libui'

include Glimmer

window('hello world').show

Basic Button

require 'glimmer-dsl-libui'

include Glimmer

window('hello world', 300, 200) {
  button('Button') {
    on_clicked do
      msg_box('Information', 'You clicked the button')
    end
  }
}.show

Basic Table Progress Bar

…

Form Table

…

Area Gallery

…

Check out many more examples over here! Check out many real apps built with Glimmer DSL for LibUI over here!

NOTE: Glimmer DSL for LibUI is regularly catching up with changes in the C libui-ng library API and in beta mode. The C libui-ng is still mid-alpha, which is why Glimmer DSL for LibUI cannot be declared v1.0.0 yet. Please help make better by contributing, adopting for small or low risk projects, and providing feedback. The more feedback and issues you report the better.

Learn more about the differences between various Glimmer DSLs by looking at the Glimmer DSL Comparison Table.

Table of Contents

• Glimmer DSL for LibUI
  • Setup
  • Usage
    • Experimentation Usage
    • Prototyping Usage
    • Serious Usage
  • Glimmer Command
    • Run Application
    • Run Examples
    • Scaffold Application
    • Scaffold Custom Control
    • Scaffold Custom Window
    • Scaffold Custom Shape
    • Scaffold Custom Control Gem
    • Scaffold Custom Window Gem
    • Scaffold Custom Shape Gem
    • List Custom Control Gems
    • List Custom Window Gems
    • List Custom Shape Gems
    • List Glimmer DSLs
  • Girb (Glimmer IRB)
  • Glimmer GUI DSL Concepts
  • API
    • Supported Keywords
    • Common Control Properties
    • Common Control Operations
    • LibUI Operations
    • Extra Dialogs
    • Extra Operations
    • Table API
    • Area API
      • Scrolling Area
      • Area Path Shapes
      • Area Text
      • Area Image
      • Colors
      • Area Draw Params
      • Area Listeners
      • Area Methods/Attributes
      • Area Transform Matrix
      • Area Composite Shape
      • Area Animation
    • Smart Defaults and Conventions
    • Custom Components
      • Method-Based Custom Components
      • Class-Based Custom Components
    • Observer Pattern
    • Data-Binding
      • Bidirectional (Two-Way) Data-Binding
        • Table Data-Binding
      • Unidirectional (One-Way) Data-Binding
      • Data-Binding API
      • Data-Binding Gotchas
    • API Gotchas
    • Original API
  • Packaging
  • Glimmer Style Guide
  • Examples
    • Basic Examples
    • Advanced Examples
  • Applications
    • Manga2PDF
    • Befunge98 GUI
    • i3off Gtk Ruby
    • Chess
    • RubyCrumbler
    • Rubio-Radio
    • PMV Calc
  • Design Principles
  • Glimmer Process
  • Resources
  • Help
    • Issues
    • Chat
  • Planned Features and Feature Suggestions
  • Change Log
  • Contributing
  • Contributors
  • License

Setup

Note: the newest Ruby 3.3 is not fully supported yet.

Install glimmer-dsl-libui gem directly into a maintained Ruby version:

gem install glimmer-dsl-libui

Or install via Bundler Gemfile:

gem 'glimmer-dsl-libui', '~> 0.13.1'

Test that installation worked by running the Glimmer Meta-Example:

glimmer examples

Or alternatively, run using the explicit Ruby command:

ruby -r glimmer-dsl-libui -e "require 'examples/meta_example'"

Usage

Start by requiring the glimmer-dsl-libui Ruby gem, whether through a Ruby require 'glimmer-dsl-libui statement or Bundler.

Afterwards, to access the Glimmer GUI DSL:

• If you are learning/experimenting/prototyping with Glimmer DSL for LibUI, include the Glimmer module into the top-level scope or a Ruby class.
• If you are building a serious application, include Glimmer::LibUI::Application into the main view Ruby class
• If you are building a custom control, include Glimmer::LibUI::CustomControl into a Ruby class
• If you are building a cusotm window, include Glimmer::LibUI::CustomWindow into a Ruby class
• If you are building a custom shape, include Glimmer::LibUI::CustomShape into a Ruby class.

You may learn more about the different options above with basic examples in the following subsections: Experimentation Usage, Prototyping Usage, Serious Usage.

If you are new to Glimmer DSL for LibUI (beginner), after going through the subsections below, check out the RubyConf 2022 talk "Building Native GUI Apps in Ruby", Glimmer GUI DSL Concepts, Glimmer Style Guide, Glimmer Command (just the basics, how to run an app, and how to run examples to start), [Girb](#girb