glimmer-dsl-libui 0.1.4 → 0.1.8

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.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.8
 ## 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)
@@ -80,51 +80,85 @@ 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 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
     }
+    
+    on_mouse_event do |area_mouse_event|
+      p area_mouse_event
+    end
+    
+    on_mouse_moved do |area_mouse_event|
+      puts 'moved'
+    end
+    
+    on_mouse_down do |area_mouse_event|
+      puts 'mouse down'
+    end
+    
+    on_mouse_up do |area_mouse_event|
+      puts 'mouse up'
+    end
+    
+    on_mouse_drag_started do |area_mouse_event|
+      puts 'drag started'
+    end
+    
+    on_mouse_dragged do |area_mouse_event|
+      puts 'dragged'
+    end
+    
+    on_mouse_dropped do |area_mouse_event|
+      puts 'dropped'
+    end
+    
+    on_mouse_entered do
+      puts 'entered'
+    end
+    
+    on_mouse_exited do
+      puts 'exited'
+    end
   }
 }.show
 ```
@@ -145,7 +179,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
 
 ## Table of Contents
 
-- [Glimmer DSL for LibUI 0.1.4](#-glimmer-dsl-for-libui-014)
+- [Glimmer DSL for LibUI 0.1.8](#-glimmer-dsl-for-libui-018)
   - [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
   - [Usage](#usage)
   - [Girb (Glimmer IRB)](#girb-glimmer-irb)
@@ -186,6 +220,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)
@@ -249,10 +285,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
   }
   
@@ -273,7 +309,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.1.4'
+gem 'glimmer-dsl-libui', '~> 0.1.8'
 ```
 
 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.
@@ -347,7 +383,7 @@ w.libui # => #<Fiddle::Pointer:0x00007fde53997980 ptr=0x00007fde51352a60 size=0
 Control(Args) | Properties | Listeners
 ------------- | ---------- | ---------
 `about_menu_item` | None | `on_clicked`
-`area` | None | `on_draw`
+`area` | None | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`
 `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)` | `x_center` (`Numeric`), `y_center` (`Numeric`), `radius` (`Numeric`), `start_angle` (`Numeric`), `sweep` (`Numeric`), `is_negative` (Boolean) | None
 `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)` | `c1_x` (`Numeric`), `c1_y` (`Numeric`), `c2_x` (`Numeric`), `c2_y` (`Numeric`), `end_x` (`Numeric`), `end_y` (`Numeric`) | None
 `button(text as String)` | `text` (`String`) | `on_clicked`
@@ -374,13 +410,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
@@ -394,7 +431,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`
 
@@ -530,9 +567,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)):
 
@@ -558,7 +595,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'
@@ -571,7 +608,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
@@ -584,6 +621,8 @@ 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)`
@@ -592,16 +631,123 @@ Available nested `path` shapes:
 - `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=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)
 
-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.
+Check [examples/area_gallery.rb](#area-gallery) for an overiew of all `path` shapes.
+
+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
+
+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:
+- `on_mouse_event {|area_mouse_event| ...}`: general catch-all mouse event (recommend use fine-grained event below instead)
+- `on_mouse_down {|area_mouse_event)`
+- `on_mouse_up {|area_mouse_event)`
+- `on_mouse_drag_started {|area_mouse_event)`
+- `on_mouse_dragged {|area_mouse_event)`
+- `on_mouse_dropped {|area_mouse_event)`
+- `on_mouse_entered {...}`
+- `on_mouse_exited {...}`
+- `on_mouse_crossed {|left| ...}` (NOT RECOMMENDED; it does what `on_mouse_entered` and `on_mouse_exited` do by returning a `left` argument indicating if mouse left `area`)
+- `on_drag_broken {...}` (NOT RECOMMENDED; varies per platforms; use `on_mouse_dropped` instead)
+
+The `area_mouse_event` argument for mouse events that receive it (e.g. `on_mouse_up`, `on_mouse_dragged`) consist of the following keys:
+- `:x`: mouse x location in relation to area's top-left-corner
+- `:y`: mouse y location in relation to area's top-left-corner
+- `:area_width`: area current width
+- `:area_height`: area current height
+- `:down`: mouse pressed button (e.g. `1` is left button, `3` is right button)
+- `:up`: mouse depressed button (e.g. `1` is left button, `3` is right button)
+- `:count`: count of mouse clicks (e.g. `2` for double-click, `1` for single-click)
+- `:modifers`: `Array` of `Symbol`s from one of the following: `[:command, :shift, :alt, :control]`
+- `:held`: mouse held button during dragging (e.g. `1` is left button, `4` is right button)
+
+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)
 
-To redraw an `area`, you may call `#queue_redraw_all` 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.
 
 ### 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'}}`)
@@ -627,6 +773,11 @@ 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
 
@@ -654,6 +805,8 @@ The following examples include reimplementions of the examples in the [LibUI](ht
 
 To browse all examples, simply launch the [Meta-Example](examples/meta_example.rb), which lists all examples and displays each example's code when selected. It also enables code editing to facilitate experimentation and learning.
 
+(note that for examples that emit output to terminal/command-line via `p` or `puts`, you must run them directly to see output)
+
 [examples/meta_example.rb](examples/meta_example.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -704,7 +857,7 @@ class MetaExample
   end
   
   def launch
-    window('Meta-Example', 700, 500) { |w|
+    window('Meta-Example', 700, 500) {
       margined true
       
       horizontal_box {
@@ -726,7 +879,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])}"
@@ -810,7 +963,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'
@@ -891,10 +1044,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
   }
   
@@ -978,7 +1131,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
@@ -994,7 +1147,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
     }
   }
@@ -1098,12 +1251,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:
 
@@ -1249,23 +1402,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
@@ -1281,7 +1433,7 @@ class TinyMidiPlayer
             end
           }
         }
-        
+
         combobox { |c|
           items @midi_files.map { |path| File.basename(path) }
           
@@ -1291,8 +1443,7 @@ class TinyMidiPlayer
           end
         }
       }
-    }
-    @main_window.show
+    }.show
   end
 end
 
@@ -1528,14 +1679,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
   }
@@ -1578,7 +1729,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
           }
 
@@ -1586,7 +1737,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
@@ -2040,7 +2191,7 @@ require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('Form') { |w|
+window('Form') {
   margined true
   
   vertical_box {
@@ -2056,7 +2207,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
     }
   }
@@ -2956,7 +3107,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'
@@ -2969,7 +3120,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
@@ -3099,7 +3250,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
@@ -3110,7 +3261,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'
@@ -3244,21 +3395,264 @@ 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
+    }
+    
+    on_mouse_event do |area_mouse_event|
+      p area_mouse_event
+    end
+    
+    on_mouse_moved do |area_mouse_event|
+      puts 'moved'
+    end
+    
+    on_mouse_down do |area_mouse_event|
+      puts 'mouse down'
+    end
+    
+    on_mouse_up do |area_mouse_event|
+      puts 'mouse up'
+    end
+    
+    on_mouse_drag_started do |area_mouse_event|
+      puts 'drag started'
+    end
+    
+    on_mouse_dragged do |area_mouse_event|
+      puts 'dragged'
+    end
+    
+    on_mouse_dropped do |area_mouse_event|
+      puts 'dropped'
+    end
+    
+    on_mouse_entered do
+      puts 'entered'
+    end
+    
+    on_mouse_exited do
+      puts 'exited'
+    end
+  }
+}.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
+    }
+    
+    on_mouse_event do |area_mouse_event|
+      p area_mouse_event
+    end
+    
+    on_mouse_moved do |area_mouse_event|
+      puts 'moved'
+    end
+    
+    on_mouse_down do |area_mouse_event|
+      puts 'mouse down'
+    end
+    
+    on_mouse_up do |area_mouse_event|
+      puts 'mouse up'
+    end
+    
+    on_mouse_drag_started do |area_mouse_event|
+      puts 'drag started'
+    end
+    
+    on_mouse_dragged do |area_mouse_event|
+      puts 'dragged'
+    end
+    
+    on_mouse_dropped do |area_mouse_event|
+      puts 'dropped'
+    end
+    
+    on_mouse_entered do
+      puts 'entered'
+    end
+    
+    on_mouse_exited do
+      puts 'exited'
+    end
+  }
+}.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)
@@ -3270,7 +3664,7 @@ window('Area Gallery', 400, 400) {
         fill r: 202, g: 102, b: 104, a: 0.5
         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)
@@ -3280,20 +3674,56 @@ 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
+        
+    on_mouse_event do |area_mouse_event|
+      p area_mouse_event
+    end
+    
+    on_mouse_moved do |area_mouse_event|
+      puts 'moved'
+    end
+    
+    on_mouse_down do |area_mouse_event|
+      puts 'mouse down'
+    end
+    
+    on_mouse_up do |area_mouse_event|
+      puts 'mouse up'
+    end
+    
+    on_mouse_drag_started do |area_mouse_event|
+      puts 'drag started'
+    end
+    
+    on_mouse_dragged do |area_mouse_event|
+      puts 'dragged'
+    end
+    
+    on_mouse_dropped do |area_mouse_event|
+      puts 'dropped'
+    end
+    
+    on_mouse_entered do
+      puts 'entered'
+    end
+    
+    on_mouse_exited do
+      puts 'exited'
+    end
   }
 }.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 4 (setting shape properties instead of arguments with semi-declarative `on_draw` dynamic `path` approach):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -3301,9 +3731,9 @@ require 'glimmer-dsl-libui'
 include Glimmer
 
 window('Area Gallery', 400, 400) {
-  vertical_box {
-    area {
-      path { # declarative stable path
+  area {
+    on_draw do |area_draw_params|
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         square {
           x 0
           y 0
@@ -3317,7 +3747,7 @@ window('Area Gallery', 400, 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 {
           x 0
           y 100
@@ -3333,7 +3763,7 @@ window('Area Gallery', 400, 400) {
         
         fill r: 204, g: 102, b: 204
       }
-      path { # declarative stable path
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         figure {
           x 100
           y 100
@@ -3357,7 +3787,7 @@ window('Area Gallery', 400, 400) {
         fill r: 202, g: 102, b: 104, a: 0.5
         stroke r: 0, g: 0, b: 0
       }
-      path { # declarative stable path
+      path { # a dynamic path is added semi-declaratively inside on_draw block
         figure {
           x 0
           y 0
@@ -3391,9 +3821,9 @@ 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 {
           x_center 200
           y_center 200
@@ -3404,185 +3834,383 @@ 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
       }
-    }
+    end
+        
+    on_mouse_event do |area_mouse_event|
+      p area_mouse_event
+    end
+    
+    on_mouse_moved do |area_mouse_event|
+      puts 'moved'
+    end
+    
+    on_mouse_down do |area_mouse_event|
+      puts 'mouse down'
+    end
+    
+    on_mouse_up do |area_mouse_event|
+      puts 'mouse up'
+    end
+    
+    on_mouse_drag_started do |area_mouse_event|
+      puts 'drag started'
+    end
+    
+    on_mouse_dragged do |area_mouse_event|
+      puts 'dragged'
+    end
+    
+    on_mouse_dropped do |area_mouse_event|
+      puts 'dropped'
+    end
+    
+    on_mouse_entered do
+      puts 'entered'
+    end
+    
+    on_mouse_exited do
+      puts 'exited'
+    end
   }
 }.show
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3:
+### 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
-require 'glimmer-dsl-libui'
+# https://github.com/jamescook/libui-ruby/blob/master/example/histogram.rb
 
-include Glimmer
+require 'libui'
 
-window('Area Gallery', 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
-          square(0, 0, 100)
-          square(100, 100, 400)
-          
-          fill r: 102, g: 102, b: 204
-        }
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
-          rectangle(0, 100, 100, 400)
-          rectangle(100, 0, 400, 100)
+UI = LibUI
 
-          fill r: 204, g: 102, b: 204
-        }
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
-          figure(100, 100) {
-            line(100, 400)
-            line(400, 100)
-            line(400, 400)
+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
 
-            closed true
-          }
+matrix = UI::FFI::DrawMatrix.malloc
 
-          fill r: 202, g: 102, b: 104, a: 0.5
-          stroke r: 0, g: 0, b: 0
-        }
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
-          figure(0, 0) {
-            bezier(200, 100, 100, 200, 400, 100)
-            bezier(300, 100, 100, 300, 100, 400)
-            bezier(100, 300, 300, 100, 400, 400)
+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
 
-            closed true
-          }
+  data = []
+  datapoints.each_with_index do |dp, i|
+    val = 100 - UI.spinbox_value(dp)
+    data << [xincr * i, yincr * val]
+    i += 1
+  end
 
-          fill r: 202, g: 102, b: 204, a: 0.5
-          stroke thickness: 2, r: 0, g: 0, b: 0
-        }
-        path(area_draw_params) { # a dynamic path is added semi-declaratively inside on_draw block
-          arc(200, 200, 90, 0, 360, false)
+  data
+end
 
-          fill r: 202, g: 102, b: 204, a: 0.5
-          stroke thickness: 2, r: 0, g: 0, b: 0
-        }
-      end
-    }
-  }
-}.show
+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
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 4:
+[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
 
-window('Area Gallery', 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
-          square {
-            x 0
-            y 0
-            length 100
-          }
-          square {
-            x 100
-            y 100
-            length 400
-          }
+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]
           
-          fill r: 102, g: 102, b: 204
+          on_changed do
+            @datapoints[i] = sb.value
+            @area.queue_redraw_all
+          end
         }
-        path(area_draw_params) { # 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
-          }
+      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 r: 204, g: 102, b: 204
+          fill 0xFFFFFF
         }
-        path(area_draw_params) { # 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
+        
+        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)
           }
-  
-          fill r: 202, g: 102, b: 104, a: 0.5
-          stroke r: 0, g: 0, b: 0
+          
+          stroke 0x000000, thickness: 2, miter_limit: 10
         }
-        path(area_draw_params) { # 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 thickness: 2, r: 0, g: 0, b: 0
+      
+        # 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)
         }
-        path(area_draw_params) { # 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 thickness: 2, r: 0, g: 0, b: 0
+        
+        # now draw the histogram line
+        graph_path(graph_width, graph_height, false) {
+          stroke @color_button.color.merge(thickness: 2, miter_limit: 10)
         }
       end
     }
@@ -3590,6 +4218,62 @@ window('Area Gallery', 400, 400) {
 }.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
+```
+
 ## Contributing to glimmer-dsl-libui
 
 -   Check out the latest master to make sure the feature hasn't been