glimmer-dsl-libui 0.2.6 → 0.2.10

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.2.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
 ## 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)
@@ -14,10 +14,10 @@ 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
-- 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 +61,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 +84,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 +118,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
+      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 {
+        font family: 'Times', size: 14
+        color :black
+        
+        'Area Gallery'
+      }
     }
     
     on_mouse_event do |area_mouse_event|
@@ -186,7 +196,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 +207,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.2.6](#-glimmer-dsl-for-libui-026)
+- [Glimmer DSL for LibUI 0.2.10](#-glimmer-dsl-for-libui-0210)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -211,8 +221,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)
@@ -235,6 +247,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Table Checkbox](#basic-table-checkbox)
     - [Basic Table Checkbox Text](#basic-table-checkbox-text)
     - [Basic Table Progress Bar](#basic-table-progress-bar)
+    - [Basic Table Color](#basic-table-color)
     - [Form Table](#form-table)
     - [Basic Area](#basic-area)
     - [Dynamic Area](#dynamic-area)
@@ -246,6 +259,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)
@@ -333,7 +347,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.6'
+gem 'glimmer-dsl-libui', '~> 0.2.10'
 ```
 
 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.
@@ -409,12 +423,14 @@ Control(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)`
 `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)` | `x_center` (`Numeric`), `y_center` (`Numeric`), `radius` (`Numeric`), `start_angle` (`Numeric`), `sweep` (`Numeric`), `is_negative` (Boolean) | None
+`background_color_column(name as String)` | None | None
 `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)` | `c1_x` (`Numeric`), `c1_y` (`Numeric`), `c2_x` (`Numeric`), `c2_y` (`Numeric`), `end_x` (`Numeric`), `end_y` (`Numeric`) | None
 `button(text as String)` | `text` (`String`) | `on_clicked`
 `button_column(name as String)` | `enabled` (Boolean) | None
 `checkbox(text as String)` | `checked` (Boolean), `text` (`String`) | `on_toggled`
 `checkbox_column(name as String)` | `editable` (Boolean) | None
 `checkbox_text_column(name as String)` | `editable` (Boolean), `editable_checkbox` (Boolean), `editable_text` (Boolean) | None
+`checkbox_text_color_column(name as String)` | `editable` (Boolean), `editable_checkbox` (Boolean), `editable_text` (Boolean) | None
 `combobox` | `items` (`Array` of `String`), `selected` (`Integer`) | `on_selected`
 `color_button` | `color` (Array of `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float`), `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float` | `on_changed`
 `date_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`, `mday` as `Integer`, `mon` as `Integer`, `year` as `Integer`, `wday` as `Integer`, `yday` as `Integer`, `dst` as Boolean) | `on_changed`
@@ -432,6 +448,7 @@ Control(Args) | Properties | Listeners
 `image_part(pixels as String [encoded image rgba byte array], width as Numeric, height as Numeric, byte_stride as Numeric [usually width*4])` | None | None
 `image_column(name as String)` | None | None
 `image_text_column(name as String)` | None | None
+`image_text_color_column(name as String)` | None | None
 `label(text as String)` | `text` (`String`) | None
 `line(x as Numeric, y as Numeric)` | `x` (`Numeric`), `y` (`Numeric`) | None
 `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
@@ -442,7 +459,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
@@ -453,10 +470,13 @@ 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
 `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 | 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| ...}`
+`text(x = 0 as Numeric, y = 0 as Numeric, width = area_width as Numeric)` | `align`, `default_font` | None
 `text_column(name as String)` | `editable` (Boolean) | None
+`text_color_column(name as String)` | `editable` (Boolean) | None
 `time_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`) | `on_changed`
 `vertical_box` | `padded` (Boolean) | None
 `vertical_separator` | None | None
@@ -510,12 +530,16 @@ 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)):
+  - `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_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
+  - `text_color_column`: expects dual-element `Array` of `String` and color cell values
   - `progress_bar_column`: expects `Integer` cell values
   
 Afterwards, it must declare its `cell_rows` array (`Array` of `Array`s of column cell values) and whether it is `editable` (Boolean) for all its columns.
@@ -798,11 +822,11 @@ To draw `text` in an `area`, you simply nest a `text(x, y, width)` control direc
 
 `string` can have 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 color
-- `background`: rgba, hex, or x11 color
+- `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 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.
+- `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.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -871,16 +895,126 @@ window('area text drawing') {
 - 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 `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 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 {
+    field(address, :street)
+    field(address, :p_o_box)
+    field(address, :city)
+    field(address, :state)
+    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).
-- It seems that `arc` `start_angle` and `sweep` properties are ignored by [libui](https://github.com/andlabs/libui) and always set to `0` and `360` respectively, producing a full circle.
+- `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)
 
 ### 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
 
@@ -897,8 +1031,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:
@@ -924,65 +1056,118 @@ 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'
 
 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 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)
+                  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(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
@@ -2049,6 +2234,8 @@ include Glimmer
 
 window('color button', 230) {
   color_button { |cb|
+    color :blue
+    
     on_changed do
       rgba = cb.color
       p rgba
@@ -2513,6 +2700,14 @@ window('Editable animal sounds', 300, 200) {
 
       cell_rows data
       editable true
+      
+      on_changed do |row, type, row_data| # fires on all changes (even ones happening through data array)
+        puts "Row #{row} #{type}: #{row_data}"
+      end
+      
+      on_edited do |row, row_data| # only fires on direct table editing
+        puts "Row #{row} edited: #{row_data}"
+      end
     }
   }
   
@@ -2584,7 +2779,7 @@ window('Editable column animal sounds', 400, 200) {
 
 ### Basic Table Image
 
-This example has a prerequisite of installing `chunky_png` Ruby gem:
+This example requires pre-installing `chunky_png` Ruby gem:
 
 ```
 gem install chunky_png -v1.4.0
@@ -2871,6 +3066,10 @@ window('Animal sounds', 300, 200) {
       }
 
       cell_rows data # implicit data-binding
+      
+      on_changed do |row, type, row_data|
+        puts "Row #{row} #{type}: #{row_data}"
+      end
     }
   }
 }.show
@@ -3033,7 +3232,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
     }
@@ -3041,6 +3240,78 @@ window('Task Progress', 300, 200) {
 }.show
 ```
 
+### Basic Table Color
+
+This example requires pre-installing `chunky_png` Ruby gem:
+
+```
+gem install chunky_png -v1.4.0
+```
+
+[examples/basic_table_color.rb](examples/basic_table_color.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_table_color.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/basic_table_color'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-table-color.png](images/glimmer-dsl-libui-mac-basic-table-color.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-basic-table-color.png](images/glimmer-dsl-libui-linux-basic-table-color.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'chunky_png'
+
+include Glimmer
+
+f = File.open(File.expand_path('../icons/glimmer.png', __dir__))
+canvas = ChunkyPNG::Canvas.from_io(f)
+f.close
+canvas.resample_nearest_neighbor!(24, 24)
+data = canvas.to_rgba_stream
+width = canvas.width
+height = canvas.height
+img = image {
+  image_part(data, width, height, width * 4)
+}
+
+data = [
+  [['cat', :red]      , ['meow', :blue]                  , [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], {r: 255, g: 120, b: 0, a: 0.5}],
+  [['dog', :yellow]   , ['woof', {r: 240, g: 32, b: 32}] , [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], :skyblue],
+  [['chicken', :beige], ['cock-a-doodle-doo', :blue]     , [false, 'mammal', :red] , [img, 'Glimmer', :beige], {r: 5, g: 120, b: 110}],
+  [['horse', :purple] , ['neigh', {r: 240, g: 32, b: 32}], [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], '13a1fb'],
+  [['cow', :gray]     , ['moo', :blue]                   , [true, 'mammal', :green], [img, 'Glimmer', :brown], 0x12ff02]
+]
+
+window('Animals', 500, 200) {
+  horizontal_box {
+    table {
+      text_color_column('Animal')
+      text_color_column('Sound')
+      checkbox_text_color_column('Description')
+      image_text_color_column('GUI')
+      background_color_column('Mammal')
+
+      cell_rows data
+    }
+  }
+}.show
+```
+
 ### Form Table
 
 [examples/form_table.rb](examples/form_table.rb)
@@ -3156,6 +3427,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
@@ -3551,14 +3826,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) {
@@ -3584,17 +3860,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
+      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 {
+        font family: 'Times', size: 14
+        color :black
+        
+        'Area Gallery'
+      }
     }
     
     on_mouse_event do |area_mouse_event|
@@ -3685,7 +3970,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 {
@@ -3747,16 +4033,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
@@ -3767,9 +4043,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
@@ -3842,7 +4141,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) {
@@ -3868,17 +4168,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
+        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 {
+          font family: 'Times', size: 14
+          color :black
+          
+          'Area Gallery'
+        }
       }
     end
     
@@ -3971,7 +4280,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 {
@@ -4033,16 +4343,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
@@ -4053,9 +4353,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|
@@ -5441,11 +5764,11 @@ class CustomDrawText
             text { # default arguments for x, y, and width are (0, 0, area_draw_params[:area_width])
               # align :left # default alignment
                 
-              @string = string {
-                font @font unless @font.nil?
-                color @color unless @color.nil?
-                background @background unless @background.nil?
-                underline @underline unless @underline.nil?
+              string {
+                font @font
+                color @color
+                background @background
+                underline @underline
                 
                 '  At last Ygramul sensed that something was coming toward ' \
                 'her. With the speed of lightning, she turned about, confronting ' \
@@ -5479,7 +5802,122 @@ 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 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 {
+    field(address, :street)
+    field(address, :p_o_box)
+    field(address, :city)
+    field(address, :state)
+    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