glimmer-dsl-libui 0.5.5 → 0.5.8

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.5.5
+# [<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.5.8
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -19,7 +19,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - [Declarative DSL syntax](#glimmer-gui-dsl-concepts) that visually maps to the GUI control hierarchy
 - [Convention over configuration](#smart-defaults-and-conventions) via smart defaults and automation of low-level details
 - Requiring the [least amount of syntax](#glimmer-gui-dsl-concepts) possible to build GUI
-- [Custom Keyword](#custom-keywords) support
+- [Custom Control](#custom-keywords) support
 - [Bidirectional/Unidirectional Data-Binding](#data-binding) to declaratively wire and automatically synchronize GUI Views with Models
 - [Far Future Plan] Scaffolding for new custom controls, apps, and gems
 - [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
@@ -405,6 +405,7 @@ DSL | Platforms | Native? | Vector Graphics? | Pros | Cons | Prereqs
       - [Basic Image](#basic-image)
       - [Basic Transform](#basic-transform)
       - [Basic Draw Text](#basic-draw-text)
+      - [Basic Code Area](#basic-code-area)
     - [Advanced Examples](#advanced-examples)
       - [Area Gallery](#area-gallery)
       - [Button Counter](#button-counter)
@@ -419,7 +420,8 @@ DSL | Platforms | Native? | Vector Graphics? | Pros | Cons | Prereqs
       - [Grid](#grid)
       - [Histogram](#histogram)
       - [Login](#login)
-      - [Method-Based Custom Keyword](#method-based-custom-keyword)
+      - [Method-Based Custom Controls](#method-based-custom-controls)
+      - [Class-Based Custom Controls](#class-based-custom-controls)
       - [Area-Based Custom Controls](#area-based-custom-controls)
       - [Midi Player](#midi-player)
       - [Snake](#snake)
@@ -454,7 +456,7 @@ The Glimmer GUI DSL follows these simple concepts in mapping from [LibUI](https:
 
 **Keyword(args)**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword from list of [supported keywords](#supported-keywords)) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
 
-**Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls. 
+**Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls.
 
 Example:
 
@@ -464,7 +466,7 @@ window {
   
   on_closing do # listener (always has a do; end block to signify logic)
     puts 'Bye'
-  end 
+  end
   
   button('greet') { # nested control
     on_clicked do
@@ -474,13 +476,13 @@ window {
 }
 ```
 
-Content block optionally receives one arg representing the controll 
+Content block optionally receives one arg representing the controll
 
 Example:
 
 ```ruby
-button('greet') { |b| 
-  on_clicked do 
+button('greet') { |b|
+  on_clicked do
     puts b.text
   end
 }
@@ -488,7 +490,7 @@ button('greet') { |b|
 
 **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
 
-**Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (always followed by a `do; end` style block to signify logic). 
+**Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (always followed by a `do; end` style block to signify logic).
 
 Example:
 
@@ -500,11 +502,11 @@ button('click') {
 }
 ```
 
-Optionally, the listener block can receive an arg representing the control. 
+Optionally, the listener block can receive an arg representing the control.
 
 ```ruby
 button('click') {
-  on_clicked do |btn| 
+  on_clicked do |btn|
     puts btn.text
   end
 }
@@ -567,7 +569,7 @@ window('hello world', 300, 200) {
 
 ## Usage
 
-Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly:
+Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly into a [maintained Ruby version](https://www.ruby-lang.org/en/downloads/):
 
 ```
 gem install glimmer-dsl-libui
@@ -576,7 +578,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.5.5'
+gem 'glimmer-dsl-libui', '~> 0.5.8'
 ```
 
 Test that installation worked by running the [Meta-Example](#examples):
@@ -589,14 +591,40 @@ Mac | Windows | Linux
 ----|---------|------
 ![glimmer-dsl-libui-mac-meta-example.png](images/glimmer-dsl-libui-mac-meta-example.png) | ![glimmer-dsl-libui-windows-meta-example.png](images/glimmer-dsl-libui-windows-meta-example.png) | ![glimmer-dsl-libui-linux-meta-example.png](images/glimmer-dsl-libui-linux-meta-example.png)
 
-Now to use [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui), 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.
+Now to use [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui), add `require 'glimmer-dsl-libui'` at the top.
 
-Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Afterwards, `include Glimmer` into the top-level main object for testing or into an actual class for serious usage.
+
+Alternatively, `include Glimmer::LibUI::Application` to conveniently declare the GUI `body` and run via the `::launch` method (`Glimmer::LibUI::Application` is an alias for `Glimmer::LibUI::CustomWindow` since that is what it represents).
+
+Example including `Glimmer::LibUI::Application` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class SomeGlimmerApp
+  include Glimmer::LibUI::Application
+  
+  body {
+    window('hello world', 300, 200) {
+      button('Button') {
+        on_clicked do
+          puts 'Button Clicked'
+        end
+      }
+    }
+  }
+end
+
+SomeGlimmerApp.launch
+```
+
+Example including `Glimmer` and manually implementing the `#launch` method (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
 
-class Application
+class SomeGlimmerApp
   include Glimmer
   
   def launch
@@ -610,7 +638,23 @@ class Application
   end
 end
 
-Application.new.launch
+SomeGlimmerApp.new.launch
+```
+
+Example including `Glimmer` at the top-level scope just for some prototyping/demoing/testing (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+  
+window('hello world', 300, 200) {
+  button('Button') {
+    on_clicked do
+      puts 'Button Clicked'
+    end
+  }
+}.show
 ```
 
 If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), check out [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. You may refer to the [API](#api) later on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
@@ -674,6 +718,7 @@ Keyword(Args) | Properties | Listeners
 `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
 `check_menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
+`code_area` | `language` (String) (default: `'ruby'`), `theme` (String) (default: `'glimmer'`), `code` (String) | None
 `combobox` | `items` (`Array` of `String`), `selected` (`Integer`), `selected_item` (`String`) | `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`
@@ -1598,15 +1643,15 @@ SpinnerExample.new.launch
 
 Custom keywords can be defined to represent custom controls (components) that provide new features or act as composites of [existing controls](#supported-keywords) that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
 
-For example, you can define a custom `address` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
-
-To define custom keywords, simply define a method representing the custom control you want (e.g. `address`) with any arguments needed (e.g. `address(address_model)`).
+For example, you can define a custom `address_view` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
 
-To make custom keywords externally reusable, you can define in modules and simply include the modules in the view classes that need them.
+There are two ways to define custom keywords:
+- Method-Based: simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
+- Class-Based: define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
 
-It is OK to use terms "custom keyword" and "custom control" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
+It is OK to use the terms "custom keyword" and "custom control" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
 
-Example that defines `form_field`, `address_form`, `label_pair`, and `address` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Example that defines `form_field`, `address_form`, `label_pair`, and `address_view` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -1643,7 +1688,7 @@ def label_pair(model, attribute, value)
   }
 end
 
-def address(address_model)
+def address_view(address_model)
   vertical_box {
     address_model.each_pair do |attribute, value|
       label_pair(address_model, attribute, value)
@@ -1673,7 +1718,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -1695,7 +1740,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -1703,6 +1748,136 @@ window('Method-Based Custom Keyword') {
 
 ![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
 
+You can also define Custom Window keywords, that is custom controls with `window` being the body root. These are also known as Applications. To define a Custom Window, you `include Glimmer::LibUI::CustomWindow` or `include Glimmer:LibUI::Application` and then you can invoke the `::launch` method on the class.
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'facets'
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+class FormField
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute
+  
+  body {
+    entry { |e|
+      label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+      text <=> [model, attribute]
+    }
+  }
+end
+
+class AddressForm
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    form {
+      form_field(model: address, attribute: :street)
+      form_field(model: address, attribute: :p_o_box)
+      form_field(model: address, attribute: :city)
+      form_field(model: address, attribute: :state)
+      form_field(model: address, attribute: :zip_code)
+    }
+  }
+end
+
+class LabelPair
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute, :value
+  
+  body {
+    horizontal_box {
+      label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+      label(value.to_s) {
+        text <= [model, attribute]
+      }
+    }
+  }
+end
+
+class AddressView
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    vertical_box {
+      address.each_pair do |attribute, value|
+        label_pair(model: address, attribute: attribute, value: value)
+      end
+    }
+  }
+end
+
+class ClassBasedCustomControls
+  include Glimmer::LibUI::Application # alias: Glimmer::LibUI::CustomWindow
+  
+  before_body do
+    @address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+    @address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+  end
+  
+  body {
+    window('Class-Based Custom Keyword') {
+      margined true
+      
+      horizontal_box {
+        vertical_box {
+          label('Address 1') {
+            stretchy false
+          }
+          
+          address_form(address: @address1)
+          
+          horizontal_separator {
+            stretchy false
+          }
+          
+          label('Address 1 (Saved)') {
+            stretchy false
+          }
+          
+          address_view(address: @address1)
+        }
+        
+        vertical_separator {
+          stretchy false
+        }
+        
+        vertical_box {
+          label('Address 2') {
+            stretchy false
+          }
+          
+          address_form(address: @address2)
+          
+          horizontal_separator {
+            stretchy false
+          }
+          
+          label('Address 2 (Saved)') {
+            stretchy false
+          }
+          
+          address_view(address: @address2)
+        }
+      }
+    }
+  }
+end
+
+ClassBasedCustomControls.launch
+```
+
+![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
+
 The [`area`](#area-api) control can be utilized to build non-native custom controls from scratch by leveraging vector graphics, formattable text, keyboard events, and mouse events. This is demonstrated in the [Area-Based Custom Controls](#area-based-custom-controls) example.
 
 Defining custom keywords enables unlimited extension of the [Glimmer GUI DSL](#glimmer-gui-dsl). The sky is the limit on what can be done with custom keywords as a result. You can compose new visual vocabulary to build applications in any domain from higher concepts rather than [mere standard controls](#supported-keywords). For example, in a traffic signaling app, you could define `street`, `light_signal`, `traffic_sign`, and `car` as custom keywords and build your application from these concepts directly, saving enormous time and achieving much higher productivity.
@@ -1978,6 +2153,7 @@ Data-bound model attribute can be:
 - **Direct:** `Symbol` representing attribute reader/writer (e.g. `[person, :name`])
 - **Nested:** `String` representing nested attribute path (e.g. `[company, 'address.street']`). That results in "nested data-binding"
 - **Indexed:** `String` containing array attribute index (e.g. `[customer, 'addresses[0].street']`). That results in "indexed data-binding"
+- **Keyed:** `String` containing hash attribute key (e.g. `[customer, 'addresses[:main].street']`). That results in "keyed data-binding"
 
 Data-binding options include:
 - `before_read {|value| ...}`: performs an operation before reading data from Model to update View.
@@ -4855,6 +5031,62 @@ end
 BasicDrawText.new.launch
 ```
 
+#### Basic Code Area
+
+[examples/basic_code_area.rb](examples/basic_code_area.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_code_area.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_code_area'"
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-basic-code-area.png](images/glimmer-dsl-libui-mac-basic-code-area.png) | ![glimmer-dsl-libui-windows-basic-code-area.png](images/glimmer-dsl-libui-windows-basic-code-area.png) | ![glimmer-dsl-libui-linux-basic-code-area.png](images/glimmer-dsl-libui-linux-basic-code-area.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class BasicCodeArea
+  include Glimmer::LibUI::Application
+  
+  before_body do
+    @code = <<~CODE
+      # Greets target with greeting
+      def greet(greeting: 'Hello', target: 'World')
+        
+        puts "\#{greeting}, \#{target}!"
+      end
+      
+      greet
+      greet(target: 'Robert')
+      greet(greeting: 'Aloha')
+      greet(greeting: 'Aloha', target: 'Nancy')
+      greet(greeting: 'Howdy', target: 'Doodle')
+    CODE
+  end
+  
+  body {
+    window('Basic Code Area', 400, 300) {
+      margined true
+      
+      code_area(language: 'ruby', code: @code)
+    }
+  }
+end
+
+BasicCodeArea.launch
+```
+
 ### Advanced Examples
 
 #### Area Gallery
@@ -8580,26 +8812,26 @@ window('Login') {
 }.show
 ```
 
-#### Method-Based Custom Keyword
+#### Method-Based Custom Controls
 
 [Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
   
-This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom control keywords.
+This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
 
 The custom keywords are defined via methods (thus are "method-based").
 
-[examples/method_based_custom_keyword.rb](examples/method_based_custom_keyword.rb)
+[examples/method_based_custom_controls.rb](examples/method_based_custom_controls.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
+ruby -r './lib/glimmer-dsl-libui' examples/method_based_custom_controls.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'"
+ruby -r glimmer-dsl-libui -e "require 'examples/method_based_custom_controls'"
 ```
 
 Mac | Windows | Linux
@@ -8624,13 +8856,13 @@ def form_field(model, attribute)
   }
 end
 
-def address_form(address)
+def address_form(address_model)
   form {
-    form_field(address, :street)
-    form_field(address, :p_o_box)
-    form_field(address, :city)
-    form_field(address, :state)
-    form_field(address, :zip_code)
+    form_field(address_model, :street)
+    form_field(address_model, :p_o_box)
+    form_field(address_model, :city)
+    form_field(address_model, :state)
+    form_field(address_model, :zip_code)
   }
 end
 
@@ -8643,10 +8875,10 @@ def label_pair(model, attribute, value)
   }
 end
 
-def address(address)
+def address_view(address_model)
   vertical_box {
-    address.each_pair do |attribute, value|
-      label_pair(address, attribute, value)
+    address_model.each_pair do |attribute, value|
+      label_pair(address_model, attribute, value)
     end
   }
 end
@@ -8654,7 +8886,7 @@ 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') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -8673,7 +8905,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8695,7 +8927,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -8723,13 +8955,13 @@ def form_field(model, property)
   }
 end
 
-def address_form(address)
+def address_form(address_model)
   form {
-    form_field(address, :street)
-    form_field(address, :p_o_box)
-    form_field(address, :city)
-    form_field(address, :state)
-    form_field(address, :zip_code)
+    form_field(address_model, :street)
+    form_field(address_model, :p_o_box)
+    form_field(address_model, :city)
+    form_field(address_model, :state)
+    form_field(address_model, :zip_code)
   }
 end
 
@@ -8745,10 +8977,10 @@ def label_pair(model, attribute, value)
   end
 end
 
-def address(address)
+def address_view(address_model)
   vertical_box {
-    address.each_pair do |attribute, value|
-      label_pair(address, attribute, value)
+    address_model.each_pair do |attribute, value|
+      label_pair(address_model, attribute, value)
     end
   }
 end
@@ -8756,7 +8988,7 @@ 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') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -8775,7 +9007,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8797,12 +9029,164 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
 ```
 
+#### Class-Based Custom Controls
+
+[Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
+  
+This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
+
+The custom keywords are defined via classes that include `Glimmer::LibUI::CustomControl` (thus are "class-based"), thus enabling offloading each custom control into its own file when needed for better code organization.
+
+[examples/class_based_custom_controls.rb](examples/class_based_custom_controls.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/class_based_custom_controls.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/class_based_custom_controls'"
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png) | ![glimmer-dsl-libui-windows-method-based-custom-keyword.png](images/glimmer-dsl-libui-windows-method-based-custom-keyword.png) | ![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 (with [data-binding](#data-binding)):
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'facets'
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+class FormField
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute
+  
+  body {
+    entry { |e|
+      label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+      text <=> [model, attribute]
+    }
+  }
+end
+
+class AddressForm
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    form {
+      form_field(model: address, attribute: :street)
+      form_field(model: address, attribute: :p_o_box)
+      form_field(model: address, attribute: :city)
+      form_field(model: address, attribute: :state)
+      form_field(model: address, attribute: :zip_code)
+    }
+  }
+end
+
+class LabelPair
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute, :value
+  
+  body {
+    horizontal_box {
+      label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+      label(value.to_s) {
+        text <= [model, attribute]
+      }
+    }
+  }
+end
+
+class AddressView
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    vertical_box {
+      address.each_pair do |attribute, value|
+        label_pair(model: address, attribute: attribute, value: value)
+      end
+    }
+  }
+end
+
+class ClassBasedCustomControls
+  include Glimmer::LibUI::Application # alias: Glimmer::LibUI::CustomWindow
+  
+  before_body do
+    @address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+    @address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+  end
+  
+  body {
+    window('Class-Based Custom Keyword') {
+      margined true
+      
+      horizontal_box {
+        vertical_box {
+          label('Address 1') {
+            stretchy false
+          }
+          
+          address_form(address: @address1)
+          
+          horizontal_separator {
+            stretchy false
+          }
+          
+          label('Address 1 (Saved)') {
+            stretchy false
+          }
+          
+          address_view(address: @address1)
+        }
+        
+        vertical_separator {
+          stretchy false
+        }
+        
+        vertical_box {
+          label('Address 2') {
+            stretchy false
+          }
+          
+          address_form(address: @address2)
+          
+          horizontal_separator {
+            stretchy false
+          }
+          
+          label('Address 2 (Saved)') {
+            stretchy false
+          }
+          
+          address_view(address: @address2)
+        }
+      }
+    }
+  }
+end
+
+ClassBasedCustomControls.launch
+```
+
 #### Area-Based Custom Controls
 
 [Custom keywords](#custom-keywords) can be defined for graphical custom controls (components) built completely from scratch as vector-graphics on top of the [`area`](#area-api) control while leveraging keyboard and mouse listeners.
@@ -9514,6 +9898,8 @@ Snake provides an example of building a desktop application [test-first](/spec/e
 
 Use arrows to move and spacebar to pause/resume.
 
+Note that Snake relies on the new [Ruby Pattern Matching feature](https://docs.ruby-lang.org/en/3.0/doc/syntax/pattern_matching_rdoc.html) available starting in Ruby 2.7 experimentally and in Ruby 3.0 officially.
+
 [examples/snake.rb](examples/snake.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -9738,6 +10124,8 @@ Snake.new.launch
 
 Glimmer Tetris utilizes many small areas to represent Tetromino blocks because this ensures smaller redraws per tetromino block color change, thus achieving higher performance than redrawing one large area on every little change.
 
+Note that Tetris relies on the new [Ruby Pattern Matching feature](https://docs.ruby-lang.org/en/3.0/doc/syntax/pattern_matching_rdoc.html) available starting in Ruby 2.7 experimentally and in Ruby 3.0 officially.
+
 [examples/tetris.rb](examples/tetris.rb)
 
 Run with this command from the root of the project if you cloned the project: