glimmer-dsl-libui 0.2.21 → 0.3.0

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.21
+# [<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.3.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)
@@ -143,7 +143,7 @@ window('Area Gallery', 400, 400) {
     }
     text(161, 40, 100) { # x, y, width
       string('Area Gallery') {
-        font family: 'Arial', size: 14
+        font family: 'Arial', size: (OS.mac? ? 14 : 11)
         color :black
       }
     }
@@ -218,9 +218,10 @@ NOTE: [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) is fe
 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
-- [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (MRI Ruby Desktop Development GUI Library)
 
 ## Table of Contents
 
@@ -237,6 +238,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Extra Operations](#extra-operations)
     - [Table API](#table-api)
     - [Area API](#area-api)
+      - [Image Glimmer Custom Control](#image-glimmer-custom-control)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
     - [Custom Keywords](#custom-keywords)
     - [API Gotchas](#api-gotchas)
@@ -269,6 +271,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Basic Area](#basic-area)
     - [Dynamic Area](#dynamic-area)
     - [Area Gallery](#area-gallery)
+    - [Basic Image](#basic-image)
     - [Histogram](#histogram)
     - [Basic Transform](#basic-transform)
     - [Login](#login)
@@ -279,6 +282,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Method-Based Custom Keyword](#method-based-custom-keyword)
     - [Tetris](#tetris)
     - [Tic Tac Toe](#tic-tac-toe)
+    - [Snake](#snake)
   - [Applications](#applications)
     - [Manga2PDF](#manga2pdf)
     - [Befunge98 GUI](#befunge98-gui)
@@ -371,7 +375,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.21'
+gem 'glimmer-dsl-libui', '~> 0.3.0'
 ```
 
 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.
@@ -471,7 +475,7 @@ Keyword(Args) | Properties | Listeners
 `group(text as String)` | `margined` (Boolean), `title` (`String`) | None
 `horizontal_box` | `padded` (Boolean) | None
 `horizontal_separator` | None | None
-`image(width as Numeric, height as Numeric)` | None | None
+`image(file as String = nil, width as Numeric = nil, height as Numeric = nil)` | None | None
 `image_part(pixels as String [encoded image rgba byte array], width as Numeric, height as Numeric, byte_stride as Numeric [usually width*4])` | None | None
 `image_column(name as String)` | None | None
 `image_text_column(name as String)` | None | None
@@ -550,8 +554,8 @@ There are additional useful `Glimmer::LibUI` operations that are not found in `L
 - `Glimmer::LibUI::integer_to_boolean(int, allow_nil: true)`
 - `Glimmer::LibUI::boolean_to_integer(int, allow_nil: true)`
 - `Glimmer::LibUI::degrees_to_radians(degrees)`
-- `Glimmer::LibUI::interpret_color(value)`: interprets a color in any form like `String`, `Symbol`, or hex into an rgb `Hash`
-- `Glimmer::LibUI::hex_to_rgb(value)`: converts a hex color to an rgb `Hash`
+- `Glimmer::LibUI::interpret_color(value)`: interprets a color in any form like `String`, `Symbol`, or hex into an rgb `Hash` (including `0x1f3b5d`, `'0x1f3b5d'`, `'#1f3b5d'`, and 3-char hex-shorthand variations)
+- `Glimmer::LibUI::hex_to_rgb(value)`: converts a hex color to an rgb `Hash` (including `0x1f3b5d`, `'0x1f3b5d'`, `'#1f3b5d'`, and 3-char hex-shorthand variations)
 - `Glimmer::LibUI::enum_names`: provides all possible enum names to use with `Glimmer::LibUI::enum_symbols(enum_name)`
 - `Glimmer::LibUI::enum_symbols(enum_name)`: returns all possible values for an enum. `enum_name` can be:
   - `:draw_brush_type`: `[:solid, :linear_gradient, :radial_gradient, :image]`
@@ -899,9 +903,11 @@ transform m1
 # and then reuse m1 elsewhere too
 ```
 
+You can set a `matrix`/`transform` on `area` directly to conveniently apply to all nested `path`s too.
+
 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.
 
-`fill` and `stroke` accept [X11](https://en.wikipedia.org/wiki/X11_color_names) color `Symbol`s/`String`s like `:skyblue` and `'sandybrown'` or 6-number hex or 3-number hex-shorthand (as `Integer` or `String` with or without `0x` prefix)
+`fill` and `stroke` accept [X11](https://en.wikipedia.org/wiki/X11_color_names) color `Symbol`s/`String`s like `:skyblue` and `'sandybrown'` or 6-char hex or 3-char hex-shorthand (as `Integer` or `String` with or without `0x` prefix)
 
 Available [X11 colors](https://en.wikipedia.org/wiki/X11_color_names) can be obtained through `Glimmer::LibUI.x11_colors` method.
 
@@ -958,6 +964,172 @@ window('area text drawing') {
 }.show
 ```
 
+#### Image Glimmer Custom Control
+
+**(ALPHA FEATURE)**
+
+[libui](https://github.com/andlabs/libui) does not support `image` rendering outside of `table` yet.
+However, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) adds a special `image` custom control that renders an image unto an `area` pixel by pixel (and when possible to optimize, line by line).
+
+Given that it is not a [libui](https://github.com/andlabs/libui)-native control, please keep these notes in mind:
+- [libui](https://github.com/andlabs/libui) pixel-by-pixel rendering performance is slow
+- Including an `image` inside an `area` `on_draw` listener improves performance due to not retaining pixel/line data in memory.
+- Supplying `width` and `height` (2nd and 3rd arguments) greatly improves performance when shrinking image
+
+Currently, it is recommended to use `image` with very small `width` and `height` values only.
+
+Setting a `transform` `matrix` is supported under `image` just like it is under `path` and `text` inside `area`.
+
+Example of using `image` declaratively (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+![Basic Image](/images/glimmer-dsl-libui-mac-basic-image.png)
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    image(File.expand_path('icons/glimmer.png', __dir__), 96, 96)
+  }
+}.show
+```
+
+Example of better performance via `on_draw` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      image(File.expand_path('icons/glimmer.png', __dir__), 96, 96)
+    end
+  }
+}.show
+```
+
+Example of using `image` declaratively with explicit properties (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    image {
+      file File.expand_path('icons/glimmer.png', __dir__)
+      width 96
+      height 96
+    }
+  }
+}.show
+```
+
+Example of better performance via `on_draw` with explicit properties (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      image {
+        file File.expand_path('icons/glimmer.png', __dir__)
+        width 96
+        height 96
+      }
+    end
+  }
+}.show
+```
+
+If you need to render an image pixel by pixel (e.g. to support a format other than `.png`) for very exceptional scenarios, you may use this example as a guide, including a line-merge optimization for neighboring horizontal pixels with the same color:
+
+```ruby
+# This is the manual way of rendering an image unto an area control.
+# It could come in handy in special situations.
+# Otherwise, it is recommended to simply utilize the `image` control that
+# can be nested under area or area on_draw listener to automate all this work.
+
+require 'glimmer-dsl-libui'
+require 'chunky_png'
+
+include Glimmer
+
+puts 'Parsing image...'; $stdout.flush
+
+f = File.open(File.expand_path('icons/glimmer.png', __dir__))
+canvas = ChunkyPNG::Canvas.from_io(f)
+f.close
+canvas.resample_nearest_neighbor!(96, 96)
+data = canvas.to_rgba_stream
+width = canvas.width
+height = canvas.height
+puts "Image width: #{width}"
+puts "Image height: #{height}"
+
+puts 'Parsing colors...'; $stdout.flush
+
+color_maps = height.times.map do |y|
+  width.times.map do |x|
+    r = data[(y*width + x)*4].ord
+    g = data[(y*width + x)*4 + 1].ord
+    b = data[(y*width + x)*4 + 2].ord
+    a = data[(y*width + x)*4 + 3].ord
+    {x: x, y: y, color: {r: r, g: g, b: b, a: a}}
+  end
+end.flatten
+puts "#{color_maps.size} pixels to render..."; $stdout.flush
+
+puts 'Parsing shapes...'; $stdout.flush
+
+shape_maps = []
+original_color_maps = color_maps.dup
+indexed_original_color_maps = Hash[original_color_maps.each_with_index.to_a]
+color_maps.each do |color_map|
+  index = indexed_original_color_maps[color_map]
+  @rectangle_start_x ||= color_map[:x]
+  @rectangle_width ||= 1
+  if color_map[:x] < width - 1 && color_map[:color] == original_color_maps[index + 1][:color]
+    @rectangle_width += 1
+  else
+    if color_map[:x] > 0 && color_map[:color] == original_color_maps[index - 1][:color]
+      shape_maps << {x: @rectangle_start_x, y: color_map[:y], width: @rectangle_width, height: 1, color: color_map[:color]}
+    else
+      shape_maps << {x: color_map[:x], y: color_map[:y], width: 1, height: 1, color: color_map[:color]}
+    end
+    @rectangle_width = 1
+    @rectangle_start_x = color_map[:x] == width - 1 ? 0 : color_map[:x] + 1
+  end
+end
+puts "#{shape_maps.size} shapes to render..."; $stdout.flush
+
+puts 'Rendering image...'; $stdout.flush
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      shape_maps.each do |shape_map|
+        path {
+          rectangle(shape_map[:x], shape_map[:y], shape_map[:width], shape_map[:height])
+
+          fill shape_map[:color]
+        }
+      end
+    end
+  }
+}.show
+```
+
+Check out [examples/basic_image.rb](#basic-image) (all versions) for examples of using `image` Glimmer custom control.
+
 ### 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
@@ -980,7 +1152,7 @@ window('area text drawing') {
 - When destroying a control nested under a `form`, it is automatically deleted from the form's children
 - When destroying a control nested under a `window` or `group`, it is automatically unset as their child to allow successful destruction
 - For `date_time_picker`, `date_picker`, and `time_picker`, make sure `time` hash values for `mon`, `wday`, and `yday` are 1-based instead of [libui](https://github.com/andlabs/libui) original 0-based values, and return `dst` as Boolean instead of `isdst` as `1`/`0`
-- Smart defaults for `grid` child attributes are `left` (`0`), `top` (`0`), `xspan` (`1`), `yspan` (`1`), `hexpand` (`false`), `halign` (`:fill`), `vexpand` (`false`), and `valign` (`:fill`)
+- Smart defaults for `grid` child properties are `left` (`0`), `top` (`0`), `xspan` (`1`), `yspan` (`1`), `hexpand` (`false`), `halign` (`:fill`), `vexpand` (`false`), and `valign` (`:fill`)
 - The `table` control automatically constructs required `TableModelHandler`, `TableModel`, and `TableParams`, calculating all their arguments from `cell_rows` and `editable` properties (e.g. `NumRows`) as well as nested columns (e.g. `text_column`)
 - Table model instances are automatically freed from memory after `window` is destroyed.
 - Table `cell_rows` data has implicit data-binding to table cell values for deletion, insertion, and change (done by diffing `cell_rows` value before and after change and auto-informing `table` of deletions [`LibUI.table_model_row_deleted`], insertions [`LibUI.table_model_row_deleted`], and changes [`LibUI.table_model_row_changed`]). When deleting data rows from `cell_rows` array, then actual rows from the `table` are automatically deleted. When inserting data rows into `cell_rows` array, then actual `table` rows are automatically inserted. When updating data rows in `cell_rows` array, then actual `table` rows are automatically updated.
@@ -994,7 +1166,7 @@ window('area text drawing') {
 - All controls are protected from garbage collection until no longer needed (explicitly destroyed), so there is no need to worry about surprises.
 - All resources are freed automatically once no longer needed or left to garbage collection.
 - When nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
-- Colors may be passed in as a hash of `:r`, `:g`, `:b`, `:a`, or `:red`, `:green`, `:blue`, `:alpha`, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color like `:skyblue`, or 6-number hex or 3-number hex (as `Integer` or `String` with or without `0x` prefix)
+- Colors may be passed in as a hash of `:r`, `:g`, `:b`, `:a`, or `:red`, `:green`, `:blue`, `:alpha`, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color like `:skyblue`, or 6-char hex or 3-char hex (as `Integer` or `String` with or without `0x` prefix)
 - Color alpha value defaults to `1.0` when not specified.
 
 ### Custom Keywords
@@ -1221,7 +1393,7 @@ class MetaExample
   
   def run_example(example)
     Thread.new do
-      command = "ruby -r #{glimmer_dsl_libui_file} #{example} 2>&1"
+      command = "#{RbConfig.ruby} -r #{glimmer_dsl_libui_file} #{example} 2>&1"
       result = ''
       IO.popen(command) do |f|
         sleep(0.0001) # yield to main thread
@@ -1758,11 +1930,11 @@ class TinyMidiPlayer
 
       UI.new_horizontal_box.tap do |hbox|
         UI.new_vertical_box.tap do |vbox|
-          UI.new_button('▶').tap do |button1|
+          UI.new_button('â–¶').tap do |button1|
             UI.button_on_clicked(button1) { play_midi }
             UI.box_append(vbox, button1, 1)
           end
-          UI.new_button('■').tap do |button2|
+          UI.new_button('â– ').tap do |button2|
             UI.button_on_clicked(button2) { stop_midi }
             UI.box_append(vbox, button2, 1)
           end
@@ -1856,12 +2028,12 @@ class TinyMidiPlayer
         vertical_box {
           stretchy false
           
-          button('▶') {
+          button('â–¶') {
             on_clicked do
               play_midi
             end
           }
-          button('■') {
+          button('â– ') {
             on_clicked do
               stop_midi
             end
@@ -2992,13 +3164,7 @@ window('Editable column animal sounds', 400, 200) {
 
 ### Basic Table Image
 
-This example requires pre-installing `chunky_png` Ruby gem:
-
-```
-gem install chunky_png -v1.4.0
-```
-
-Also, note that behavior varies per platform (i.e. how `table` chooses to size images by default).
+Note that behavior varies per platform (i.e. how `table` chooses to size images by default).
 
 [examples/basic_table_image.rb](examples/basic_table_image.rb)
 
@@ -3154,13 +3320,7 @@ window('The Red Turtle', 310, 350, false) {
 
 ### Basic Table Image Text
 
-This example has a prerequisite of installing `chunky_png` Ruby gem:
-
-```
-gem install chunky_png -v1.4.0
-```
-
-Also, note that behavior varies per platform (i.e. how `table` chooses to size images by default).
+Note that behavior varies per platform (i.e. how `table` chooses to size images by default).
 
 [examples/basic_table_image_text.rb](examples/basic_table_image_text.rb)
 
@@ -3480,12 +3640,6 @@ window('Task Progress', 300, 200) {
 
 ### Basic Table Color
 
-This example requires pre-installing `chunky_png` Ruby gem:
-
-```
-gem install chunky_png -v1.4.0
-```
-
 [examples/basic_table_color.rb](examples/basic_table_color.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -4127,7 +4281,7 @@ window('Area Gallery', 400, 400) {
     }
     text(161, 40, 100) { # x, y, width
       string('Area Gallery') {
-        font family: 'Arial', size: 14
+        font family: 'Arial', size: (OS.mac? ? 14 : 11)
         color :black
       }
     }
@@ -4337,7 +4491,7 @@ window('Area Gallery', 400, 400) {
       width 100
       
       string {
-        font family: 'Arial', size: 14
+        font family: 'Arial', size: (OS.mac? ? 14 : 11)
         color :black
         
         'Area Gallery'
@@ -4450,7 +4604,7 @@ window('Area Gallery', 400, 400) {
       }
       text(161, 40, 100) { # x, y, width
         string('Area Gallery') {
-          font family: 'Arial', size: 14
+          font family: 'Arial', size: (OS.mac? ? 14 : 11)
           color :black
         }
       }
@@ -4662,7 +4816,7 @@ window('Area Gallery', 400, 400) {
         width 100
         
         string {
-          font family: 'Arial', size: 14
+          font family: 'Arial', size: (OS.mac? ? 14 : 11)
           color :black
           
           'Area Gallery'
@@ -4721,6 +4875,196 @@ window('Area Gallery', 400, 400) {
 }.show
 ```
 
+### Basic Image
+
+[examples/basic_image.rb](examples/basic_image.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_image.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/basic_image'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-image.png](images/glimmer-dsl-libui-mac-basic-image.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    # image is not a real LibUI control. It is built in Glimmer as a custom control that renders
+    # tiny pixels/lines as rectangle paths. As such, it does not have good performance, but can
+    # be used in exceptional circumstances where an image control is really needed.
+    #
+    # Furthermore, adding image directly under area is even slower due to taking up more memory for every
+    # image pixel rendered. Check basic_image2.rb for a faster alternative using on_draw manually.
+    #
+    # It is recommended to pass width/height args to shrink image and achieve faster performance.
+    image(File.expand_path('../icons/glimmer.png', __dir__), 96, 96)
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (better performance via `on_draw`):
+
+```ruby
+# frozen_string_literal: true
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      image(File.expand_path('../icons/glimmer.png', __dir__), 96, 96)
+    end
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (explicit properties):
+
+```ruby
+# frozen_string_literal: true
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    # image is not a real LibUI control. It is built in Glimmer as a custom control that renders
+    # tiny pixels/lines as rectangle paths. As such, it does not have good performance, but can
+    # be used in exceptional circumstances where an image control is really needed.
+    #
+    # Furthermore, adding image directly under area is even slower due to taking up more memory for every
+    # image pixel rendered. Check basic_image4.rb for a faster alternative using on_draw manually.
+    #
+    # It is recommended to pass width/height args to shrink image and achieve faster performance.
+    image {
+      file File.expand_path('../icons/glimmer.png', __dir__)
+      width 96
+      height 96
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 4 (better performance with `on_draw` when setting explicit properties):
+
+```ruby
+# frozen_string_literal: true
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      image {
+        file File.expand_path('../icons/glimmer.png', __dir__)
+        width 96
+        height 96
+      }
+    end
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 5 (fully manual pixel-by-pixel rendering):
+
+```ruby
+# frozen_string_literal: true
+
+# This is the manual way of rendering an image unto an area control.
+# It could come in handy in special situations.
+# Otherwise, it is recommended to simply utilize the `image` control that
+# can be nested under area or area on_draw listener to automate all this work.
+
+require 'glimmer-dsl-libui'
+require 'chunky_png'
+
+include Glimmer
+
+puts 'Parsing image...'; $stdout.flush
+
+f = File.open(File.expand_path('../icons/glimmer.png', __dir__))
+canvas = ChunkyPNG::Canvas.from_io(f)
+f.close
+canvas.resample_nearest_neighbor!(96, 96)
+data = canvas.to_rgba_stream
+width = canvas.width
+height = canvas.height
+puts "Image width: #{width}"
+puts "Image height: #{height}"
+
+puts 'Parsing colors...'; $stdout.flush
+
+color_maps = height.times.map do |y|
+  width.times.map do |x|
+    r = data[(y*width + x)*4].ord
+    g = data[(y*width + x)*4 + 1].ord
+    b = data[(y*width + x)*4 + 2].ord
+    a = data[(y*width + x)*4 + 3].ord
+    {x: x, y: y, color: {r: r, g: g, b: b, a: a}}
+  end
+end.flatten
+puts "#{color_maps.size} pixels to render..."; $stdout.flush
+
+puts 'Parsing shapes...'; $stdout.flush
+
+shape_maps = []
+original_color_maps = color_maps.dup
+indexed_original_color_maps = Hash[original_color_maps.each_with_index.to_a]
+color_maps.each do |color_map|
+  index = indexed_original_color_maps[color_map]
+  @rectangle_start_x ||= color_map[:x]
+  @rectangle_width ||= 1
+  if color_map[:x] < width - 1 && color_map[:color] == original_color_maps[index + 1][:color]
+    @rectangle_width += 1
+  else
+    if color_map[:x] > 0 && color_map[:color] == original_color_maps[index - 1][:color]
+      shape_maps << {x: @rectangle_start_x, y: color_map[:y], width: @rectangle_width, height: 1, color: color_map[:color]}
+    else
+      shape_maps << {x: color_map[:x], y: color_map[:y], width: 1, height: 1, color: color_map[:color]}
+    end
+    @rectangle_width = 1
+    @rectangle_start_x = color_map[:x] == width - 1 ? 0 : color_map[:x] + 1
+  end
+end
+puts "#{shape_maps.size} shapes to render..."; $stdout.flush
+
+puts 'Rendering image...'; $stdout.flush
+
+window('Basic Image', 96, 96) {
+  area {
+    on_draw do |area_draw_params|
+      shape_maps.each do |shape_map|
+        path {
+          rectangle(shape_map[:x], shape_map[:y], shape_map[:width], shape_map[:height])
+
+          fill shape_map[:color]
+        }
+      end
+    end
+  }
+}.show
+```
+
 ### Histogram
 
 [examples/histogram.rb](examples/histogram.rb)
@@ -6290,6 +6634,22 @@ Mac
 
 ![glimmer-dsl-libui-mac-tetris-high-scores.png](images/glimmer-dsl-libui-mac-tetris-high-scores.png)
 
+Windows
+
+![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)
+
+Linux
+
+![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)
+
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
@@ -6530,7 +6890,19 @@ class Tetris
       on_key_down do |key_event|
         case key_event
         in ext_key: :down
-          @game.down!
+          if OS.windows?
+            # rate limit downs in Windows as they go too fast when key is held
+            @queued_downs ||= 0
+            if @queued_downs < 2
+              @queued_downs += 1
+              Glimmer::LibUI.timer(0.01, repeat: false) do
+                @game.down! if @queued_downs < 2
+                @queued_downs -= 1
+              end
+            end
+          else
+            @game.down!
+          end
         in key: ' '
           @game.down!(instant: true)
         in ext_key: :up
@@ -6614,8 +6986,11 @@ class Tetris
   end
   
   def start_moving_tetrominos_down
-    Glimmer::LibUI.timer(@game.delay) do
-      @game.down! if !@game.game_over? && !@game.paused?
+    unless @tetrominos_start_moving_down
+      @tetrominos_start_moving_down = true
+      Glimmer::LibUI.timer(@game.delay) do
+        @game.down! if !@game.game_over? && !@game.paused?
+      end
     end
   end
   
@@ -6628,6 +7003,8 @@ class Tetris
   
   def show_high_scores
     Glimmer::LibUI.queue_main do
+      game_paused = !!@game.paused
+      @game.paused = true
       if @game.high_scores.empty?
         high_scores_string = "No games have been scored yet."
       else
@@ -6636,6 +7013,7 @@ class Tetris
         end.join("\n")
       end
       msg_box('High Scores', high_scores_string)
+      @game.paused = game_paused
     end
   end
   
@@ -6675,6 +7053,26 @@ Mac
 
 ![glimmer-dsl-libui-mac-tic-tac-toe-draw.png](images/glimmer-dsl-libui-mac-tic-tac-toe-draw.png)
 
+Windows
+
+![glimmer-dsl-libui-windows-tic-tac-toe.png](images/glimmer-dsl-libui-windows-tic-tac-toe.png)
+
+![glimmer-dsl-libui-windows-tic-tac-toe-player-o-wins.png](images/glimmer-dsl-libui-windows-tic-tac-toe-player-o-wins.png)
+
+![glimmer-dsl-libui-windows-tic-tac-toe-player-x-wins.png](images/glimmer-dsl-libui-windows-tic-tac-toe-player-x-wins.png)
+
+![glimmer-dsl-libui-windows-tic-tac-toe-draw.png](images/glimmer-dsl-libui-windows-tic-tac-toe-draw.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-tic-tac-toe.png](images/glimmer-dsl-libui-linux-tic-tac-toe.png)
+
+![glimmer-dsl-libui-linux-tic-tac-toe-player-o-wins.png](images/glimmer-dsl-libui-linux-tic-tac-toe-player-o-wins.png)
+
+![glimmer-dsl-libui-linux-tic-tac-toe-player-x-wins.png](images/glimmer-dsl-libui-linux-tic-tac-toe-player-x-wins.png)
+
+![glimmer-dsl-libui-linux-tic-tac-toe-draw.png](images/glimmer-dsl-libui-linux-tic-tac-toe-draw.png)
+
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
 ```ruby
@@ -6765,6 +7163,137 @@ end
 TicTacToe.new.launch
 ```
 
+### Snake
+
+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.
+
+[examples/snake.rb](examples/snake.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/snake.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/snake'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-snake.png](images/glimmer-dsl-libui-mac-snake.png)
+
+![glimmer-dsl-libui-mac-snake-game-over.png](images/glimmer-dsl-libui-mac-snake-game-over.png)
+
+Windows
+
+![glimmer-dsl-libui-windows-snake.png](images/glimmer-dsl-libui-windows-snake.png)
+
+![glimmer-dsl-libui-windows-snake-game-over.png](images/glimmer-dsl-libui-windows-snake-game-over.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-snake.png](images/glimmer-dsl-libui-linux-snake.png)
+
+![glimmer-dsl-libui-linux-snake-game-over.png](images/glimmer-dsl-libui-linux-snake-game-over.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'glimmer/data_binding/observer'
+
+require_relative 'snake/presenter/grid'
+
+class Snake
+  CELL_SIZE = 15
+  SNAKE_MOVE_DELAY = 0.1
+  include Glimmer
+  
+  def initialize
+    @game = Model::Game.new
+    @grid = Presenter::Grid.new(@game)
+    @game.start
+    create_gui
+    register_observers
+  end
+  
+  def launch
+    @main_window.show
+  end
+  
+  def register_observers
+    @game.height.times do |row|
+      @game.width.times do |column|
+        Glimmer::DataBinding::Observer.proc do |new_color|
+          @cell_grid[row][column].fill = new_color
+        end.observe(@grid.cells[row][column], :color)
+      end
+    end
+    
+    Glimmer::DataBinding::Observer.proc do |game_over|
+      Glimmer::LibUI.queue_main do
+        if game_over
+          msg_box('Game Over!', "Score: #{@game.score}")
+          @game.start
+        end
+      end
+    end.observe(@game, :over)
+    
+    Glimmer::LibUI.timer(SNAKE_MOVE_DELAY) do
+      unless @game.over?
+        @game.snake.move
+        @main_window.title = "Glimmer Snake (Score: #{@game.score})"
+      end
+    end
+  end
+  
+  def create_gui
+    @cell_grid = []
+    @main_window = window('Glimmer Snake', @game.width * CELL_SIZE, @game.height * CELL_SIZE) {
+      resizable false
+      
+      vertical_box {
+        padded false
+        
+        @game.height.times do |row|
+          @cell_grid << []
+          horizontal_box {
+            padded false
+            
+            @game.width.times do |column|
+              area {
+                @cell_grid.last << path {
+                  square(0, 0, CELL_SIZE)
+                  
+                  fill Presenter::Cell::COLOR_CLEAR
+                }
+                
+                on_key_up do |area_key_event|
+                  orientation_and_key = [@game.snake.head.orientation, area_key_event[:ext_key]]
+                  case orientation_and_key
+                  in [:north, :right] | [:east, :down] | [:south, :left] | [:west, :up]
+                    @game.snake.turn_right
+                  in [:north, :left] | [:west, :down] | [:south, :right] | [:east, :up]
+                    @game.snake.turn_left
+                  else
+                    # No Op
+                  end
+                end
+              }
+            end
+          }
+        end
+      }
+    }
+  end
+end
+
+Snake.new.launch
+```
+
 ## Applications
 
 Here are some applications built with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui)