glimmer-dsl-libui 0.2.9 → 0.2.13

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.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.13
 ## 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!
@@ -10,14 +9,16 @@
 
 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
-- Bidirectional Data-Binding to declaratively wire and automatically synchronize GUI with Business Models
 - Custom Control support
-- Scaffolding for new custom controls, apps, and gems
-- Native-Executable packaging on Mac, Windows, and Linux.
+- [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.
 
 Hello, World!
 
@@ -84,14 +85,15 @@ window('Area Gallery', 400, 400) {
     path { # declarative stable path
       square(0, 0, 100)
       square(100, 100, 400)
-      
+
       fill r: 102, g: 102, b: 204
     }
     path { # declarative stable path
       rectangle(0, 100, 100, 400)
       rectangle(100, 0, 400, 100)
-      
-      fill r: 204, g: 102, b: 204
+
+      # linear gradient (has x0, y0, x1, y1, and stops)
+      fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
     }
     path { # declarative stable path
       figure(100, 100) {
@@ -117,17 +119,26 @@ 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
     }
-    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
-    }
-    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
+    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
+    text(160, 40, 100) { # x, y, width
+      string('Area Gallery') {
+        font family: 'Times', size: 14
+        color :black
+      }
     }
     
     on_mouse_event do |area_mouse_event|
@@ -186,7 +197,7 @@ window('Area Gallery', 400, 400) {
 
 [Check Out Many More Examples Over Here!](#examples)
 
-NOTE: [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) is in early alpha mode (only supports included [examples](#examples)). Please help make better by contributing, adopting for small or low risk projects, and providing feedback. It is still an early alpha, so the more feedback and issues you report the better.
+NOTE: [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) is feature-complete and in beta mode (though the C [libui](https://github.com/andlabs/libui) is still mid-alpha). Please help make better by contributing, adopting for small or low risk projects, and providing feedback. The more feedback and issues you report the better.
 
 Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interested in:
 - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Framework)
@@ -197,7 +208,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.2.9](#-glimmer-dsl-for-libui-029)
+- [Glimmer DSL for LibUI](#)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -211,8 +222,10 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Table API](#table-api)
     - [Area API](#area-api)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
+    - [Custom Keywords](#custom-keywords)
     - [API Gotchas](#api-gotchas)
     - [Original API](#original-api)
+  - [Packaging](#packaging)
   - [Glimmer Style Guide](#glimmer-style-guide)
   - [Examples](#examples)
     - [Basic Window](#basic-window)
@@ -244,9 +257,10 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Transform](#basic-transform)
     - [Login](#login)
     - [Timer](#timer)
-    - [Color The Circles](#color-the-circles)
+    - [Color The Shapes](#color-the-shapes)
     - [Basic Draw Text](#basic-draw-text)
     - [Custom Draw Text](#custom-draw-text)
+    - [Method-Based Custom Keyword](#method-based-custom-keyword)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -334,7 +348,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.9'
+gem 'glimmer-dsl-libui', '~> 0.2.13'
 ```
 
 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.
@@ -446,7 +460,7 @@ Control(Args) | Properties | Listeners
 `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
+`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`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `stroke` (`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), `: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
 `progress_bar_column(name as String)` | None | None
@@ -457,7 +471,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`, `background`, `underline`, `underline_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| ...}`
@@ -801,19 +815,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`: it must have a block containing `open_type_tag` occurrances, which take the a, b, c, d arguments plus a number at the end.
+- `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)):
 
@@ -834,12 +852,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
@@ -876,22 +895,147 @@ window('area text drawing') {
 - `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.
 - Colors may be passed in as a hash of `:r`, `:g`, `:b`, `:a`, or `:red`, `:green`, `:blue`, `:alpha`, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color like `:skyblue`, or 6-number hex or 3-number hex (as `Integer` or `String` with or without `0x` prefix)
 - Color alpha value defaults to `1.0` when not specified.
 
+### Custom Keywords
+
+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 `form_field`, `address_form`, `label_pair`, and `address` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'facets'
+
+include Glimmer
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+def form_field(model, property)
+  property = property.to_s
+  entry { |e|
+    label property.underscore.split('_').map(&:capitalize).join(' ')
+    text model.send(property).to_s
+
+    on_changed do
+      model.send("#{property}=", e.text)
+    end
+  }
+end
+
+def address_form(address)
+  form {
+    form_field(address, :street)
+    form_field(address, :p_o_box)
+    form_field(address, :city)
+    form_field(address, :state)
+    form_field(address, :zip_code)
+  }
+end
+
+def label_pair(model, attribute, value)
+  name_label = nil
+  value_label = nil
+  horizontal_box {
+    name_label = label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+    value_label = label(value.to_s)
+  }
+  Glimmer::DataBinding::Observer.proc do
+    value_label.text = model.send(attribute)
+  end.observe(model, attribute)
+end
+
+def address(address)
+  vertical_box {
+    address.each_pair do |attribute, value|
+      label_pair(address, attribute, value)
+    end
+  }
+end
+
+address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+
+window('Method-Based Custom Keyword') {
+  margined true
+  
+  horizontal_box {
+    vertical_box {
+      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
+```
+
+![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
+
 ### 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).
 - `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).
+- `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.
 
 ### Original API
 
-To learn more about the [LibUI](https://github.com/kojix2/LibUI) API exposed through [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui),
-check out the [libui C headers](https://github.com/andlabs/libui/blob/master/ui.h)
+To learn more about the [LibUI](https://github.com/kojix2/LibUI) API exposed through [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui):
+- Check out [LibUI ffi.rb](https://github.com/kojix2/LibUI/blob/main/lib/libui/ffi.rb)
+- Check out the [libui C headers](https://github.com/andlabs/libui/blob/master/ui.h)
+- Check out the [Go UI (Golang LibUI) documentation](https://pkg.go.dev/github.com/andlabs/ui) for an alternative well-documented [libui](https://github.com/andlabs/libui) reference.
+
+## Packaging
+
+I am documenting options for packaging, which I have not tried myself, but figured they would still be useful to add to the README.md until I can expand further effort into supporting packaging.
+
+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 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/).
 
 ## Glimmer Style Guide
 
@@ -908,8 +1052,6 @@ The following examples include reimplementions of the examples in the [LibUI](ht
 
 To browse all examples, simply launch the [Meta-Example](examples/meta_example.rb), which lists all examples and displays each example's code when selected. It also enables code editing to facilitate experimentation and learning.
 
-(note that for examples that emit output to terminal/command-line via `p` or `puts`, you must run them directly to see output)
-
 [examples/meta_example.rb](examples/meta_example.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -941,59 +1083,122 @@ require 'facets'
 class MetaExample
   include Glimmer
   
+  def initialize
+    @selected_example_index = 0
+  end
+  
   def examples
     if @examples.nil?
       example_files = Dir.glob(File.join(File.expand_path('.', __dir__), '**', '*.rb'))
       example_file_names = example_files.map { |f| File.basename(f, '.rb') }
-      example_file_names = example_file_names.reject { |f| f == 'meta_example' }
+      example_file_names = example_file_names.reject { |f| f == 'meta_example' || f.match(/\d$/) }
       @examples = example_file_names.map { |f| f.underscore.titlecase }
     end
     @examples
   end
   
+  def examples_with_versions
+    examples.map do |example|
+      version_count_for(example) > 1 ? "#{example} (#{version_count_for(example)} versions)" : example
+    end
+  end
+  
   def file_path_for(example)
     File.join(File.expand_path('.', __dir__), "#{example.underscore}.rb")
   end
   
+  def version_count_for(example)
+    Dir.glob(File.join(File.expand_path('.', __dir__), "#{example.underscore}*.rb")).select {|file| file.match(/\d\.rb$/)}.count + 1
+  end
+  
   def glimmer_dsl_libui_file
     File.expand_path('../lib/glimmer-dsl-libui', __dir__)
   end
   
+  def selected_example
+    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
       
       horizontal_box {
         vertical_box {
-          @rbs = radio_buttons {
+          stretchy false
+          
+          @example_radio_buttons = radio_buttons {
             stretchy false
-            items examples
-            selected 0
+            items examples_with_versions
+            selected @selected_example_index
             
             on_selected do
-              @nwme.text = File.read(file_path_for(@examples[@rbs.selected]))
+              @selected_example_index = @example_radio_buttons.selected
+              example = selected_example
+              @code_entry.text = File.read(file_path_for(example))
+              @version_spinbox.value = 1
             end
           }
-          button('Launch') {
+          
+          horizontal_box {
+            label('Version') {
+              stretchy false
+            }
+            
+            @version_spinbox = spinbox(1, 100) {
+              value 1
+              
+              on_changed do
+                example = selected_example
+                if @version_spinbox.value > version_count_for(example)
+                  @version_spinbox.value -= 1
+                else
+                  version_number = @version_spinbox.value == 1 ? '' : @version_spinbox.value
+                  example = "#{selected_example}#{version_number}"
+                  @code_entry.text = File.read(file_path_for(example))
+                end
+              end
+            }
+          }
+          
+          horizontal_box {
             stretchy false
             
-            on_clicked do
-              begin
-                meta_example_file = File.join(Dir.home, '.meta_example.rb')
-                File.write(meta_example_file, @nwme.text)
-                result = `ruby -r #{glimmer_dsl_libui_file} #{meta_example_file} 2>&1`
-                msg_box('Error Running Example', result) if result.include?('error')
-              rescue => e
-                puts 'Unable to write code changes! Running original example...'
-                system "ruby -r #{glimmer_dsl_libui_file} #{file_path_for(@examples[@rbs.selected])}"
+            button('Launch') {
+              on_clicked do
+                begin
+                  meta_example_file = File.join(Dir.home, '.meta_example.rb')
+                  File.write(meta_example_file, @code_entry.text)
+                  run_example(meta_example_file)
+                rescue => e
+                  puts e.full_message
+                  puts 'Unable to write code changes! Running original example...'
+                  run_example(file_path_for(selected_example))
+                end
               end
-            end
+            }
+            button('Reset') {
+              on_clicked do
+                @code_entry.text = File.read(file_path_for(selected_example))
+              end
+            }
           }
         }
-        vertical_box {
-          @nwme = non_wrapping_multiline_entry {
-            text File.read(file_path_for(@examples[@rbs.selected]))
-          }
+        
+        @code_entry = non_wrapping_multiline_entry {
+          text File.read(file_path_for(selected_example))
         }
       }
     }.show
@@ -2060,6 +2265,8 @@ include Glimmer
 
 window('color button', 230) {
   color_button { |cb|
+    color :blue
+    
     on_changed do
       rgba = cb.color
       p rgba
@@ -2342,11 +2549,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
     }
   }
@@ -3650,14 +3867,15 @@ window('Area Gallery', 400, 400) {
     path { # declarative stable path
       square(0, 0, 100)
       square(100, 100, 400)
-      
+
       fill r: 102, g: 102, b: 204
     }
     path { # declarative stable path
       rectangle(0, 100, 100, 400)
       rectangle(100, 0, 400, 100)
-      
-      fill r: 204, g: 102, b: 204
+
+      # linear gradient (has x0, y0, x1, y1, and stops)
+      fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
     }
     path { # declarative stable path
       figure(100, 100) {
@@ -3683,17 +3901,26 @@ 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
     }
-    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
-    }
-    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
+    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
+    text(160, 40, 100) { # x, y, width
+      string('Area Gallery') {
+        font family: 'Times', size: 14
+        color :black
+      }
     }
     
     on_mouse_event do |area_mouse_event|
@@ -3784,7 +4011,8 @@ window('Area Gallery', 400, 400) {
         height 100
       }
       
-      fill r: 204, g: 102, b: 204
+      # linear gradient (has x0, y0, x1, y1, and stops)
+      fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
     }
     path { # declarative stable path
       figure {
@@ -3846,28 +4074,43 @@ 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
     }
-    path { # declarative stable path
-      circle {
-        x_center 200
-        y_center 200
-        radius 90
+    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
       }
-
-      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
+      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
+      }
+    end
+    text {
+      x 160
+      y 40
+      width 100
+      
+      string {
+        font family: 'Times', size: 14
+        color :black
+        
+        'Area Gallery'
       }
-
-      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|
@@ -3941,7 +4184,8 @@ window('Area Gallery', 400, 400) {
         rectangle(0, 100, 100, 400)
         rectangle(100, 0, 400, 100)
 
-        fill r: 204, g: 102, b: 204
+        # linear gradient (has x0, y0, x1, y1, and stops)
+        fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
         figure(100, 100) {
@@ -3967,17 +4211,26 @@ 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
       }
-      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
-      }
-      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
+      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
+      text(160, 40, 100) { # x, y, width
+        string('Area Gallery') {
+          font family: 'Times', size: 14
+          color :black
+        }
       }
     end
     
@@ -4070,7 +4323,8 @@ window('Area Gallery', 400, 400) {
           height 100
         }
         
-        fill r: 204, g: 102, b: 204
+        # linear gradient (has x0, y0, x1, y1, and stops)
+        fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
         figure {
@@ -4132,28 +4386,43 @@ 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
       }
-      path { # a dynamic path is added semi-declaratively inside on_draw block
-        circle {
-          x_center 200
-          y_center 200
-          radius 90
+      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
         }
-  
-        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
+        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
+        }
+      end
+      text {
+        x 160
+        y 40
+        width 100
+        
+        string {
+          font family: 'Times', size: 14
+          color :black
+          
+          'Area Gallery'
         }
-  
-        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
     
@@ -4845,70 +5114,74 @@ end
 Timer.new
 ```
 
-### Color The Circles
+### Color The Shapes
 
-[examples/color_the_circles.rb](examples/color_the_circles.rb)
+[examples/color_the_shapes.rb](examples/color_the_shapes.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
+ruby -r './lib/glimmer-dsl-libui' examples/color_the_shapes.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'"
+ruby -r glimmer-dsl-libui -e "require 'examples/color_the_shapes'"
 ```
 
 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)
+![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)
 
 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)
+![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)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
 require 'glimmer-dsl-libui'
 
-class ColorTheCircles
+class ColorTheShapes
   include Glimmer
   
   WINDOW_WIDTH = 800
   WINDOW_HEIGHT = 600
-  CIRCLE_MIN_RADIUS = 15
-  CIRCLE_MAX_RADIUS = 50
+  SHAPE_MIN_SIZE = 15
+  SHAPE_MAX_SIZE = 100
   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
-    @circles_data = []
+    @shapes_data = []
     @score = 0
     @time_max = TIME_MAX_HARD
+    @game_over = false
     register_observers
-    setup_circle_factory
+    setup_shape_factory
   end
   
   def register_observers
     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
@@ -4916,13 +5189,15 @@ class ColorTheCircles
     observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
   end
   
-  def setup_circle_factory
+  def setup_shape_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 @shapes_data.empty?
+          # start with 3 shapes to make more challenging
+          add_shape until @shapes_data.size > 3
+        else
+          add_shape
+        end
       end
       delay = rand * @time_max
       Glimmer::LibUI.timer(delay, repeat: false, &consumer)
@@ -4930,13 +5205,13 @@ class ColorTheCircles
     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
+  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
     stroke_color = Glimmer::LibUI.x11_colors.sample
-    @circles_data << {
-      args: [circle_x_center, circle_y_center, circle_radius],
+    @shapes_data << {
+      args: [shape_x, shape_y, shape_size],
       fill: nil,
       stroke: stroke_color
     }
@@ -4946,9 +5221,29 @@ class ColorTheCircles
   
   def restart_game
     @score = 0 # update variable directly to avoid notifying observers
-    @circles_data.clear
+    @shapes_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)
+    end
+    if clicked_shape_data
+      clicked_shape_data[:fill] = clicked_shape_data[:stroke]
+      push_colored_shape_behind_uncolored_shapes(clicked_shape_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)
+  end
+
   def launch
     menu('Actions') {
       menu_item('Restart') {
@@ -4991,12 +5286,12 @@ class ColorTheCircles
     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.")
+          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.")
         end
       }
     }
     
-    window('Color The Circles', WINDOW_WIDTH, WINDOW_HEIGHT) {
+    window('Color The Shapes', WINDOW_WIDTH, WINDOW_HEIGHT) {
       margined true
       
       grid {
@@ -5010,13 +5305,13 @@ class ColorTheCircles
           end
         }
         
-        label('Score goes down as circles are added. If it reaches -20, you lose!') {
+        label('Score goes down as shapes 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!') {
+        label('Click shapes to color and score! Once score reaches 0, you win!') {
           left 0
           top 2
           halign :center
@@ -5036,51 +5331,41 @@ 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
+            }
+
+            @shapes_data.each do |shape_data|
               path {
-                rectangle(0, 0, WINDOW_WIDTH, WINDOW_HEIGHT)
-                
-                fill :white
+                shape_data[:shape] = send(SHAPES.sample, *shape_data[:args])
+
+                fill shape_data[:fill]
+                stroke shape_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_shape(area_mouse_event[:x], area_mouse_event[:y])
+          end
         }
-        
       }
     }.show
   end
 end
 
-ColorTheCircles.new.launch
+ColorTheShapes.new.launch
 ```
 
 ### Basic Draw Text
@@ -5578,7 +5863,132 @@ class CustomDrawText
 end
 
 CustomDrawText.new.launch
+```
+
+### Method-Based Custom Keyword
+
+[examples/method_based_custom_keyword.rb](examples/method_based_custom_keyword.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/method_based_custom_keyword.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/method_based_custom_keyword'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-method-based-custom-keyword.png](images/glimmer-dsl-libui-linux-method-based-custom-keyword.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'facets'
+
+include Glimmer
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+def form_field(model, property)
+  property = property.to_s
+  entry { |e|
+    label property.underscore.split('_').map(&:capitalize).join(' ')
+    text model.send(property).to_s
+
+    on_changed do
+      model.send("#{property}=", e.text)
+    end
+  }
+end
+
+def address_form(address)
+  form {
+    form_field(address, :street)
+    form_field(address, :p_o_box)
+    form_field(address, :city)
+    form_field(address, :state)
+    form_field(address, :zip_code)
+  }
+end
+
+def label_pair(model, attribute, value)
+  name_label = nil
+  value_label = nil
+  horizontal_box {
+    name_label = label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+    value_label = label(value.to_s)
+  }
+  Glimmer::DataBinding::Observer.proc do
+    value_label.text = model.send(attribute)
+  end.observe(model, attribute)
+end
+
+def address(address)
+  vertical_box {
+    address.each_pair do |attribute, value|
+      label_pair(address, attribute, value)
+    end
+  }
+end
+
+address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
 
+window('Method-Based Custom Keyword') {
+  margined true
+  
+  horizontal_box {
+    vertical_box {
+      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
 ```
 
 ## Contributing to glimmer-dsl-libui