glimmer-dsl-libui 0.1.9 → 0.2.1

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.1.9
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.2.1
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ce2853efdbecf6ebdc73/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-libui/maintainability)
@@ -118,11 +118,17 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(200, 200, 90, 0, 360, false)
+      circle(200, 200, 90)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -191,7 +197,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.1.9](#-glimmer-dsl-for-libui-019)
+- [Glimmer DSL for LibUI 0.2.1](#-glimmer-dsl-for-libui-021)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -199,6 +205,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Supported Controls](#supported-controls)
     - [Common Control Properties](#common-control-properties)
     - [Common Control Operations](#common-control-operations)
+    - [LibUI Operations](#libui-operations)
     - [Extra Dialogs](#extra-dialogs)
     - [Extra Operations](#extra-operations)
     - [Table API](#table-api)
@@ -234,6 +241,9 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Area Gallery](#area-gallery)
     - [Histogram](#histogram)
     - [Basic Transform](#basic-transform)
+    - [Login](#login)
+    - [Timer](#timer)
+    - [Color The Circles](#color-the-circles)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -321,7 +331,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.1.9'
+gem 'glimmer-dsl-libui', '~> 0.2.1'
 ```
 
 Add `require 'glimmer-dsl-libui'` at the top, and then `include Glimmer` into the top-level main object for testing or into an actual class for serious usage.
@@ -429,6 +439,7 @@ Control(Args) | Properties | Listeners
 `msg_box(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `msg_box_error(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `non_wrapping_multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
+`password_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `path(draw_fill_mode = :winding)` | `fill` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`), `stroke` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, `:cap` as (`:round`, `:square`, `:flat`), `:join` as (`:miter`, `:round`, `:bevel`), `:thickness` as `Numeric`, `:miter_limit` as `Numeric`, `:dashes` as `Array` of `Numeric` ) | None
 `preferences_menu_item` | None | `on_clicked`
 `progress_bar` | `value` (`Numeric`) | None
@@ -436,6 +447,7 @@ Control(Args) | Properties | Listeners
 `quit_menu_item` | None | `on_clicked`
 `radio_buttons` | `selected` (`Integer`) | `on_selected`
 `rectangle(x as Numeric, y as Numeric, width as Numeric, height as Numeric)` |  `x` (`Numeric`), `y` (`Numeric`), `width` (`Numeric`), `height` (`Numeric`) | None
+`search_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `slider(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
 `spinbox(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
 `square(x as Numeric, y as Numeric, length as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `length` (`Numeric`) | None
@@ -445,6 +457,7 @@ Control(Args) | Properties | Listeners
 `text_column(name as String)` | `editable` (Boolean) | None
 `time_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`) | `on_changed`
 `vertical_box` | `padded` (Boolean) | None
+`vertical_separator` | None | None
 `window(title as String, width as Integer, height as Integer, has_menubar as Boolean)` | `borderless` (Boolean), `content_size` (width `Numeric`, height `Numeric`), `fullscreen` (Boolean), `margined` (Boolean), `title` (`String`) | `on_closing`, `on_content_size_changed`, `on_destroy`
 
 ### Common Control Properties
@@ -460,9 +473,9 @@ Control(Args) | Properties | Listeners
 - `xspan` [dsl-only] (`Integer`) [default=`1`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
 - `yspan` [dsl-only] (`Integer`) [default=`1`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
 - `hexpand` [dsl-only] (Boolean) [default=`false`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
-- `halign` [dsl-only] (`Integer`) [default=`0`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
+- `halign` [dsl-only] (`:fill`, `:start`, `:center`, or `:end`) [default=`:fill`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
 - `vexpand` [dsl-only] (Boolean) [default=`false`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
-- `valign` [dsl-only] (`Integer`) [default=`0`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
+- `valign` [dsl-only] (`:fill`, `:start`, `:center`, or `:end`) [default=`:fill`]: available in [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) when nested under `grid`
 
 ### Common Control Operations
 - `destroy`
@@ -471,6 +484,13 @@ Control(Args) | Properties | Listeners
 - `hide`
 - `show`
 
+### LibUI Operations
+
+All operations that could normally be called on `LibUI` can also be called on `Glimmer::LibUI`, but some have enhancements as detailed below.
+
+- `Glimmer::LibUI::queue_main(&block)`: queues an operation to be run on the main event loop at the earliest opportunity possible
+- `Glimmer::LibUI::timer(time_in_seconds=0.1, repeat: true, &block)`: calls block after time_in_seconds has elapsed, repeating indefinitely unless repeat is `false` or an `Integer` for finite number of repeats. Block can return `false` or `true` to override next repetition.
+
 ### Extra Dialogs
 
 - `open_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
@@ -684,7 +704,9 @@ The `area_mouse_event` `Hash` argument for mouse events that receive it (e.g. `o
 
 The `area_key_event` `Hash` argument for keyboard events that receive it (e.g. `on_key_up`, `on_key_down`) consist of the following hash keys:
 - `:key`: key character (`String`)
-- `:ext_key`: non-character extra key (`Symbol`) such as `:left`, `:right`, `:escape`, `:insert`
+- `:key_value`: key value (`Integer`). Useful in rare cases for numeric processing of keys instead of dealing with as `:key` character `String`
+- `:ext_key`: non-character extra key (`Symbol`) from `Glimmer::LibUI.enum_symbols(:ext_key)` such as `:left`, `:right`, `:escape`, `:insert`
+- `:ext_key_value`: non-character extra key value (`Integer`). Useful in rare cases for numeric processing of extra keys instead of dealing with as `:ext_key` `Symbol`
 - `:modifier`: modifier key pressed alone (e.g. `:shift` or `:control`)
 - `:modifiers`: modifier keys pressed simultaneously with `:key`, `:ext_key`, or `:modifier`
 - `:up`: indicates if key has been released or not (Boolean)
@@ -760,6 +782,8 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 
 `fill` and `stroke` accept [X11](https://en.wikipedia.org/wiki/X11_color_names) color `Symbol`s/`String`s like `:skyblue` and `'sandybrown'` or 6-number hex or 3-number hex-shorthand (as `Integer` or `String` with or without `0x` prefix)
 
+Available [X11](https://en.wikipedia.org/wiki/X11_color_names) colors can be obtained through `Glimmer::LibUI.x11_colors` method.
+
 Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wikipedia.org/wiki/X11_color_names) colors.
 
 Check [Histogram](#histogram) example for use of hex colors.
@@ -786,7 +810,7 @@ Check [Histogram](#histogram) example for use of hex colors.
 - When destroying a control nested under a `form`, it is automatically deleted from the form's children
 - When destroying a control nested under a `window` or `group`, it is automatically unset as their child to allow successful destruction
 - For `date_time_picker`, `date_picker`, and `time_picker`, make sure `time` hash values for `mon`, `wday`, and `yday` are 1-based instead of [libui](https://github.com/andlabs/libui) original 0-based values, and return `dst` as Boolean instead of `isdst` as `1`/`0`
-- Smart defaults for `grid` child attributes are `left` (`0`), `top` (`0`), `xspan` (`1`), `yspan` (`1`), `hexpand` (`false`), `halign` (`0`), `vexpand` (`false`), and `valign` (`0`)
+- Smart defaults for `grid` child attributes are `left` (`0`), `top` (`0`), `xspan` (`1`), `yspan` (`1`), `hexpand` (`false`), `halign` (`:fill`), `vexpand` (`false`), and `valign` (`:fill`)
 - The `table` control automatically constructs required `TableModelHandler`, `TableModel`, and `TableParams`, calculating all their arguments from `cell_rows` and `editable` properties (e.g. `NumRows`) as well as nested columns (e.g. `text_column`)
 - Table model instances are automatically freed from memory after `window` is destroyed.
 - Table `cell_rows` data has implicit data-binding to table cell values for deletion, insertion, and change (done by diffing `cell_rows` value before and after change and auto-informing `table` of deletions [`LibUI.table_model_row_deleted`], insertions [`LibUI.table_model_row_deleted`], and changes [`LibUI.table_model_row_changed`]). When deleting data rows from `cell_rows` array, then actual rows from the `table` are automatically deleted. When inserting data rows into `cell_rows` array, then actual `table` rows are automatically inserted. When updating data rows in `cell_rows` array, then actual `table` rows are automatically updated.
@@ -1432,7 +1456,7 @@ class TinyMidiPlayer
   end
 
   def create_gui
-    menu('Help') { |m|
+    menu('Help') {
       menu_item('Version') {
         on_clicked do
           show_version
@@ -2097,13 +2121,15 @@ ruby -r glimmer-dsl-libui -e "require 'examples/grid'"
 
 Mac
 
-![glimmer-dsl-libui-mac-grid-spanning.png](images/glimmer-dsl-libui-mac-grid-spanning.png)
-![glimmer-dsl-libui-mac-grid-expanding.png](images/glimmer-dsl-libui-mac-grid-expanding.png)
+![glimmer-dsl-libui-mac-grid-span.png](images/glimmer-dsl-libui-mac-grid-span.png)
+![glimmer-dsl-libui-mac-grid-expand.png](images/glimmer-dsl-libui-mac-grid-expand.png)
+![glimmer-dsl-libui-mac-grid-align.png](images/glimmer-dsl-libui-mac-grid-align.png)
 
 Linux
 
-![glimmer-dsl-libui-linux-grid-spanning.png](images/glimmer-dsl-libui-linux-grid-spanning.png)
-![glimmer-dsl-libui-linux-grid-expanding.png](images/glimmer-dsl-libui-linux-grid-expanding.png)
+![glimmer-dsl-libui-linux-grid-span.png](images/glimmer-dsl-libui-linux-grid-span.png)
+![glimmer-dsl-libui-linux-grid-expand.png](images/glimmer-dsl-libui-linux-grid-expand.png)
+![glimmer-dsl-libui-linux-grid-align.png](images/glimmer-dsl-libui-linux-grid-align.png)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
@@ -2114,7 +2140,7 @@ include Glimmer
 
 window('Grid') {
   tab {
-    tab_item('Spanning') {
+    tab_item('Span') {
       grid {
         4.times { |top_value|
           4.times { |left_value|
@@ -2154,7 +2180,7 @@ window('Grid') {
         }
       }
     }
-    tab_item('Expanding') {
+    tab_item('Expand') {
       grid {
         label("(0, 0) hexpand/vexpand\nall available horizontal space is taken\nand\nall\navailable\nvertical\nspace\nis\ntaken") {
           left 0
@@ -2176,6 +2202,42 @@ window('Grid') {
         }
       }
     }
+    tab_item('Align') {
+      grid {
+        label("(0, 0) halign/valign fill\nall available horizontal space is taken\nand\nall\navailable\nvertical\nspace\nis\ntaken") {
+          left 0
+          top 0
+          hexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          vexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          halign :fill
+          valign :fill
+        }
+        label("(1, 0) halign/valign start") {
+          left 1
+          top 0
+          hexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          vexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          halign :start
+          valign :start
+        }
+        label("(0, 1) halign/valign center") {
+          left 0
+          top 1
+          hexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          vexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          halign :center
+          valign :center
+        }
+        label("(1, 1) halign/valign end") {
+          left 1
+          top 1
+          hexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          vexpand true unless OS.mac? # on Mac, only the first label is given all space, so avoid expanding
+          halign :end
+          valign :end
+        }
+      }
+    }
   }
 }.show
 ```
@@ -2955,15 +3017,19 @@ Mac
 
 ![glimmer-dsl-libui-mac-form-table.png](images/glimmer-dsl-libui-mac-form-table.png)
 ![glimmer-dsl-libui-mac-form-table-contact-entered.png](images/glimmer-dsl-libui-mac-form-table-contact-entered.png)
+![glimmer-dsl-libui-mac-form-table-filtered.png](images/glimmer-dsl-libui-mac-form-table-filtered.png)
 
 Linux
 
 ![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
 ![glimmer-dsl-libui-linux-form-table-contact-entered.png](images/glimmer-dsl-libui-linux-form-table-contact-entered.png)
+![glimmer-dsl-libui-linux-form-table-filtered.png](images/glimmer-dsl-libui-linux-form-table-filtered.png)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
+# frozen_string_literal: true
+
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3009,6 +3075,7 @@ window('Contacts', 600, 600) { |w|
           msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
         else
           data << new_row # automatically inserts a row into the table due to implicit data-binding
+          @unfiltered_data = data.dup
           @name_entry.text = ''
           @email_entry.text = ''
           @phone_entry.text = ''
@@ -3018,6 +3085,25 @@ window('Contacts', 600, 600) { |w|
       end
     }
     
+    search_entry { |se|
+      stretchy false
+      
+      on_changed do
+        filter_value = se.text
+        @unfiltered_data ||= data.dup
+        # Unfilter first to remove any previous filters
+        data.replace(@unfiltered_data) # affects table indirectly through implicit data-binding
+        # Now, apply filter if entered
+        unless filter_value.empty?
+          data.filter! do |row_data| # affects table indirectly through implicit data-binding
+            row_data.any? do |cell|
+              cell.to_s.downcase.include?(filter_value.downcase)
+            end
+          end
+        end
+      end
+    }
+    
     table {
       text_column('Name')
       text_column('Email')
@@ -3455,11 +3541,17 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(200, 200, 90, 0, 360, false)
+      circle(200, 200, 90)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -3612,18 +3704,28 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc {
+      circle {
         x_center 200
         y_center 200
         radius 90
-        start_angle 0
-        sweep 360
-        is_negative false
       }
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
+    path { # declarative stable path
+      arc {
+        x_center 400
+        y_center 220
+        radius 180
+        start_angle 90
+        sweep 90
+        is_negative false
+      }
+
+      fill r: 204, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -3723,13 +3825,19 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        arc(200, 200, 90, 0, 360, false)
-
+        circle(200, 200, 90)
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc(400, 220, 180, 90, 90, false)
+  
+        fill r: 204, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+      }
     end
-        
+    
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
     end
@@ -3882,20 +3990,30 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        arc {
+        circle {
           x_center 200
           y_center 200
           radius 90
-          start_angle 0
-          sweep 360
-          is_negative false
         }
-
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc {
+          x_center 400
+          y_center 220
+          radius 180
+          start_angle 90
+          sweep 90
+          is_negative false
+        }
+  
+        fill r: 204, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+      }
     end
-        
+    
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
     end
@@ -4344,6 +4462,483 @@ window('Basic Transform', 350, 350) {
 }.show
 ```
 
+### Login
+
+[examples/login.rb](examples/login.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/login.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/login'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-login.png](images/glimmer-dsl-libui-mac-login.png)
+![glimmer-dsl-libui-mac-login-logged-in.png](images/glimmer-dsl-libui-mac-login-logged-in.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-login.png](images/glimmer-dsl-libui-linux-login.png)
+![glimmer-dsl-libui-linux-login-logged-in.png](images/glimmer-dsl-libui-linux-login-logged-in.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Login') {
+  margined true
+  
+  vertical_box {
+    form {
+      @username_entry = entry {
+        label 'Username:'
+      }
+      
+      @password_entry = password_entry {
+        label 'Password:'
+      }
+    }
+    
+    horizontal_box {
+      @login_button = button('Login') {
+        on_clicked do
+          @username_entry.enabled = false
+          @password_entry.enabled = false
+          @login_button.enabled = false
+          @logout_button.enabled = true
+        end
+      }
+      
+      @logout_button = button('Logout') {
+        enabled false
+        
+        on_clicked do
+          @username_entry.text = ''
+          @password_entry.text = ''
+          @username_entry.enabled = true
+          @password_entry.enabled = true
+          @login_button.enabled = true
+          @logout_button.enabled = false
+        end
+      }
+    }
+  }
+}.show
+```
+
+### Timer
+
+[examples/timer.rb](examples/timer.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/timer.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/timer'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-timer.png](images/glimmer-dsl-libui-mac-timer.png)
+![glimmer-dsl-libui-mac-timer-in-progress.png](images/glimmer-dsl-libui-mac-timer-in-progress.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-timer.png](images/glimmer-dsl-libui-linux-timer.png)
+![glimmer-dsl-libui-linux-timer-in-progress.png](images/glimmer-dsl-libui-linux-timer-in-progress.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+# frozen_string_literal: true
+
+require 'glimmer-dsl-libui'
+
+class Timer
+  include Glimmer
+  
+  SECOND_MAX = 59
+  MINUTE_MAX = 59
+  HOUR_MAX = 23
+  
+  def initialize
+    @pid = nil
+    @midi_file = File.expand_path('../sounds/AlanWalker-Faded.mid', __dir__)
+    at_exit { stop_midi }
+    setup_timer
+    create_gui
+  end
+
+  def stop_midi
+    if @pid
+      if @th.alive?
+        Process.kill(:SIGKILL, @pid)
+        @pid = nil
+      else
+        @pid = nil
+      end
+    end
+  end
+
+  def play_midi
+    stop_midi
+    if @pid.nil?
+      begin
+        @pid = spawn "timidity -G 0.0-10.0 #{@midi_file}"
+        @th = Process.detach @pid
+      rescue Errno::ENOENT
+        warn 'Timidty++ not found. Please install Timidity++.'
+        warn 'https://sourceforge.net/projects/timidity/'
+      end
+    end
+  end
+
+  def setup_timer
+    unless @setup_timer
+      Glimmer::LibUI.timer(1) do
+        if @started
+          seconds = @sec_spinbox.value
+          minutes = @min_spinbox.value
+          hours = @hour_spinbox.value
+          if seconds > 0
+            @sec_spinbox.value = seconds -= 1
+          end
+          if seconds == 0
+            if minutes > 0
+              @min_spinbox.value = minutes -= 1
+              @sec_spinbox.value = seconds = SECOND_MAX
+            end
+            if minutes == 0
+              if hours > 0
+                @hour_spinbox.value = hours -= 1
+                @min_spinbox.value = minutes = MINUTE_MAX
+                @sec_spinbox.value = seconds = SECOND_MAX
+              end
+              if hours == 0 && minutes == 0 && seconds == 0
+                @start_button.enabled = true
+                @stop_button.enabled = false
+                @started = false
+                unless @played
+                  play_midi
+                  @played = true
+                end
+              end
+            end
+          end
+        end
+      end
+      @setup_timer = true
+    end
+  end
+
+  def create_gui
+    window('Timer') {
+      margined true
+      
+      group('Countdown') {
+        vertical_box {
+          horizontal_box {
+            @hour_spinbox = spinbox(0, HOUR_MAX) {
+              stretchy false
+              value 0
+            }
+            label(':') {
+              stretchy false
+            }
+            @min_spinbox = spinbox(0, MINUTE_MAX) {
+              stretchy false
+              value 0
+            }
+            label(':') {
+              stretchy false
+            }
+            @sec_spinbox = spinbox(0, SECOND_MAX) {
+              stretchy false
+              value 0
+            }
+          }
+          horizontal_box {
+            @start_button = button('Start') {
+              on_clicked do
+                @start_button.enabled = false
+                @stop_button.enabled = true
+                @started = true
+                @played = false
+              end
+            }
+            
+            @stop_button = button('Stop') {
+              enabled false
+              
+              on_clicked do
+                @start_button.enabled = true
+                @stop_button.enabled = false
+                @started = false
+              end
+            }
+          }
+        }
+      }
+    }.show
+  end
+end
+
+Timer.new
+```
+
+### Color The Circles
+
+[examples/color_the_circles.rb](examples/color_the_circles.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/color_the_circles.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/color_the_circles'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-color-the-circles.png](images/glimmer-dsl-libui-mac-color-the-circles.png)
+![glimmer-dsl-libui-mac-color-the-circles-lost.png](images/glimmer-dsl-libui-mac-color-the-circles-lost.png)
+![glimmer-dsl-libui-mac-color-the-circles-won.png](images/glimmer-dsl-libui-mac-color-the-circles-won.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-color-the-circles.png](images/glimmer-dsl-libui-linux-color-the-circles.png)
+![glimmer-dsl-libui-linux-color-the-circles-lost.png](images/glimmer-dsl-libui-linux-color-the-circles-lost.png)
+![glimmer-dsl-libui-linux-color-the-circles-won.png](images/glimmer-dsl-libui-linux-color-the-circles-won.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class ColorTheCircles
+  include Glimmer
+  
+  WINDOW_WIDTH = 800
+  WINDOW_HEIGHT = 600
+  CIRCLE_MIN_RADIUS = 15
+  CIRCLE_MAX_RADIUS = 50
+  MARGIN_WIDTH = 55
+  MARGIN_HEIGHT = 155
+  TIME_MAX_EASY = 4
+  TIME_MAX_MEDIUM = 3
+  TIME_MAX_HARD = 2
+  TIME_MAX_INSANE = 1
+  
+  attr_accessor :score
+  
+  def initialize
+    @circles_data = []
+    @score = 0
+    @time_max = TIME_MAX_HARD
+    register_observers
+    setup_circle_factory
+  end
+  
+  def register_observers
+    observer = Glimmer::DataBinding::Observer.proc do |new_score|
+      @score_label.text = new_score.to_s
+      if new_score == -20
+        msg_box('You Lost!', 'Sorry! Your score reached -20')
+        restart_game
+      elsif new_score == 0
+        msg_box('You Won!', 'Congratulations! Your score reached 0')
+        restart_game
+      end
+    end
+    observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
+  end
+  
+  def setup_circle_factory
+    consumer = Proc.new do
+      if @circles_data.empty?
+        # start with 3 circles to make more challenging
+        add_circle until @circles_data.size > 3
+      else
+        add_circle
+      end
+      delay = rand * @time_max
+      Glimmer::LibUI.timer(delay, repeat: false, &consumer)
+    end
+    Glimmer::LibUI.queue_main(&consumer)
+  end
+  
+  def add_circle
+    circle_x_center = rand * (WINDOW_WIDTH - MARGIN_WIDTH - CIRCLE_MAX_RADIUS) + CIRCLE_MAX_RADIUS
+    circle_y_center = rand * (WINDOW_HEIGHT - MARGIN_HEIGHT - CIRCLE_MAX_RADIUS) + CIRCLE_MAX_RADIUS
+    circle_radius = rand * (CIRCLE_MAX_RADIUS - CIRCLE_MIN_RADIUS) + CIRCLE_MIN_RADIUS
+    stroke_color = Glimmer::LibUI.x11_colors.sample
+    @circles_data << {
+      args: [circle_x_center, circle_y_center, circle_radius],
+      fill: nil,
+      stroke: stroke_color
+    }
+    @area.queue_redraw_all
+    self.score -= 1 # notifies score observers automatically of change
+  end
+  
+  def restart_game
+    @score = 0 # update variable directly to avoid notifying observers
+    @circles_data.clear
+  end
+  
+  def launch
+    menu('Actions') {
+      menu_item('Restart') {
+        on_clicked do
+          restart_game
+        end
+      }
+      
+      quit_menu_item
+    }
+    
+    menu('Difficulty') {
+      radio_menu_item('Easy') {
+        on_clicked do
+          @time_max = TIME_MAX_EASY
+        end
+      }
+      
+      radio_menu_item('Medium') {
+        on_clicked do
+          @time_max = TIME_MAX_MEDIUM
+        end
+      }
+      
+      radio_menu_item('Hard') {
+        checked true
+        
+        on_clicked do
+          @time_max = TIME_MAX_HARD
+        end
+      }
+      
+      radio_menu_item('Insane') {
+        on_clicked do
+          @time_max = TIME_MAX_INSANE
+        end
+      }
+    }
+    
+    menu('Help') {
+      menu_item('Instructions') {
+        on_clicked do
+          msg_box('Instructions', "Score goes down as circles are added.\nIf it reaches -20, you lose!\n\nClick circles to color and score!\nOnce score reaches 0, you win!\n\nBeware of concealed light-colored circles!\nThey are revealed once darker circles intersect them.\n\nThere are four levels of difficulty.\nChange via difficulty menu if the game gets too tough.")
+        end
+      }
+    }
+    
+    window('Color The Circles', WINDOW_WIDTH, WINDOW_HEIGHT) {
+      margined true
+      
+      grid {
+        button('Restart') {
+          left 0
+          top 0
+          halign :center
+          
+          on_clicked do
+            restart_game
+          end
+        }
+        
+        label('Score goes down as circles are added. If it reaches -20, you lose!') {
+          left 0
+          top 1
+          halign :center
+        }
+        
+        label('Click circles to color and score! Once score reaches 0, you win!') {
+          left 0
+          top 2
+          halign :center
+        }
+        
+        horizontal_box {
+          left 0
+          top 3
+          halign :center
+          
+          label('Score:') {
+            stretchy false
+          }
+          
+          @score_label = label(@score.to_s) {
+            stretchy false
+          }
+        }
+        
+        vertical_box {
+          left 0
+          top 4
+          hexpand true
+          vexpand true
+          halign :fill
+          valign :fill
+          
+          @area = area {
+            on_draw do |area_draw_params|
+              path {
+                rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
+                
+                fill :white
+              }
+              
+              @circles_data.each do |circle_data|
+                path {
+                  circle_data[:circle] = circle(*circle_data[:args])
+                  
+                  fill circle_data[:fill]
+                  stroke circle_data[:stroke]
+                }
+              end
+            end
+            
+            on_mouse_down do |area_mouse_event|
+              clicked_circle_data = @circles_data.find do |circle_data|
+                circle_data[:fill].nil? && circle_data[:circle].include?(area_mouse_event[:x], area_mouse_event[:y])
+              end
+              if clicked_circle_data
+                clicked_circle_data[:fill] = clicked_circle_data[:stroke]
+                @area.queue_redraw_all
+                self.score += 1 # notifies score observers automatically of change
+              end
+            end
+          }
+        }
+        
+      }
+    }.show
+  end
+end
+
+ColorTheCircles.new.launch
+```
+
 ## Contributing to glimmer-dsl-libui
 
 -   Check out the latest master to make sure the feature hasn't been