glimmer-dsl-libui 0.2.13 → 0.2.14

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.2.13
+# [<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.14
 ## 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)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -9,13 +9,11 @@
 
 The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) as opposed to [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) or [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk) is the fact that [SWT](https://www.eclipse.org/swt/) and [Tk](https://www.tcl.tk/) are more mature than mid-alpha [libui](https://github.com/andlabs/libui) as GUI toolkits. Still, if there is only a need to build a small simple application, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) could be a good convenient choice due to having zero prerequisites beyond the dependencies included in the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui). Also, just like [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk), its apps start instantly and have a small memory footprint. [LibUI](https://github.com/kojix2/LibUI) is a promising new GUI toolkit that might prove quite worthy in the future.
 
-**(Note: although LibUI works on Windows, this project has not been tested on Windows yet. It has only been verified on Mac x64 and Linux x64. Issue reporting for Windows is appreciated in the meantime.)**
-
 [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) aims to provide a DSL similar to the [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-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 Control support
+- Custom Keyword support
 - [Far Future Plan] Bidirectional Data-Binding to declaratively wire and automatically synchronize GUI with Business Models
 - [Far Future Plan] Scaffolding for new custom controls, apps, and gems
 - [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
@@ -119,21 +117,19 @@ window('Area Gallery', 400, 400) {
       fill r: 202, 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
     }
-    unless OS.windows?
-      path { # declarative stable path
-        arc(400, 220, 180, 90, 90, false)
-  
-        # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
-        fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
-        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
-      }
-      path { # declarative stable path
-        circle(200, 200, 90)
-  
-        fill r: 202, g: 102, b: 204, a: 0.5
-        stroke r: 0, g: 0, b: 0, thickness: 2
-      }
-    end
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
+      fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
+    path { # declarative stable path
+      circle(200, 200, 90)
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
     text(160, 40, 100) { # x, y, width
       string('Area Gallery') {
         font family: 'Times', size: 14
@@ -213,7 +209,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
   - [API](#api)
-    - [Supported Controls](#supported-controls)
+    - [Supported Keywords](#supported-keywords)
     - [Common Control Properties](#common-control-properties)
     - [Common Control Operations](#common-control-operations)
     - [LibUI Operations](#libui-operations)
@@ -257,10 +253,13 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Transform](#basic-transform)
     - [Login](#login)
     - [Timer](#timer)
-    - [Color The Shapes](#color-the-shapes)
+    - [Color The Circles](#color-the-circles)
     - [Basic Draw Text](#basic-draw-text)
     - [Custom Draw Text](#custom-draw-text)
     - [Method-Based Custom Keyword](#method-based-custom-keyword)
+  - [Applications](#applications)
+    - [Manga2PDF](#manga2pdf)
+    - [Befunge98 GUI](#befunge98-gui)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -281,10 +280,10 @@ The Glimmer GUI DSL provides object-oriented declarative hierarchical syntax for
 - Requires the minimum amount of syntax needed to describe an app's GUI
 
 The Glimmer GUI DSL follows these simple concepts in mapping from [LibUI](https://github.com/kojix2/LibUI) syntax:
-- **Control**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
-- **Content/Properties/Listeners Block**: Any keyword may be optionally followed by a Ruby curly-brace multi-line-block containing nested controls (content) and/or properties (attributes) (e.g. `window('hello world', 300, 200, true) {button('greet')}`). It optionally receives one arg representing the control (e.g. `button('greet') {|b| on_clicked { puts b.text}}`)
-- **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `control_set_property` methods.
-- **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (e.g. `on_clicked {puts 'clicked'}` inside `button`). Behind the scenes, listeners correspond to `control_on_event` methods.
+- **Keyword(args)**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
+- **Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls (e.g. `window {title 'hello world'; on_closing {puts 'Bye'}; button('greet')}`). Content block optionally receives one arg representing the control (e.g. `button('greet') {|b| on_clicked { puts b.text}}`)
+- **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
+- **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (e.g. `on_clicked {puts 'clicked'}` inside `button`). Optionally, the listener block can receive an arg representing the control (e.g. `on_clicked {|btn| puts btn.text}`). Behind the scenes, listeners correspond to `LibUI.control_on_event` methods.
 
 Example of an app written in [LibUI](https://github.com/kojix2/LibUI)'s procedural imperative syntax:
 
@@ -348,7 +347,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.13'
+gem 'glimmer-dsl-libui', '~> 0.2.14'
 ```
 
 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.
@@ -408,7 +407,7 @@ w.set_title 'aloha'
 puts w.title # => aloha
 ```
 
-Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed.
+Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped [LibUI](https://github.com/kojix2/LibUI) Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -417,9 +416,11 @@ w = window('hello world') # => #<Glimmer::LibUI::WindowProxy:0x00007fde4ea39fb0
 w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0 free=0x0000000000000000>
 ```
 
-### Supported Controls
+### Supported Keywords
+
+These are all the supported keywords. Note that some keywords do not represent controls, but produce objects that are used as the property values of controls (e.g. `image` builds objects to use in `cell_rows` for a `table` with an image column)
 
-Control(Args) | Properties | Listeners
+Keyword(Args) | Properties | Listeners
 ------------- | ---------- | ---------
 `about_menu_item` | None | `on_clicked`
 `area` | None | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`, `on_key_event(area_key_event)`, `on_key_down(area_key_event)`, `on_key_up(area_key_event)`
@@ -455,6 +456,8 @@ Control(Args) | Properties | Listeners
 `matrix(m11 = nil as Numeric, m12 = nil as Numeric, m21 = nil as Numeric, m22 = nil as Numeric, m31 = nil as Numeric, m32 = nil as Numeric)` | `m11` (`Numeric`), `m12` (`Numeric`), `m21` (`Numeric`), `m22` (`Numeric`), `m31` (`Numeric`), `m32` (`Numeric`) | None
 `menu(text as String)` | None | None
 `menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
+`message_box` (alias for `msg_box`; see for arguments) | None | None
+`message_box_error` (alias for `msg_box_error`; see for arguments) | None | None
 `multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `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
@@ -516,8 +519,8 @@ All operations that could normally be called on `LibUI` can also be called on `G
 
 ### Extra Dialogs
 
-- `open_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
-- `save_file(window as Glimmer::LibUI::WindowProxy)`: returns selected file (`String`) or `nil` if cancelled
+- `open_file(window as Glimmer::LibUI::WindowProxy = ControlProxy::main_window_proxy)`: returns selected file (`String`) or `nil` if cancelled
+- `save_file(window as Glimmer::LibUI::WindowProxy = ControlProxy::main_window_proxy)`: returns selected file (`String`) or `nil` if cancelled
 
 ### Extra Operations
 
@@ -530,13 +533,13 @@ All operations that could normally be called on `LibUI` can also be called on `G
 
 ### Table API
 
-The `table` control must first declare its columns via one of these column keywords (mentioned in [Supported Controls](#supported-controls)):
+The `table` control must first declare its columns via one of these column keywords (mentioned in [Supported Keywords](#supported-keywords)):
   - `background_color_column`: expects color cell values
   - `button_column`: expects `String` cell values
   - `checkbox_column`: expects Boolean cell values
   - `checkbox_text_column`: expects dual-element `Array` of Boolean and `String` cell values
   - `checkbox_text_color_column`: expects triple-element `Array` of Boolean, `String`, and color cell values
-  - `image_column`: expects `image` cell values (produced by `image` and `image_part` keywords as per [Supported Controls](#supported-controls))
+  - `image_column`: expects `image` cell values (produced by `image` and `image_part` keywords as per [Supported Keywords](#supported-keywords))
   - `image_text_column`: expects dual-element `Array` of `image` and `String` cell values
   - `image_text_color_column`: expects triple-element `Array` of `image`, `String`, and color cell values
   - `text_column`: expects `String` cell values
@@ -598,6 +601,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 = ''
@@ -607,6 +611,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')
@@ -615,6 +638,10 @@ window('Contacts', 600, 600) { |w|
       text_column('State')
 
       cell_rows data # implicit data-binding
+      
+      on_changed do |row, type, row_data|
+        puts "Row #{row} #{type}: #{row_data}"
+      end
     }
   }
 }.show
@@ -627,8 +654,8 @@ Learn more by checking out [examples](#examples).
 ### Area API
 
 The `area` control is a canvas-like control for drawing paths that can be used in one of two ways:
-- Declaratively via stable paths: useful for stable paths that will not change later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be few stable paths (mostly for decorative reasons).
-- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change. Open an `on_draw` listener block that receives a `area_draw_params` argument and nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
+- Declaratively via stable paths: useful for stable paths that will not change often later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be relatively few stable paths (mostly for decorative reasons).
+- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change very often. Open an `on_draw` listener block that receives a `area_draw_params` argument and nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
 
 Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -892,6 +919,7 @@ window('area text drawing') {
 - 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.
 - `image` instances are automatically freed from memory after `window` is destroyed.
 - `image` `width` and `height` can be left off if it has one `image_part` only as they default to the same `width` and `height` of the `image_part`
+- Automatically provide shifted `:key` characters in `area_key_event` provided in `area` key listeners `on_key_event`, `on_key_down`, and `on_key_up`
 - `area` paths are specified declaratively with figures underneath (e.g. `rectangle`) and `area` draw listener is automatically generated
 - Observe figure properties (e.g. `rectangle` `width`) for changes and automatically redraw containing area accordingly
 - Observe `path` `fill` and `stroke` hashes for changes and automatically redraw containing area accordingly
@@ -1013,12 +1041,13 @@ window('Method-Based Custom Keyword') {
 ### API Gotchas
 
 - There is no proper way to destroy `grid` children due to [libui](https://github.com/andlabs/libui) not offering any API for deleting them from `grid` (no `grid_delete` similar to `box_delete` for `horizontal_box` and `vertical_box`).
-- `table` `checkbox_column` and `checkbox_text_column` checkbox editing only works on Windows and Linux (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- `table` `checkbox_column` and `checkbox_text_column` checkbox editing only works on Linux and Windows (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
 - `text` `align` property seems not to work on the Mac ([libui](https://github.com/andlabs/libui) has an [issue](https://github.com/andlabs/libui/pull/407) about it)
-- `text` `string` `background` does not work on Windows due to an issue in [libui](https://github.com/andlabs/libui).
-- `arc` shape does not work on Windows due to an issue in [libui](https://github.com/andlabs/libui).
+- `text` `string` `background` does not work on Windows due to an [issue in libui](https://github.com/andlabs/libui/issues/347).
+- `arc` shape does not work on Windows unless a figure is started due to implementation of [libui](https://github.com/andlabs/libui).
 - `table` controls on Windows intentionally get an extra empty row at the end because if any row were to be deleted for the first time, double-deletion happens due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
 - `table` `progress_bar` column on Windows cannot be updated with a positive value if it started initially with `-1` (it ignores update to avoid crashing due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
+- It seems that [libui](https://github.com/andlabs/libui) does not support nesting multiple `area` controls under a `grid` as only the first one shows up in that scenario. To workaround that limitation, use a `vertical_box` with nested `horizontal_box`s instead to include multiple `area`s in a GUI.
 
 ### Original API
 
@@ -1033,7 +1062,7 @@ I am documenting options for packaging, which I have not tried myself, but figur
 
 For Windows, the [LibUI](https://github.com/kojix2/LibUI) project recommends [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application), which builds Windows executables from Ruby source.
 
-For Mac, consider [Platybus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
+For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
 
 For Linux, simply package your app as a [Ruby Gem](https://guides.rubygems.org/what-is-a-gem/) and [build rpm package from Ruby Gem](https://www.redpill-linpro.com/sysadvent/2015/12/07/building-rpms-from-gems.html) or [build deb package from Ruby Gem](https://openpreservation.org/blogs/building-debian-package-ruby-program/).
 
@@ -3384,8 +3413,6 @@ Linux
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3901,21 +3928,19 @@ window('Area Gallery', 400, 400) {
       fill r: 202, 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
     }
-    unless OS.windows?
-      path { # declarative stable path
-        arc(400, 220, 180, 90, 90, false)
-  
-        # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
-        fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
-        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
-      }
-      path { # declarative stable path
-        circle(200, 200, 90)
-  
-        fill r: 202, g: 102, b: 204, a: 0.5
-        stroke r: 0, g: 0, b: 0, thickness: 2
-      }
-    end
+    path { # declarative stable path
+      arc(400, 220, 180, 90, 90, false)
+
+      # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
+      fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
+    path { # declarative stable path
+      circle(200, 200, 90)
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
     text(160, 40, 100) { # x, y, width
       string('Area Gallery') {
         font family: 'Times', size: 14
@@ -4074,32 +4099,30 @@ window('Area Gallery', 400, 400) {
       fill r: 202, 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
     }
-    unless OS.windows?
-      path { # declarative stable path
-        arc {
-          x_center 400
-          y_center 220
-          radius 180
-          start_angle 90
-          sweep 90
-          is_negative false
-        }
-  
-        # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
-        fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
-        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    path { # declarative stable path
+      arc {
+        x_center 400
+        y_center 220
+        radius 180
+        start_angle 90
+        sweep 90
+        is_negative false
       }
-      path { # declarative stable path
-        circle {
-          x_center 200
-          y_center 200
-          radius 90
-        }
-  
-        fill r: 202, g: 102, b: 204, a: 0.5
-        stroke r: 0, g: 0, b: 0, thickness: 2
+
+      # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
+      fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
+      stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
+    }
+    path { # declarative stable path
+      circle {
+        x_center 200
+        y_center 200
+        radius 90
       }
-    end
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
     text {
       x 160
       y 40
@@ -4211,21 +4234,19 @@ window('Area Gallery', 400, 400) {
         fill r: 202, 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
       }
-      unless OS.windows?
-        path { # a dynamic path is added semi-declaratively inside on_draw block
-          arc(400, 220, 180, 90, 90, false)
-    
-          # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
-          fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
-          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
-          circle(200, 200, 90)
-    
-          fill r: 202, g: 102, b: 204, a: 0.5
-          stroke r: 0, g: 0, b: 0, thickness: 2
-        }
-      end
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc(400, 220, 180, 90, 90, false)
+  
+        # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
+        fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
+        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
+        circle(200, 200, 90)
+  
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
       text(160, 40, 100) { # x, y, width
         string('Area Gallery') {
           font family: 'Times', size: 14
@@ -4386,32 +4407,30 @@ window('Area Gallery', 400, 400) {
         fill r: 202, 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
       }
-      unless OS.windows?
-        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
-          }
-    
-          # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
-          fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
-          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 {
+          x_center 400
+          y_center 220
+          radius 180
+          start_angle 90
+          sweep 90
+          is_negative false
         }
-        path { # a dynamic path is added semi-declaratively inside on_draw block
-          circle {
-            x_center 200
-            y_center 200
-            radius 90
-          }
-    
-          fill r: 202, g: 102, b: 204, a: 0.5
-          stroke r: 0, g: 0, b: 0, thickness: 2
+  
+        # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
+        fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
+        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
+        circle {
+          x_center 200
+          y_center 200
+          radius 90
         }
-      end
+  
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
       text {
         x 160
         y 40
@@ -5114,63 +5133,62 @@ end
 Timer.new
 ```
 
-### Color The Shapes
+### Color The Circles
 
-[examples/color_the_shapes.rb](examples/color_the_shapes.rb)
+[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_shapes.rb
+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_shapes'"
+ruby -r glimmer-dsl-libui -e "require 'examples/color_the_circles'"
 ```
 
 Mac
 
-![glimmer-dsl-libui-mac-color-the-shapes.png](images/glimmer-dsl-libui-mac-color-the-shapes.png)
-![glimmer-dsl-libui-mac-color-the-shapes-lost.png](images/glimmer-dsl-libui-mac-color-the-shapes-lost.png)
-![glimmer-dsl-libui-mac-color-the-shapes-won.png](images/glimmer-dsl-libui-mac-color-the-shapes-won.png)
+![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-shapes.png](images/glimmer-dsl-libui-linux-color-the-shapes.png)
-![glimmer-dsl-libui-linux-color-the-shapes-lost.png](images/glimmer-dsl-libui-linux-color-the-shapes-lost.png)
-![glimmer-dsl-libui-linux-color-the-shapes-won.png](images/glimmer-dsl-libui-linux-color-the-shapes-won.png)
+![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 ColorTheShapes
+class ColorTheCircles
   include Glimmer
   
   WINDOW_WIDTH = 800
   WINDOW_HEIGHT = 600
   SHAPE_MIN_SIZE = 15
-  SHAPE_MAX_SIZE = 100
+  SHAPE_MAX_SIZE = 75
   MARGIN_WIDTH = 55
   MARGIN_HEIGHT = 155
   TIME_MAX_EASY = 4
   TIME_MAX_MEDIUM = 3
   TIME_MAX_HARD = 2
   TIME_MAX_INSANE = 1
-  SHAPES = ['square'] + (OS.windows? ? [] : ['circle'])
   
   attr_accessor :score
   
   def initialize
-    @shapes_data = []
+    @circles_data = []
     @score = 0
     @time_max = TIME_MAX_HARD
     @game_over = false
     register_observers
-    setup_shape_factory
+    setup_circle_factory
   end
   
   def register_observers
@@ -5189,14 +5207,14 @@ class ColorTheShapes
     observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
   end
   
-  def setup_shape_factory
+  def setup_circle_factory
     consumer = Proc.new do
       unless @game_over
-        if @shapes_data.empty?
-          # start with 3 shapes to make more challenging
-          add_shape until @shapes_data.size > 3
+        if @circles_data.empty?
+          # start with 3 circles to make more challenging
+          add_circle until @circles_data.size > 3
         else
-          add_shape
+          add_circle
         end
       end
       delay = rand * @time_max
@@ -5205,13 +5223,13 @@ class ColorTheShapes
     Glimmer::LibUI.queue_main(&consumer)
   end
   
-  def add_shape
-    shape_x = rand * (WINDOW_WIDTH - MARGIN_WIDTH - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
-    shape_y = rand * (WINDOW_HEIGHT - MARGIN_HEIGHT - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
-    shape_size = rand * (SHAPE_MAX_SIZE - SHAPE_MIN_SIZE) + SHAPE_MIN_SIZE
+  def add_circle
+    circle_x = rand * (WINDOW_WIDTH - MARGIN_WIDTH - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
+    circle_y = rand * (WINDOW_HEIGHT - MARGIN_HEIGHT - SHAPE_MAX_SIZE) + SHAPE_MAX_SIZE
+    circle_size = rand * (SHAPE_MAX_SIZE - SHAPE_MIN_SIZE) + SHAPE_MIN_SIZE
     stroke_color = Glimmer::LibUI.x11_colors.sample
-    @shapes_data << {
-      args: [shape_x, shape_y, shape_size],
+    @circles_data << {
+      args: [circle_x, circle_y, circle_size],
       fill: nil,
       stroke: stroke_color
     }
@@ -5221,27 +5239,27 @@ class ColorTheShapes
   
   def restart_game
     @score = 0 # update variable directly to avoid notifying observers
-    @shapes_data.clear
+    @circles_data.clear
     @game_over = false
   end
   
-  def color_shape(x, y)
-    clicked_shape_data = @shapes_data.find do |shape_data|
-      shape_data[:fill].nil? && shape_data[:shape]&.include?(x, y)
+  def color_circle(x, y)
+    clicked_circle_data = @circles_data.find do |circle_data|
+      circle_data[:fill].nil? && circle_data[:circle]&.include?(x, y)
     end
-    if clicked_shape_data
-      clicked_shape_data[:fill] = clicked_shape_data[:stroke]
-      push_colored_shape_behind_uncolored_shapes(clicked_shape_data)
+    if clicked_circle_data
+      clicked_circle_data[:fill] = clicked_circle_data[:stroke]
+      push_colored_circle_behind_uncolored_circles(clicked_circle_data)
       @area.queue_redraw_all
       self.score += 1 # notifies score observers automatically of change
     end
   end
   
-  def push_colored_shape_behind_uncolored_shapes(colored_shape_data)
-    removed_colored_shape_data = @shapes_data.delete(colored_shape_data)
-    last_colored_shape_data = @shapes_data.select {|cd| cd[:fill]}.last
-    last_colored_shape_data_index = @shapes_data.index(last_colored_shape_data) || -1
-    @shapes_data.insert(last_colored_shape_data_index + 1, removed_colored_shape_data)
+  def push_colored_circle_behind_uncolored_circles(colored_circle_data)
+    removed_colored_circle_data = @circles_data.delete(colored_circle_data)
+    last_colored_circle_data = @circles_data.select {|cd| cd[:fill]}.last
+    last_colored_circle_data_index = @circles_data.index(last_colored_circle_data) || -1
+    @circles_data.insert(last_colored_circle_data_index + 1, removed_colored_circle_data)
   end
 
   def launch
@@ -5286,12 +5304,12 @@ class ColorTheShapes
     menu('Help') {
       menu_item('Instructions') {
         on_clicked do
-          msg_box('Instructions', "Score goes down as shapes are added.\nIf it reaches -20, you lose!\n\nClick shapes to color and score!\nOnce score reaches 0, you win!\n\nBeware of concealed light-colored shapes!\nThey are revealed once darker shapes intersect them.\n\nThere are four levels of difficulty.\nChange via difficulty menu if the game gets too tough.")
+          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 Shapes', WINDOW_WIDTH, WINDOW_HEIGHT) {
+    window('Color The Circles', WINDOW_WIDTH, WINDOW_HEIGHT) {
       margined true
       
       grid {
@@ -5305,13 +5323,13 @@ class ColorTheShapes
           end
         }
         
-        label('Score goes down as shapes are added. If it reaches -20, you lose!') {
+        label('Score goes down as circles are added. If it reaches -20, you lose!') {
           left 0
           top 1
           halign :center
         }
         
-        label('Click shapes to color and score! Once score reaches 0, you win!') {
+        label('Click circles to color and score! Once score reaches 0, you win!') {
           left 0
           top 2
           halign :center
@@ -5346,18 +5364,18 @@ class ColorTheShapes
               fill :white
             }
 
-            @shapes_data.each do |shape_data|
+            @circles_data.each do |circle_data|
               path {
-                shape_data[:shape] = send(SHAPES.sample, *shape_data[:args])
+                circle_data[:circle] = circle(*circle_data[:args])
 
-                fill shape_data[:fill]
-                stroke shape_data[:stroke]
+                fill circle_data[:fill]
+                stroke circle_data[:stroke]
               }
             end
           end
 
           on_mouse_down do |area_mouse_event|
-            color_shape(area_mouse_event[:x], area_mouse_event[:y])
+            color_circle(area_mouse_event[:x], area_mouse_event[:y])
           end
         }
       }
@@ -5365,7 +5383,7 @@ class ColorTheShapes
   end
 end
 
-ColorTheShapes.new.launch
+ColorTheCircles.new.launch
 ```
 
 ### Basic Draw Text
@@ -5991,6 +6009,26 @@ window('Method-Based Custom Keyword') {
 }.show
 ```
 
+## Applications
+
+Here are some applications built with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)
+
+### Manga2PDF
+
+Download and merge manga images into a single pdf file.
+
+https://github.com/PinGunter/manga2pdf
+
+![manga2pdf screenshot](https://raw.githubusercontent.com/PinGunter/manga2pdf/master/screenshots/manga2pdf-gui.png)
+
+### Befunge98 GUI
+
+Ruby implementation of the Befunge-98 programmming language.
+
+https://github.com/AndyObtiva/befunge98/tree/gui
+
+![befunge98 gui screenshot](https://raw.githubusercontent.com/AndyObtiva/befunge98/master/gui/glimmer-dsl-libui/befunge98_gui_glimmer_dsl_libui/screenshots/befunge98_gui_glimmer_dsl_libui_example.png)
+
 ## Contributing to glimmer-dsl-libui
 
 -   Check out the latest master to make sure the feature hasn't been