glimmer-dsl-libui 0.2.23 → 0.3.2

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.23
+# [<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.2
 ## 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)
@@ -238,6 +238,14 @@ 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)
+      - [Area Path Shapes](#area-path-shapes)
+      - [Area Text](#area-text)
+      - [Area Image](#area-image)
+      - [Colors](#colors)
+      - [Area Draw Params](#area-draw-params)
+      - [Area Listeners](#area-listeners)
+      - [Area Methods/Attributes](#area-methods-attributes)
+      - [Area Transform Matrix](#area-transform-matrix)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
     - [Custom Keywords](#custom-keywords)
     - [API Gotchas](#api-gotchas)
@@ -270,6 +278,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)
@@ -373,7 +382,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.2.23'
+gem 'glimmer-dsl-libui', '~> 0.3.2'
 ```
 
 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.
@@ -444,7 +453,7 @@ w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0
 
 ### Supported Keywords
 
-These are all the supported keywords. Note that some keywords do not represent controls, but produce objects that are used as the property values of controls (e.g. `image` builds objects to use in `cell_rows` for a `table` with an image column)
+These are all the supported keywords. Note that some keywords do not represent controls, but produce objects that are used as the property values of controls (e.g. `image` can be used as a control under `area` or alternatively build objects to use in `cell_rows` for a `table` with an `image_column`)
 
 Keyword(Args) | Properties | Listeners
 ------------- | ---------- | ---------
@@ -473,7 +482,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)` | `file` (`String` path or URL), `width`, `height` | 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
@@ -552,8 +561,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]`
@@ -717,6 +726,8 @@ The `area` control is a canvas-like control for drawing paths that can be used i
 - Declaratively via stable paths: useful for stable paths that will not change often later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be relatively few stable paths (mostly for decorative reasons).
 - Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change very often. Open an `on_draw` listener block that receives a `area_draw_params` argument and nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
 
+Note that 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.
+
 Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
@@ -739,8 +750,18 @@ window('Basic Area', 400, 400) {
 }.show
 ```
 
+Mac
+
 ![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png)
 
+Windows
+
+![glimmer-dsl-libui-windows-basic-area.png](images/glimmer-dsl-libui-windows-basic-area.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-basic-area.png](images/glimmer-dsl-libui-linux-basic-area.png)
+
 Here is the same example using a semi-declarative `area` with `on_draw` listener that receives a `area_draw_params` argument and a dynamic path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
@@ -767,6 +788,8 @@ window('Basic Area', 400, 400) {
 
 Check [examples/dynamic_area.rb](#dynamic-area) for a more detailed semi-declarative example.
 
+#### Area Path Shapes
+
 `path` can receive a `draw_fill_mode` argument that can accept values `:winding` or `:alternate` and defaults to `:winding`.
 
 Available nested `path` shapes:
@@ -782,6 +805,270 @@ Available nested `path` shapes:
 
 Check [examples/area_gallery.rb](#area-gallery) for an overiew of all `path` shapes.
 
+Mac
+
+![glimmer-dsl-libui-mac-area-gallery.png](images/glimmer-dsl-libui-mac-area-gallery.png)
+
+Windows
+
+![glimmer-dsl-libui-windows-area-gallery.png](images/glimmer-dsl-libui-windows-area-gallery.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-area-gallery.png](images/glimmer-dsl-libui-linux-area-gallery.png)
+
+#### Area Text
+
+To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {[attributes]; string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` or `<p>` element in html, which contains a string of text). Alternatively, you can nest attributed `string(string_value) {[attributes]}` if `string_value` is a short single-line string. An attributed `string` value can be changed dynamically via its `string` property.
+
+`text` has the following properties:
+- `default_font`:
+- `align`: `:left` (default), `:center`, or `:right` (`align` currently seems not to work on the Mac)
+- `x`: x coordinate in relation to parent `area` top-left corner
+- `y`: y coordinate in relation to parent `area` top-left corner
+- `width` (default: area width - x*2): width of text to display
+
+`string` has the following properties:
+- `font`: font descriptor hash consisting of `:family`, `:size`, `:weight` (`[:minimum, :thin, :ultra_light, :light, :book, :normal, :medium, :semi_bold, :bold, :ultra_bold, :heavy, :ultra_heavy, :maximum]`), `:italic` (`[:normal, :oblique, :italic]`), and `:stretch` (`[:ultra_condensed, :extra_condensed, :condensed, :semi_condensed, :normal, :semi_expanded, :expanded, :extra_expanded, :ultra_expanded]`) key values
+- `color`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
+- `background`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
+- `underline`: one of `:none`, `:single`, `:double`, `:suggestion`, `:color_custom`, `:color_spelling`, `:color_grammar`, `:color_auxiliary`
+- `underline_color`: one of `:spelling`, `:grammar`, `:auxiliary`, rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
+- `open_type_features`: Open Type Features (https://www.microsoft.com/typography/otspec/featuretags.htm) consist of `open_type_tag`s nested in content block, which accept (`a`, `b`, `c`, `d`, `Integer`) arguments.
+- `string`: string value (`String`)
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+window('area text drawing') {
+  area {
+    text {
+      default_font family: 'Helvetica', size: 12, weight: :normal, italic: :normal, stretch: :normal
+        
+      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
+        underline :single
+        underline_color :spelling
+        open_type_features {
+          open_type_tag 'l', 'i', 'g', 'a', 0
+          open_type_tag 'l', 'i', 'g', 'a', 1
+        }
+        
+        "This is a demonstration\n" \
+        "of a very long\n" \
+        "attributed string\n" \
+        "spanning multiple lines\n\n"
+      }
+      
+      string('This is a short unattributed string')
+    }
+  }
+}.show
+```
+
+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
+
+![glimmer-dsl-libui-mac-custom-draw-text-changed.png](images/glimmer-dsl-libui-mac-custom-draw-text-changed.png)
+
+Windows
+
+![glimmer-dsl-libui-windows-custom-draw-text-changed.png](images/glimmer-dsl-libui-windows-custom-draw-text-changed.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-custom-draw-text-changed.png](images/glimmer-dsl-libui-linux-custom-draw-text-changed.png)
+
+#### Area Image
+
+**(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(file as String path or web URL, width as Numeric, height as Numeric)` custom control that renders an image unto an `area` pixel by pixel (and when possible to optimize, line by line).
+
+Given that it is very new and is not a [libui](https://github.com/andlabs/libui)-native control, please keep these notes in mind:
+- It only supports the `.png` file format.
+- [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)):
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-image.png](images/glimmer-dsl-libui-mac-basic-image.png)
+
+Windows
+
+![glimmer-dsl-libui-windows-basic-image.png](images/glimmer-dsl-libui-windows-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
+```
+
+One final note is that in Linux, table images grow and shrink with the image size unlike on the Mac where table row heights are constant regardless of image sizes. As such, you may be able to repurpose a table with a single image column and a single row as an image control with more native libui rendering if you are only targeting Linux with your app.
+
+Check out [examples/basic_image.rb](#basic-image) (all versions) for examples of using `image` Glimmer custom control.
+
+#### Colors
+
+`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.
+
+Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wikipedia.org/wiki/X11_color_names) colors.
+
+Check [Histogram](#histogram) example for use of hex colors.
+
+#### Area Draw Params
+
 The `area_draw_params` argument for `on_draw` block is a hash consisting of the following keys:
 - `:context`: the drawing context object
 - `:area_width`: area width
@@ -793,7 +1080,9 @@ The `area_draw_params` argument for `on_draw` block is a hash consisting of the
 
 In general, it is recommended to use declarative stable paths whenever feasible since they require less code and simpler maintenance. But, in more advanced cases, semi-declarative dynamic paths could be used instead, especially if there are thousands of dynamic paths that need maximum performance and low memory footprint.
 
-`area` supported mouse listeners are:
+#### Area Listeners
+
+`area` supported listeners are:
 - `on_key_event {|area_key_event| ...}`: general catch-all key event (recommend using fine-grained key events below instead)
 - `on_key_down {|area_key_event| ...}`
 - `on_key_up {|area_key_event| ...}`
@@ -821,14 +1110,14 @@ The `area_mouse_event` `Hash` argument for mouse events that receive it (e.g. `o
 
 The `area_key_event` `Hash` argument for keyboard events that receive it (e.g. `on_key_up`, `on_key_down`) consist of the following hash keys:
 - `:key`: key character (`String`)
-- `:key_value`: key value (`Integer`). Useful in rare cases for numeric processing of keys instead of dealing with as `:key` character `String`
+- `:key_value` (alias: `:key_code`): key code value (`Integer`). Useful in rare cases for numeric processing of keys instead of dealing with as `:key` character `String`
 - `:ext_key`: non-character extra key (`Symbol`) from `Glimmer::LibUI.enum_symbols(:ext_key)` such as `:left`, `:right`, `:escape`, `:insert`
 - `:ext_key_value`: non-character extra key value (`Integer`). Useful in rare cases for numeric processing of extra keys instead of dealing with as `:ext_key` `Symbol`
 - `:modifier`: modifier key pressed alone (e.g. `:shift` or `:control`)
 - `:modifiers`: modifier keys pressed simultaneously with `:key`, `:ext_key`, or `:modifier`
 - `:up`: indicates if key has been released or not (Boolean)
 
-Note that 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.
+#### Area Methods/Attributes
 
 To redraw an `area`, you may call the `#queue_redraw_all` method, or simply `#redraw`.
 
@@ -838,6 +1127,8 @@ To redraw an `area`, you may call the `#queue_redraw_all` method, or simply `#re
 - `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
 
+#### Area Transform Matrix
+
 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.
@@ -901,64 +1192,9 @@ transform m1
 # and then reuse m1 elsewhere 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)
-
-Available [X11 colors](https://en.wikipedia.org/wiki/X11_color_names) can be obtained through `Glimmer::LibUI.x11_colors` method.
-
-Check [Basic Transform](#basic-transform) example for use of [X11](https://en.wikipedia.org/wiki/X11_color_names) colors.
-
-Check [Histogram](#histogram) example for use of hex colors.
-
-To draw `text` in an `area`, you simply nest a `text(x, y, width)` control directly under `area` or inside a `on_draw` listener, and then nest attributed `string {[attributes]; string_value}` controls underneath it returning an actual `String` (think of them as the `<span>` or `<p>` element in html, which contains a string of text). Alternatively, you can nest attributed `string(string_value) {[attributes]}` if `string_value` is a short single-line string. An attributed `string` value can be changed dynamically via its `string` property.
+You can set a `matrix`/`transform` on `area` directly to conveniently apply to all nested `path`s too.
 
-`text` has the following properties:
-- `default_font`:
-- `align`: `:left` (default), `:center`, or `:right` (`align` currently seems not to work on the Mac)
-- `x`: x coordinate in relation to parent `area` top-left corner
-- `y`: y coordinate in relation to parent `area` top-left corner
-- `width` (default: area width - x*2): width of text to display
-
-`string` has the following properties:
-- `font`: font descriptor hash consisting of `:family`, `:size`, `:weight` (`[:minimum, :thin, :ultra_light, :light, :book, :normal, :medium, :semi_bold, :bold, :ultra_bold, :heavy, :ultra_heavy, :maximum]`), `:italic` (`[:normal, :oblique, :italic]`), and `:stretch` (`[:ultra_condensed, :extra_condensed, :condensed, :semi_condensed, :normal, :semi_expanded, :expanded, :extra_expanded, :ultra_expanded]`) key values
-- `color`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
-- `background`: rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
-- `underline`: one of `:none`, `:single`, `:double`, `:suggestion`, `:color_custom`, `:color_spelling`, `:color_grammar`, `:color_auxiliary`
-- `underline_color`: one of `:spelling`, `:grammar`, `:auxiliary`, rgba, hex, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color
-- `open_type_features`: Open Type Features (https://www.microsoft.com/typography/otspec/featuretags.htm) consist of `open_type_tag`s nested in content block, which accept (`a`, `b`, `c`, `d`, `Integer`) arguments.
-- `string`: string value (`String`)
-
-Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
-
-```ruby
-window('area text drawing') {
-  area {
-    text {
-      default_font family: 'Helvetica', size: 12, weight: :normal, italic: :normal, stretch: :normal
-        
-      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
-        underline :single
-        underline_color :spelling
-        open_type_features {
-          open_type_tag 'l', 'i', 'g', 'a', 0
-          open_type_tag 'l', 'i', 'g', 'a', 1
-        }
-        
-        "This is a demonstration\n" \
-        "of a very long\n" \
-        "attributed string\n" \
-        "spanning multiple lines\n\n"
-      }
-      
-      string('This is a short unattributed string')
-    }
-  }
-}.show
-```
+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.
 
 ### Smart Defaults and Conventions
 
@@ -982,7 +1218,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.
@@ -996,7 +1232,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
@@ -1110,7 +1346,8 @@ window('Method-Based Custom Keyword') {
 ### API Gotchas
 
 - There is no proper way to destroy `grid` children due to [libui](https://github.com/andlabs/libui) not offering any API for deleting them from `grid` (no `grid_delete` similar to `box_delete` for `horizontal_box` and `vertical_box`).
-- `table` `checkbox_column` and `checkbox_text_column` checkbox editing only works on Linux and Windows (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- `table` `checkbox_column` checkbox editing only works on Linux and Windows (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- `table` `checkbox_text_column` checkbox editing only works on Linux (not Mac or Windows) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
 - `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` 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.
@@ -1760,11 +1997,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
@@ -1858,12 +2095,12 @@ class TinyMidiPlayer
         vertical_box {
           stretchy false
           
-          button('â–¶') {
+          button('â–¶') {
             on_clicked do
               play_midi
             end
           }
-          button('â– ') {
+          button('â– ') {
             on_clicked do
               stop_midi
             end
@@ -2994,13 +3231,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)
 
@@ -3114,6 +3345,41 @@ UI.quit
 # NOTE:
 # This example displays images that can be freely downloaded from the Studio Ghibli website.
 
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+IMAGE_ROWS = []
+
+50.times do |i|
+  url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
+  puts "Processing Image: #{url}"; $stdout.flush # for Windows
+  IMAGE_ROWS << [image(url)] # array of one column cell
+rescue StandardError => e
+  warn url, e.message
+end
+
+window('The Red Turtle', 310, 350, false) {
+  horizontal_box {
+    table {
+      image_column('www.ghibli.jp/works/red-turtle')
+      
+      cell_rows IMAGE_ROWS
+    }
+  }
+  
+  on_closing do
+    puts 'Bye Bye'
+  end
+}.show
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of `image` from `image_part`):
+
+```ruby
+# NOTE:
+# This example displays images that can be freely downloaded from the Studio Ghibli website.
+
 require 'glimmer-dsl-libui'
 require 'chunky_png'
 require 'open-uri'
@@ -3156,13 +3422,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)
 
@@ -3196,6 +3456,42 @@ New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version
 # NOTE:
 # This example displays images that can be freely downloaded from the Studio Ghibli website.
 
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+IMAGE_ROWS = []
+
+5.times do |i|
+  url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
+  puts "Processing Image: #{url}"; $stdout.flush # for Windows
+  text = url.sub('https://www.ghibli.jp/gallery/thumb-redturtle', '').sub('.png', '')
+  img = image(url)
+  IMAGE_ROWS << [[img, text], [img, text]] # cell values are dual-element arrays
+rescue StandardError => e
+  warn url, e.message
+end
+
+window('The Red Turtle', 670, 350) {
+  horizontal_box {
+    table {
+      image_text_column('image/number')
+      image_text_column('image/number (editable)') {
+        editable true
+      }
+      
+      cell_rows IMAGE_ROWS
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of `image` from `image_part`):
+
+```ruby
+# NOTE:
+# This example displays images that can be freely downloaded from the Studio Ghibli website.
+
 require 'glimmer-dsl-libui'
 require 'chunky_png'
 require 'open-uri'
@@ -3482,12 +3778,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:
@@ -3516,6 +3806,40 @@ Linux
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
+```ruby
+# frozen_string_literal: true
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+img = image(File.expand_path('../icons/glimmer.png', __dir__), 24, 24)
+
+data = [
+  [['cat', :red]      , ['meow', :blue]                  , [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], {r: 255, g: 120, b: 0, a: 0.5}],
+  [['dog', :yellow]   , ['woof', {r: 240, g: 32, b: 32}] , [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], :skyblue],
+  [['chicken', :beige], ['cock-a-doodle-doo', :blue]     , [false, 'mammal', :red] , [img, 'Glimmer', :beige], {r: 5, g: 120, b: 110}],
+  [['horse', :purple] , ['neigh', {r: 240, g: 32, b: 32}], [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], '13a1fb'],
+  [['cow', :gray]     , ['moo', :blue]                   , [true, 'mammal', :green], [img, 'Glimmer', :brown], 0x12ff02]
+]
+
+window('Animals', 500, 200) {
+  horizontal_box {
+    table {
+      text_color_column('Animal')
+      text_color_column('Sound')
+      checkbox_text_color_column('Description')
+      image_text_color_column('GUI')
+      background_color_column('Mammal')
+
+      cell_rows data
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of [libui](https://github.com/andlabs/libui) `image` from `image_part`):
+
 ```ruby
 require 'glimmer-dsl-libui'
 require 'chunky_png'
@@ -4723,6 +5047,200 @@ 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)
+
+Windows
+
+![glimmer-dsl-libui-windows-basic-image.png](images/glimmer-dsl-libui-windows-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)