glimmer-dsl-libui 0.4.19 → 0.5.0

data/README.md

@@ -1,9 +1,11 @@
-# [<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.4.19
+# [<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.0
 ## 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)
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/kojix2/LibUI) is a prerequisite-free Ruby desktop development GUI (Graphical User Interface) library. No need to pre-install any prerequisites. Just install the [gem](https://rubygems.org/gems/glimmer-dsl-libui) and have platform-independent native GUI that just works!
+[**(Fukuoka Ruby Award Competition 2022 Special Award Winner)**](http://www.digitalfukuoka.jp/topics/187?locale=ja)
+
+[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/kojix2/LibUI) is a prerequisite-free [MRI Ruby](https://www.ruby-lang.org) desktop development GUI (Graphical User Interface) library. No need to pre-install any prerequisites. Just install the [gem](https://rubygems.org/gems/glimmer-dsl-libui) and have platform-independent native GUI that just works!
 
 Mac | Windows | Linux
 ----|---------|------
@@ -22,6 +24,8 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - [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
@@ -320,19 +324,27 @@ Mac | Windows | Linux
 
 [Check Out Many More Examples Over Here!](#examples)
 
-Mac | Windows | Linux
-----|---------|------
-![glimmer-dsl-libui-mac-tetris.png](images/glimmer-dsl-libui-mac-tetris.png) | ![glimmer-dsl-libui-windows-tetris.png](images/glimmer-dsl-libui-windows-tetris.png) | ![glimmer-dsl-libui-linux-tetris.png](images/glimmer-dsl-libui-linux-tetris.png)
+![glimmer-dsl-libui-mac-snake.gif](images/glimmer-dsl-libui-mac-snake.gif)
+
+![glimmer-dsl-libui-mac-color-the-circles.gif](images/glimmer-dsl-libui-mac-color-the-circles.gif)
 
-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.
+![glimmer-dsl-libui-mac-tetris.gif](images/glimmer-dsl-libui-mac-tetris.gif)
 
-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)
-- [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Pure Ruby Web GUI and Auto-Webifier of Desktop Apps)
-- [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (MRI Ruby Desktop Development GUI Library)
-- [glimmer-dsl-gtk](https://github.com/AndyObtiva/glimmer-dsl-gtk): Glimmer DSL for GTK (Ruby-GNOME Desktop Development GUI Library)
-- [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
-- [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS
+NOTE: [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) is 100% feature-complete with regards to covering the C [libui](https://github.com/andlabs/libui) library API and in beta mode (though the C [libui](https://github.com/andlabs/libui) is still mid-alpha, which is why [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) cannot be declared v1.0.0 yet). 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.
+
+**[Glimmer](https://rubygems.org/gems/glimmer) DSL Comparison Table:**
+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 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
+[Glimmer DSL for Swing (JRuby Swing Desktop Development GUI Library)](https://github.com/AndyObtiva/glimmer-dsl-swing) | Mac / Windows / Linux | No | Yes (Java2D) | Very Mature | Slow JRuby Startup Time / Heavy Memory Footprint / Widgets Do Not Look Native | Java / JRuby
+[Glimmer DSL for XML (& HTML)](https://github.com/AndyObtiva/glimmer-dsl-xml) | All Web Browsers | No | Yes (SVG) | Programmable / Lighter-weight Than Actual XML | XML Elements Are Sometimes Not Well-Named (Many Types of Input) | None
+[Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css) | All Web Browsers | No | Yes | Programmable | CSS Is Over-Engineered / Too Many Features To Learn | None
 
 ## Table of Contents
 
@@ -409,6 +421,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
       - [Histogram](#histogram)
       - [Login](#login)
       - [Method-Based Custom Keyword](#method-based-custom-keyword)
+      - [Area-Based Custom Controls](#area-based-custom-controls)
       - [Midi Player](#midi-player)
       - [Snake](#snake)
       - [Tetris](#tetris)
@@ -506,7 +519,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.4.19'
+gem 'glimmer-dsl-libui', '~> 0.5.0'
 ```
 
 Test that installation worked by running the [Meta-Example](#examples):
@@ -576,13 +589,14 @@ w.set_title 'aloha'
 puts w.title # => aloha
 ```
 
-Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped [LibUI](https://github.com/kojix2/LibUI) Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed.
+Controls are wrapped as Ruby proxy objects, having a `#libui` method to obtain the wrapped [LibUI](https://github.com/kojix2/LibUI) Fiddle pointer object. Ruby proxy objects rely on composition (via [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern)) instead of inheritance to shield consumers from having to deal with lower-level details unless absolutely needed. That said, you can invoke any [LibUI operation](#libui-operations) on the Glimmer proxy object directly and it gets proxied automatically to the wrapped Fiddle pointer object (e.g. `window_proxy.title` gets proxied to `LibUI.window_title(window_proxy.libui).to_s` automatically), so you rarely have to refer to the wrapped `#libui` Fiddle pointer object directly.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 w = window('hello world') # => #<Glimmer::LibUI::WindowProxy:0x00007fde4ea39fb0
 w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0 free=0x0000000000000000>
+w.title == LibUI.window_title(w.libui).to_s # => true
 ```
 
 ### Supported Keywords
@@ -994,15 +1008,49 @@ To draw `text` in an `area`, you simply nest a `text(x, y, width)` control direc
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
 window('area text drawing') {
   area {
     text {
       default_font family: 'Helvetica', size: 12, weight: :normal, italic: :normal, stretch: :normal
         
+      string('This ') {
+        font size: 20, weight: :bold, italic: :normal, stretch: :normal
+        color r: 128, g: 0, b: 0, a: 1
+      }
+        
+      string('is ') {
+        font size: 20, weight: :bold, italic: :normal, stretch: :normal
+        color r: 0, g: 128, b: 0, a: 1
+      }
+        
+      string('a ') {
+        font size: 20, weight: :bold, italic: :normal, stretch: :normal
+        color r: 0, g: 0, b: 128, a: 1
+      }
+        
+      string('short ') {
+        font size: 20, weight: :bold, italic: :italic, stretch: :normal
+        color r: 128, g: 128, b: 0, a: 1
+      }
+        
+      string('attributed ') {
+        font size: 20, weight: :bold, italic: :normal, stretch: :normal
+        color r: 0, g: 128, b: 128, a: 1
+      }
+        
+      string("string \n\n") {
+        font size: 20, weight: :bold, italic: :normal, stretch: :normal
+        color r: 128, g: 0, b: 128, a: 1
+      }
+        
       string {
         font family: 'Georgia', size: 13, weight: :medium, italic: :normal, stretch: :normal
-        color r: 230, g: 100, b: 50, a: 0.5
-        background r: 230, g: 200, b: 250, a: 0.8
+        color r: 0, g: 128, b: 255, a: 1
+        background r: 255, g: 255, b: 0, a: 0.5
         underline :single
         underline_color :spelling
         open_type_features {
@@ -1015,13 +1063,14 @@ window('area text drawing') {
         "attributed string\n" \
         "spanning multiple lines\n\n"
       }
-      
-      string('This is a short unattributed string')
     }
   }
 }.show
 ```
 
+![glimmer-dsl-libui-mac-area-text-drawing.png](/images/glimmer-dsl-libui-mac-area-text-drawing.png)
+
+
 You may checkout [examples/basic_draw_text.rb](#basic-draw-text) and [examples/custom_draw_text.rb](#custom-draw-text) for examples of using `text` inside `area`.
 
 Mac | Windows | Linux
@@ -1365,8 +1414,8 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 - All boolean property readers return `true` or `false` in Ruby instead of the [libui](https://github.com/andlabs/libui) original `0` or `1` in C.
 - All boolean property writers accept `true`/`false` in addition to `1`/`0` in Ruby
 - All string property readers return a `String` object in Ruby instead of the [libui](https://github.com/andlabs/libui) Fiddle pointer object.
-- Automatically allocate font descriptors upon instantiating `font_button` controls and free them when destorying `font_button` controls
-- Automatically allocate color value pointers upon instantiating `color_button` controls and free them when destorying `color_button` controls
+- Automatically allocate font descriptors upon instantiating `font_button` controls and free them when destroying `font_button` controls
+- Automatically allocate color value pointers upon instantiating `color_button` controls and free them when destroying `color_button` controls
 - On the Mac, if no `menu` items were added, an automatic `quit_menu_item` is added to enable quitting with CTRL+Q
 - When destroying a control nested under a `horizontal_box` or `vertical_box`, it is automatically deleted from the box's children
 - When destroying a control nested under a `form`, it is automatically deleted from the form's children
@@ -1396,14 +1445,16 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 
 ### Custom Keywords
 
-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 maintainbility.
-  
+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)`).
 
 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 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)):
 
 ```ruby
@@ -1501,11 +1552,11 @@ window('Method-Based Custom Keyword') {
 
 ![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.
+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.
 
-Learn more from custom keyword usage in [Method-Based Custom Keyword](#method-based-custom-keyword), [Histogram](#histogram), and [Tetris](#tetris) examples.
+Learn more from custom keyword usage in [Method-Based Custom Keyword](#method-based-custom-keyword), [Area-Based Custom Controls](#area-based-custom-controls), [Basic Scrolling Area](#basic-scrolling-area), [Histogram](#histogram), and [Tetris](#tetris) examples.
 
 ### Observer Pattern
 
@@ -1778,9 +1829,9 @@ Data-bound model attribute can be:
 - **Indexed:** `String` containing array attribute index (e.g. `[customer, 'addresses[0].street']`). That results in "indexed data-binding"
 
 Data-binding options include:
-- `before_read {|value| ...}`: performs an operation before reading data from Model to update the View.
+- `before_read {|value| ...}`: performs an operation before reading data from Model to update View.
 - `on_read {|value| ...}`: converts value read from Model to update the View.
-- `after_read {|converted_value| ...}`: performs an operation after read from Model and updating the View.
+- `after_read {|converted_value| ...}`: performs an operation after read from Model to update View.
 - `before_write {|value| ...}`: performs an operation before writing data to Model from View.
 - `on_write {|value| ...}`: converts value read from View to update the Model.
 - `after_write {|converted_value| ...}`: performs an operation after writing to Model from View.
@@ -1812,6 +1863,7 @@ Learn more from data-binding usage in [Login](#login) (4 data-binding versions),
 - `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.
+- `radio_buttons` on Linux has an issue where it always selects the first item even if you did not set its `selected` value or set it to `-1` (meaning unselected). It works correctly on Mac and Windows.
 - 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
@@ -1836,6 +1888,8 @@ For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a
 
 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/).
 
+Also, there is a promising project called [ruby-packer](https://github.com/pmq20/ruby-packer) that supports all platforms.
+
 ## Glimmer Style Guide
 
 **1 - Control arguments are always wrapped by parentheses.**
@@ -8375,7 +8429,7 @@ window('Login') {
 
 #### Method-Based Custom Keyword
 
-[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 maintainbility.
+[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.
 
@@ -8596,6 +8650,317 @@ window('Method-Based Custom Keyword') {
 }.show
 ```
 
+#### 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.
+
+This example defines `text_label` and `push_button` as [`area`](#area-api)-based graphical custom controls that can have width, height, font, fill, stroke, border, and custom text location.
+      
+[examples/area_based_custom_controls.rb](examples/area_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/area_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/area_based_custom_controls'"
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-area-based-custom-controls.png](images/glimmer-dsl-libui-mac-area-based-custom-controls-text-label.png) ![glimmer-dsl-libui-mac-area-based-custom-controls.png](images/glimmer-dsl-libui-mac-area-based-custom-controls-push-button.png) ![glimmer-dsl-libui-mac-area-based-custom-controls.png](images/glimmer-dsl-libui-mac-area-based-custom-controls-push-button-clicked.png) | ![glimmer-dsl-libui-windows-area-based-custom-controls.png](images/glimmer-dsl-libui-windows-area-based-custom-controls-text-label.png) ![glimmer-dsl-libui-windows-area-based-custom-controls.png](images/glimmer-dsl-libui-windows-area-based-custom-controls-push-button.png) ![glimmer-dsl-libui-windows-area-based-custom-controls.png](images/glimmer-dsl-libui-windows-area-based-custom-controls-push-button-clicked.png) | ![glimmer-dsl-libui-linux-area-based-custom-controls.png](images/glimmer-dsl-libui-linux-area-based-custom-controls-text-label.png) ![glimmer-dsl-libui-linux-area-based-custom-controls.png](images/glimmer-dsl-libui-linux-area-based-custom-controls-push-button.png) ![glimmer-dsl-libui-linux-area-based-custom-controls.png](images/glimmer-dsl-libui-linux-area-based-custom-controls-push-button-clicked.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class AreaBasedCustomControls
+  include Glimmer
+  
+  attr_accessor :label_width, :label_height, :label_font_descriptor,
+                :label_text_color, :label_background_fill, :label_border_stroke,
+                :label_text_x, :label_text_y,
+                :button_width, :button_height, :button_font_descriptor,
+                :button_text_color, :button_background_fill, :button_border_stroke,
+                :button_text_x, :button_text_y
+  
+  def initialize
+    self.label_width = 335
+    self.label_height = 50
+    self.label_font_descriptor = {family: OS.linux? ? 'Monospace Bold Italic' : 'Courier New', size: 16, weight: :bold, italic: :italic}
+    self.label_text_color = :red
+    self.label_background_fill = :yellow
+    self.label_border_stroke = :limegreen
+    
+    self.button_width = 150
+    self.button_height = 50
+    self.button_font_descriptor = {family: OS.linux? ? 'Monospace Bold Italic' : 'Courier New', size: 36, weight: OS.linux? ? :normal : :bold, italic: :italic}
+    self.button_text_color = :green
+    self.button_background_fill = :yellow
+    self.button_border_stroke = :limegreen
+  end
+  
+  def rebuild_text_label
+    @text_label.destroy
+    @text_label_vertical_box.content { # re-open vertical box content and shove in a new label
+      @text_label = text_label('This is a text label.',
+                               width: label_width, height: label_height, font_descriptor: label_font_descriptor,
+                               background_fill: label_background_fill, text_color: label_text_color, border_stroke: label_border_stroke,
+                               text_x: label_text_x, text_y: label_text_y)
+    }
+  end
+  
+  def rebuild_push_button
+    @push_button.destroy
+    @push_button_vertical_box.content { # re-open vertical box content and shove in a new button
+      @push_button = push_button('Push',
+                                 width: button_width, height: button_height, font_descriptor: button_font_descriptor,
+                                 background_fill: button_background_fill, text_color: button_text_color, border_stroke: button_border_stroke,
+                                 text_x: button_text_x, text_y: button_text_y) {
+        on_mouse_up do
+          message_box('Button Pushed', 'Thank you for pushing the button!')
+        end
+      }
+    }
+  end
+  
+  def launch
+    window('Area-Based Custom Controls', 385, 385) { |w|
+      margined true
+      
+      tab {
+        tab_item('Text Label') {
+          @text_label_vertical_box = vertical_box {
+            vertical_box {
+              text_label('Text Label Form:', width: 385, height: 30, background_fill: OS.windows? ? :white : {a: 0}, border_stroke: OS.windows? ? :white : {a: 0}, font_descriptor: {size: 16, weight: :bold}, text_x: 0, text_y: OS.windows? ? 0 : 5)
+
+              horizontal_box {
+                label('Width')
+                spinbox(1, 1000) {
+                  value <=> [self, :label_width, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Height')
+                spinbox(1, 1000) {
+                  value <=> [self, :label_height, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Font')
+                font_button {
+                  font <=> [self, :label_font_descriptor, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text Color')
+                color_button {
+                  color <=> [self, :label_text_color, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Background Color')
+                color_button {
+                  color <=> [self, :label_background_fill, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Border Color')
+                color_button {
+                  color <=> [self, :label_border_stroke, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text X (0=centered)')
+                spinbox(0, 1000) {
+                  value <=> [self, :label_text_x, on_read: ->(x) {x.nil? ? 0 : x}, on_write: ->(x) {x == 0 ? nil : x}, after_write: method(:rebuild_text_label)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text Y (0=centered)')
+                spinbox(0, 1000) {
+                  value <=> [self, :label_text_y, on_read: ->(y) {y.nil? ? 0 : y}, on_write: ->(y) {y == 0 ? nil : y}, after_write: method(:rebuild_text_label)]
+                }
+              }
+            }
+            
+            @text_label = text_label('This is a text label.',
+                                     width: label_width, height: label_height, font_descriptor: label_font_descriptor,
+                                     background_fill: label_background_fill, text_color: label_text_color, border_stroke: label_border_stroke,
+                                     text_x: label_text_x, text_y: label_text_y)
+          }
+        }
+        
+        tab_item('Push Button') {
+          @push_button_vertical_box = vertical_box {
+            vertical_box {
+              text_label('Push Button Form:', width: 385, height: 30, background_fill: OS.windows? ? :white : {a: 0}, border_stroke: OS.windows? ? :white : {a: 0}, font_descriptor: {size: 16, weight: :bold}, text_x: 0, text_y: OS.windows? ? 0 : 5)
+              
+              horizontal_box {
+                label('Width')
+                spinbox(1, 1000) {
+                  value <=> [self, :button_width, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Height')
+                spinbox(1, 1000) {
+                  value <=> [self, :button_height, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Font')
+                font_button {
+                  font <=> [self, :button_font_descriptor, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text Color')
+                color_button {
+                  color <=> [self, :button_text_color, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Background Color')
+                color_button {
+                  color <=> [self, :button_background_fill, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Border Color')
+                color_button {
+                  color <=> [self, :button_border_stroke, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text X (0=centered)')
+                spinbox(0, 1000) {
+                  value <=> [self, :button_text_x, on_read: ->(x) {x.nil? ? 0 : x}, on_write: ->(x) {x == 0 ? nil : x}, after_write: method(:rebuild_push_button)]
+                }
+              }
+              
+              horizontal_box {
+                label('Text Y (0=centered)')
+                spinbox(0, 1000) {
+                  value <=> [self, :button_text_y, on_read: ->(y) {y.nil? ? 0 : y}, on_write: ->(y) {y == 0 ? nil : y}, after_write: method(:rebuild_push_button)]
+                }
+              }
+            }
+            
+            @push_button = push_button('Push',
+                                       width: button_width, height: button_height, font_descriptor: button_font_descriptor,
+                                       background_fill: button_background_fill, text_color: button_text_color, border_stroke: button_border_stroke,
+                                       text_x: button_text_x, text_y: button_text_y) {
+              on_mouse_up do
+                message_box('Button Pushed', 'Thank you for pushing the button!')
+              end
+            }
+          }
+        }
+      }
+    }.show
+  end
+    
+  # text label (area-based custom control) built with vector graphics on top of area.
+  #
+  # background_fill is transparent by default.
+  # background_fill can accept a single color or gradient stops just as per `fill` property in README.
+  # border_stroke is transparent by default.
+  # border_stroke can accept thickness and dashes in addition to color just as per `stroke` property in README.
+  # text_x and text_y are the offset of the label text in relation to its top-left corner.
+  # When text_x, text_y are left nil, the text is automatically centered in the label area.
+  # Sometimes, the centering calculation is not perfect due to using a custom font, so
+  # in that case, pass in text_x, and text_y manually.
+  def text_label(label_text,
+                  width: 80, height: 30, font_descriptor: {},
+                  background_fill: {a: 0}, text_color: :black, border_stroke: {a: 0},
+                  text_x: nil, text_y: nil,
+                  &content)
+    area { |the_area|
+      rectangle(1, 1, width, height) {
+        fill background_fill
+      }
+      rectangle(1, 1, width, height) {
+        stroke border_stroke
+      }
+      
+      text_height = (font_descriptor[:size] || 12) * (OS.mac? ? 0.75 : 1.35)
+      text_width = (text_height * label_text.size) * (OS.mac? ? 0.75 : 0.60)
+      text_x ||= (width - text_width) / 2.0
+      text_y ||= (height - 4 - text_height) / 2.0
+      text(text_x, text_y, width) {
+        string(label_text) {
+          color text_color
+          font font_descriptor
+        }
+      }
+      
+      content&.call(the_area)
+    }
+  end
+  
+  # push button (area-based custom control) built with vector graphics on top of area.
+  #
+  # background_fill is white by default.
+  # background_fill can accept a single color or gradient stops just as per `fill` property in README.
+  # border_stroke is black by default.
+  # border_stroke can accept thickness and dashes in addition to color just as per `stroke` property in README.
+  # text_x and text_y are the offset of the button text in relation to its top-left corner.
+  # When text_x, text_y are left nil, the text is automatically centered in the button area.
+  # Sometimes, the centering calculation is not perfect due to using a custom font, so
+  # in that case, pass in text_x, and text_y manually.
+  #
+  # reuses the text_label custom control
+  def push_button(button_text,
+                  width: 80, height: 30, font_descriptor: {},
+                  background_fill: :white, text_color: :black, border_stroke: {r: 201, g: 201, b: 201},
+                  text_x: nil, text_y: nil,
+                  &content)
+    text_label(button_text,
+                  width: width, height: height, font_descriptor: font_descriptor,
+                  background_fill: background_fill, text_color: text_color, border_stroke: border_stroke,
+                  text_x: text_x, text_y: text_y) { |the_area|
+      
+      # dig into the_area content and grab elements to modify in mouse listeners below
+      background_rectangle = the_area.children[0]
+      button_string = the_area.children[2].children[0]
+      
+      on_mouse_down do
+        background_rectangle.fill = {x0: 0, y0: 0, x1: 0, y1: height, stops: [{pos: 0, r: 72, g: 146, b: 247}, {pos: 1, r: 12, g: 85, b: 214}]}
+        button_string.color = :white
+      end
+      
+      on_mouse_up do
+        background_rectangle.fill = background_fill
+        button_string.color = text_color
+      end
+      
+      content&.call(the_area)
+    }
+  end
+end
+
+AreaBasedCustomControls.new.launch
+```
+
 #### Midi Player
 
 To run this example, install [TiMidity](http://timidity.sourceforge.net) and ensure `timidity` command is in `PATH` (can be installed via [Homebrew](https://brew.sh) on Mac or [apt-get](https://help.ubuntu.com/community/AptGet/Howto) on Linux).
@@ -8994,6 +9359,8 @@ TinyMidiPlayer.new
 
 Snake provides an example of building a desktop application [test-first](/spec/examples/snake/model/game_spec.rb) following the MVP ([Model](/examples/snake/model/game.rb) / [View](/examples/snake.rb) / [Presenter](/examples/snake/presenter/grid.rb)) architectural pattern.
 
+Use arrows to move and spacebar to pause/resume.
+
 [examples/snake.rb](examples/snake.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -9049,7 +9416,7 @@ class Snake
     end
     
     Glimmer::LibUI.timer(SNAKE_MOVE_DELAY) do
-      unless @game.over?
+      unless @game.paused? || @game.over?
         process_queued_keypress
         @game.snake.move
       end
@@ -9090,7 +9457,11 @@ class Snake
                 }
                 
                 on_key_up do |area_key_event|
-                  @keypress_queue << area_key_event[:ext_key]
+                  if area_key_event[:key] == ' '
+                    @game.toggle_pause
+                  else
+                    @keypress_queue << area_key_event[:ext_key]
+                  end
                 end
               }
             end
@@ -9149,7 +9520,7 @@ class Snake
     end
     
     Glimmer::LibUI.timer(SNAKE_MOVE_DELAY) do
-      unless @game.over?
+      unless @game.paused? || @game.over?
         process_queued_keypress
         @game.snake.move
       end
@@ -9192,7 +9563,11 @@ class Snake
                 }
                 
                 on_key_up do |area_key_event|
-                  @keypress_queue << area_key_event[:ext_key]
+                  if area_key_event[:key] == ' '
+                    @game.toggle_pause
+                  else
+                    @keypress_queue << area_key_event[:ext_key]
+                  end
                 end
               }
             end
@@ -9226,7 +9601,7 @@ ruby -r glimmer-dsl-libui -e "require 'examples/tetris'"
 
 Mac | Windows | Linux
 ----|---------|------
-![glimmer-dsl-libui-mac-tetris.png](images/glimmer-dsl-libui-mac-tetris.png) ![glimmer-dsl-libui-mac-tetris-game-over.png](images/glimmer-dsl-libui-mac-tetris-game-over.png) ![glimmer-dsl-libui-mac-tetris-high-scores.png](images/glimmer-dsl-libui-mac-tetris-high-scores.png) | ![glimmer-dsl-libui-windows-tetris.png](images/glimmer-dsl-libui-windows-tetris.png) ![glimmer-dsl-libui-windows-tetris-game-over.png](images/glimmer-dsl-libui-windows-tetris-game-over.png) ![glimmer-dsl-libui-windows-tetris-high-scores.png](images/glimmer-dsl-libui-windows-tetris-high-scores.png) | ![glimmer-dsl-libui-linux-tetris.png](images/glimmer-dsl-libui-linux-tetris.png) ![glimmer-dsl-libui-linux-tetris-game-over.png](images/glimmer-dsl-libui-linux-tetris-game-over.png) ![glimmer-dsl-libui-linux-tetris-high-scores.png](images/glimmer-dsl-libui-linux-tetris-high-scores.png)
+![glimmer-dsl-libui-mac-tetris.png](images/glimmer-dsl-libui-mac-tetris.png) | ![glimmer-dsl-libui-windows-tetris.png](images/glimmer-dsl-libui-windows-tetris.png) | ![glimmer-dsl-libui-linux-tetris.png](images/glimmer-dsl-libui-linux-tetris.png)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
@@ -9304,18 +9679,31 @@ class Tetris
     
     Model::Game::PREVIEW_PLAYFIELD_HEIGHT.times do |row|
       Model::Game::PREVIEW_PLAYFIELD_WIDTH.times do |column|
-        observe(@game.preview_playfield[row][column], :color) do |new_color|
+        preview_updater = proc do
           Glimmer::LibUI.queue_main do
+            new_color = @game.preview_playfield[row][column].color
             color = Glimmer::LibUI.interpret_color(new_color)
             block = @preview_playfield_blocks[row][column]
-            block[:background_square].fill = color
-            block[:top_bevel_edge].fill = {r: color[:r] + 4*BEVEL_CONSTANT, g: color[:g] + 4*BEVEL_CONSTANT, b: color[:b] + 4*BEVEL_CONSTANT}
-            block[:right_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
-            block[:bottom_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
-            block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
-            block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
+            if @game.show_preview_tetromino?
+              block[:background_square].fill = color
+              block[:top_bevel_edge].fill = {r: color[:r] + 4*BEVEL_CONSTANT, g: color[:g] + 4*BEVEL_CONSTANT, b: color[:b] + 4*BEVEL_CONSTANT}
+              block[:right_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
+              block[:bottom_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
+              block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
+              block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
+            else
+              transparent_color = {r: 255, g: 255, b: 255, a: 0}
+              block[:background_square].fill = transparent_color
+              block[:top_bevel_edge].fill = transparent_color
+              block[:right_bevel_edge].fill = transparent_color
+              block[:bottom_bevel_edge].fill = transparent_color
+              block[:left_bevel_edge].fill = transparent_color
+              block[:border_square].stroke = transparent_color
+            end
           end
         end
+        observe(@game.preview_playfield[row][column], :color, &preview_updater)
+        observe(@game, :show_preview_tetromino, &preview_updater)
       end
     end
 
@@ -9363,6 +9751,12 @@ class Tetris
     }
     
     menu('View') {
+      check_menu_item('Show Next Block Preview') {
+        checked <=> [@game, :show_preview_tetromino]
+      }
+      
+      separator_menu_item
+      
       menu_item('Show High Scores') {
         on_clicked do
           show_high_scores
@@ -9374,18 +9768,20 @@ class Tetris
           @game.clear_high_scores!
         }
       }
+      
+      separator_menu_item
     }
 
     menu('Options') {
-      radio_menu_item('Instant Down on Up Arrow') { |r|
+      radio_menu_item('Instant Down on Up Arrow') {
         checked <=> [@game, :instant_down_on_up]
       }
       
-      radio_menu_item('Rotate Right on Up Arrow') { |r|
+      radio_menu_item('Rotate Right on Up Arrow') {
         checked <=> [@game, :rotate_right_on_up]
       }
       
-      radio_menu_item('Rotate Left on Up Arrow') { |r|
+      radio_menu_item('Rotate Left on Up Arrow') {
         checked <=> [@game, :rotate_left_on_up]
       }
     }
@@ -9432,7 +9828,7 @@ class Tetris
     block = {}
     bevel_pixel_size = 0.16 * block_size.to_f
     color = Glimmer::LibUI.interpret_color(Model::Block::COLOR_CLEAR)
-    area {
+    block[:area] = area {
       block[:background_square] = square(0, 0, block_size) {
         fill color
       }
@@ -9508,12 +9904,6 @@ class Tetris
   
   def score_board(block_size: , &extra_content)
     vertical_box {
-      horizontal_box {
-        label # filler
-        @preview_playfield_blocks = playfield(playfield_width: Model::Game::PREVIEW_PLAYFIELD_WIDTH, playfield_height: Model::Game::PREVIEW_PLAYFIELD_HEIGHT, block_size: block_size)
-        label # filler
-      }
-
       horizontal_box {
         label # filler
         grid {
@@ -9554,6 +9944,12 @@ class Tetris
         }
         label # filler
       }
+      
+      horizontal_box {
+        label # filler
+        @preview_playfield_blocks = playfield(playfield_width: Model::Game::PREVIEW_PLAYFIELD_WIDTH, playfield_height: Model::Game::PREVIEW_PLAYFIELD_HEIGHT, block_size: block_size)
+        label # filler
+      }
     
       extra_content&.call
     }
@@ -9593,7 +9989,7 @@ class Tetris
   
   def show_about_dialog
     Glimmer::LibUI.queue_main do
-      msg_box('About', 'Glimmer Tetris - Glimmer DSL for LibUI Example - Copyright (c) 2021 Andy Maleh')
+      msg_box('About', 'Glimmer Tetris - Glimmer DSL for LibUI Example - Copyright (c) 2021-2022 Andy Maleh')
     end
   end
 end
@@ -10103,6 +10499,10 @@ https://github.com/AndyObtiva/befunge98/tree/gui
 
 https://github.com/iraamaro/i3off-gtk-ruby
 
+### Chess
+
+https://github.com/mikeweber/chess
+
 ## Process
 
 [Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
@@ -10162,7 +10562,7 @@ Note that the latest development sometimes takes place in the [development](http
 
 [MIT](LICENSE.txt)
 
-Copyright (c) 2021 Andy Maleh
+Copyright (c) 2021-2022 Andy Maleh
 
 --