glimmer-dsl-libui 0.1.3 → 0.1.7

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.1.3
+# [<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.1.7
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ce2853efdbecf6ebdc73/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-libui/maintainability)
@@ -47,13 +47,23 @@ data = [
   ['task 5', -1],
 ]
 
-window('Task progress', 300, 200) {
-  horizontal_box {
+window('Task Progress', 300, 200) {
+  vertical_box {
     table {
       text_column('Task')
       progress_bar_column('Progress')
 
-      cell_rows data
+      cell_rows data # implicit data-binding
+    }
+    
+    button('Mark All As Done') {
+      stretchy false
+      
+      on_clicked do
+        data.each_with_index do |row_data, row|
+          data[row] = [row_data[0], 100] # automatically updates table due to implicit data-binding
+        end
+      end
     }
   }
 }.show
@@ -70,50 +80,48 @@ require 'glimmer-dsl-libui'
 include Glimmer
 
 window('Area Gallery', 400, 400) {
-  vertical_box {
-    area {
-      path { # declarative stable path
-        square(0, 0, 100)
-        square(100, 100, 400)
-        
-        fill r: 102, g: 102, b: 204
-      }
-      path { # declarative stable path
-        rectangle(0, 100, 100, 400)
-        rectangle(100, 0, 400, 100)
-        
-        fill r: 204, g: 102, b: 204
-      }
-      path { # declarative stable path
-        figure(100, 100) {
-          line(100, 400)
-          line(400, 100)
-          line(400, 400)
-
-          closed true
-        }
+  area {
+    path { # declarative stable path
+      square(0, 0, 100)
+      square(100, 100, 400)
+      
+      fill r: 102, g: 102, b: 204
+    }
+    path { # declarative stable path
+      rectangle(0, 100, 100, 400)
+      rectangle(100, 0, 400, 100)
+      
+      fill r: 204, g: 102, b: 204
+    }
+    path { # declarative stable path
+      figure(100, 100) {
+        line(100, 400)
+        line(400, 100)
+        line(400, 400)
 
-        fill r: 202, g: 102, b: 104, a: 0.5
-        stroke thickness: 1, r: 0, g: 0, b: 0
+        closed true
       }
-      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
-        }
+      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)
 
-        fill r: 202, g: 102, b: 204, a: 0.5
-        stroke thickness: 2, r: 0, g: 0, b: 0
+        closed true
       }
-      path { # declarative stable path
-        arc(200, 200, 90, 0, 360, false)
 
-        fill r: 202, g: 102, b: 204, a: 0.5
-        stroke thickness: 2, r: 0, g: 0, b: 0
-      }
+      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(200, 200, 90, 0, 360, false)
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
     }
   }
 }.show
@@ -135,7 +143,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.1.3](#-glimmer-dsl-for-libui-013)
+- [Glimmer DSL for LibUI 0.1.7](#-glimmer-dsl-for-libui-017)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -176,6 +184,8 @@ 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)
+    - [Histogram](#histogram)
+    - [Basic Transform](#basic-transform)
   - [Contributing to glimmer-dsl-libui](#contributing-to-glimmer-dsl-libui)
   - [Help](#help)
     - [Issues](#issues)
@@ -239,10 +249,10 @@ require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('hello world', 300, 200) { |w|
+window('hello world', 300, 200) {
   button('Button') {
     on_clicked do
-      msg_box(w, 'Information', 'You clicked the button')
+      msg_box('Information', 'You clicked the button')
     end
   }
   
@@ -263,7 +273,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.1.3'
+gem 'glimmer-dsl-libui', '~> 0.1.7'
 ```
 
 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.
@@ -351,7 +361,7 @@ Control(Args) | Properties | Listeners
 `date_time_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`
 `editable_combobox` | `items` (`Array` of `String`), `text` (`String`) | `on_changed`
 `entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
-`figure(x as Numeric, y as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `closed` (Boolean) | None
+`figure(x=nil as Numeric, y=nil as Numeric)` | `x` (`Numeric`), `y` (`Numeric`), `closed` (Boolean) | None
 `font_button` | `font` [read-only] (`Hash` of keys: `:family`, `:size`, `:weight`, `:italic`, `:stretch`), `family` as `String`, `size` as `Float`, `weight` as `Integer`, `italic` as `Integer`, `stretch` as `Integer` | `on_changed`
 `form` | `padded` (Boolean) | None
 `grid` | `padded` (Boolean) | None
@@ -364,13 +374,14 @@ Control(Args) | Properties | Listeners
 `image_text_column(name as String)` | None | None
 `label(text as String)` | `text` (`String`) | None
 `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`
 `multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
-`msg_box(window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
-`msg_box_error(window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
+`msg_box(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
+`msg_box_error(window = main_window as Glimmer::LibUI::WindowProxy, title as String, description as String)` | None | None
 `non_wrapping_multiline_entry` | `read_only` (Boolean), `text` (`String`) | `on_changed`
-`path` | `fill` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`), `stroke` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, `:cap` as `Numeric`, `:join` as `Numeric`, `:thickness` as `Numeric`, `:miter_limit` as `Numeric` ) | None
+`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`), `stroke` (`Hash` of `:r` as `0`-`255`, `:g` as `0`-`255`, `:b` as `0`-`255`, `:a` as `0.0`-`1.0`, `:cap` as (`:round`, `:square`, `:flat`), `:join` as (`:miter`, `:round`, `:bevel`), `:thickness` as `Numeric`, `:miter_limit` as `Numeric`, `:dashes` as `Array` of `Numeric` ) | None
 `preferences_menu_item` | None | `on_clicked`
 `progress_bar` | `value` (`Numeric`) | None
 `progress_bar_column(name as String)` | None | None
@@ -384,7 +395,7 @@ Control(Args) | Properties | Listeners
 `tab_item(name as String)` | `index` [read-only] (`Integer`), `margined` (Boolean), `name` [read-only] (`String`) | None
 `table` | `cell_rows` (`Array` (rows) of `Arrays` (row columns) of cell values (e.g. `String` values for `text_column` cells or `Array` of `image`/`String` for `image_text_column`)), `editable` as Boolean | None
 `text_column(name as String)` | `editable` (Boolean) | None
-`time_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`
+`time_picker` | `time` (`Hash` of keys: `sec` as `Integer`, `min` as `Integer`, `hour` as `Integer`) | `on_changed`
 `vertical_box` | `padded` (Boolean) | 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`
 
@@ -520,9 +531,9 @@ Learn more by checking out [examples](#examples).
 
 ### Area API
 
-The `area` control can be used in one of two ways:
-- Declaratively via stable paths: useful for stable paths that will not change later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Paths proxy objects are preserved across redraws assuming there would be few stable paths (mostly for decorative reasons).
-- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change. Open an `on_draw` listener block and nest `path(area_draw_params)` 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.
+The `area` control is a canvas-like control for drawing paths that can be used in one of two ways:
+- Declaratively via stable paths: useful for stable paths that will not change 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 few stable paths (mostly for decorative reasons).
+- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change. 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.
 
 Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -548,7 +559,7 @@ window('Basic Area', 400, 400) {
 
 ![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png)
 
-Here is the same example using a semi-declarative `area` with `on_draw` listener and a dynamic path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+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
 require 'glimmer-dsl-libui'
@@ -561,7 +572,7 @@ window('Basic Area', 400, 400) {
   vertical_box {
     area {
       on_draw do |area_draw_params|
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+        path { # a dynamic path is added semi-declaratively inside on_draw block
           rectangle(0, 0, 400, 400)
           
           fill r: 102, g: 102, b: 204, a: 1.0
@@ -574,24 +585,110 @@ window('Basic Area', 400, 400) {
 
 Check [examples/dynamic_area.rb](#dynamic-area) for a more detailed semi-declarative example.
 
+`path` can receive a `draw_fill_mode` argument that can accept values `:winding` or `:alternate` and defaults to `:winding`.
+
 Available nested `path` shapes:
 - `rectangle(x as Numeric, y as Numeric, width as Numeric, height as Numeric)`
 - `square(x as Numeric, y as Numeric, length as Numeric)`
 - `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)`
-- `figure(x as Numeric, y as Numeric)` (composite that can contain other shapes) (can set `closed true` to connect last point to first point automatically)
+- `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.
 
-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 paths.
+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
+- `:area_height`: area height
+- `:clip_x`: clip region top-left x coordinate
+- `:clip_y`: clip region top-left y coordinate
+- `:clip_width`: clip region width
+- `:clip_height`: clip region height
 
-To redraw an `area`, you may call `#queue_redraw_all` method.
+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.
+
+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.
+
+To redraw an `area`, you may call the `#queue_redraw_all` method, or simply `#redraw`.
+
+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.
+
+Here are the following operations that can be performed in a `matrix` body:
+- `identity` [alias: `set_identity`]: resets matrix to identity matrix
+- `translate(x as Numeric, y as Numeric)`
+- `scale(x_center = 0 as Numeric, y_center = 0 as Numeric, x as Numeric, y as Numeric)`
+- `skew(x = 0 as Numeric, y = 0 as Numeric, x_amount as Numeric, y_amount as Numeric)`
+- `rotate(x = 0 as Numeric, y = 0 as Numeric, degrees as Numeric)`
+
+Example of using transform matrix (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Transform', 350, 350) {
+  area {
+    path {
+      square(0, 0, 350)
+      
+      fill r: 255, g: 255, b: 0
+    }
+    40.times do |n|
+      path {
+        square(0, 0, 100)
+        
+        fill r: [255 - n*5, 0].max, g: [n*5, 255].min, b: 0, a: 0.5
+        stroke :black, thickness: 2
+        transform {
+          skew 0.15, 0.15
+          translate 50, 50
+          rotate 100, 100, -9 * n
+          scale 1.1, 1.1
+        }
+      }
+    end
+  }
+}.show
+```
+
+Keep in mind that this part could be written differently when there is a need to reuse the matrix:
+
+```ruby
+transform {
+  translate 100, 100
+  rotate 100, 100, -9 * n
+}
+```
+
+Alternatively:
+
+```ruby
+m1 = matrix {
+  translate 100, 100
+  rotate 100, 100, -9 * n
+}
+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)
+
+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.
 
 ### 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
 - `group` controls have `margined` as `true` upon instantiation to ensure more user-friendly GUI by default
 - All controls nested under a `horizontal_box`, `vertical_box`, and `form` have `stretchy` property (fill maximum space) as `true` by default (passed to `box_append`/`form_append` method)
-- `window` instatiation args can be left off, having the following defaults when unspecified: `title` as `''`, `width` as `150`, `height` as `150`, and `has_menubar` as `true`)
+- `window` instatiation args can be left off, having the following defaults when unspecified: `title` as `''`, `width` as `190`, `height` as `150`, and `has_menubar` as `true`)
 - `window` has an `on_closing` listener by default that quits application upon hitting the close button (can be overridden with a manual `on_closing` implementation that returns integer `0` for success)
 - `group` has `title` property default to `''` if not specified in instantiation args, so it can be instantiated without args with `title` property specified in nested block (e.g. `group {title 'Address'; ...}`)
 - `button`, `checkbox`, and `label` have `text` default to `''` if not specified in instantiation args, so they can be instantiated without args with `text` property specified in nested block (e.g. `button {text 'Greet'; on_clicked {puts 'Hello'}}`)
@@ -617,11 +714,17 @@ To redraw an `area`, you may call `#queue_redraw_all` method.
 - `area` paths are specified declaratively with figures underneath (e.g. `rectangle`) and `area` draw listener is automatically generated
 - Observe figure properties (e.g. `rectangle` `width`) for changes and automatically redraw containing area accordingly
 - Observe `path` `fill` and `stroke` hashes for changes and automatically redraw containing area accordingly
+- 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)
+- Color alpha value defaults to `1.0` when not specified.
 
 ### 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 Windows and Linux (not Mac) due to a current limitation in [libui](https://github.com/andlabs/ui/issues/357).
+- It seems that `arc` `start_angle` and `sweep` properties are ignored by [libui](https://github.com/andlabs/libui) and always set to `0` and `360` respectively, producing a full circle.
 
 ### Original API
 
@@ -693,7 +796,7 @@ class MetaExample
   end
   
   def launch
-    window('Meta-Example', 700, 500) { |w|
+    window('Meta-Example', 700, 500) {
       margined true
       
       horizontal_box {
@@ -715,7 +818,7 @@ class MetaExample
                 meta_example_file = File.join(Dir.home, '.meta_example.rb')
                 File.write(meta_example_file, @nwme.text)
                 result = `ruby -r #{glimmer_dsl_libui_file} #{meta_example_file} 2>&1`
-                msg_box(w, 'Error Running Example', result) if result.include?('error')
+                msg_box('Error Running Example', result) if result.include?('error')
               rescue => e
                 puts 'Unable to write code changes! Running original example...'
                 system "ruby -r #{glimmer_dsl_libui_file} #{file_path_for(@examples[@rbs.selected])}"
@@ -799,7 +902,7 @@ window('hello world', 300, 200, true) {
 }.show
 ```
 
-[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (setting `window` properties instead of arguments):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -880,10 +983,10 @@ require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('hello world', 300, 200) { |w|
+window('hello world', 300, 200) {
   button('Button') {
     on_clicked do
-      msg_box(w, 'Information', 'You clicked the button')
+      msg_box('Information', 'You clicked the button')
     end
   }
   
@@ -967,7 +1070,7 @@ require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('Basic Entry', 300, 50) { |w|
+window('Basic Entry', 300, 50) {
   horizontal_box {
     e = entry {
       # stretchy true # Smart default option for appending to horizontal_box
@@ -983,7 +1086,7 @@ window('Basic Entry', 300, 50) { |w|
       
       on_clicked do
         text = e.text
-        msg_box(w, 'You entered', text)
+        msg_box('You entered', text)
       end
     }
   }
@@ -1087,12 +1190,12 @@ ruby -r glimmer-dsl-libui -e "require 'examples/midi_player'"
 Mac
 
 ![glimmer-dsl-libui-mac-midi-player.png](images/glimmer-dsl-libui-mac-midi-player.png)
-![glimmer-dsl-libui-mac-midi-player-version-msg-box.png](images/glimmer-dsl-libui-mac-midi-player-version-msg-box.png)
+![glimmer-dsl-libui-mac-midi-player-msg-box.png](images/glimmer-dsl-libui-mac-midi-player-msg-box.png)
 
 Linux
 
 ![glimmer-dsl-libui-linux-midi-player.png](images/glimmer-dsl-libui-linux-midi-player.png)
-![glimmer-dsl-libui-linux-midi-player-version-msg-box.png](images/glimmer-dsl-libui-linux-midi-player-version-msg-box.png)
+![glimmer-dsl-libui-linux-midi-player-msg-box.png](images/glimmer-dsl-libui-linux-midi-player-msg-box.png)
 
 [LibUI](https://github.com/kojix2/LibUI) Original Version:
 
@@ -1238,23 +1341,22 @@ class TinyMidiPlayer
     end
   end
 
-  def show_version(main_window)
-    msg_box(main_window,
-               'Tiny Midi Player',
-               "Written in Ruby\n" \
-               "https://github.com/kojix2/libui\n" \
-               "Version #{VERSION}")
+  def show_version
+    msg_box('Tiny Midi Player',
+              "Written in Ruby\n" \
+                "https://github.com/kojix2/libui\n" \
+                "Version #{VERSION}")
   end
 
   def create_gui
     menu('Help') { |m|
       menu_item('Version') {
         on_clicked do
-          show_version(@main_window)
+          show_version
         end
       }
     }
-    @main_window = window('Tiny Midi Player', 200, 50) {
+    window('Tiny Midi Player', 200, 50) {
       horizontal_box {
         vertical_box {
           stretchy false
@@ -1270,7 +1372,7 @@ class TinyMidiPlayer
             end
           }
         }
-        
+
         combobox { |c|
           items @midi_files.map { |path| File.basename(path) }
           
@@ -1280,8 +1382,7 @@ class TinyMidiPlayer
           end
         }
       }
-    }
-    @main_window.show
+    }.show
   end
 end
 
@@ -1517,14 +1618,14 @@ include Glimmer
 menu('File') {
   menu_item('Open') {
     on_clicked do
-      file = open_file(MAIN_WINDOW)
+      file = open_file
       puts file unless file.nil?
     end
   }
 
   menu_item('Save') {
     on_clicked do
-      file = save_file(MAIN_WINDOW)
+      file = save_file
       puts file unless file.nil?
     end
   }
@@ -1567,7 +1668,7 @@ MAIN_WINDOW = window('Control Gallery', 600, 500) {
             stretchy false
 
             on_clicked do
-              msg_box(MAIN_WINDOW, 'Information', 'You clicked the button')
+              msg_box('Information', 'You clicked the button')
             end
           }
 
@@ -1575,7 +1676,7 @@ MAIN_WINDOW = window('Control Gallery', 600, 500) {
             stretchy false
 
             on_toggled do |c|
-              checked = c.checked == 1
+              checked = c.checked?
               MAIN_WINDOW.title = "Checkbox is #{checked}"
               c.text = "I am the checkbox (#{checked})"
             end
@@ -2029,7 +2130,7 @@ require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('Form') { |w|
+window('Form') {
   margined true
   
   vertical_box {
@@ -2045,7 +2146,7 @@ window('Form') { |w|
     
     button('Display Name') {
       on_clicked do
-        msg_box(w, 'Name', "#{@first_name_entry.text} #{@last_name_entry.text}")
+        msg_box('Name', "#{@first_name_entry.text} #{@last_name_entry.text}")
       end
     }
   }
@@ -2729,13 +2830,23 @@ data = [
   ['task 5', -1],
 ]
 
-window('Task progress', 300, 200) {
-  horizontal_box {
+window('Task Progress', 300, 200) {
+  vertical_box {
     table {
       text_column('Task')
       progress_bar_column('Progress')
 
-      cell_rows data
+      cell_rows data # implicit data-binding
+    }
+    
+    button('Mark All As Done') {
+      stretchy false
+      
+      on_clicked do
+        data.each_with_index do |row_data, row|
+          data[row] = [row_data[0], 100] # automatically updates table due to implicit data-binding
+        end
+      end
     }
   }
 }.show
@@ -2935,7 +3046,7 @@ window('Basic Area', 400, 400) {
 }.show
 ```
 
-[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (semi-declarative `on_draw` dynamic `path` approach):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -2948,7 +3059,7 @@ window('Basic Area', 400, 400) {
   vertical_box {
     area {
       on_draw do |area_draw_params|
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+        path { # a dynamic path is added semi-declaratively inside on_draw block
           rectangle(0, 0, 400, 400)
           
           fill r: 102, g: 102, b: 204, a: 1.0
@@ -3078,7 +3189,7 @@ window('Dynamic Area', 240, 500) {
     
     @area = area {
       on_draw do |area_draw_params|
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
+        path { # a dynamic path is added semi-declaratively inside on_draw block
           rectangle(@x_spinbox.value, @y_spinbox.value, @width_spinbox.value, @height_spinbox.value)
           
           fill r: @red_spinbox.value, g: @green_spinbox.value, b: @blue_spinbox.value, a: @alpha_spinbox.value / 100.0
@@ -3089,7 +3200,7 @@ window('Dynamic Area', 240, 500) {
 }.show
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2:
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (declarative stable `path` approach):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -3223,21 +3334,192 @@ require 'glimmer-dsl-libui'
 include Glimmer
 
 window('Area Gallery', 400, 400) {
-  vertical_box {
-    area {
-      path { # declarative stable path
+  area {
+    path { # declarative stable path
+      square(0, 0, 100)
+      square(100, 100, 400)
+      
+      fill r: 102, g: 102, b: 204
+    }
+    path { # declarative stable path
+      rectangle(0, 100, 100, 400)
+      rectangle(100, 0, 400, 100)
+      
+      fill r: 204, g: 102, b: 204
+    }
+    path { # declarative stable path
+      figure(100, 100) {
+        line(100, 400)
+        line(400, 100)
+        line(400, 400)
+
+        closed true
+      }
+
+      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
+      }
+
+      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(200, 200, 90, 0, 360, false)
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (setting shape properties instead of arguments):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Area Gallery', 400, 400) {
+  area {
+    path { # declarative stable path
+      square {
+        x 0
+        y 0
+        length 100
+      }
+      square {
+        x 100
+        y 100
+        length 400
+      }
+      
+      fill r: 102, g: 102, b: 204
+    }
+    path { # declarative stable path
+      rectangle {
+        x 0
+        y 100
+        width 100
+        height 400
+      }
+      rectangle {
+        x 100
+        y 0
+        width 400
+        height 100
+      }
+      
+      fill r: 204, g: 102, b: 204
+    }
+    path { # declarative stable path
+      figure {
+        x 100
+        y 100
+        
+        line {
+          x 100
+          y 400
+        }
+        line {
+          x 400
+          y 100
+        }
+        line {
+          x 400
+          y 400
+        }
+
+        closed true
+      }
+
+      fill r: 202, g: 102, b: 104, a: 0.5
+      stroke r: 0, g: 0, b: 0
+    }
+    path { # declarative stable path
+      figure {
+        x 0
+        y 0
+        
+        bezier {
+          c1_x 200
+          c1_y 100
+          c2_x 100
+          c2_y 200
+          end_x 400
+          end_y 100
+        }
+        bezier {
+          c1_x 300
+          c1_y 100
+          c2_x 100
+          c2_y 300
+          end_x 100
+          end_y 400
+        }
+        bezier {
+          c1_x 100
+          c1_y 300
+          c2_x 300
+          c2_y 100
+          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
+      arc {
+        x_center 200
+        y_center 200
+        radius 90
+        start_angle 0
+        sweep 360
+        is_negative false
+      }
+
+      fill r: 202, g: 102, b: 204, a: 0.5
+      stroke r: 0, g: 0, b: 0, thickness: 2
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (semi-declarative `on_draw` dynamic `path` approach):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Area Gallery', 400, 400) {
+  area {
+    on_draw do |area_draw_params|
+      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 { # declarative stable path
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         rectangle(0, 100, 100, 400)
         rectangle(100, 0, 400, 100)
-        
+
         fill r: 204, g: 102, b: 204
       }
-      path { # declarative stable path
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         figure(100, 100) {
           line(100, 400)
           line(400, 100)
@@ -3247,9 +3529,9 @@ window('Area Gallery', 400, 400) {
         }
 
         fill r: 202, g: 102, b: 104, a: 0.5
-        stroke thickness: 1, r: 0, g: 0, b: 0
+        stroke r: 0, g: 0, b: 0
       }
-      path { # declarative stable path
+      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)
@@ -3259,15 +3541,530 @@ window('Area Gallery', 400, 400) {
         }
 
         fill r: 202, g: 102, b: 204, a: 0.5
-        stroke thickness: 2, r: 0, g: 0, b: 0
+        stroke r: 0, g: 0, b: 0, thickness: 2, dashes: [50, 10, 10, 10], dash_phase: -50.0
       }
-      path { # declarative stable path
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         arc(200, 200, 90, 0, 360, false)
 
         fill r: 202, g: 102, b: 204, a: 0.5
-        stroke thickness: 2, r: 0, g: 0, b: 0
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
+    end
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 4 (setting shape properties instead of arguments with semi-declarative `on_draw` dynamic `path` approach):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Area Gallery', 400, 400) {
+  area {
+    on_draw do |area_draw_params|
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        square {
+          x 0
+          y 0
+          length 100
+        }
+        square {
+          x 100
+          y 100
+          length 400
+        }
+        
+        fill r: 102, g: 102, b: 204
+      }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        rectangle {
+          x 0
+          y 100
+          width 100
+          height 400
+        }
+        rectangle {
+          x 100
+          y 0
+          width 400
+          height 100
+        }
+        
+        fill r: 204, g: 102, b: 204
+      }
+      path { # a dynamic path is added semi-declaratively inside on_draw block
+        figure {
+          x 100
+          y 100
+          
+          line {
+            x 100
+            y 400
+          }
+          line {
+            x 400
+            y 100
+          }
+          line {
+            x 400
+            y 400
+          }
+
+          closed true
+        }
+
+        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 {
+          x 0
+          y 0
+          
+          bezier {
+            c1_x 200
+            c1_y 100
+            c2_x 100
+            c2_y 200
+            end_x 400
+            end_y 100
+          }
+          bezier {
+            c1_x 300
+            c1_y 100
+            c2_x 100
+            c2_y 300
+            end_x 100
+            end_y 400
+          }
+          bezier {
+            c1_x 100
+            c1_y 300
+            c2_x 300
+            c2_y 100
+            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
+        arc {
+          x_center 200
+          y_center 200
+          radius 90
+          start_angle 0
+          sweep 360
+          is_negative false
+        }
+
+        fill r: 202, g: 102, b: 204, a: 0.5
+        stroke r: 0, g: 0, b: 0, thickness: 2
+      }
+    end
+  }
+}.show
+```
+
+### Histogram
+
+[examples/histogram.rb](examples/histogram.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/histogram.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/histogram'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-histogram.png](images/glimmer-dsl-libui-mac-histogram.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-histogram.png](images/glimmer-dsl-libui-linux-histogram.png)
+
+[LibUI](https://github.com/kojix2/LibUI) Original Version:
+
+```ruby
+# https://github.com/jamescook/libui-ruby/blob/master/example/histogram.rb
+
+require 'libui'
+
+UI = LibUI
+
+X_OFF_LEFT   = 20
+Y_OFF_TOP    = 20
+X_OFF_RIGHT  = 20
+Y_OFF_BOTTOM = 20
+POINT_RADIUS = 5
+
+init         = UI.init
+handler      = UI::FFI::AreaHandler.malloc
+histogram    = UI.new_area(handler)
+brush        = UI::FFI::DrawBrush.malloc
+color_button = UI.new_color_button
+blue         = 0x1E90FF
+datapoints   = []
+
+def graph_size(area_width, area_height)
+  graph_width = area_width - X_OFF_LEFT - X_OFF_RIGHT
+  graph_height = area_height - Y_OFF_TOP - Y_OFF_BOTTOM
+  [graph_width, graph_height]
+end
+
+matrix = UI::FFI::DrawMatrix.malloc
+
+def point_locations(datapoints, width, height)
+  xincr = width / 9.0 # 10 - 1 to make the last point be at the end
+  yincr = height / 100.0
+
+  data = []
+  datapoints.each_with_index do |dp, i|
+    val = 100 - UI.spinbox_value(dp)
+    data << [xincr * i, yincr * val]
+    i += 1
+  end
+
+  data
+end
+
+def construct_graph(datapoints, width, height, should_extend)
+  locations = point_locations(datapoints, width, height)
+  path = UI.draw_new_path(0) # winding
+  first_location = locations[0] # x and y
+  UI.draw_path_new_figure(path, first_location[0], first_location[1])
+  locations.each do |loc|
+    UI.draw_path_line_to(path, loc[0], loc[1])
+  end
+
+  if should_extend
+    UI.draw_path_line_to(path, width, height)
+    UI.draw_path_line_to(path, 0, height)
+    UI.draw_path_close_figure(path)
+  end
+
+  UI.draw_path_end(path)
+
+  path
+end
+
+handler_draw_event = Fiddle::Closure::BlockCaller.new(
+  0, [1, 1, 1]
+) do |_area_handler, _area, area_draw_params|
+  area_draw_params = UI::FFI::AreaDrawParams.new(area_draw_params)
+  path = UI.draw_new_path(0) # winding
+  UI.draw_path_add_rectangle(path, 0, 0, area_draw_params.AreaWidth, area_draw_params.AreaHeight)
+  UI.draw_path_end(path)
+  set_solid_brush(brush, 0xFFFFFF, 1.0) # white
+  UI.draw_fill(area_draw_params.Context, path, brush.to_ptr)
+  UI.draw_free_path(path)
+  dsp = UI::FFI::DrawStrokeParams.malloc
+  dsp.Cap = 0 # flat
+  dsp.Join = 0 # miter
+  dsp.Thickness = 2
+  dsp.MiterLimit = 10 # DEFAULT_MITER_LIMIT
+  dashes = Fiddle::Pointer.malloc(8)
+  dsp.Dashes = dashes
+  dsp.NumDashes = 0
+  dsp.DashPhase = 0
+
+  # draw axes
+  set_solid_brush(brush, 0x000000, 1.0) # black
+  graph_width, graph_height = *graph_size(area_draw_params.AreaWidth, area_draw_params.AreaHeight)
+
+  path = UI.draw_new_path(0) # winding
+  UI.draw_path_new_figure(path, X_OFF_LEFT, Y_OFF_TOP)
+  UI.draw_path_line_to(path, X_OFF_LEFT, Y_OFF_TOP + graph_height)
+  UI.draw_path_line_to(path, X_OFF_LEFT + graph_width, Y_OFF_TOP + graph_height)
+  UI.draw_path_end(path)
+  UI.draw_stroke(area_draw_params.Context, path, brush, dsp)
+  UI.draw_free_path(path)
+
+  # now transform the coordinate space so (0, 0) is the top-left corner of the graph
+  UI.draw_matrix_set_identity(matrix)
+  UI.draw_matrix_translate(matrix, X_OFF_LEFT, Y_OFF_TOP)
+  UI.draw_transform(area_draw_params.Context, matrix)
+
+  # now get the color for the graph itself and set up the brush
+  #  uiColorButtonColor(colorButton, &graphR, &graphG, &graphB, &graphA)
+  graph_r = Fiddle::Pointer.malloc(8) # double
+  graph_g = Fiddle::Pointer.malloc(8) # double
+  graph_b = Fiddle::Pointer.malloc(8) # double
+  graph_a = Fiddle::Pointer.malloc(8) # double
+
+  UI.color_button_color(color_button, graph_r, graph_g, graph_b, graph_a)
+  brush.Type = 0 # solid
+  brush.R = graph_r[0, 8].unpack1('d')
+  brush.G = graph_g[0, 8].unpack1('d')
+  brush.B = graph_b[0, 8].unpack1('d')
+
+  # now create the fill for the graph below the graph line
+  path = construct_graph(datapoints, graph_width, graph_height, true)
+  brush.A = graph_a[0, 8].unpack1('d') / 2.0
+  UI.draw_fill(area_draw_params.Context, path, brush)
+  UI.draw_free_path(path)
+
+  # now draw the histogram line
+  path = construct_graph(datapoints, graph_width, graph_height, false)
+  brush.A = graph_a[0, 8].unpack1('d')
+  UI.draw_stroke(area_draw_params.Context, path, brush, dsp)
+  UI.draw_free_path(path)
+end
+
+handler.Draw         = handler_draw_event
+
+# Assigning to local variables
+# This is intended to protect Fiddle::Closure from garbage collection.
+# See https://github.com/kojix2/LibUI/issues/8
+handler.MouseEvent   = (c1 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.MouseCrossed = (c2 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.DragBroken   = (c3 = Fiddle::Closure::BlockCaller.new(0, [0]) {})
+handler.KeyEvent     = (c4 = Fiddle::Closure::BlockCaller.new(1, [0]) { 0 })
+
+UI.freeInitError(init) unless init.nil?
+
+hbox = UI.new_horizontal_box
+UI.box_set_padded(hbox, 1)
+
+vbox = UI.new_vertical_box
+UI.box_set_padded(vbox, 1)
+UI.box_append(hbox, vbox, 0)
+UI.box_append(hbox, histogram, 1)
+
+datapoints = Array.new(10) do
+  UI.new_spinbox(0, 100).tap do |datapoint|
+    UI.spinbox_set_value(datapoint, Random.new.rand(90))
+    UI.spinbox_on_changed(datapoint) do
+      UI.area_queue_redraw_all(histogram)
+    end
+    UI.box_append(vbox, datapoint, 0)
+  end
+end
+
+def set_solid_brush(brush, color, alpha)
+  brush.Type = 0 # solid
+  brush.R = ((color >> 16) & 0xFF) / 255.0
+  brush.G = ((color >> 8) & 0xFF) / 255.0
+  brush.B = (color & 0xFF) / 255.0
+  brush.A = alpha
+  brush
+end
+
+set_solid_brush(brush, blue, 1.0)
+UI.color_button_set_color(color_button, brush.R, brush.G, brush.B, brush.A)
+
+UI.color_button_on_changed(color_button) do
+  UI.area_queue_redraw_all(histogram)
+end
+
+UI.box_append(vbox, color_button, 0)
+
+MAIN_WINDOW = UI.new_window('histogram example', 640, 480, 1)
+UI.window_set_margined(MAIN_WINDOW, 1)
+UI.window_set_child(MAIN_WINDOW, hbox)
+
+should_quit = proc do |_ptr|
+  UI.control_destroy(MAIN_WINDOW)
+  UI.quit
+  0
+end
+
+UI.window_on_closing(MAIN_WINDOW, should_quit)
+UI.on_should_quit(should_quit)
+UI.control_show(MAIN_WINDOW)
+
+UI.main
+UI.quit
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+# https://github.com/jamescook/libui-ruby/blob/master/example/histogram.rb
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+X_OFF_LEFT   = 20
+Y_OFF_TOP    = 20
+X_OFF_RIGHT  = 20
+Y_OFF_BOTTOM = 20
+POINT_RADIUS = 5
+COLOR_BLUE   = 0x1E90FF
+
+@datapoints   = 10.times.map {Random.new.rand(90)}
+
+def graph_size(area_width, area_height)
+  graph_width = area_width - X_OFF_LEFT - X_OFF_RIGHT
+  graph_height = area_height - Y_OFF_TOP - Y_OFF_BOTTOM
+  [graph_width, graph_height]
+end
+
+def point_locations(width, height)
+  xincr = width / 9.0 # 10 - 1 to make the last point be at the end
+  yincr = height / 100.0
+
+  @datapoints.each_with_index.map do |value, i|
+    val = 100 - value
+    [xincr * i, yincr * val]
+  end
+end
+
+# method-based custom control representing a graph path
+def graph_path(width, height, should_extend, &block)
+  locations = point_locations(width, height)
+  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
+    }
+    
+    # apply a transform to the coordinate space for this path so (0, 0) is the top-left corner of the graph
+    transform {
+      translate X_OFF_LEFT, Y_OFF_TOP
+    }
+    
+    block.call
+  }
+end
+
+window('histogram example', 640, 480) {
+  margined true
+  
+  horizontal_box {
+    vertical_box {
+      stretchy false
+      
+      10.times do |i|
+        spinbox(0, 100) { |sb|
+          stretchy false
+          value @datapoints[i]
+          
+          on_changed do
+            @datapoints[i] = sb.value
+            @area.queue_redraw_all
+          end
+        }
+      end
+      
+      @color_button = color_button {
+        stretchy false
+        color COLOR_BLUE
+        
+        on_changed do
+          @area.queue_redraw_all
+        end
       }
     }
+    
+    @area = area {
+      on_draw do |area_draw_params|
+        path {
+          rectangle(0, 0, area_draw_params[:area_width], area_draw_params[:area_height])
+          
+          fill 0xFFFFFF
+        }
+        
+        graph_width, graph_height = *graph_size(area_draw_params[:area_width], area_draw_params[:area_height])
+      
+        path {
+          figure(X_OFF_LEFT, Y_OFF_TOP) {
+            line(X_OFF_LEFT, Y_OFF_TOP + graph_height)
+            line(X_OFF_LEFT + graph_width, Y_OFF_TOP + graph_height)
+          }
+          
+          stroke 0x000000, thickness: 2, miter_limit: 10
+        }
+      
+        # now create the fill for the graph below the graph line
+        graph_path(graph_width, graph_height, true) {
+          fill @color_button.color.merge(a: 0.5)
+        }
+        
+        # now draw the histogram line
+        graph_path(graph_width, graph_height, false) {
+          stroke @color_button.color.merge(thickness: 2, miter_limit: 10)
+        }
+      end
+    }
+  }
+}.show
+```
+
+### Basic Transform
+
+[examples/basic_transform.rb](examples/basic_transform.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_transform.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_transform'"
+```
+
+Mac
+
+![glimmer-dsl-libui-mac-basic-transform.png](images/glimmer-dsl-libui-mac-basic-transform.png)
+
+Linux
+
+![glimmer-dsl-libui-linux-basic-transform.png](images/glimmer-dsl-libui-linux-basic-transform.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Transform', 350, 350) {
+  area {
+    path {
+      square(0, 0, 350)
+      
+      fill r: 255, g: 255, b: 0
+    }
+    40.times do |n|
+      path {
+        square(0, 0, 100)
+        
+        fill r: [255 - n*5, 0].max, g: [n*5, 255].min, b: 0, a: 0.5
+        stroke :black, thickness: 2
+        transform {
+          skew 0.15, 0.15
+          translate 50, 50
+          rotate 100, 100, -9 * n
+          scale 1.1, 1.1
+        }
+      }
+    end
   }
 }.show
 ```