glimmer-dsl-libui 0.5.4 → 0.5.7

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.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.7
 ## 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,13 +19,11 @@ 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.
 
-Note that currently, [LibUI](https://github.com/kojix2/LibUI) only includes x86_64 binaries out of the box, but there are plans to include ARM64/AARCH64 binaries too in the future.
-
 Hello, World!
 
 ```ruby
@@ -338,7 +336,7 @@ DSL | Platforms | Native? | Vector Graphics? | Pros | Cons | Prereqs
 [Glimmer DSL for SWT (JRuby Desktop Development GUI Framework)](https://github.com/AndyObtiva/glimmer-dsl-swt) | Mac / Windows / Linux | Yes | Yes (Canvas Shape DSL) | Very Mature / Scaffolding / Native Executable Packaging / Custom Widgets | Slow JRuby Startup Time / Heavy Memory Footprint | Java / JRuby
 [Glimmer DSL for Opal (Pure Ruby Web GUI and Auto-Webifier of Desktop Apps)](https://github.com/AndyObtiva/glimmer-dsl-opal) | All Web Browsers | No | Yes (Canvas Shape DSL) | Simpler than All JavaScript Technologies / Auto-Webify Desktop Apps | Setup Process / Only Rails 5 Support for Now | Rails
 [Glimmer DSL for LibUI (Prerequisite-Free Ruby Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-libui) | Mac / Windows / Linux | Yes | Yes (Area API) | Fast Startup Time / Light Memory Footprint | LibUI is an Incomplete Mid-Alpha Only | None Other Than MRI Ruby
-[Glimmer DSL for Tk (MRI Ruby Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-tk) | Mac / Windows / Linux | Some Native-Themed Widgets (Not Truly Native) | Yes (Canvas) | Fast Startup Time / Light Memory Footprint | Widgets Do Not Look Truly Native, Espcially on Linux | ActiveTcl / MRI Ruby
+[Glimmer DSL for Tk (Ruby Tk Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-tk) | Mac / Windows / Linux | Some Native-Themed Widgets (Not Truly Native) | Yes (Canvas) | Fast Startup Time / Light Memory Footprint | Complicated Setup / Widgets Do Not Look Truly Native, Espcially on Linux | ActiveTcl / MRI Ruby
 [Glimmer DSL for GTK (Ruby-GNOME Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-gtk) | Mac / Windows / Linux | Only on Linux | Yes (Cairo) | Complete Access to GNOME Features on Linux (Forte) | Not Native on Mac and Windows | None Other Than MRI Ruby on Linux / Brew Packages on Mac / MSYS & MING Toolchains on Windows / MRI Ruby
 [Glimmer DSL for FX (FOX Toolkit Ruby Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-fx) | Mac (requires XQuartz) / Windows / Linux | No | Yes (Canvas) | No Prerequisites on Windows (Forte Since Binaries Are Included Out of The Box) | Widgets Do Not Look Native / Mac Usage Obtrusively Starts XQuartz | None Other Than MRI Ruby on Windows / XQuarts on Mac / MRI Ruby
 [Glimmer DSL for JFX (JRuby JavaFX Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-jfx) | Mac / Windows / Linux | No | Yes (javafx.scene.shape and javafx.scene.canvas) | Rich in Custom Widgets | Slow JRuby Startup Time / Heavy Memory Footprint / Widgets Do Not Look Native | Java / JRuby / JavaFX SDK
@@ -370,6 +368,7 @@ DSL | Platforms | Native? | Vector Graphics? | Pros | Cons | Prereqs
       - [Area Listeners](#area-listeners)
       - [Area Methods/Attributes](#area-methods-attributes)
       - [Area Transform Matrix](#area-transform-matrix)
+      - [Area Animation](#area-animation)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
     - [Custom Keywords](#custom-keywords)
     - [Observer Pattern](#observer-pattern)
@@ -420,7 +419,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)
@@ -452,10 +452,68 @@ The Glimmer GUI DSL provides object-oriented declarative hierarchical syntax for
 - Requires the minimum amount of syntax needed to describe an app's GUI
 
 The Glimmer GUI DSL follows these simple concepts in mapping from [LibUI](https://github.com/kojix2/LibUI) syntax:
-- **Keyword(args)**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
-- **Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls (e.g. `window {title 'hello world'; on_closing {puts 'Bye'}; button('greet')}`). Content block optionally receives one arg representing the control (e.g. `button('greet') {|b| on_clicked { puts b.text}}`)
-- **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
-- **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (e.g. `on_clicked {puts 'clicked'}` inside `button`). Optionally, the listener block can receive an arg representing the control (e.g. `on_clicked {|btn| puts btn.text}`). Behind the scenes, listeners correspond to `LibUI.control_on_event` methods.
+
+**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.
+
+Example:
+
+```ruby
+window {
+  title 'hello world' # property
+  
+  on_closing do # listener (always has a do; end block to signify logic)
+    puts 'Bye'
+  end
+  
+  button('greet') { # nested control
+    on_clicked do
+      puts 'hello world'
+    end
+  }
+}
+```
+
+Content block optionally receives one arg representing the controll
+
+Example:
+
+```ruby
+button('greet') { |b|
+  on_clicked do
+    puts b.text
+  end
+}
+```
+
+**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).
+
+Example:
+
+```ruby
+button('click') {
+  on_clicked do
+    puts 'clicked'
+  end
+}
+```
+
+Optionally, the listener block can receive an arg representing the control.
+
+```ruby
+button('click') {
+  on_clicked do |btn|
+    puts btn.text
+  end
+}
+```
+
+Behind the scenes, listeners correspond to `LibUI.control_on_event` methods.
+
+**Method**: Controls have methods that invoke certain operations on them. For example, `window` has a `#show` method that shows the window GUI. More methods are mentioned under [API](#api)
 
 Example of an app written in [LibUI](https://github.com/kojix2/LibUI)'s procedural imperative syntax:
 
@@ -510,7 +568,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
@@ -519,7 +577,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.5.4'
+gem 'glimmer-dsl-libui', '~> 0.5.7'
 ```
 
 Test that installation worked by running the [Meta-Example](#examples):
@@ -1404,6 +1462,92 @@ You can set a `matrix`/`transform` on `area` directly to conveniently apply to a
 
 Note that `area`, `path`, and nested shapes are all truly declarative, meaning they do not care about the ordering of calls to `fill`, `stroke`, and `transform`. Furthermore, any transform that is applied is reversed at the end of the block, so you never have to worry about the ordering of `transform` calls among different paths. You simply set a transform on the `path`s that need it and it is guaranteed to be called before all its content is drawn, and then undone afterwards to avoid affecting later paths. Matrix `transform` can be set on an entire `area` too, applying to all nested `path`s.
 
+#### Area Animation
+
+If you need to animate `area` vector graphics, you just have to use the [`Glimmer::LibUI::timer`](#libui-operations) method along with making changes to shape attributes.
+
+Spinner example that has a fully customizable method-based custom control called `spinner`, which is destroyed if you click on it (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class SpinnerExample
+  include Glimmer
+  
+  SIZE = 120
+  
+  def initialize
+    create_gui
+  end
+  
+  def launch
+    @main_window.show
+  end
+  
+  def create_gui
+    @main_window = window {
+      title 'Spinner'
+      content_size SIZE*2, SIZE*2
+      
+      horizontal_box {
+        padded false
+        
+        vertical_box {
+          padded false
+          
+          spinner(size: SIZE)
+          spinner(size: SIZE, fill_color: [42, 153, 214])
+        }
+        
+        vertical_box {
+          padded false
+          
+          spinner(size: SIZE/2.0, fill_color: :orange)
+          spinner(size: SIZE/2.0, fill_color: {x0: 0, y0: 0, x1: SIZE/2.0, y1: SIZE/2.0, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 1, r: 2, g: 2, b: 254}]})
+          spinner(size: SIZE/2.0, fill_color: :green, unfilled_color: :yellow)
+          spinner(size: SIZE/2.0, fill_color: :white, unfilled_color: :gray, background_color: :black)
+        }
+      }
+    }
+  end
+  
+  def spinner(size: 40.0, fill_color: :gray, background_color: :white, unfilled_color: {r: 243, g: 243, b: 243}, donut_percentage: 0.25)
+    arc1 = arc2 = nil
+    area { |the_area|
+      rectangle(0, 0, size, size) {
+        fill background_color
+      }
+      circle(size/2.0, size/2.0, size/2.0) {
+        fill fill_color
+      }
+      arc1 = arc(size/2.0, size/2.0, size/2.0, 0, 180) {
+        fill unfilled_color
+      }
+      arc2 = arc(size/2.0, size/2.0, size/2.0, 90, 180) {
+        fill unfilled_color
+      }
+      circle(size/2.0, size/2.0, (size/2.0)*(1.0 - donut_percentage)) {
+        fill background_color
+      }
+      
+      on_mouse_up do
+        the_area.destroy
+      end
+    }.tap do
+      Glimmer::LibUI.timer(0.05) do
+        delta = 10
+        arc1.start_angle += delta
+        arc2.start_angle += delta
+      end
+    end
+  end
+end
+
+SpinnerExample.new.launch
+```
+
+![mac spinner](/images/glimmer-dsl-libui-mac-spinner.gif)
+
 ### Smart Defaults and Conventions
 
 - `horizontal_box`, `vertical_box`, `grid`, and `form` controls have `padded` as `true` upon instantiation to ensure more user-friendly GUI by default
@@ -1455,15 +1599,15 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 
 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.
+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 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)`).
+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.
 
-To make custom keywords externally reusable, you can define in modules and simply include the modules in the view classes that need them.
+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`).
 
-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`).
-
-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'
@@ -1500,7 +1644,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)
@@ -1530,7 +1674,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -1552,7 +1696,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -1560,6 +1704,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.
@@ -1835,6 +2109,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.
@@ -1868,6 +2143,7 @@ Learn more from data-binding usage in [Login](#login) (4 data-binding versions),
 - 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` checkbox editing only works on Linux and Windows (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
 - `table` `checkbox_text_column` checkbox editing only works on Linux (not Mac or Windows) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- `checkbox` only supports obtaining the `checked` property, but not updating it due to a current limitation in [libui](https://github.com/andlabs/libui).
 - `text` `align` property seems not to work on the Mac ([libui](https://github.com/andlabs/libui) has an [issue](https://github.com/andlabs/libui/pull/407) about it)
 - `text` `string` `background` does not work on Windows due to an [issue in libui](https://github.com/andlabs/libui/issues/347).
 - `table` `progress_bar` column on Windows cannot be updated with a positive value if it started initially with `-1` (it ignores update to avoid crashing due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
@@ -1875,6 +2151,7 @@ Learn more from data-binding usage in [Login](#login) (4 data-binding versions),
 - It seems that [libui](https://github.com/andlabs/libui) does not support nesting multiple `area` controls under a `grid` as only the first one shows up in that scenario. To workaround that limitation, use a `vertical_box` with nested `horizontal_box`s instead to include multiple `area`s in a GUI.
 - As per the code of [examples/basic_transform.rb](#basic-transform), Windows requires different ordering of transforms than Mac and Linux.
 - `scrolling_area#scroll_to` does not seem to work on Windows and Linux, but works fine on Mac
+- When creating/showing a window other than the main window and then closing the secondary window, the entire app closes. This is a current limitation to the windowing system that should be fixed with [child window support](https://github.com/andlabs/libui/issues/137) in [libui](https://github.com/andlabs/libui)
 
 ### Original API
 
@@ -8435,26 +8712,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
@@ -8479,13 +8756,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
 
@@ -8498,10 +8775,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
@@ -8509,7 +8786,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 {
@@ -8528,7 +8805,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8550,7 +8827,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -8578,13 +8855,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
 
@@ -8600,10 +8877,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
@@ -8611,7 +8888,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 {
@@ -8630,7 +8907,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8652,7 +8929,151 @@ 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'
+
+include Glimmer
+
+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
+
+address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+
+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)
     }
   }
 }.show
@@ -9369,6 +9790,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:
@@ -9593,6 +10016,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: