glimmer-dsl-libui 0.4.10 → 0.4.14

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.4.10
+# [<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.4.14
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -77,6 +77,127 @@ Mac | Windows | Linux
 ----|---------|------
 ![glimmer-dsl-libui-mac-basic-table-progress-bar.png](images/glimmer-dsl-libui-mac-basic-table-progress-bar.png) | ![glimmer-dsl-libui-windows-basic-table-progress-bar.png](images/glimmer-dsl-libui-windows-basic-table-progress-bar.png) | ![glimmer-dsl-libui-linux-basic-table-progress-bar.png](images/glimmer-dsl-libui-linux-basic-table-progress-bar.png)
 
+Form Table
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class FormTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts, :name, :email, :phone, :city, :state, :filter_value
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 600) { |w|
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          entry {
+            label 'Name'
+            text <=> [self, :name] # bidirectional data-binding between entry text and self.name
+          }
+          
+          entry {
+            label 'Email'
+            text <=> [self, :email]
+          }
+          
+          entry {
+            label 'Phone'
+            text <=> [self, :phone]
+          }
+          
+          entry {
+            label 'City'
+            text <=> [self, :city]
+          }
+          
+          entry {
+            label 'State'
+            text <=> [self, :state]
+          }
+        }
+        
+        button('Save Contact') {
+          stretchy false
+          
+          on_clicked do
+            new_row = [name, email, phone, city, state]
+            if new_row.include?('')
+              msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+            else
+              @contacts << Contact.new(*new_row) # automatically inserts a row into the table due to explicit data-binding
+              @unfiltered_contacts = @contacts.dup
+              self.name = '' # automatically clears name entry through explicit data-binding
+              self.email = ''
+              self.phone = ''
+              self.city = ''
+              self.state = ''
+            end
+          end
+        }
+        
+        search_entry {
+          stretchy false
+          # bidirectional data-binding of text to self.filter_value with after_write option
+          text <=> [self, :filter_value,
+            after_write: ->(filter_value) { # execute after write to self.filter_value
+              @unfiltered_contacts ||= @contacts.dup
+              # Unfilter first to remove any previous filters
+              self.contacts = @unfiltered_contacts.dup # affects table indirectly through explicit data-binding
+              # Now, apply filter if entered
+              unless filter_value.empty?
+                self.contacts = @contacts.filter do |contact| # affects table indirectly through explicit data-binding
+                  contact.members.any? do |attribute|
+                    contact[attribute].to_s.downcase.include?(filter_value.downcase)
+                  end
+                end
+              end
+            }
+          ]
+        }
+        
+        table {
+          text_column('Name')
+          text_column('Email')
+          text_column('Phone')
+          text_column('City')
+          text_column('State')
+    
+          editable true
+          cell_rows <=> [self, :contacts] # explicit data-binding to self.contacts Modal Array, auto-inferring model attribute names from underscored table column names by convention
+          
+          on_changed do |row, type, row_data|
+            puts "Row #{row} #{type}: #{row_data}"
+          end
+        }
+      }
+    }.show
+  end
+end
+
+FormTable.new.launch
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-form-table.png](images/glimmer-dsl-libui-mac-form-table.png) | ![glimmer-dsl-libui-windows-form-table.png](images/glimmer-dsl-libui-windows-form-table.png) | ![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
+
 Area Gallery
 
 ```ruby
@@ -235,6 +356,11 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
     - [Custom Keywords](#custom-keywords)
     - [Observer Pattern](#observer-pattern)
     - [Data-Binding](#data-binding)
+      - [Bidirectional (Two-Way) Data-Binding](#bidirectional-two-way-data-binding)
+        - [Table Data-Binding](#table-data-binding)
+      - [Unidirectional (One-Way) Data-Binding](#unidirectional-one-way-data-binding)
+      - [Data-Binding API](#data-binding-api)
+      - [Data-Binding Gotchas](#data-binding-gotchas)
     - [API Gotchas](#api-gotchas)
     - [Original API](#original-api)
   - [Packaging](#packaging)
@@ -374,10 +500,20 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.4.10'
+gem 'glimmer-dsl-libui', '~> 0.4.14'
+```
+
+Test that installation worked by running the [Meta-Example](#examples):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/meta_example'"
 ```
 
-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.
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-meta-example.png](images/glimmer-dsl-libui-mac-meta-example.png) | ![glimmer-dsl-libui-windows-meta-example.png](images/glimmer-dsl-libui-windows-meta-example.png) | ![glimmer-dsl-libui-linux-meta-example.png](images/glimmer-dsl-libui-linux-meta-example.png)
+
+Now to use [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui), 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.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
@@ -452,7 +588,7 @@ Keyword(Args) | Properties | Listeners
 `about_menu_item` | None | `on_clicked`
 `area` | `auto_draw_enabled` | `on_draw(area_draw_params)`, `on_mouse_event(area_mouse_event)`, `on_mouse_down(area_mouse_event)`, `on_mouse_up(area_mouse_event)`, `on_mouse_drag_started(area_mouse_event)`, `on_mouse_dragged(area_mouse_event)`, `on_mouse_dropped(area_mouse_event)`, `on_mouse_entered`, `on_mouse_exited`, `on_key_event(area_key_event)`, `on_key_down(area_key_event)`, `on_key_up(area_key_event)`
 `arc(x_center as Numeric, y_center as Numeric, radius as Numeric, start_angle as Numeric, sweep as Numeric, is_negative as Boolean)` | `x_center` (`Numeric`), `y_center` (`Numeric`), `radius` (`Numeric`), `start_angle` (`Numeric`), `sweep` (`Numeric`), `is_negative` (Boolean) | None
-`background_color_column(name as String)` | None | None
+`background_color_column` | None | None
 `bezier(c1_x as Numeric, c1_y as Numeric, c2_x as Numeric, c2_y as Numeric, end_x as Numeric, end_y as Numeric)` | `c1_x` (`Numeric`), `c1_y` (`Numeric`), `c2_x` (`Numeric`), `c2_y` (`Numeric`), `end_x` (`Numeric`), `end_y` (`Numeric`) | None
 `button(text as String)` | `text` (`String`) | `on_clicked`
 `button_column(name as String)` | `enabled` (Boolean) | None
@@ -616,160 +752,150 @@ Note that the `cell_rows` property declaration results in "implicit data-binding
 - Inserting cell rows: Calling `Array#<<`, `Array#push`, `Array#prepend`, or any insertion/addition `Array` method automatically inserts rows in actual `table` control
 - Changing cell rows: Calling `Array#[]=`, `Array#map!`, or any update `Array` method automatically updates rows in actual `table` control
 
-Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
-
-```ruby
-require 'glimmer-dsl-libui'
-
-class FormTable
-  include Glimmer
-  
-  attr_accessor :name, :email, :phone, :city, :state, :filter_value
-  
-  def initialize
-    @data = [
-      ['Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'],
-      ['Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'],
-      ['Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'],
-      ['Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'],
-      ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'],
-    ]
-  end
-  
-  def launch
-    window('Contacts', 600, 600) { |w|
-      margined true
-      
-      vertical_box {
-        form {
-          stretchy false
-          
-          entry {
-            label 'Name'
-            text <=> [self, :name]
-          }
-          
-          entry {
-            label 'Email'
-            text <=> [self, :email]
-          }
-          
-          entry {
-            label 'Phone'
-            text <=> [self, :phone]
-          }
-          
-          entry {
-            label 'City'
-            text <=> [self, :city]
-          }
-          
-          entry {
-            label 'State'
-            text <=> [self, :state]
-          }
-        }
-        
-        button('Save Contact') {
-          stretchy false
-          
-          on_clicked do
-            new_row = [name, email, phone, city, state]
-            if new_row.include?('')
-              msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
-            else
-              @data << new_row # automatically inserts a row into the table due to implicit data-binding
-              @unfiltered_data = @data.dup
-              self.name = '' # automatically clears name entry through explicit data-binding
-              self.email = ''
-              self.phone = ''
-              self.city = ''
-              self.state = ''
-            end
-          end
-        }
-        
-        search_entry {
-          stretchy false
-          text <=> [self, :filter_value, # bidirectional data-binding of text to self.filter_value with after_write option
-            after_write: ->(filter_value) { # execute after write to self.filter_value
-              @unfiltered_data ||= @data.dup
-              # Unfilter first to remove any previous filters
-              @data.replace(@unfiltered_data) # affects table indirectly through implicit data-binding
-              # Now, apply filter if entered
-              unless filter_value.empty?
-                @data.filter! do |row_data| # affects table indirectly through implicit data-binding
-                  row_data.any? do |cell|
-                    cell.to_s.downcase.include?(filter_value.downcase)
-                  end
-                end
-              end
-            }
-          ]
-        }
-        
-        table {
-          text_column('Name')
-          text_column('Email')
-          text_column('Phone')
-          text_column('City')
-          text_column('State')
-    
-          cell_rows @data # implicit data-binding
-          
-          on_changed do |row, type, row_data|
-            puts "Row #{row} #{type}: #{row_data}"
-          end
-        }
-      }
-    }.show
-  end
-end
-
-FormTable.new.launch
-```
-
-![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
-
-Learn more by checking out [examples](#examples).
-
-### Area API
-
-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 often later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be relatively few stable paths (mostly for decorative reasons).
-- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change very often. Open an `on_draw` listener block that receives an [`area_draw_params`](#area-draw-params) argument and nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
-
-Note that when nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
+([explicit data-binding](#data-binding) supports everything available with implicit data-binding too)
 
-Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
 
 include Glimmer
 
-window('Basic Area', 400, 400) {
+data = [
+  ['Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'],
+  ['Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'],
+  ['Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'],
+  ['Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'],
+  ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'],
+]
+
+window('Contacts', 600, 600) { |w|
   margined true
   
   vertical_box {
-    area {
-      path { # a stable path is added declaratively
-        rectangle(0, 0, 400, 400)
-        
-        fill r: 102, g: 102, b: 204, a: 1.0
+    form {
+      stretchy false
+      
+      @name_entry = entry {
+        label 'Name'
       }
-    }
-  }
-}.show
-```
-
-Mac | Windows | Linux
-----|---------|------
-![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png) | ![glimmer-dsl-libui-windows-basic-area.png](images/glimmer-dsl-libui-windows-basic-area.png) | ![glimmer-dsl-libui-linux-basic-area.png](images/glimmer-dsl-libui-linux-basic-area.png)
-
-Here is the same example using a semi-declarative `area` with `on_draw` listener that receives a [`area_draw_params`](#area-draw-params) argument and a dynamic path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
-
-```ruby
+      
+      @email_entry = entry {
+        label 'Email'
+      }
+      
+      @phone_entry = entry {
+        label 'Phone'
+      }
+      
+      @city_entry = entry {
+        label 'City'
+      }
+      
+      @state_entry = entry {
+        label 'State'
+      }
+    }
+    
+    button('Save Contact') {
+      stretchy false
+      
+      on_clicked do
+        new_row = [@name_entry.text, @email_entry.text, @phone_entry.text, @city_entry.text, @state_entry.text]
+        if new_row.include?('')
+          msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+        else
+          data << new_row # automatically inserts a row into the table due to implicit data-binding
+          @unfiltered_data = data.dup
+          @name_entry.text = ''
+          @email_entry.text = ''
+          @phone_entry.text = ''
+          @city_entry.text = ''
+          @state_entry.text = ''
+        end
+      end
+    }
+    
+    search_entry { |se|
+      stretchy false
+      
+      on_changed do
+        filter_value = se.text
+        @unfiltered_data ||= data.dup
+        # Unfilter first to remove any previous filters
+        data.replace(@unfiltered_data) # affects table indirectly through implicit data-binding
+        # Now, apply filter if entered
+        unless filter_value.empty?
+          data.filter! do |row_data| # affects table indirectly through implicit data-binding
+            row_data.any? do |cell|
+              cell.to_s.downcase.include?(filter_value.downcase)
+            end
+          end
+        end
+      end
+    }
+    
+    table {
+      text_column('Name')
+      text_column('Email')
+      text_column('Phone')
+      text_column('City')
+      text_column('State')
+
+      editable true
+      cell_rows data # implicit data-binding to raw data Array of Arrays
+      
+      on_changed do |row, type, row_data|
+        puts "Row #{row} #{type}: #{row_data}"
+      end
+    }
+  }
+}.show
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-form-table.png](images/glimmer-dsl-libui-mac-form-table.png) | ![glimmer-dsl-libui-windows-form-table.png](images/glimmer-dsl-libui-windows-form-table.png) | ![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
+
+Learn more by checking out [examples](#examples).
+
+### Area API
+
+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 often later on. Simply nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are preserved across redraws assuming there would be relatively few stable paths (mostly for decorative reasons).
+- Semi-declaratively via on_draw listener dynamic paths: useful for more dynamic paths that will definitely change very often. Open an `on_draw` listener block that receives an [`area_draw_params`](#area-draw-params) argument and nest `path` and figures like `rectangle` and all drawing logic is generated automatically. Path proxy objects are destroyed (thrown-away) at the end of drawing, thus having less memory overhead for drawing thousands of dynamic paths.
+
+Note that when nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
+
+Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+window('Basic Area', 400, 400) {
+  margined true
+  
+  vertical_box {
+    area {
+      path { # a stable path is added declaratively
+        rectangle(0, 0, 400, 400)
+        
+        fill r: 102, g: 102, b: 204, a: 1.0
+      }
+    }
+  }
+}.show
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-basic-area.png](images/glimmer-dsl-libui-mac-basic-area.png) | ![glimmer-dsl-libui-windows-basic-area.png](images/glimmer-dsl-libui-windows-basic-area.png) | ![glimmer-dsl-libui-linux-basic-area.png](images/glimmer-dsl-libui-linux-basic-area.png)
+
+Here is the same example using a semi-declarative `area` with `on_draw` listener that receives a [`area_draw_params`](#area-draw-params) argument and a dynamic path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -799,17 +925,23 @@ Check [examples/dynamic_area.rb](#dynamic-area) for a more detailed semi-declara
 - `scroll_to(x as Numeric, y as Numeric, width as Numeric = main_window.width, height as Numeric = main_window.height)`: scrolls to `x`/`y` location with `width` and `height` viewport size.
 - `set_size(width as Numeric, height as Numeric)`: set size of scrolling area, which must must exceed that of visible viewport in order for scrolling to be enabled.
 
-Mac |Linux
-----|-----
-![glimmer-dsl-libui-mac-dynamic-area.png](images/glimmer-dsl-libui-mac-basic-scrolling-area.png) ![glimmer-dsl-libui-mac-dynamic-area-updated.png](images/glimmer-dsl-libui-mac-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-linux-dynamic-area.png](images/glimmer-dsl-libui-linux-basic-scrolling-area.png) ![glimmer-dsl-libui-linux-dynamic-area-updated.png](images/glimmer-dsl-libui-linux-basic-scrolling-area-scrolled.png)
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-dynamic-area.png](images/glimmer-dsl-libui-mac-basic-scrolling-area.png) ![glimmer-dsl-libui-mac-dynamic-area-updated.png](images/glimmer-dsl-libui-mac-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-windows-dynamic-area.png](images/glimmer-dsl-libui-windows-basic-scrolling-area.png) ![glimmer-dsl-libui-windows-dynamic-area-updated.png](images/glimmer-dsl-libui-windows-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-linux-dynamic-area.png](images/glimmer-dsl-libui-linux-basic-scrolling-area.png) ![glimmer-dsl-libui-linux-dynamic-area-updated.png](images/glimmer-dsl-libui-linux-basic-scrolling-area-scrolled.png)
 
 Check [examples/basic_scrolling_area.rb](#basic-scrolling-area) for a more detailed example.
 
 #### Area Path Shapes
 
+`area` can have geometric shapes drawn by adding `path` elements.
+
+To add `path` shapes under an `area`, you can do so:
+- Explicitly: by adding `path` under `area` and nesting shapes (e.g. `rectangle`) underneath that share the same `fill`/`stroke`/`transform` properties
+- Implicitly: by adding shapes directly under `area` when the shapes have unique `fill`/`stroke`/`transform` properties ([Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) automatically constructs `path`s as intermediary parents for shapes directly added under `area`)
+
 `path` can receive a `draw_fill_mode` argument that can accept values `:winding` or `:alternate` and defaults to `:winding`.
 
-Available nested `path` shapes:
+Available `path` shapes (that can be nested explicitly under `path` or implicitly under `area` directly):
 - `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)`
@@ -895,7 +1027,8 @@ Given that it is very new and is not a [libui](https://github.com/andlabs/libui)
 - It only supports the `.png` file format.
 - [libui](https://github.com/andlabs/libui) pixel-by-pixel rendering performance is slow.
 - Including an `image` inside an `area` `on_draw` listener improves performance due to not retaining pixel/line data in memory.
-- Supplying `width` and `height` (2nd and 3rd arguments) greatly improves performance when shrinking image.
+- Supplying `width` and `height` options greatly improves performance when shrinking image (e.g. `image('somefile.png', width: 24, height: 24)`). You can also supply one of the two dimensions, and the other one gets calculated automatically while preserving original aspect ratio (e.g. `image('somefile.png', height: 24)`)
+- [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) lets you optionally specify `x` and `y` in addition to `file`, `width` and `height` (5 arguments total) to offset image location.
 
 Currently, it is recommended to use `image` with very small `width` and `height` values only (e.g. 24x24).
 
@@ -914,7 +1047,11 @@ include Glimmer
 
 window('Basic Image', 96, 96) {
   area {
-    image(File.expand_path('icons/glimmer.png', __dir__), 96, 96)
+    image(File.expand_path('icons/glimmer.png', __dir__), height: 96) # width is automatically calculated from height while preserving original aspect ratio
+#     image(File.expand_path('icons/glimmer.png', __dir__), width: 96, height: 96) # you can specify both width and height options
+#     image(File.expand_path('icons/glimmer.png', __dir__), 96, 96) # you can specify width, height as args
+#     image(File.expand_path('../icons/glimmer.png', __dir__), 0, 0, 96, 96) # you can specify x, y, width, height args as alternative
+#     image(File.expand_path('../icons/glimmer.png', __dir__), x: 0, y: 0, width: 96, height: 96) # you can specify x, y, width, height options as alternative
   }
 }.show
 ```
@@ -946,6 +1083,8 @@ window('Basic Image', 96, 96) {
   area {
     image {
       file File.expand_path('icons/glimmer.png', __dir__)
+#       x 0 # default
+#       y 0 # default
       width 96
       height 96
     }
@@ -1217,6 +1356,7 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 - When destroying a control nested under a `horizontal_box` or `vertical_box`, it is automatically deleted from the box's children
 - When destroying a control nested under a `form`, it is automatically deleted from the form's children
 - When destroying a control nested under a `window` or `group`, it is automatically unset as their child to allow successful destruction
+- When destroying a control that has a data-binding to a model attribute, the data-binding observer registration is automatically deregistered
 - For `date_time_picker`, `date_picker`, and `time_picker`, make sure `time` hash values for `mon`, `wday`, and `yday` are 1-based instead of [libui](https://github.com/andlabs/libui) original 0-based values, and return `dst` as Boolean instead of `isdst` as `1`/`0`
 - Smart defaults for `grid` child properties are `left` (`0`), `top` (`0`), `xspan` (`1`), `yspan` (`1`), `hexpand` (`false`), `halign` (`:fill`), `vexpand` (`false`), and `valign` (`:fill`)
 - The `table` control automatically constructs required `TableModelHandler`, `TableModel`, and `TableParams`, calculating all their arguments from `cell_rows` and `editable` properties (e.g. `NumRows`) as well as nested columns (e.g. `text_column`)
@@ -1227,7 +1367,8 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 - Automatically provide shifted `:key` characters in `area_key_event` provided in `area` key listeners `on_key_event`, `on_key_down`, and `on_key_up`
 - `scrolling_area` `width` and `height` default to main window width and height if not specified.
 - `scrolling_area` `#scroll_to` 3rd and 4th arguments (`width` and `height`) default to main window width and height if not specified.
-- `area` paths are specified declaratively with figures underneath (e.g. `rectangle`) and `area` draw listener is automatically generated
+- `area` paths are specified declaratively with shapes/figures underneath (e.g. `rectangle`), and `area` draw listener is automatically generated
+- `area` path shapes can be added directly under `area` without declaring `path` explicitly as a convenient shorthand
 - 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
 - Observe `text` and `string` properties for changes and automatically redraw containing area accordingly
@@ -1382,6 +1523,8 @@ Data-binding supports utilizing the [MVP (Model View Presenter)](https://en.wiki
 
 ![MVP](https://www.researchgate.net/profile/Gilles-Perrouin/publication/320249584/figure/fig8/AS:668260987068418@1536337243385/Model-view-presenter-architecture.png)
 
+#### Bidirectional (Two-Way) Data-Binding
+
 [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) supports bidirectional (two-way) data-binding of the following controls/properties via the `<=>` operator (indicating data is moving in both directions between View and Model):
 - `checkbox`: `checked`
 - `check_menu_item`: `checked`
@@ -1422,6 +1565,162 @@ entry {
 
 That is data-binding `entered_text` attribute on `self` to `entry` `text` property and printing text after write to the model.
 
+##### Table Data-Binding
+
+One note about `table` `cell_rows` data-binding is that it works with either:
+- Raw data `Array` (rows) of `Array`s (column cells)
+- Model `Array` (rows) of objects having attributes (column cells) matching the underscored names of `table` columns by convention. Model attribute names can be overridden when needed by passing an `Array` enumerating all mapped model attributes in the order of `table` columns or alternatively a `Hash` mapping only the column names that have model attribute names different from their table column underscored version.
+
+Example of `table` implicit data-binding of `cell_rows` to raw data `Array` of `Array`s (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+data = [
+  ['Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'],
+  ['Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'],
+  ['Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'],
+  ['Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'],
+  ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'],
+]
+
+window('Contacts', 600, 600) {
+  table {
+    text_column('Name')
+    text_column('Email')
+    text_column('Phone')
+    text_column('City')
+    text_column('State')
+  
+    cell_rows data
+  }
+}.show
+```
+
+Example of `table` explicit data-binding of `cell_rows` to Model `Array` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class SomeTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 200) {
+      table {
+        text_column('Name')
+        text_column('Email')
+        text_column('Phone')
+        text_column('City')
+        text_column('State')
+  
+        cell_rows <=> [self, :contacts] # explicit data-binding to self.contacts Model Array, auto-inferring model attribute names from underscored table column names by convention
+      }
+    }.show
+  end
+end
+
+SomeTable.new.launch
+```
+
+Example of `table` explicit data-binding of `cell_rows` to Model `Array` with `column_attributes` `Hash` mapping for custom column names (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class SomeTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 200) {
+      table {
+        text_column('Name')
+        text_column('Email')
+        text_column('Phone')
+        text_column('City/Town')
+        text_column('State/Province')
+  
+        cell_rows <=> [self, :contacts, column_attributes: {'City/Town' => :city, 'State/Province' => :state}]
+      }
+    }.show
+  end
+end
+
+SomeTable.new.launch
+```
+
+Example of `table` explicit data-binding of `cell_rows` to Model `Array` with complete `column_attributes` `Array` mapping (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class SomeTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 200) {
+      table {
+        text_column('Full Name')
+        text_column('Email Address')
+        text_column('Phone Number')
+        text_column('City or Town')
+        text_column('State or Province')
+  
+        cell_rows <=> [self, :contacts, column_attributes: [:name, :email, :phone, :city, :state]]
+      }
+    }.show
+  end
+end
+
+SomeTable.new.launch
+```
+
+#### Unidirectional (One-Way) Data-Binding
+
 [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) supports unidirectional (one-way) data-binding of any control/shape/attributed-string property via the `<=` operator (indicating data is moving from the right side, which is the Model, to the left side, which is the GUI View object).
 
 Example of unidirectional data-binding:
@@ -1444,6 +1743,8 @@ window {
 
 That is data-binding the `window` `title` property to the `score` attribute of a `@game`, but converting on read from the Model to a `String`.
 
+#### Data-Binding API
+
 To summarize the data-binding API:
 - `view_property <=> [model, attribute, *read_or_write_options]`: Bidirectional (two-way) data-binding to Model attribute accessor
 - `view_property <= [model, attribute, *read_only_options]`: Unidirectional (one-way) data-binding to Model attribute reader
@@ -1474,11 +1775,13 @@ entry {
 }
 ```
 
-Data-binding gotchas:
+Learn more from data-binding usage in [Login](#login) (4 data-binding versions), [Basic Entry](#basic-entry), [Form](#form), [Form Table](#form-table) (5 data-binding versions), [Method-Based Custom Keyword](#method-based-custom-keyword), [Snake](#snake) and [Tic Tac Toe](#tic_tac_toe) examples.
+
+#### Data-Binding Gotchas
+
 - Never data-bind a control property to an attribute on the same view object with the same exact name (e.g. binding `entry` `text` property to `self` `text` attribute) as it would conflict with it. Instead, data-bind view property to an attribute with a different name on the view object or with the same name, but on a presenter or model object (e.g. data-bind `entry` `text` to `self` `legal_text` attribute or to `contract` model `text` attribute)
 - Data-binding a property utilizes the control's listener associated with the property (e.g. `on_changed` for `entry` `text`), so you cannot hook into the listener directly anymore as that would negate data-binding. Instead, you can add an `after_write: ->(val) {}` option to perform something on trigger of the control listener instead.
-
-Learn more from data-binding usage in [Login](#login) (4 data-binding versions), [Basic Entry](#basic-entry), [Form](#form), [Form Table](#form-table), [Method-Based Custom Keyword](#method-based-custom-keyword), [Snake](#snake) and [Tic Tac Toe](#tic_tac_toe) examples.
+- Data-binding a View control to another View control directly is not a good idea. Instead, data-bind both View controls to the same Presenter/Model attribute, and that keeps them in sync while keeping the code decoupled.
 
 ### API Gotchas
 
@@ -1491,6 +1794,7 @@ Learn more from data-binding usage in [Login](#login) (4 data-binding versions),
 - `table` `progress_bar` column on Windows cannot be updated with a positive value if it started initially with `-1` (it ignores update to avoid crashing due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
 - It seems that [libui](https://github.com/andlabs/libui) does not support nesting multiple `area` controls under a `grid` as only the first one shows up in that scenario. To workaround that limitation, use a `vertical_box` with nested `horizontal_box`s instead to include multiple `area`s in a GUI.
 - As per the code of [examples/basic_transform.rb](#basic-transform), Windows requires different ordering of transforms than Mac and Linux.
+- `scrolling_area#scroll_to` does not seem to work on Windows and Linux, but works fine on Mac
 
 ### Original API
 
@@ -2804,7 +3108,44 @@ UI.main
 UI.quit
 ```
 
-[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (passing file url as image):
+
+```ruby
+# frozen_string_literal: true
+
+# NOTE:
+# This example displays images that can be freely downloaded from the Studio Ghibli website.
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+IMAGE_ROWS = []
+
+50.times do |i|
+  url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
+  puts "Processing Image: #{url}"; $stdout.flush # for Windows
+  IMAGE_ROWS << [url] # array of one column cell
+rescue StandardError => e
+  warn url, e.message
+end
+
+window('The Red Turtle', 310, 350, false) {
+  horizontal_box {
+    table {
+      image_column('www.ghibli.jp/works/red-turtle')
+      
+      cell_rows IMAGE_ROWS
+    }
+  }
+  
+  on_closing do
+    puts 'Bye Bye'
+  end
+}.show
+```
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (automatic construction of `image`):
 
 ```ruby
 # NOTE:
@@ -2839,7 +3180,7 @@ window('The Red Turtle', 310, 350, false) {
 }.show
 ```
 
-[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of `image` from `image_part`):
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (manual construction of `image` from `image_part`):
 
 ```ruby
 # NOTE:
@@ -2907,9 +3248,11 @@ Mac | Windows | Linux
 ----|---------|------
 ![glimmer-dsl-libui-mac-basic-table-image-text.png](images/glimmer-dsl-libui-mac-basic-table-image-text.png) | ![glimmer-dsl-libui-windows-basic-table-image-text.png](images/glimmer-dsl-libui-windows-basic-table-image-text.png) | ![glimmer-dsl-libui-linux-basic-table-image-text.png](images/glimmer-dsl-libui-linux-basic-table-image-text.png)
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (passing file url as image):
 
 ```ruby
+# frozen_string_literal: true
+
 # NOTE:
 # This example displays images that can be freely downloaded from the Studio Ghibli website.
 
@@ -2923,8 +3266,7 @@ IMAGE_ROWS = []
   url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
   puts "Processing Image: #{url}"; $stdout.flush # for Windows
   text = url.sub('https://www.ghibli.jp/gallery/thumb-redturtle', '').sub('.png', '')
-  img = image(url)
-  IMAGE_ROWS << [[img, text], [img, text]] # cell values are dual-element arrays
+  IMAGE_ROWS << [[url, text], [url, text]] # cell values are dual-element arrays
 rescue StandardError => e
   warn url, e.message
 end
@@ -2943,15 +3285,13 @@ window('The Red Turtle', 670, 350) {
 }.show
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of `image` from `image_part`):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (automatic construction of `image`):
 
 ```ruby
 # NOTE:
 # This example displays images that can be freely downloaded from the Studio Ghibli website.
 
 require 'glimmer-dsl-libui'
-require 'chunky_png'
-require 'open-uri'
 
 include Glimmer
 
@@ -2959,9 +3299,47 @@ IMAGE_ROWS = []
 
 5.times do |i|
   url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
-  puts "Processing Image: #{url}"
-  f = URI.open(url)
-  canvas = ChunkyPNG::Canvas.from_io(f)
+  puts "Processing Image: #{url}"; $stdout.flush # for Windows
+  text = url.sub('https://www.ghibli.jp/gallery/thumb-redturtle', '').sub('.png', '')
+  img = image(url)
+  IMAGE_ROWS << [[img, text], [img, text]] # cell values are dual-element arrays
+rescue StandardError => e
+  warn url, e.message
+end
+
+window('The Red Turtle', 670, 350) {
+  horizontal_box {
+    table {
+      image_text_column('image/number')
+      image_text_column('image/number (editable)') {
+        editable true
+      }
+      
+      cell_rows IMAGE_ROWS
+    }
+  }
+}.show
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of `image` from `image_part`):
+
+```ruby
+# NOTE:
+# This example displays images that can be freely downloaded from the Studio Ghibli website.
+
+require 'glimmer-dsl-libui'
+require 'chunky_png'
+require 'open-uri'
+
+include Glimmer
+
+IMAGE_ROWS = []
+
+5.times do |i|
+  url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
+  puts "Processing Image: #{url}"
+  f = URI.open(url)
+  canvas = ChunkyPNG::Canvas.from_io(f)
   f.close
   data = canvas.to_rgba_stream
   width = canvas.width
@@ -3012,22 +3390,28 @@ Mac | Windows | Linux
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 class BasicTableButton
+  BasicAnimal = Struct.new(:name, :sound)
+  
+  class Animal < BasicAnimal
+    def action
+      'delete'
+    end
+  end
+  
   include Glimmer
   
-  attr_accessor :data
+  attr_accessor :animals
   
   def initialize
-    @data = [
-      %w[cat meow delete],
-      %w[dog woof delete],
-      %w[chicken cock-a-doodle-doo delete],
-      %w[horse neigh delete],
-      %w[cow moo delete]
+    @animals = [
+      Animal.new('cat', 'meow'),
+      Animal.new('dog', 'woof'),
+      Animal.new('chicken', 'cock-a-doodle-doo'),
+      Animal.new('horse', 'neigh'),
+      Animal.new('cow', 'moo'),
     ]
   end
   
@@ -3040,17 +3424,19 @@ class BasicTableButton
           button_column('Action') {
             on_clicked do |row|
               # Option 1: direct data deletion is the simpler solution
-#               @data.delete_at(row) # automatically deletes actual table row due to explicit data-binding
+#               @animals.delete_at(row) # automatically deletes actual table row due to explicit data-binding
               
-              # Option 2: cloning only to demonstrate table row deletion upon explicit setting of data attribute (cloning is not recommended beyond demonstrating this point)
-              new_data = @data.clone
-              new_data.delete_at(row)
-              self.data = new_data # automatically loses deleted table row due to explicit data-binding
+              # Option 2: cloning only to demonstrate table row deletion upon explicit setting of animals attribute (cloning is not recommended beyond demonstrating this point)
+              new_animals = @animals.clone
+              new_animals.delete_at(row)
+              self.animals = new_animals # automatically loses deleted table row due to explicit data-binding
             end
           }
     
-          cell_rows <=> [self, :data] # explicit data-binding of table cell_rows to self.data
           
+          cell_rows <= [self, :animals, column_attributes: {'Animal' => :name, 'Description' => :sound}]
+          
+          # explicit unidirectional data-binding of table cell_rows to self.animals
           on_changed do |row, type, row_data|
             puts "Row #{row} #{type}: #{row_data}"
             $stdout.flush
@@ -3273,16 +3659,126 @@ Mac | Windows | Linux
 ----|---------|------
 ![glimmer-dsl-libui-mac-basic-table-color.png](images/glimmer-dsl-libui-mac-basic-table-color.png) | ![glimmer-dsl-libui-windows-basic-table-color.png](images/glimmer-dsl-libui-windows-basic-table-color.png) | ![glimmer-dsl-libui-linux-basic-table-color.png](images/glimmer-dsl-libui-linux-basic-table-color.png)
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding) to model rows using a presenter):
 
 ```ruby
-# frozen_string_literal: true
+require 'glimmer-dsl-libui'
+
+class BasicTableColor
+  Animal = Struct.new(:name, :sound, :mammal)
+  
+  class AnimalPresenter < Animal
+    def name_color
+      color = case name
+      when 'cat'
+        :red
+      when 'dog'
+        :yellow
+      when 'chicken'
+        :beige
+      when 'horse'
+        :purple
+      when 'cow'
+        :gray
+      end
+      [name, color]
+    end
+    
+    def sound_color
+      color = case name
+      when 'cat', 'chicken', 'cow'
+        :blue
+      when 'dog', 'horse'
+        {r: 240, g: 32, b: 32}
+      end
+      [sound, color]
+    end
+    
+    def mammal_description_color
+      color = case name
+      when 'cat', 'dog', 'horse', 'cow'
+        :green
+      when 'chicken'
+        :red
+      end
+      [mammal, 'mammal', color]
+    end
+    
+    def image_description_color
+      color = case name
+      when 'cat', 'dog', 'horse'
+        :dark_blue
+      when 'chicken'
+        :beige
+      when 'cow'
+        :brown
+      end
+      [img, 'Glimmer', color]
+    end
+    
+    def img
+      # scale image to 24x24 (can be passed as file path String only instead of Array to avoid scaling)
+      [File.expand_path('../icons/glimmer.png', __dir__), 24, 24]
+    end
+    
+    def background_color
+      case name
+      when 'cat'
+        {r: 255, g: 120, b: 0, a: 0.5}
+      when 'dog'
+        :skyblue
+      when 'chicken'
+        {r: 5, g: 120, b: 110}
+      when 'horse'
+        '#13a1fb'
+      when 'cow'
+        0x12ff02
+      end
+    end
+  end
+  
+  include Glimmer
+  
+  attr_accessor :animals
+  
+  def initialize
+    @animals = [
+      AnimalPresenter.new('cat', 'meow', true),
+      AnimalPresenter.new('dog', 'woof', true),
+      AnimalPresenter.new('chicken', 'cock-a-doodle-doo', false),
+      AnimalPresenter.new('horse', 'neigh', true),
+      AnimalPresenter.new('cow', 'moo', true),
+    ]
+  end
+  
+  def launch
+    window('Animals', 500, 200) {
+      horizontal_box {
+        table {
+          text_color_column('Animal')
+          text_color_column('Sound')
+          checkbox_text_color_column('Description')
+          image_text_color_column('GUI')
+          background_color_column # must always be the last column and always expects data-binding model attribute `background_color` when binding to Array of models
+    
+          cell_rows <= [self, :animals, column_attributes: {'Animal' => :name_color, 'Sound' => :sound_color, 'Description' => :mammal_description_color, 'GUI' => :image_description_color}]
+        }
+      }
+    }.show
+  end
+end
+
+BasicTableColor.new.launch
+```
 
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (with implicit [data-binding](#data-binding) to raw data rows):
+
+```ruby
 require 'glimmer-dsl-libui'
 
 include Glimmer
 
-img = image(File.expand_path('../icons/glimmer.png', __dir__), 24, 24)
+img = [File.expand_path('../icons/glimmer.png', __dir__), 24, 24] # scales image to 24x24 (can be passed as file path String only instead of Array to avoid scaling)
 
 data = [
   [['cat', :red]      , ['meow', :blue]                  , [true, 'mammal', :green], [img, 'Glimmer', :dark_blue], {r: 255, g: 120, b: 0, a: 0.5}],
@@ -3299,7 +3795,7 @@ window('Animals', 500, 200) {
       text_color_column('Sound')
       checkbox_text_color_column('Description')
       image_text_color_column('GUI')
-      background_color_column('Mammal')
+      background_color_column # must be the last column
 
       cell_rows data
     }
@@ -3307,7 +3803,7 @@ window('Animals', 500, 200) {
 }.show
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (manual construction of [libui](https://github.com/andlabs/libui) `image` from `image_part`):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (with implicit [data-binding](#data-binding) to raw data rows and manual construction of [libui](https://github.com/andlabs/libui) `image` from `image_part`):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -3341,7 +3837,7 @@ window('Animals', 500, 200) {
       text_color_column('Sound')
       checkbox_text_color_column('Description')
       image_text_color_column('GUI')
-      background_color_column('Mammal')
+      background_color_column
 
       cell_rows data
     }
@@ -3483,9 +3979,9 @@ Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/
 ruby -r glimmer-dsl-libui -e "require 'examples/basic_scrolling_area'"
 ```
 
-Mac | Linux
-----|------
-![glimmer-dsl-libui-mac-dynamic-area.png](images/glimmer-dsl-libui-mac-basic-scrolling-area.png) ![glimmer-dsl-libui-mac-dynamic-area-updated.png](images/glimmer-dsl-libui-mac-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-linux-dynamic-area.png](images/glimmer-dsl-libui-linux-basic-scrolling-area.png) ![glimmer-dsl-libui-linux-dynamic-area-updated.png](images/glimmer-dsl-libui-linux-basic-scrolling-area-scrolled.png)
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-dynamic-area.png](images/glimmer-dsl-libui-mac-basic-scrolling-area.png) ![glimmer-dsl-libui-mac-dynamic-area-updated.png](images/glimmer-dsl-libui-mac-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-windows-dynamic-area.png](images/glimmer-dsl-libui-windows-basic-scrolling-area.png) ![glimmer-dsl-libui-windows-dynamic-area-updated.png](images/glimmer-dsl-libui-windows-basic-scrolling-area-scrolled.png) | ![glimmer-dsl-libui-linux-dynamic-area.png](images/glimmer-dsl-libui-linux-basic-scrolling-area.png) ![glimmer-dsl-libui-linux-dynamic-area-updated.png](images/glimmer-dsl-libui-linux-basic-scrolling-area-scrolled.png)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
@@ -3572,6 +4068,8 @@ BasicScrollingArea.new.launch
 
 #### Basic Image
 
+Please note the caveats of [Area Image](#area-image) **(Alpha Feature)** with regards to this example.
+
 [examples/basic_image.rb](examples/basic_image.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -3607,7 +4105,11 @@ window('Basic Image', 96, 96) {
     # image pixel rendered. Check basic_image2.rb for a faster alternative using on_draw manually.
     #
     # It is recommended to pass width/height args to shrink image and achieve faster performance.
-    image(File.expand_path('../icons/glimmer.png', __dir__), 96, 96)
+    image(File.expand_path('../icons/glimmer.png', __dir__), height: 96) # width is automatically calculated from height while preserving original aspect ratio
+#     image(File.expand_path('../icons/glimmer.png', __dir__), width: 96, height: 96) # you can specify both width, height options as alternative
+#     image(File.expand_path('../icons/glimmer.png', __dir__), 96, 96) # you can specify width, height args as alternative
+#     image(File.expand_path('../icons/glimmer.png', __dir__), 0, 0, 96, 96) # you can specify x, y, width, height args as alternative
+#     image(File.expand_path('../icons/glimmer.png', __dir__), x: 0, y: 0, width: 96, height: 96) # you can specify x, y, width, height options as alternative
   }
 }.show
 ```
@@ -3615,8 +4117,6 @@ window('Basic Image', 96, 96) {
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (better performance via `on_draw`):
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3624,7 +4124,7 @@ include Glimmer
 window('Basic Image', 96, 96) {
   area {
     on_draw do |area_draw_params|
-      image(File.expand_path('../icons/glimmer.png', __dir__), 96, 96)
+      image(File.expand_path('../icons/glimmer.png', __dir__), height: 96)
     end
   }
 }.show
@@ -3633,8 +4133,6 @@ window('Basic Image', 96, 96) {
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (explicit properties):
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3651,7 +4149,9 @@ window('Basic Image', 96, 96) {
     # It is recommended to pass width/height args to shrink image and achieve faster performance.
     image {
       file File.expand_path('../icons/glimmer.png', __dir__)
-      width 96
+#       x 0 # default
+#       y 0 # default
+#       width 96 # gets calculated from height while preserving original aspect ratio of 512x512
       height 96
     }
   }
@@ -3661,8 +4161,6 @@ window('Basic Image', 96, 96) {
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 4 (better performance with `on_draw` when setting explicit properties):
 
 ```ruby
-# frozen_string_literal: true
-
 require 'glimmer-dsl-libui'
 
 include Glimmer
@@ -3672,7 +4170,6 @@ window('Basic Image', 96, 96) {
     on_draw do |area_draw_params|
       image {
         file File.expand_path('../icons/glimmer.png', __dir__)
-        width 96
         height 96
       }
     end
@@ -4822,9 +5319,9 @@ Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/
 ruby -r glimmer-dsl-libui -e "require 'examples/button_counter'"
 ```
 
-Mac | Linux
-----|------
-![glimmer-dsl-libui-mac-button-counter.png](images/glimmer-dsl-libui-mac-button-counter.png) | ![glimmer-dsl-libui-linux-button-counter.png](images/glimmer-dsl-libui-linux-button-counter.png)
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-button-counter.png](images/glimmer-dsl-libui-mac-button-counter.png) | ![glimmer-dsl-libui-windows-button-counter.png](images/glimmer-dsl-libui-windows-button-counter.png) | ![glimmer-dsl-libui-linux-button-counter.png](images/glimmer-dsl-libui-linux-button-counter.png)
 
 New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version:
 
@@ -5540,7 +6037,7 @@ Glimmer::LibUI.timer(1) do
   data[0][2] = cpu_percentage_value
 end
 
-window('CPU Percentage', 400, 200) {
+window('CPU Percentage', 400, 50) {
   vertical_box {
     table {
       text_column('Name')
@@ -6263,8 +6760,8 @@ window('Editable animal sounds', 300, 200) {
       text_column('Animal')
       text_column('Description')
 
-      cell_rows data
       editable true
+      cell_rows data
       
       on_changed do |row, type, row_data| # fires on all changes (even ones happening through data array)
         puts "Row #{row} #{type}: #{row_data}"
@@ -6302,7 +6799,359 @@ Mac | Windows | Linux
 ----|---------|------
 ![glimmer-dsl-libui-mac-form-table.png](images/glimmer-dsl-libui-mac-form-table.png) ![glimmer-dsl-libui-mac-form-table-contact-entered.png](images/glimmer-dsl-libui-mac-form-table-contact-entered.png) ![glimmer-dsl-libui-mac-form-table-filtered.png](images/glimmer-dsl-libui-mac-form-table-filtered.png) | ![glimmer-dsl-libui-windows-form-table.png](images/glimmer-dsl-libui-windows-form-table.png) ![glimmer-dsl-libui-windows-form-table-contact-entered.png](images/glimmer-dsl-libui-windows-form-table-contact-entered.png) ![glimmer-dsl-libui-windows-form-table-filtered.png](images/glimmer-dsl-libui-windows-form-table-filtered.png) | ![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png) ![glimmer-dsl-libui-linux-form-table-contact-entered.png](images/glimmer-dsl-libui-linux-form-table-contact-entered.png) ![glimmer-dsl-libui-linux-form-table-filtered.png](images/glimmer-dsl-libui-linux-form-table-filtered.png)
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with [data-binding](#data-binding)):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class FormTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts, :name, :email, :phone, :city, :state, :filter_value
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 600) { |w|
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          entry {
+            label 'Name'
+            text <=> [self, :name] # bidirectional data-binding between entry text and self.name
+          }
+          
+          entry {
+            label 'Email'
+            text <=> [self, :email]
+          }
+          
+          entry {
+            label 'Phone'
+            text <=> [self, :phone]
+          }
+          
+          entry {
+            label 'City'
+            text <=> [self, :city]
+          }
+          
+          entry {
+            label 'State'
+            text <=> [self, :state]
+          }
+        }
+        
+        button('Save Contact') {
+          stretchy false
+          
+          on_clicked do
+            new_row = [name, email, phone, city, state]
+            if new_row.include?('')
+              msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+            else
+              @contacts << Contact.new(*new_row) # automatically inserts a row into the table due to explicit data-binding
+              @unfiltered_contacts = @contacts.dup
+              self.name = '' # automatically clears name entry through explicit data-binding
+              self.email = ''
+              self.phone = ''
+              self.city = ''
+              self.state = ''
+            end
+          end
+        }
+        
+        search_entry {
+          stretchy false
+          # bidirectional data-binding of text to self.filter_value with after_write option
+          text <=> [self, :filter_value,
+            after_write: ->(filter_value) { # execute after write to self.filter_value
+              @unfiltered_contacts ||= @contacts.dup
+              # Unfilter first to remove any previous filters
+              self.contacts = @unfiltered_contacts.dup # affects table indirectly through explicit data-binding
+              # Now, apply filter if entered
+              unless filter_value.empty?
+                self.contacts = @contacts.filter do |contact| # affects table indirectly through explicit data-binding
+                  contact.members.any? do |attribute|
+                    contact[attribute].to_s.downcase.include?(filter_value.downcase)
+                  end
+                end
+              end
+            }
+          ]
+        }
+        
+        table {
+          text_column('Name')
+          text_column('Email')
+          text_column('Phone')
+          text_column('City')
+          text_column('State')
+    
+          editable true
+          cell_rows <=> [self, :contacts] # explicit data-binding to self.contacts Model Array, auto-inferring model attribute names from underscored table column names by convention
+          
+          on_changed do |row, type, row_data|
+            puts "Row #{row} #{type}: #{row_data}"
+          end
+        }
+      }
+    }.show
+  end
+end
+
+FormTable.new.launch
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
+
+```ruby
+require 'glimmer-dsl-libui'
+
+class FormTable
+  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  
+  include Glimmer
+  
+  attr_accessor :contacts, :name, :email, :phone, :city, :state, :filter_value
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 600) { |w|
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          entry {
+            label 'Name'
+            text <=> [self, :name] # bidirectional data-binding between entry text and self.name
+          }
+          
+          entry {
+            label 'Email'
+            text <=> [self, :email]
+          }
+          
+          entry {
+            label 'Phone'
+            text <=> [self, :phone]
+          }
+          
+          entry {
+            label 'City'
+            text <=> [self, :city]
+          }
+          
+          entry {
+            label 'State'
+            text <=> [self, :state]
+          }
+        }
+        
+        button('Save Contact') {
+          stretchy false
+          
+          on_clicked do
+            new_row = [name, email, phone, city, state]
+            if new_row.include?('')
+              msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+            else
+              @contacts << Contact.new(*new_row) # automatically inserts a row into the table due to implicit data-binding
+              @unfiltered_contacts = @contacts.dup
+              self.name = '' # automatically clears name entry through explicit data-binding
+              self.email = ''
+              self.phone = ''
+              self.city = ''
+              self.state = ''
+            end
+          end
+        }
+        
+        search_entry {
+          stretchy false
+          # bidirectional data-binding of text to self.filter_value with after_write option
+          text <=> [self, :filter_value,
+            after_write: ->(filter_value) { # execute after write to self.filter_value
+              @unfiltered_contacts ||= @contacts.dup
+              # Unfilter first to remove any previous filters
+              self.contacts = @unfiltered_contacts.dup # affects table indirectly through explicit data-binding
+              # Now, apply filter if entered
+              unless filter_value.empty?
+                self.contacts = @contacts.filter do |contact| # affects table indirectly through explicit data-binding
+                  contact.members.any? do |attribute|
+                    contact[attribute].to_s.downcase.include?(filter_value.downcase)
+                  end
+                end
+              end
+            }
+          ]
+        }
+        
+        table {
+          text_column('Name')
+          text_column('Email')
+          text_column('Phone')
+          text_column('City')
+          text_column('State/Province')
+    
+          editable true
+          cell_rows <=> [self, :contacts, column_attributes: {'State/Province' => :state}] # explicit data-binding to Model Array with column_attributes mapping for a specific column
+          
+          on_changed do |row, type, row_data|
+            puts "Row #{row} #{type}: #{row_data}"
+          end
+        }
+      }
+    }.show
+  end
+end
+
+FormTable.new.launch
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
+
+```ruby
+
+require 'glimmer-dsl-libui'
+
+class FormTable
+  Contact = Struct.new(:full_name, :email_address, :phone_number, :city_or_town, :state_or_province)
+  
+  include Glimmer
+  
+  attr_accessor :contacts, :name, :email, :phone, :city, :state, :filter_value
+  
+  def initialize
+    @contacts = [
+      Contact.new('Lisa Sky', 'lisa@sky.com', '720-523-4329', 'Denver', 'CO'),
+      Contact.new('Jordan Biggins', 'jordan@biggins.com', '617-528-5399', 'Boston', 'MA'),
+      Contact.new('Mary Glass', 'mary@glass.com', '847-589-8788', 'Elk Grove Village', 'IL'),
+      Contact.new('Darren McGrath', 'darren@mcgrath.com', '206-539-9283', 'Seattle', 'WA'),
+      Contact.new('Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'),
+    ]
+  end
+  
+  def launch
+    window('Contacts', 600, 600) { |w|
+      margined true
+      
+      vertical_box {
+        form {
+          stretchy false
+          
+          entry {
+            label 'Name'
+            text <=> [self, :name] # bidirectional data-binding between entry text and self.name
+          }
+          
+          entry {
+            label 'Email'
+            text <=> [self, :email]
+          }
+          
+          entry {
+            label 'Phone'
+            text <=> [self, :phone]
+          }
+          
+          entry {
+            label 'City'
+            text <=> [self, :city]
+          }
+          
+          entry {
+            label 'State'
+            text <=> [self, :state]
+          }
+        }
+        
+        button('Save Contact') {
+          stretchy false
+          
+          on_clicked do
+            new_row = [name, email, phone, city, state]
+            if new_row.include?('')
+              msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
+            else
+              @contacts << Contact.new(*new_row) # automatically inserts a row into the table due to implicit data-binding
+              @unfiltered_contacts = @contacts.dup
+              self.name = '' # automatically clears name entry through explicit data-binding
+              self.email = ''
+              self.phone = ''
+              self.city = ''
+              self.state = ''
+            end
+          end
+        }
+        
+        search_entry {
+          stretchy false
+          # bidirectional data-binding of text to self.filter_value with after_write option
+          text <=> [self, :filter_value,
+            after_write: ->(filter_value) { # execute after write to self.filter_value
+              @unfiltered_contacts ||= @contacts.dup
+              # Unfilter first to remove any previous filters
+              self.contacts = @unfiltered_contacts.dup # affects table indirectly through explicit data-binding
+              # Now, apply filter if entered
+              unless filter_value.empty?
+                self.contacts = @contacts.filter do |contact| # affects table indirectly through explicit data-binding
+                  contact.members.any? do |attribute|
+                    contact[attribute].to_s.downcase.include?(filter_value.downcase)
+                  end
+                end
+              end
+            }
+          ]
+        }
+        
+        table {
+          text_column('Name')
+          text_column('Email')
+          text_column('Phone')
+          text_column('City')
+          text_column('State')
+    
+          editable true
+          cell_rows <=> [self, :contacts, column_attributes: [:full_name, :email_address, :phone_number, :city_or_town, :state_or_province]] # explicit data-binding to Model Array with column_attributes mapping for all columns
+          
+          on_changed do |row, type, row_data|
+            puts "Row #{row} #{type}: #{row_data}"
+          end
+        }
+      }
+    }.show
+  end
+end
+
+FormTable.new.launch
+```
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 4 (with explicit [data-binding](#data-binding) to raw data):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -6332,7 +7181,7 @@ class FormTable
           
           entry {
             label 'Name'
-            text <=> [self, :name]
+            text <=> [self, :name] # bidirectional data-binding between entry text and self.name
           }
           
           entry {
@@ -6364,8 +7213,8 @@ class FormTable
             if new_row.include?('')
               msg_box_error(w, 'Validation Error!', 'All fields are required! Please make sure to enter a value for all fields.')
             else
-              @data << new_row # automatically inserts a row into the table due to implicit data-binding
-              @unfiltered_data = @data.dup
+              data << new_row # automatically inserts a row into the table due to implicit data-binding
+              @unfiltered_data = data.dup
               self.name = '' # automatically clears name entry through explicit data-binding
               self.email = ''
               self.phone = ''
@@ -6377,14 +7226,15 @@ class FormTable
         
         search_entry {
           stretchy false
-          text <=> [self, :filter_value, # bidirectional data-binding of text to self.filter_value with after_write option
+          # bidirectional data-binding of text to self.filter_value with after_write option
+          text <=> [self, :filter_value,
             after_write: ->(filter_value) { # execute after write to self.filter_value
-              @unfiltered_data ||= @data.dup
+              @unfiltered_data ||= data.dup
               # Unfilter first to remove any previous filters
-              self.data = @unfiltered_data # affects table indirectly through explicit data-binding
+              data.replace(@unfiltered_data) # affects table indirectly through implicit data-binding
               # Now, apply filter if entered
               unless filter_value.empty?
-                self.data = @data.filter do |row_data| # affects table indirectly through explicit data-binding
+                data.filter! do |row_data| # affects table indirectly through implicit data-binding
                   row_data.any? do |cell|
                     cell.to_s.downcase.include?(filter_value.downcase)
                   end
@@ -6400,8 +7250,9 @@ class FormTable
           text_column('Phone')
           text_column('City')
           text_column('State')
-    
-          cell_rows <=> [self, :data] # explicit data-binding
+          
+          editable true
+          cell_rows <=> [self, :data] # explicit data-binding to raw data Array of Arrays
           
           on_changed do |row, type, row_data|
             puts "Row #{row} #{type}: #{row_data}"
@@ -6415,7 +7266,7 @@ end
 FormTable.new.launch
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (without [data-binding](#data-binding)):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 5 (with implicit [data-binding](#data-binding)):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -6503,7 +7354,8 @@ window('Contacts', 600, 600) { |w|
       text_column('City')
       text_column('State')
 
-      cell_rows data # implicit data-binding
+      editable true
+      cell_rows data # implicit data-binding to raw data Array of Arrays
       
       on_changed do |row, type, row_data|
         puts "Row #{row} #{type}: #{row_data}"