glimmer-dsl-libui 0.4.11 → 0.4.15

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.11
+# [<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.15
 ## 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)
@@ -100,7 +100,7 @@ class FormTable
   end
   
   def launch
-    window('Contacts', 600, 600) { |w|
+    window('Contacts', 600, 600) {
       margined true
       
       vertical_box {
@@ -138,8 +138,8 @@ class FormTable
           
           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.')
+            if new_row.map(&:to_s).include?('')
+              msg_box_error('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
@@ -180,10 +180,16 @@ class FormTable
           text_column('State')
     
           editable true
-          cell_rows <=> [self, :contacts] # explicit data-binding to Model Array
+          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}"
+            $stdout.flush # for Windows
+          end
+          
+          on_edited do |row, row_data| # only fires on direct table editing
+            puts "Row #{row} edited: #{row_data}"
+            $stdout.flush # for Windows
           end
         }
       }
@@ -356,6 +362,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)
@@ -495,7 +506,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.4.11'
+gem 'glimmer-dsl-libui', '~> 0.4.15'
 ```
 
 Test that installation worked by running the [Meta-Example](#examples):
@@ -764,7 +775,7 @@ data = [
   ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'],
 ]
 
-window('Contacts', 600, 600) { |w|
+window('Contacts', 600, 600) {
   margined true
   
   vertical_box {
@@ -797,8 +808,8 @@ window('Contacts', 600, 600) { |w|
       
       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.')
+        if new_row.map(&:to_s).include?('')
+          msg_box_error('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
@@ -842,13 +853,21 @@ window('Contacts', 600, 600) { |w|
       
       on_changed do |row, type, row_data|
         puts "Row #{row} #{type}: #{row_data}"
+        $stdout.flush # for Windows
+      end
+      
+      on_edited do |row, row_data| # only fires on direct table editing
+        puts "Row #{row} edited: #{row_data}"
+        $stdout.flush # for Windows
       end
     }
   }
 }.show
 ```
 
-![glimmer-dsl-libui-linux-form-table.png](images/glimmer-dsl-libui-linux-form-table.png)
+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).
 
@@ -926,9 +945,15 @@ Check [examples/basic_scrolling_area.rb](#basic-scrolling-area) for a more detai
 
 #### 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)`
@@ -1014,7 +1039,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).
 
@@ -1033,7 +1059,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
 ```
@@ -1065,6 +1095,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
     }
@@ -1320,13 +1352,16 @@ Note that `area`, `path`, and nested shapes are all truly declarative, meaning t
 - `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)
+- If an event listener is repeated under a control (e.g. two `on_clicked {}` listeners under `button`), it does not overwrite the previous listener, yet it is added to an `Array` of listeners for the event. [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) provides multiple-event-listener support unlike [LibUI](https://github.com/kojix2/LibUI)
 - `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'}}`)
 - `quit_menu_item` has an `on_clicked` listener by default that quits application upon selecting the quit menu item (can be overridden with a manual `on_clicked` implementation that returns integer `0` for success)
 - If an `on_closing` listener was defined on `window` and it does not return an integer, default exit behavior is assumed (`window.destroy` is called followed by `LibUI.quit`, returning `0`).
-- If an `on_clicked` listener was defined on `quit_menu_item` and it does not return an integer, default exit behavior is assumed (`main_window.destroy` is called followed by `LibUI.quit`, returning `0`).
+- If multiple `on_closing` listeners were added for `window`, and none return an integer, they are all executed. On the other hand, if one of them returns an integer, it is counted as the final return value and stops the chain of listener execution.
+- If an `on_clicked` listener was defined on `quit_menu_item` and it does not return an integer, default exit behavior is assumed (`quit_menu_item.destroy` and `main_window.destroy` are called followed by `LibUI.quit`, returning `0`).
+- If multiple `on_clicked` listeners were added for `quit_menu_item`, and none return an integer, they are all executed. On the other hand, if one of them returns an integer, it is counted as the final return value and stops the chain of listener execution.
 - All boolean property readers return `true` or `false` in Ruby instead of the [libui](https://github.com/andlabs/libui) original `0` or `1` in C.
 - All boolean property writers accept `true`/`false` in addition to `1`/`0` in Ruby
 - All string property readers return a `String` object in Ruby instead of the [libui](https://github.com/andlabs/libui) Fiddle pointer object.
@@ -1347,7 +1382,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
@@ -1502,6 +1538,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`
@@ -1542,6 +1580,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:
@@ -1564,6 +1758,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
@@ -1594,11 +1790,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
 
@@ -2925,7 +3123,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:
@@ -2960,7 +3195,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:
@@ -3028,7 +3263,44 @@ 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.
+
+require 'glimmer-dsl-libui'
+
+include Glimmer
+
+IMAGE_ROWS = []
+
+5.times do |i|
+  url = format('https://www.ghibli.jp/gallery/thumb-redturtle%03d.png', (i + 1))
+  puts "Processing Image: #{url}"; $stdout.flush # for Windows
+  text = url.sub('https://www.ghibli.jp/gallery/thumb-redturtle', '').sub('.png', '')
+  IMAGE_ROWS << [[url, text], [url, 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 (automatic construction of `image`):
 
 ```ruby
 # NOTE:
@@ -3402,16 +3674,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}],
@@ -3436,7 +3818,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'
@@ -3738,7 +4120,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
 ```
@@ -3746,8 +4132,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
@@ -3755,7 +4139,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
@@ -3764,8 +4148,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
@@ -3782,7 +4164,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
     }
   }
@@ -3792,8 +4176,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
@@ -3803,7 +4185,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
@@ -5671,7 +6052,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')
@@ -6344,6 +6725,11 @@ window('Editable column animal sounds', 400, 200) {
       }
 
       cell_rows data
+      
+      on_edited do |row, row_data| # only fires on direct table editing
+        puts "Row #{row} edited: #{row_data}"
+        $stdout.flush
+      end
     }
   }
   
@@ -6456,7 +6842,7 @@ class FormTable
   end
   
   def launch
-    window('Contacts', 600, 600) { |w|
+    window('Contacts', 600, 600) {
       margined true
       
       vertical_box {
@@ -6494,8 +6880,8 @@ class FormTable
           
           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.')
+            if new_row.map(&:to_s).include?('')
+              msg_box_error('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
@@ -6536,10 +6922,16 @@ class FormTable
           text_column('State')
     
           editable true
-          cell_rows <=> [self, :contacts] # explicit data-binding to Model Array
+          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}"
+            $stdout.flush # for Windows
+          end
+          
+          on_edited do |row, row_data| # only fires on direct table editing
+            puts "Row #{row} edited: #{row_data}"
+            $stdout.flush # for Windows
           end
         }
       }
@@ -6550,13 +6942,13 @@ end
 FormTable.new.launch
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 2 (with explicit [data-binding](#data-binding)):
 
 ```ruby
 require 'glimmer-dsl-libui'
 
 class FormTable
-  Contact = Struct.new(:name, :email, :phone, :city, :state)
+  Contact = Struct.new(:name, :email, :phone, :city, :state_province)
   
   include Glimmer
   
@@ -6573,7 +6965,7 @@ class FormTable
   end
   
   def launch
-    window('Contacts', 600, 600) { |w|
+    window('Contacts', 600, 600) {
       margined true
       
       vertical_box {
@@ -6611,8 +7003,8 @@ class FormTable
           
           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.')
+            if new_row.map(&:to_s).include?('')
+              msg_box_error('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
@@ -6650,13 +7042,19 @@ class FormTable
           text_column('Email')
           text_column('Phone')
           text_column('City')
-          text_column('State/Province')
+          text_column('State')
     
           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
+          cell_rows <=> [self, :contacts, column_attributes: {'State' => :state_province}] # 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}"
+            $stdout.flush # for Windows
+          end
+          
+          on_edited do |row, row_data| # only fires on direct table editing
+            puts "Row #{row} edited: #{row_data}"
+            $stdout.flush # for Windows
           end
         }
       }
@@ -6667,7 +7065,7 @@ end
 FormTable.new.launch
 ```
 
-New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with explicit [data-binding](#data-binding)):
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version 3 (with explicit [data-binding](#data-binding)):
 
 ```ruby
 
@@ -6691,7 +7089,7 @@ class FormTable
   end
   
   def launch
-    window('Contacts', 600, 600) { |w|
+    window('Contacts', 600, 600) {
       margined true
       
       vertical_box {
@@ -6729,8 +7127,8 @@ class FormTable
           
           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.')
+            if new_row.map(&:to_s).include?('')
+              msg_box_error('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
@@ -6775,6 +7173,12 @@ class FormTable
           
           on_changed do |row, type, row_data|
             puts "Row #{row} #{type}: #{row_data}"
+            $stdout.flush # for Windows
+          end
+          
+          on_edited do |row, row_data| # only fires on direct table editing
+            puts "Row #{row} edited: #{row_data}"
+            $stdout.flush # for Windows
           end
         }
       }
@@ -6806,7 +7210,7 @@ class FormTable
   end
   
   def launch
-    window('Contacts', 600, 600) { |w|
+    window('Contacts', 600, 600) {
       margined true
       
       vertical_box {
@@ -6844,8 +7248,8 @@ class FormTable
           
           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.')
+            if new_row.map(&:to_s).include?('')
+              msg_box_error('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
@@ -6890,6 +7294,12 @@ class FormTable
           
           on_changed do |row, type, row_data|
             puts "Row #{row} #{type}: #{row_data}"
+            $stdout.flush # for Windows
+          end
+          
+          on_edited do |row, row_data| # only fires on direct table editing
+            puts "Row #{row} edited: #{row_data}"
+            $stdout.flush # for Windows
           end
         }
       }
@@ -6915,7 +7325,7 @@ data = [
   ['Melody Hanheimer', 'melody@hanheimer.com', '213-493-8274', 'Los Angeles', 'CA'],
 ]
 
-window('Contacts', 600, 600) { |w|
+window('Contacts', 600, 600) {
   margined true
   
   vertical_box {
@@ -6948,8 +7358,8 @@ window('Contacts', 600, 600) { |w|
       
       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.')
+        if new_row.map(&:to_s).include?('')
+          msg_box_error('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
@@ -6993,6 +7403,12 @@ window('Contacts', 600, 600) { |w|
       
       on_changed do |row, type, row_data|
         puts "Row #{row} #{type}: #{row_data}"
+        $stdout.flush # for Windows
+      end
+      
+      on_edited do |row, row_data| # only fires on direct table editing
+        puts "Row #{row} edited: #{row_data}"
+        $stdout.flush # for Windows
       end
     }
   }