glimmer-dsl-libui 0.2.8 → 0.2.12

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.8
+# [<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.12
 ## 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!
 
@@ -61,7 +62,7 @@ window('Task Progress', 300, 200) {
       
       on_clicked do
         data.each_with_index do |row_data, row|
-          data[row] = [row_data[0], 100] # automatically updates table due to implicit data-binding
+          data[row][1] = 100 # automatically updates table due to implicit data-binding
         end
       end
     }
@@ -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,24 @@ 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
+      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
     }
-    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
+    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 +195,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 +206,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.2.8](#-glimmer-dsl-for-libui-028)
+- [Glimmer DSL for LibUI](#)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -211,8 +220,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)
@@ -247,6 +258,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [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)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -334,7 +346,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.8'
+gem 'glimmer-dsl-libui', '~> 0.2.12'
 ```
 
 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 +458,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 +469,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 +813,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 +850,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,12 +893,121 @@ 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`).
@@ -890,8 +1016,20 @@ window('area text drawing') {
 
 ### 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 +1046,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 +1077,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 +2259,8 @@ include Glimmer
 
 window('color button', 230) {
   color_button { |cb|
+    color :blue
+    
     on_changed do
       rgba = cb.color
       p rgba
@@ -2342,11 +2543,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
     }
   }
@@ -3056,7 +3267,7 @@ window('Task Progress', 300, 200) {
       
       on_clicked do
         data.each_with_index do |row_data, row|
-          data[row] = [row_data[0], 100] # automatically updates table due to implicit data-binding
+          data[row][1] = 100 # automatically updates table due to implicit data-binding
         end
       end
     }
@@ -3650,14 +3861,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 +3895,24 @@ 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
+      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
     }
-    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
+    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 +4003,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,16 +4066,6 @@ 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
-      }
-
-      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
@@ -3866,9 +4076,32 @@ window('Area Gallery', 400, 400) {
         is_negative false
       }
 
-      fill r: 204, g: 102, b: 204, a: 0.5
+      # 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
+      }
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
+    text {
+      x 160
+      y 40
+      width 100
+      
+      string {
+        font family: 'Times', size: 14
+        color :black
+        
+        'Area Gallery'
+      }
+    }
     
     on_mouse_event do |area_mouse_event|
       p area_mouse_event
@@ -3941,7 +4174,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 +4201,24 @@ 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
+        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
       }
-      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
+      text(160, 40, 100) { # x, y, width
+        string('Area Gallery') {
+          font family: 'Times', size: 14
+          color :black
+        }
       }
     end
     
@@ -4070,7 +4311,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,16 +4374,6 @@ 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
-        }
-  
-        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
@@ -4152,9 +4384,32 @@ window('Area Gallery', 400, 400) {
           is_negative false
         }
   
-        fill r: 204, g: 102, b: 204, a: 0.5
+        # 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
+        }
+  
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
+      text {
+        x 160
+        y 40
+        width 100
+        
+        string {
+          font family: 'Times', size: 14
+          color :black
+          
+          'Area Gallery'
+        }
+      }
     end
     
     on_mouse_event do |area_mouse_event|
@@ -5578,7 +5833,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