glimmer-dsl-libui 0.2.16 → 0.2.20

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.2.16
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.2.20
 ## 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)
@@ -112,31 +112,24 @@ window('Area Gallery', 400, 400) {
       fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
     }
     path { # declarative stable path
-      figure(100, 100) {
-        line(100, 400)
-        line(400, 100)
-        line(400, 400)
-
-        closed true
-      }
-
+      polygon(100, 100, 100, 400, 400, 100, 400, 400)
+      
       fill r: 202, g: 102, b: 104, a: 0.5
       stroke r: 0, g: 0, b: 0
     }
     path { # declarative stable path
-      figure(0, 0) {
-        bezier(200, 100, 100, 200, 400, 100)
-        bezier(300, 100, 100, 300, 100, 400)
-        bezier(100, 300, 300, 100, 400, 400)
-
-        closed true
-      }
+      polybezier(0, 0, 200, 100, 100, 200, 400, 100, 300, 100, 100, 300, 100, 400, 100, 300, 300, 100, 400, 400)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(400, 220, 180, 90, 90, false)
+      polyline(100, 100, 400, 100, 100, 400, 400, 400, 0, 0)
+    
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
+    path { # declarative stable path
+      arc(404, 216, 190, 90, 90, false)
 
       # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
       fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
@@ -148,9 +141,9 @@ window('Area Gallery', 400, 400) {
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
-    text(160, 40, 100) { # x, y, width
+    text(161, 40, 100) { # x, y, width
       string('Area Gallery') {
-        font family: 'Times', size: 14
+        font family: 'Arial', size: 14
         color :black
       }
     }
@@ -284,6 +277,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Draw Text](#basic-draw-text)
     - [Custom Draw Text](#custom-draw-text)
     - [Method-Based Custom Keyword](#method-based-custom-keyword)
+    - [Tetris](#tetris)
   - [Applications](#applications)
     - [Manga2PDF](#manga2pdf)
     - [Befunge98 GUI](#befunge98-gui)
@@ -376,7 +370,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.16'
+gem 'glimmer-dsl-libui', '~> 0.2.20'
 ```
 
 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.
@@ -452,7 +446,7 @@ These are all the supported keywords. Note that some keywords do not represent c
 Keyword(Args) | Properties | Listeners
 ------------- | ---------- | ---------
 `about_menu_item` | None | `on_clicked`
-`area` | None | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`, `on_key_event(area_key_event)`, `on_key_down(area_key_event)`, `on_key_up(area_key_event)`
+`area` | `auto_draw_enabled` | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`, `on_key_event(area_key_event)`, `on_key_down(area_key_event)`, `on_key_up(area_key_event)`
 `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)` | `x_center` (`Numeric`), `y_center` (`Numeric`), `radius` (`Numeric`), `start_angle` (`Numeric`), `sweep` (`Numeric`), `is_negative` (Boolean) | None
 `background_color_column(name as String)` | None | None
 `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)` | `c1_x` (`Numeric`), `c1_y` (`Numeric`), `c2_x` (`Numeric`), `c2_y` (`Numeric`), `end_x` (`Numeric`), `end_y` (`Numeric`) | None
@@ -462,6 +456,7 @@ Keyword(Args) | Properties | Listeners
 `checkbox_column(name as String)` | `editable` (Boolean) | None
 `checkbox_text_column(name as String)` | `editable` (Boolean), `editable_checkbox` (Boolean), `editable_text` (Boolean) | None
 `checkbox_text_color_column(name as String)` | `editable` (Boolean), `editable_checkbox` (Boolean), `editable_text` (Boolean) | None
+`check_menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
 `combobox` | `items` (`Array` of `String`), `selected` (`Integer`) | `on_selected`
 `color_button` | `color` (Array of `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float`), `red` as `Float`, `green` as `Float`, `blue` as `Float`, `alpha` as `Float` | `on_changed`
 `date_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`, `mday` as `Integer`, `mon` as `Integer`, `year` as `Integer`, `wday` as `Integer`, `yday` as `Integer`, `dst` as Boolean) | `on_changed`
@@ -484,7 +479,7 @@ Keyword(Args) | Properties | Listeners
 `line(x as Numeric, y as Numeric)` | `x` (`Numeric`), `y` (`Numeric`) | None
 `matrix(m11 = nil as Numeric, m12 = nil as Numeric, m21 = nil as Numeric, m22 = nil as Numeric, m31 = nil as Numeric, m32 = nil as Numeric)` | `m11` (`Numeric`), `m12` (`Numeric`), `m21` (`Numeric`), `m22` (`Numeric`), `m31` (`Numeric`), `m32` (`Numeric`) | None
 `menu(text as String)` | None | None
-`menu_item(text as String)` | `checked` (Boolean) | `on_clicked`
+`menu_item(text as String)` | None | `on_clicked`
 `message_box` (alias for `msg_box`; see for arguments) | None | None
 `message_box_error` (alias for `msg_box_error`; see for arguments) | None | None
 `multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
@@ -493,6 +488,9 @@ Keyword(Args) | Properties | Listeners
 `non_wrapping_multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `password_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
 `path(draw_fill_mode = :winding)` | `fill` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `stroke` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color), `:cap` as (`:round`, `:square`, `:flat`), `:join` as (`:miter`, `:round`, `:bevel`), `:thickness` as `Numeric`, `:miter_limit` as `Numeric`, `:dashes` as `Array` of `Numeric` ) | None
+`polygon(point_array as Array of Arrays of Numeric or Array of Numeric)` | `point_array` (`Array of Arrays of Numeric or Array of Numeric`) | None
+`polyline(point_array as Array of Arrays of Numeric or Array of Numeric)` | `point_array` (`Array of Arrays of Numeric or Array of Numeric`) | None
+`polybezier(point_array as Array of Arrays of Numeric or Array of Numeric)` | `point_array` (`Array of Arrays of Numeric or Array of Numeric`) | None
 `preferences_menu_item` | None | `on_clicked`
 `progress_bar` | `value` (`Numeric`) | None
 `progress_bar_column(name as String)` | None | None
@@ -500,6 +498,7 @@ Keyword(Args) | Properties | Listeners
 `radio_buttons` | `selected` (`Integer`) | `on_selected`
 `rectangle(x as Numeric, y as Numeric, width as Numeric, height as Numeric)` |  `x` (`Numeric`), `y` (`Numeric`), `width` (`Numeric`), `height` (`Numeric`) | None
 `search_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
+`separator_menu_item` | None | None
 `slider(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
 `spinbox(min as Numeric, max as Numeric)` | `value` (`Numeric`) | `on_changed`
 `square(x as Numeric, y as Numeric, length as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `length` (`Numeric`) | None
@@ -513,7 +512,7 @@ Keyword(Args) | Properties | Listeners
 `time_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`) | `on_changed`
 `vertical_box` | `padded` (Boolean) | None
 `vertical_separator` | None | None
-`window(title as String, width as Integer, height as Integer, has_menubar as Boolean)` | `borderless` (Boolean), `content_size` (width `Numeric`, height `Numeric`), `fullscreen` (Boolean), `margined` (Boolean), `title` (`String`) | `on_closing`, `on_content_size_changed`, `on_destroy`
+`window(title as String, width as Integer, height as Integer, has_menubar as Boolean)` | `borderless` (Boolean), `content_size` (width `Numeric`, height `Numeric`), `fullscreen` (Boolean), `margined` (Boolean), `title` (`String`), `resizable` (Boolean) | `on_closing`, `on_content_size_changed`, `on_destroy`
 
 ### Common Control Properties
 - `enabled` (Boolean)
@@ -744,6 +743,9 @@ Available nested `path` shapes:
 - `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)`
 - `line(x as Numeric, y as Numeric)`
 - `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)`
+- `polygon(point_array as Array of Arrays of Numeric or Array of Numeric)`: closed figure of lines; can receive points as [[x1, y1], [x2, y2], ...] or [x1, y1, x2, y2, ...]
+- `polyline(point_array as Array of Arrays of Numeric or Array of Numeric)`: open figure of lines; can receive points as [[x1, y1], [x2, y2], ...] or [x1, y1, x2, y2, ...]
+- `polybezier(point_array as Array of Arrays of Numeric or Array of Numeric)`: open figure of beziers; can receive points as [[start_x1, start_y1], [c1_x2, c1_y2, c2_x2, c2_y2, end_x2, end_y2], [c1_x3, c1_y3, c2_x3, c2_y3, end_x3, end_y3], ...] or [start_x1, start_y1, c1_x2, c1_y2, c2_x2, c2_y2, end_x2, end_y2, c1_x3, c1_y3, c2_x3, c2_y3, end_x3, end_y3, ...]
 - `figure(x=nil as Numeric, y=nil as Numeric)` (composite that can contain other shapes) (can set `closed true` to connect last point to first point automatically)
 
 Check [examples/area_gallery.rb](#area-gallery) for an overiew of all `path` shapes.
@@ -798,6 +800,12 @@ Note that when nesting an `area` directly underneath `window` (without a layout
 
 To redraw an `area`, you may call the `#queue_redraw_all` method, or simply `#redraw`.
 
+`area` has the following Glimmer-added API methods/attributes:
+- `request_auto_redraw`: requests auto redraw upon changes to nested stable `path` or shapes
+- `pause_auto_redraw`: pause auto redraw upon changes to nested stable `path` or shapes (useful to avoid too many micro-change redraws, to group all redraws as one after many micro-changes)
+- `resume_auto_redraw`: resume auto redraw upon changes to nested stable `path` or shapes
+- `auto_redraw_enabled`/`auto_redraw_enabled?`/`auto_redraw_enabled=`: an attribute to disable/enable auto redraw on an `area` upon changes to nested stable `path` or shapes
+
 A transform `matrix` can be set on a path by building a `matrix(m11 = nil, m12 = nil, m21 = nil, m22 = nil, m31 = nil, m32 = nil) {operations}` proxy object and then setting via `transform` property, or alternatively by building and setting the matrix in one call to `transform(m11 = nil, m12 = nil, m21 = nil, m22 = nil, m31 = nil, m32 = nil) {operations}` passing it the matrix arguments and/or content operations.
 
 When instantiating a `matrix` object, it always starts with identity matrix.
@@ -1076,6 +1084,7 @@ window('Method-Based Custom Keyword') {
 - `table` controls on Windows intentionally get an extra empty row at the end because if any row were to be deleted for the first time, double-deletion happens due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
 - `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.
 - 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.
 
 ### Original API
 
@@ -4057,31 +4066,24 @@ window('Area Gallery', 400, 400) {
       fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
     }
     path { # declarative stable path
-      figure(100, 100) {
-        line(100, 400)
-        line(400, 100)
-        line(400, 400)
-
-        closed true
-      }
-
+      polygon(100, 100, 100, 400, 400, 100, 400, 400)
+      
       fill r: 202, g: 102, b: 104, a: 0.5
       stroke r: 0, g: 0, b: 0
     }
     path { # declarative stable path
-      figure(0, 0) {
-        bezier(200, 100, 100, 200, 400, 100)
-        bezier(300, 100, 100, 300, 100, 400)
-        bezier(100, 300, 300, 100, 400, 400)
-
-        closed true
-      }
+      polybezier(0, 0, 200, 100, 100, 200, 400, 100, 300, 100, 100, 300, 100, 400, 100, 300, 300, 100, 400, 400)
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
     path { # declarative stable path
-      arc(400, 220, 180, 90, 90, false)
+      polyline(100, 100, 400, 100, 100, 400, 400, 400, 0, 0)
+    
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
+    path { # declarative stable path
+      arc(404, 216, 190, 90, 90, false)
 
       # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
       fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
@@ -4093,9 +4095,9 @@ window('Area Gallery', 400, 400) {
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
-    text(160, 40, 100) { # x, y, width
+    text(161, 40, 100) { # x, y, width
       string('Area Gallery') {
-        font family: 'Times', size: 14
+        font family: 'Arial', size: 14
         color :black
       }
     }
@@ -4244,18 +4246,42 @@ window('Area Gallery', 400, 400) {
           end_x 400
           end_y 400
         }
-
-        closed true
       }
 
       fill r: 202, g: 102, b: 204, a: 0.5
       stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
     }
+    path { # declarative stable path
+      polyline(100, 100, 400, 100, 100, 400, 400, 400, 0, 0)
+      figure {
+        x 100
+        y 100
+        
+        line {
+          x 400
+          y 100
+        }
+        line {
+          x 100
+          y 400
+        }
+        line {
+          x 400
+          y 400
+        }
+        line {
+          x 0
+          y 0
+        }
+      }
+    
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
     path { # declarative stable path
       arc {
-        x_center 400
-        y_center 220
-        radius 180
+        x_center 404
+        y_center 216
+        radius 190
         start_angle 90
         sweep 90
         is_negative false
@@ -4276,12 +4302,12 @@ window('Area Gallery', 400, 400) {
       stroke r: 0, g: 0, b: 0, thickness: 2
     }
     text {
-      x 160
+      x 161
       y 40
       width 100
       
       string {
-        font family: 'Times', size: 14
+        font family: 'Arial', size: 14
         color :black
         
         'Area Gallery'
@@ -4352,42 +4378,35 @@ window('Area Gallery', 400, 400) {
       path { # a dynamic path is added semi-declaratively inside on_draw block
         square(0, 0, 100)
         square(100, 100, 400)
-        
+  
         fill r: 102, g: 102, b: 204
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
         rectangle(0, 100, 100, 400)
         rectangle(100, 0, 400, 100)
-
+  
         # linear gradient (has x0, y0, x1, y1, and stops)
         fill x0: 10, y0: 10, x1: 350, y1: 350, stops: [{pos: 0.25, r: 204, g: 102, b: 204}, {pos: 0.75, r: 102, g: 102, b: 204}]
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        figure(100, 100) {
-          line(100, 400)
-          line(400, 100)
-          line(400, 400)
-
-          closed true
-        }
-
+        polygon(100, 100, 100, 400, 400, 100, 400, 400)
+        
         fill r: 202, g: 102, b: 104, a: 0.5
         stroke r: 0, g: 0, b: 0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        figure(0, 0) {
-          bezier(200, 100, 100, 200, 400, 100)
-          bezier(300, 100, 100, 300, 100, 400)
-          bezier(100, 300, 300, 100, 400, 400)
-
-          closed true
-        }
-
+        polybezier(0, 0, 200, 100, 100, 200, 400, 100, 300, 100, 100, 300, 100, 400, 100, 300, 300, 100, 400, 400)
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
       path { # a dynamic path is added semi-declaratively inside on_draw block
-        arc(400, 220, 180, 90, 90, false)
+        polyline(100, 100, 400, 100, 100, 400, 400, 400, 0, 0)
+      
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        arc(404, 216, 190, 90, 90, false)
   
         # radial gradient (has an outer_radius in addition to x0, y0, x1, y1, and stops)
         fill outer_radius: 90, x0: 0, y0: 0, x1: 500, y1: 500, stops: [{pos: 0.25, r: 102, g: 102, b: 204, a: 0.5}, {pos: 0.75, r: 204, g: 102, b: 204}]
@@ -4399,9 +4418,9 @@ window('Area Gallery', 400, 400) {
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
-      text(160, 40, 100) { # x, y, width
+      text(161, 40, 100) { # x, y, width
         string('Area Gallery') {
-          font family: 'Times', size: 14
+          font family: 'Arial', size: 14
           color :black
         }
       }
@@ -4516,10 +4535,10 @@ window('Area Gallery', 400, 400) {
             x 400
             y 400
           }
-
+  
           closed true
         }
-
+  
         fill r: 202, g: 102, b: 104, a: 0.5
         stroke r: 0, g: 0, b: 0
       }
@@ -4552,18 +4571,42 @@ window('Area Gallery', 400, 400) {
             end_x 400
             end_y 400
           }
-
-          closed true
         }
-
+  
         fill r: 202, g: 102, b: 204, a: 0.5
         stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        polyline(100, 100, 400, 100, 100, 400, 400, 400, 0, 0)
+        figure {
+          x 100
+          y 100
+          
+          line {
+            x 400
+            y 100
+          }
+          line {
+            x 100
+            y 400
+          }
+          line {
+            x 400
+            y 400
+          }
+          line {
+            x 0
+            y 0
+          }
+        }
+      
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
       path { # a dynamic path is added semi-declaratively inside on_draw block
         arc {
-          x_center 400
-          y_center 220
-          radius 180
+          x_center 404
+          y_center 216
+          radius 190
           start_angle 90
           sweep 90
           is_negative false
@@ -4584,12 +4627,12 @@ window('Area Gallery', 400, 400) {
         stroke r: 0, g: 0, b: 0, thickness: 2
       }
       text {
-        x 160
+        x 161
         y 40
         width 100
         
         string {
-          font family: 'Times', size: 14
+          font family: 'Arial', size: 14
           color :black
           
           'Area Gallery'
@@ -4906,20 +4949,13 @@ end
 
 # method-based custom control representing a graph path
 def graph_path(width, height, should_extend, &block)
-  locations = point_locations(width, height)
+  locations = point_locations(width, height).flatten
   path {
-    first_location = locations[0] # x and y
-    figure(first_location[0], first_location[1]) {
-      locations.each do |loc|
-        line(loc[0], loc[1])
-      end
-      if should_extend
-        line(width, height)
-        line(0, height)
-        
-        closed true
-      end
-    }
+    if should_extend
+      polygon(locations + [width, height, 0, height])
+    else
+      polyline(locations)
+    end
     
     # apply a transform to the coordinate space for this path so (0, 0) is the top-left corner of the graph
     transform {
@@ -6198,6 +6234,391 @@ window('Method-Based Custom Keyword') {
 }.show
 ```
 
+### Tetris
+
+Glimmer Tetris utilizes many small areas to represent Tetromino blocks because this ensures smaller redraws per tetromino block color change, thus higher performance than having one area that gets redrawn on every little change.
+
+[examples/tetris.rb](examples/tetris.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/tetris.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/tetris'"
+```
+
+Mac
+
+![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)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+require_relative 'tetris/model/game'
+
+class Tetris
+  include Glimmer
+  
+  BLOCK_SIZE = 25
+  BEVEL_CONSTANT = 20
+  COLOR_GRAY = {r: 192, g: 192, b: 192}
+    
+  def initialize
+    @game = Model::Game.new
+  end
+  
+  def launch
+    create_gui
+    register_observers
+    @game.start!
+    @main_window.show
+  end
+  
+  def create_gui
+    menu_bar
+    
+    @main_window = window('Glimmer Tetris') {
+      content_size Model::Game::PLAYFIELD_WIDTH * BLOCK_SIZE, Model::Game::PLAYFIELD_HEIGHT * BLOCK_SIZE + 98
+      resizable false
+      
+      vertical_box {
+        label { # filler
+          stretchy false
+        }
+        
+        score_board(block_size: BLOCK_SIZE) {
+          stretchy false
+        }
+        
+        @playfield_blocks = playfield(playfield_width: Model::Game::PLAYFIELD_WIDTH, playfield_height: Model::Game::PLAYFIELD_HEIGHT, block_size: BLOCK_SIZE)
+      }
+    }
+  end
+  
+  def register_observers
+    Glimmer::DataBinding::Observer.proc do |game_over|
+      if game_over
+        @pause_menu_item.enabled = false
+        show_game_over_dialog
+      else
+        @pause_menu_item.enabled = true
+        start_moving_tetrominos_down
+      end
+    end.observe(@game, :game_over)
+    
+    Model::Game::PLAYFIELD_HEIGHT.times do |row|
+      Model::Game::PLAYFIELD_WIDTH.times do |column|
+        Glimmer::DataBinding::Observer.proc do |new_color|
+          Glimmer::LibUI.queue_main do
+            color = Glimmer::LibUI.interpret_color(new_color)
+            block = @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
+          end
+        end.observe(@game.playfield[row][column], :color)
+      end
+    end
+    
+    Model::Game::PREVIEW_PLAYFIELD_HEIGHT.times do |row|
+      Model::Game::PREVIEW_PLAYFIELD_WIDTH.times do |column|
+        Glimmer::DataBinding::Observer.proc do |new_color|
+          Glimmer::LibUI.queue_main do
+            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
+          end
+        end.observe(@game.preview_playfield[row][column], :color)
+      end
+    end
+
+    Glimmer::DataBinding::Observer.proc do |new_score|
+      Glimmer::LibUI.queue_main do
+        @score_label.text = new_score.to_s
+      end
+    end.observe(@game, :score)
+
+    Glimmer::DataBinding::Observer.proc do |new_lines|
+      Glimmer::LibUI.queue_main do
+        @lines_label.text = new_lines.to_s
+      end
+    end.observe(@game, :lines)
+
+    Glimmer::DataBinding::Observer.proc do |new_level|
+      Glimmer::LibUI.queue_main do
+        @level_label.text = new_level.to_s
+      end
+    end.observe(@game, :level)
+  end
+  
+  def menu_bar
+    menu('Game') {
+      @pause_menu_item = check_menu_item('Pause') {
+        enabled false
+        
+        on_clicked do
+          @game.paused = @pause_menu_item.checked?
+        end
+      }
+      menu_item('Restart') {
+        on_clicked do
+          @game.restart!
+        end
+      }
+      separator_menu_item
+      menu_item('Exit') {
+        on_clicked do
+          exit(0)
+        end
+      }
+      quit_menu_item if OS.mac?
+    }
+    
+    menu('View') {
+      menu_item('Show High Scores') {
+        on_clicked do
+          show_high_scores
+        end
+      }
+      menu_item('Clear High Scores') {
+        on_clicked {
+          @game.clear_high_scores!
+        }
+      }
+    }
+
+    menu('Options') {
+      radio_menu_item('Instant Down on Up Arrow') {
+        on_clicked do
+          @game.instant_down_on_up = true
+        end
+      }
+      radio_menu_item('Rotate Right on Up Arrow') {
+        on_clicked do
+          @game.rotate_right_on_up = true
+        end
+      }
+      radio_menu_item('Rotate Left on Up Arrow') {
+        on_clicked do
+          @game.rotate_left_on_up = true
+        end
+      }
+    }
+
+    menu('Help') {
+      if OS.mac?
+        about_menu_item {
+          on_clicked do
+            show_about_dialog
+          end
+        }
+      end
+      menu_item('About') {
+        on_clicked do
+          show_about_dialog
+        end
+      }
+    }
+  end
+  
+  def playfield(playfield_width: , playfield_height: , block_size: , &extra_content)
+    blocks = []
+    vertical_box {
+      padded false
+      
+      playfield_height.times.map do |row|
+        blocks << []
+        horizontal_box {
+          padded false
+          
+          playfield_width.times.map do |column|
+            blocks.last << block(row: row, column: column, block_size: block_size)
+          end
+        }
+      end
+      
+      extra_content&.call
+    }
+    blocks
+  end
+  
+  def block(row: , column: , block_size: , &extra_content)
+    block = {}
+    bevel_pixel_size = 0.16 * block_size.to_f
+    color = Glimmer::LibUI.interpret_color(Model::Block::COLOR_CLEAR)
+    area {
+      block[:background_square] = path {
+        square(0, 0, block_size)
+        
+        fill color
+      }
+      block[:top_bevel_edge] = path {
+        polygon(0, 0, block_size, 0, block_size - bevel_pixel_size, bevel_pixel_size, bevel_pixel_size, bevel_pixel_size)
+  
+        fill r: color[:r] + 4*BEVEL_CONSTANT, g: color[:g] + 4*BEVEL_CONSTANT, b: color[:b] + 4*BEVEL_CONSTANT
+      }
+      block[:right_bevel_edge] = path {
+        polygon(block_size, 0, block_size - bevel_pixel_size, bevel_pixel_size, block_size - bevel_pixel_size, block_size - bevel_pixel_size, block_size, block_size)
+  
+        fill r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT
+      }
+      block[:bottom_bevel_edge] = path {
+        polygon(block_size, block_size, 0, block_size, bevel_pixel_size, block_size - bevel_pixel_size, block_size - bevel_pixel_size, block_size - bevel_pixel_size)
+  
+        fill r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT
+      }
+      block[:left_bevel_edge] = path {
+        polygon(0, 0, 0, block_size, bevel_pixel_size, block_size - bevel_pixel_size, bevel_pixel_size, bevel_pixel_size)
+  
+        fill r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT
+      }
+      block[:border_square] = path {
+        square(0, 0, block_size)
+  
+        stroke COLOR_GRAY
+      }
+      
+      on_key_down do |key_event|
+        case key_event
+        in ext_key: :down
+          @game.down!
+        in key: ' '
+          @game.down!(instant: true)
+        in ext_key: :up
+          case @game.up_arrow_action
+          when :instant_down
+            @game.down!(instant: true)
+          when :rotate_right
+            @game.rotate!(:right)
+          when :rotate_left
+            @game.rotate!(:left)
+          end
+        in ext_key: :left
+          @game.left!
+        in ext_key: :right
+          @game.right!
+        in modifier: :shift
+          @game.rotate!(:right)
+        in modifier: :control
+          @game.rotate!(:left)
+        else
+          # Do Nothing
+        end
+      end
+      
+      extra_content&.call
+    }
+    block
+  end
+  
+  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 {
+          stretchy false
+          
+          label('Score') {
+            left 0
+            top 0
+            halign :fill
+          }
+          @score_label = label {
+            left 0
+            top 1
+            halign :center
+          }
+    
+          label('Lines') {
+            left 1
+            top 0
+            halign :fill
+          }
+          @lines_label = label {
+            left 1
+            top 1
+            halign :center
+          }
+    
+          label('Level') {
+            left 2
+            top 0
+            halign :fill
+          }
+          @level_label = label {
+            left 2
+            top 1
+            halign :center
+          }
+        }
+        label # filler
+      }
+    
+      extra_content&.call
+    }
+  end
+  
+  def start_moving_tetrominos_down
+    Glimmer::LibUI.timer(@game.delay) do
+      @game.down! if !@game.game_over? && !@game.paused?
+    end
+  end
+  
+  def show_game_over_dialog
+    Glimmer::LibUI.queue_main do
+      msg_box('Game Over!', "Score: #{@game.high_scores.first.score}\nLines: #{@game.high_scores.first.lines}\nLevel: #{@game.high_scores.first.level}")
+      @game.restart!
+    end
+  end
+  
+  def show_high_scores
+    Glimmer::LibUI.queue_main do
+      if @game.high_scores.empty?
+        high_scores_string = "No games have been scored yet."
+      else
+        high_scores_string = @game.high_scores.map do |high_score|
+          "#{high_score.name} | Score: #{high_score.score} | Lines: #{high_score.lines} | Level: #{high_score.level}"
+        end.join("\n")
+      end
+      msg_box('High Scores', high_scores_string)
+    end
+  end
+  
+  def show_about_dialog
+    Glimmer::LibUI.queue_main do
+      msg_box('About', 'Glimmer Tetris - Glimmer DSL for LibUI Example - Copyright (c) 2021 Andy Maleh')
+    end
+  end
+end
+
+Tetris.new.launch
+```
+
 ## Applications
 
 Here are some applications built with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)