glimmer-dsl-libui 0.2.10 → 0.2.14

data/README.md

@@ -1,7 +1,6 @@
-# [<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.10
+# [<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)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ce2853efdbecf6ebdc73/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-libui/maintainability)
 [![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)
 
 [Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/kojix2/LibUI) is a prerequisite-free Ruby desktop development GUI library. No need to pre-install any prerequisites. Just install the gem and have platform-independent native GUI that just works!
@@ -14,7 +13,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - 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.
@@ -132,11 +131,9 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text(160, 40, 100) { # x, y, width
-      string {
+      string('Area Gallery') {
         font family: 'Times', size: 14
         color :black
-        
-        'Area Gallery'
       }
     }
     
@@ -207,12 +204,12 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.2.10](#-glimmer-dsl-for-libui-0210)
+- [Glimmer DSL for LibUI](#)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [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)
@@ -260,6 +257,9 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [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)
@@ -280,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:
 
@@ -347,7 +347,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.10'
+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.
@@ -407,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)):
 
@@ -416,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)`
@@ -454,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
@@ -470,7 +474,7 @@ Control(Args) | Properties | Listeners
 `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
-`string` | `font`, `color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `background` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `underline`, `underline_color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `open_type_features` | None
+`string(string = '')` | `font`, `color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `background` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `underline`, `underline_color` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `open_type_features`, `string` (`String`) | None
 `tab` | `margined` (Boolean), `num_pages` (`Integer`) | None
 `tab_item(name as String)` | `index` [read-only] (`Integer`), `margined` (Boolean), `name` [read-only] (`String`) | None
 `table` | `cell_rows` (`Array` (rows) of `Arrays` (row columns) of cell values (e.g. `String` values for `text_column` cells or `Array` of `image`/`String` for `image_text_column`)), `editable` as Boolean | `on_changed {|row, type, row_data| ...}`, `on_edited {|row, row_data| ...}`
@@ -515,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
 
@@ -529,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
@@ -597,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 = ''
@@ -606,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')
@@ -614,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
@@ -626,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)):
 
@@ -814,19 +842,23 @@ Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wi
 
 Check [Histogram](#histogram) example for use of hex colors.
 
-To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` element in html, which contains a string of text).
+To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {[attributes]; string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` or `<p>` element in html, which contains a string of text). Alternatively, you can nest attributed `string(string_value) {[attributes]}` if `string_value` is a short single-line string. An attributed `string` value can be changed dynamically via its `string` property.
 
-`text` control can have the following properties:
+`text` has the following properties:
 - `default_font`:
 - `align`: `:left` (default), `:center`, or `:right` (`align` currently seems not to work on the Mac)
+- `x`: x coordinate in relation to parent `area` top-left corner
+- `y`: y coordinate in relation to parent `area` top-left corner
+- `width` (default: area width - x*2): width of text to display
 
-`string` can have the following properties:
+`string` has the following properties:
 - `font`: font descriptor hash consisting of `:family`, `:size`, `:weight` (`[:minimum, :thin, :ultra_light, :light, :book, :normal, :medium, :semi_bold, :bold, :ultra_bold, :heavy, :ultra_heavy, :maximum]`), `:italic` (`[:normal, :oblique, :italic]`), and `:stretch` (`[:ultra_condensed, :extra_condensed, :condensed, :semi_condensed, :normal, :semi_expanded, :expanded, :extra_expanded, :ultra_expanded]`) key values
 - `color`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `background`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `underline`: one of `:none`, `:single`, `:double`, `:suggestion`, `:color_custom`, `:color_spelling`, `:color_grammar`, `:color_auxiliary`
 - `underline_color`: one of `:spelling`, `:grammar`, `:auxiliary`, rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
 - `open_type_features`: Open Type Features (https://www.microsoft.com/typography/otspec/featuretags.htm) consist of `open_type_tag`s nested in content block, which accept (`a`, `b`, `c`, `d`, `Integer`) arguments.
+- `string`: string value (`String`)
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -847,12 +879,13 @@ window('area text drawing') {
           open_type_tag 'l', 'i', 'g', 'a', 1
         }
         
-        "This is a test\n\n"
+        "This is a demonstration\n" \
+        "of a very long\n" \
+        "attributed string\n" \
+        "spanning multiple lines\n\n"
       }
       
-      string {
-        'This is another test'
-      }
+      string('This is a short unattributed string')
     }
   }
 }.show
@@ -886,9 +919,11 @@ 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
+- Observe `text` and `string` properties for changes and automatically redraw containing area accordingly
 - All controls are protected from garbage collection until no longer needed (explicitly destroyed), so there is no need to worry about surprises.
 - All resources are freed automatically once no longer needed or left to garbage collection.
 - When nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
@@ -899,7 +934,7 @@ window('area text drawing') {
 
 To define custom keywords, simply define a method representing the custom control you want. To make reusable, you can define in modules and simply include the modules in the view classes that need them.
 
-Example that defines `field`, `address_form`, `label_pair`, and `address` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Example that defines `form_field`, `address_form`, `label_pair`, and `address` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -909,7 +944,7 @@ include Glimmer
 
 Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
 
-def field(model, property)
+def form_field(model, property)
   property = property.to_s
   entry { |e|
     label property.underscore.split('_').map(&:capitalize).join(' ')
@@ -923,11 +958,11 @@ end
 
 def address_form(address)
   form {
-    field(address, :street)
-    field(address, :p_o_box)
-    field(address, :city)
-    field(address, :state)
-    field(address, :zip_code)
+    form_field(address, :street)
+    form_field(address, :p_o_box)
+    form_field(address, :city)
+    form_field(address, :state)
+    form_field(address, :zip_code)
   }
 end
 
@@ -962,29 +997,39 @@ window('Method-Based Custom Keyword') {
       label('Address 1') {
         stretchy false
       }
+      
       address_form(address1)
+      
       horizontal_separator {
         stretchy false
       }
+      
       label('Address 1 (Saved)') {
         stretchy false
       }
+      
       address(address1)
     }
+    
     vertical_separator {
       stretchy false
     }
+    
     vertical_box {
       label('Address 2') {
         stretchy false
       }
+      
       address_form(address2)
+      
       horizontal_separator {
         stretchy false
       }
+      
       label('Address 2 (Saved)') {
         stretchy false
       }
+      
       address(address2)
     }
   }
@@ -996,8 +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/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
 
@@ -1012,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/).
 
@@ -1056,8 +1106,6 @@ Linux
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 require 'facets'
 
@@ -1100,6 +1148,18 @@ class MetaExample
     examples[@selected_example_index]
   end
   
+  def run_example(example)
+    command = "ruby -r #{glimmer_dsl_libui_file} #{example} 2>&1"
+    result = ''
+    IO.popen(command) do |f|
+      f.each_line do |line|
+        result << line
+        puts line
+      end
+    end
+    msg_box('Error Running Example', result) if result.downcase.include?('error')
+  end
+  
   def launch
     window('Meta-Example', 700, 500) {
       margined true
@@ -1150,11 +1210,11 @@ class MetaExample
                 begin
                   meta_example_file = File.join(Dir.home, '.meta_example.rb')
                   File.write(meta_example_file, @code_entry.text)
-                  result = `ruby -r #{glimmer_dsl_libui_file} #{meta_example_file} 2>&1`
-                  msg_box('Error Running Example', result) if result.include?('error')
+                  run_example(meta_example_file)
                 rescue => e
+                  puts e.full_message
                   puts 'Unable to write code changes! Running original example...'
-                  system "ruby -r #{glimmer_dsl_libui_file} #{file_path_for(selected_example)}"
+                  run_example(file_path_for(selected_example))
                 end
               end
             }
@@ -2518,11 +2578,21 @@ window('Form') {
       @last_name_entry = entry {
         label 'Last Name' # label property is available when control is nested under form
       }
+      
+      @phone_entry = entry {
+        label 'Phone' # label property is available when control is nested under form
+      }
+      
+      @email_entry = entry {
+        label 'Email' # label property is available when control is nested under form
+      }
     }
     
-    button('Display Name') {
+    button('Display Info') {
+      stretchy false
+      
       on_clicked do
-        msg_box('Name', "#{@first_name_entry.text} #{@last_name_entry.text}")
+        msg_box('Info', "#{@first_name_entry.text} #{@last_name_entry.text} has phone #{@phone_entry.text} and email #{@email_entry.text}")
       end
     }
   }
@@ -3343,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
@@ -3874,11 +3942,9 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text(160, 40, 100) { # x, y, width
-      string {
+      string('Area Gallery') {
         font family: 'Times', size: 14
         color :black
-        
-        'Area Gallery'
       }
     }
     
@@ -4182,11 +4248,9 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
       text(160, 40, 100) { # x, y, width
-        string {
+        string('Area Gallery') {
           font family: 'Times', size: 14
           color :black
-          
-          'Area Gallery'
         }
       }
     end
@@ -5107,8 +5171,8 @@ class ColorTheCircles
   
   WINDOW_WIDTH = 800
   WINDOW_HEIGHT = 600
-  CIRCLE_MIN_RADIUS = 15
-  CIRCLE_MAX_RADIUS = 50
+  SHAPE_MIN_SIZE = 15
+  SHAPE_MAX_SIZE = 75
   MARGIN_WIDTH = 55
   MARGIN_HEIGHT = 155
   TIME_MAX_EASY = 4
@@ -5122,6 +5186,7 @@ class ColorTheCircles
     @circles_data = []
     @score = 0
     @time_max = TIME_MAX_HARD
+    @game_over = false
     register_observers
     setup_circle_factory
   end
@@ -5130,9 +5195,11 @@ class ColorTheCircles
     observer = Glimmer::DataBinding::Observer.proc do |new_score|
       @score_label.text = new_score.to_s
       if new_score == -20
+        @game_over = true
         msg_box('You Lost!', 'Sorry! Your score reached -20')
         restart_game
       elsif new_score == 0
+        @game_over = true
         msg_box('You Won!', 'Congratulations! Your score reached 0')
         restart_game
       end
@@ -5142,11 +5209,13 @@ class ColorTheCircles
   
   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
+      unless @game_over
+        if @circles_data.empty?
+          # start with 3 circles to make more challenging
+          add_circle until @circles_data.size > 3
+        else
+          add_circle
+        end
       end
       delay = rand * @time_max
       Glimmer::LibUI.timer(delay, repeat: false, &consumer)
@@ -5155,12 +5224,12 @@ class ColorTheCircles
   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
+    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
     @circles_data << {
-      args: [circle_x_center, circle_y_center, circle_radius],
+      args: [circle_x, circle_y, circle_size],
       fill: nil,
       stroke: stroke_color
     }
@@ -5171,8 +5240,28 @@ class ColorTheCircles
   def restart_game
     @score = 0 # update variable directly to avoid notifying observers
     @circles_data.clear
+    @game_over = false
   end
   
+  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_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_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
     menu('Actions') {
       menu_item('Restart') {
@@ -5260,45 +5349,35 @@ class ColorTheCircles
           }
         }
         
-        vertical_box {
+        @area = area {
           left 0
           top 4
           hexpand true
           vexpand true
           halign :fill
           valign :fill
-          
-          @area = area {
-            on_draw do |area_draw_params|
+
+          on_draw do |area_draw_params|
+            path {
+              rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
+
+              fill :white
+            }
+
+            @circles_data.each do |circle_data|
               path {
-                rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
-                
-                fill :white
+                circle_data[:circle] = circle(*circle_data[:args])
+
+                fill circle_data[:fill]
+                stroke circle_data[:stroke]
               }
-              
-              @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
-          }
+          end
+
+          on_mouse_down do |area_mouse_event|
+            color_circle(area_mouse_event[:x], area_mouse_event[:y])
+          end
         }
-        
       }
     }.show
   end
@@ -5838,7 +5917,7 @@ include Glimmer
 
 Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
 
-def field(model, property)
+def form_field(model, property)
   property = property.to_s
   entry { |e|
     label property.underscore.split('_').map(&:capitalize).join(' ')
@@ -5852,11 +5931,11 @@ end
 
 def address_form(address)
   form {
-    field(address, :street)
-    field(address, :p_o_box)
-    field(address, :city)
-    field(address, :state)
-    field(address, :zip_code)
+    form_field(address, :street)
+    form_field(address, :p_o_box)
+    form_field(address, :city)
+    form_field(address, :state)
+    form_field(address, :zip_code)
   }
 end
 
@@ -5891,35 +5970,65 @@ window('Method-Based Custom Keyword') {
       label('Address 1') {
         stretchy false
       }
+      
       address_form(address1)
+      
       horizontal_separator {
         stretchy false
       }
+      
       label('Address 1 (Saved)') {
         stretchy false
       }
+      
       address(address1)
     }
+    
     vertical_separator {
       stretchy false
     }
+    
     vertical_box {
       label('Address 2') {
         stretchy false
       }
+      
       address_form(address2)
+      
       horizontal_separator {
         stretchy false
       }
+      
       label('Address 2 (Saved)') {
         stretchy false
       }
+      
       address(address2)
     }
   }
 }.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