glimmer-dsl-tk 0.0.22 → 0.0.26

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 Tk 0.0.21
+# [<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 Tk 0.0.26
 ## MRI Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-tk.svg)](http://badge.fury.io/rb/glimmer-dsl-tk)
 [![Ruby](https://github.com/AndyObtiva/glimmer-dsl-tk/actions/workflows/ruby.yml/badge.svg)](https://github.com/AndyObtiva/glimmer-dsl-tk/actions/workflows/ruby.yml)
@@ -76,25 +76,28 @@ Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
     - [Supported Widgets](#supported-widgets)
       - [Common Attributes](#common-attributes)
       - [Common Themed Widget States](#common-themed-widget-states)
-    - [Smart Defaults and Convensions](#smart-defaults-and-convensions)
+    - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
       - [Grid Layout](#grid-layout)
       - [Label/Button Image](#labelbutton-image)
       - [Notebook Frame](#notebook-frame)
       - [Icon Photo](#icon-photo)
   - [The Grid Geometry Manager](#the-grid-geometry-manager)
-  - [Bidirectional Data-Binding](#bidirectional-data-binding)
+  - [Data-Binding](#data-binding)
     - [Label Data-Binding](#label-data-binding)
     - [Combobox Data-Binding](#combobox-data-binding)
     - [List Single Selection Data-Binding](#list-single-selection-data-binding)
     - [List Multi Selection Data-Binding](#list-multi-selection-data-binding)
     - [Entry Data-Binding](#entry-data-binding)
-    - [Checkbox Data-Binding](#checkbox-data-binding)
+    - [Spinbox Data-Binding](#spinbox-data-binding)
+    - [Checkbutton Data-Binding](#checkbutton-data-binding)
+    - [Radiobutton Data-Binding](#radiobutton-data-binding)
   - [Command Callback](#command-callback)
   - [Gotchas](#gotchas)
   - [Samples](#samples)
     - [Hello, World!](#hello-world)
     - [Hello, Button!](#hello-button)
     - [Hello, Checkbutton!](#hello-checkbutton)
+    - [Hello, Radiobutton!](#hello-radiobutton)
     - [Hello, Frame!](#hello-frame)
     - [Hello, Root!](#hello-root)
     - [Hello, Notebook!](#hello-notebook)
@@ -103,6 +106,9 @@ Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
     - [Hello, Combobox!](#hello-combobox)
     - [Hello, List Single Selection!](#hello-list-single-selection)
     - [Hello, List Multi Selection!](#hello-list-multi-selection)
+    - [Hello, Entry!](#hello-entry)
+    - [Hello, Text!](#hello-text)
+    - [Hello, Spinbox!](#hello-spinbox)
     - [Hello, Computed!](#hello-computed)
   - [Help](#help)
     - [Issues](#issues)
@@ -140,7 +146,7 @@ gem install glimmer-dsl-tk
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer-dsl-tk', '~> 0.0.21'
+gem 'glimmer-dsl-tk', '~> 0.0.26'
 ```
 
 And, then run:
@@ -250,15 +256,18 @@ root {
 keyword(args) | attributes | event bindings & callbacks
 ------------- | ---------- | ---------
 `button` | `text`, `image` (optional keyword args: `subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`), `compound` (`'center', 'top', 'bottom', 'left', 'right'`), `default` (`'active', 'normal'`) | `command {}`
-`checkbutton` | `text`, `variable` (Boolean), `image` (optional keyword args: `subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`), `compound` (`'center', 'top', 'bottom', 'left', 'right'`), `default` (`'active', 'normal'`) | `command {}`
+`checkbutton` | `text`, `variable` (Boolean), `image` (optional keyword args: `subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`), `compound` (`'center', 'top', 'bottom', 'left', 'right'`), `onvalue` (default: `1`), `offvalue` (default: `0`) | `command {}`
 `combobox` | `state`, `text` | `'ComboboxSelected'`
-`entry` | `width`, `text` | None
+`entry` | `width`, `text`, `validate`, `show` (`'none', 'focus', 'focusin', 'focusout', 'key', or 'all'`) | `'validate'`, `'invalid'`, `'change'`, `validatecommand {}`, `invalidcommand {}`
+`spinbox` | `text`, `from`, `to`, `increment`, `format`, [more attributes](https://tcl.tk/man/tcl8.6/TkCmd/text.htm#M116) | `command {}`, `'increment'`, `'decrement'`
 `frame(text: nil)` | `width`, `height`, `borderwidth`, `relief` (`'flat' (default), 'raised', 'sunken', 'solid', 'ridge', 'groove'`) | None
 `label` | `text`, `image` (optional keyword args: `subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`), `compound` (`'center', 'top', 'bottom', 'left', 'right'`), `font` (`'default', 'text', 'fixed', 'menu', 'heading', 'caption', 'small_caption', 'icon', 'tooltip'`), `relief` (`'flat' (default), 'raised', 'sunken', 'solid', 'ridge', 'groove'`), `justify` (`'left', 'center', 'right'`), `foreground`, `background` | None
 `list` | `selectmode`, `selection` | None
 `message_box(type: , message: , detail: , title: , icon: , default: , parent: )` | None | None
 `notebook` | None | None
+`radiobutton` | `text`, `variable` (Boolean), `image` (optional keyword args: `subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`), `compound` (`'center', 'top', 'bottom', 'left', 'right'`), `value` (default: `text`) | `command {}`
 `root` | `title`, `iconphoto`, `background`, `alpha`, `fullscreen?`, `topmost?`, `transparent?`, `stackorder`, `winfo_screendepth`, `winfo_screenvisual`, `winfo_screenwidth`, `winfo_screenheight`, `winfo_pixels('li')`, `winfo_screen`, `wm_maxsize`, `state` (`'normal', 'iconic', 'withdrawn', 'icon', 'zoomed'`) | `'DELETE_WINDOW'`, `'OPEN_WINDOW'`
+`text` | `text`, [many more attributes](https://tcl.tk/man/tcl8.6/TkCmd/text.htm#M116) | `'modified'`, `'selection'`
 
 #### Common Attributes
 
@@ -308,15 +317,19 @@ keyword(args) | attributes | event bindings & callbacks
 - `invalid?`
 - `hover?`
 
-### Smart Defaults and Convensions
+### Smart Defaults and Conventions
 
 #### Event Bindings
 
-Any events that normally can be accepted by the Tk `bind` or `protocol` methods can be accepted by the `on(event) {}` listener syntax. There is no need to surround event name by `<>` as [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk) automatically takes care of that when needed and leaves out when not needed.
+Any events that normally can be accepted by the Tk `bind` or `protocol` methods can be accepted by the `on(event) {}` listener syntax. For actual (non-virtual) events, there is no need to surround event name by `<>` as [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk) automatically takes care of that when needed and leaves out when not needed.
 
 #### Grid Layout
 
-`grid` layout is the default on most widgets (which support it).
+`grid` layout with `sticky: 'nsew'` is the default on all widgets except toplevel widgets.
+
+Also, any widget that is the first in a series of siblings has `column_weight` as `1` to automatically resize with window resizing by default.
+
+To override that behavior, you may set alternative `grid` keyword args if needed (e.g. `grid sticky: '', column_weight: 0` disables the smart defaults).
 
 #### Label/Button Image
 
@@ -350,6 +363,10 @@ root {
 }.open
 ```
 
+#### Root Background
+
+`root` `background` color attribute is automatically set to `'#ececec'` on the Mac to avoid having a non-native-looking light-colored background.
+
 ## The Grid Geometry Manager
 
 The Grid Geometry Manager is supported via the `grid` keyword just as per the [Tk documentation](https://tkdocs.com/tutorial/grid.html), except by nesting under the widget it concerns.
@@ -368,9 +385,17 @@ Example:
         }
 ```
 
+Extra convenience options may be passed to `grid` when using [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk):
+- `min_width`: alias for `columnminsize` being called on `TkGrid.columnconfigure`
+- `min_height`: alias for `rowminsize` being called on `TkGrid.rowconfigure`
+- `column_weight`: alias for `columnweight` being called on `TkGrid.columnconfigure`
+- `row_weight`: alias for `rowweight` being called on `TkGrid.rowconfigure`
+
+Note also the [Grid Layout](#grid-layout) conventions (e.g. `column_weight` is automatically set to `1` for the first widget in a series of siblings to automatically have all resize when window resize)
+
 More details can be found in the [Hello, Computed!](#hello-computed) sample below.
 
-## Bidirectional Data-Binding
+## Data-Binding
 
 Glimmer supports Shine syntax bidirectional data-binding via the `<=>` operator (read-write) and unidirectional data-binding via the `<=` operator (read-only), which takes a model and an attribute (the `bind` keyword may also be used as the old-style of data-binding).
 
@@ -400,7 +425,7 @@ This assumes a `Person` model with a `country` attribute representing their curr
 
 ```ruby
   combobox {
-    state 'readonly'
+    readonly true # this applies to text editing only (item selection still triggers a write to model)
     text <=> [person, :country]
   }
 ```
@@ -471,9 +496,49 @@ That code binds the `textvariable` value of the `entry` to the `country` attribu
 
 It automatically handles all the Tk plumbing behind the scenes.
 
-More details can be found in the [Hello, Computed!](#hello-computed) sample below.
+More details can be found in [Hello, Entry!](#hello-entry) and [Hello, Computed!](#hello-computed) samples below.
+
+### Spinbox Data-Binding
+
+Example:
+
+This assumes a `Person` model with a `donation` attribute.
+
+```ruby
+  spinbox {
+    from 1.0 # minimum value
+    to 150.0 # maximum value
+    increment 5.0 # increment on up and down
+    format '%0.2f'
+    text <=> [person, :country]
+  }
+```
+
+That code binds the `textvariable` value of the `spinbox` to the `donation` attribute on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes.
+
+More details can be found in [Hello, Spinbox!](#hello-spinbox) sample below.
+
+### Text Data-Binding
 
-### Checkbox Data-Binding
+Example:
+
+This assumes a `Person` model with a `address` attribute.
+
+```ruby
+  text {
+    text <=> [person, :address]
+  }
+```
+
+That code binds the text content of `text` to the `address` attribute on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes (including fine-grained inserts and deletes, abstracting them all away).
+
+More details can be found in [Glimmer Meta-Sample](#samples) below.
+
+### Checkbutton Data-Binding
 
 Example:
 
@@ -489,11 +554,39 @@ That code binds the `variable` value of the `checkbutton` to the boolean `adult`
 
 It automatically handles all the Tk plumbing behind the scenes.
 
+If you need to display a half-checked `checkbutton`, bind to `alternate` attribute.
+
 More details can be found in the [Hello, Checkbutton!](#hello-checkbutton) sample below.
 
+### Radiobutton Data-Binding
+
+Example:
+
+This assumes a `Person` model with boolean `male` and `female` attributes.
+
+```ruby
+  radiobutton {
+    text 'Male'
+    variable <=> [@person, :male]
+  }
+  
+  radiobutton {
+    text 'Female'
+    variable <=> [@person, :female]
+  }
+```
+
+That code binds the `variable` value of the `radiobutton` to the boolean `male` and `female` attributes on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes, including setting the `radiobutton` `value` (uses `text` attribute as `value`), enabling an API that works with simple booleans for each `radiobutton`.
+
+For very rare cases, if you need to display a half-selected `radiobutton`, set `alternate` attribute as `true` when the `variable` value is `false`.
+
+More details can be found in the [Hello, Radiobutton!](#hello-radiobutton) sample below.
+
 ## Command Callback
 
-`button` and `checkbutton` can set a `command` block to trigger when the user clicks the button/checkbutton. This may be done with the `command` keyword, passing in a block directly.
+`button`, `spinbox`, `radiobutton` and `checkbutton` can set a `command` block to trigger when the user clicks the button/checkbutton. This may be done with the `command` keyword, passing in a block directly.
 
 Example:
 
@@ -507,6 +600,18 @@ Example:
   }
 ```
 
+Alternatively, it can be treated as simply an event for consistency with other event bindings:
+
+```ruby
+  button {
+    text "Reset Selection"
+    
+    on('command') do
+      person.reset_country
+    end
+  }
+```
+
 More details can be found in the [Hello, Button!](#hello-button) sample below.
 
 ## Gotchas
@@ -515,6 +620,22 @@ More details can be found in the [Hello, Button!](#hello-button) sample below.
 
 ## Samples
 
+The easiest way to run samples is by launching the Glimmer Meta-Sample (the Sample of Samples).
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/elaborate/meta_sample'"
+```
+
+Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r ./lib/glimmer-dsl-tk.rb samples/elaborate/meta_sample.rb
+```
+
+![glimmer dsl tk screenshot sample meta sample](images/glimmer-dsl-tk-screenshot-sample-elaborate-meta-sample.png)
+
 ### Hello, World!
 
 Glimmer code (from [samples/hello/hello_world.rb](samples/hello/hello_world.rb)):
@@ -542,7 +663,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_world'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_world.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_world.rb
 ```
 
 Glimmer app:
@@ -641,7 +762,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_button'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_button.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_button.rb
 ```
 
 Glimmer app:
@@ -657,13 +778,47 @@ require 'glimmer-dsl-tk'
 
 class HelloCheckbutton
   class Person
-    attr_accessor :skiing, :snowboarding, :snowmobiling, :snowshoeing
+    attr_accessor :skiing, :snowboarding, :snowmobiling, :snowshoeing, :snow_activities, :snow_activities_alternate
     
     def initialize
       reset_activities!
+      individual_observer = Glimmer::DataBinding::Observer.proc do
+        unless @updating_group
+          @updating_individual = true
+          if skiing && snowboarding && snowmobiling && snowshoeing
+            self.snow_activities = true
+            self.snow_activities_alternate = false
+          elsif skiing || snowboarding || snowmobiling || snowshoeing
+            self.snow_activities = true
+            self.snow_activities_alternate = true
+          else
+            self.snow_activities = false
+            self.snow_activities_alternate = false
+          end
+          @updating_individual = false
+        end
+      end
+      individual_observer.observe(self, :skiing)
+      individual_observer.observe(self, :snowboarding)
+      individual_observer.observe(self, :snowmobiling)
+      individual_observer.observe(self, :snowshoeing)
+      
+      group_observer = Glimmer::DataBinding::Observer.proc do
+        unless @updating_individual
+          @updating_group = true
+          self.skiing = self.snow_activities
+          self.snowboarding = self.snow_activities
+          self.snowmobiling = self.snow_activities
+          self.snowshoeing = self.snow_activities
+          @updating_group = false
+        end
+      end
+      group_observer.observe(self, :snow_activities)
     end
     
     def reset_activities!
+      self.snow_activities = true
+      self.snow_activities_alternate = true
       self.skiing = false
       self.snowboarding = true
       self.snowmobiling = false
@@ -689,23 +844,31 @@ class HelloCheckbutton
       
       frame {
         checkbutton {
-          text 'Skiing'
-          variable <=> [@person, :skiing]
-        }
-        
-        checkbutton {
-          text 'Snowboarding'
-          variable <=> [@person, :snowboarding]
-        }
-        
-        checkbutton {
-          text 'Snowmobiling'
-          variable <=> [@person, :snowmobiling]
+          text 'Snow Activities'
+          variable <=> [@person, :snow_activities]
+          alternate <=> [@person, :snow_activities_alternate] # binds half-checked state
         }
         
-        checkbutton {
-          text 'Snowshoeing'
-          variable <=> [@person, :snowshoeing]
+        frame {
+          checkbutton {
+            text 'Skiing'
+            variable <=> [@person, :skiing]
+          }
+          
+          checkbutton {
+            text 'Snowboarding'
+            variable <=> [@person, :snowboarding]
+          }
+          
+          checkbutton {
+            text 'Snowmobiling'
+            variable <=> [@person, :snowmobiling]
+          }
+          
+          checkbutton {
+            text 'Snowshoeing'
+            variable <=> [@person, :snowshoeing]
+          }
         }
       }
       
@@ -732,13 +895,127 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_checkbutton'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_checkbutton.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_checkbutton.rb
 ```
 
 Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello checkbutton](images/glimmer-dsl-tk-screenshot-sample-hello-checkbutton.png)
 
+![glimmer dsl tk screenshot sample hello checkbutton](images/glimmer-dsl-tk-screenshot-sample-hello-checkbutton-all-checked.png)
+
+![glimmer dsl tk screenshot sample hello checkbutton](images/glimmer-dsl-tk-screenshot-sample-hello-checkbutton-none-checked.png)
+
+### Hello, Radiobutton!
+
+Glimmer code (from [samples/hello/hello_radiobutton.rb](samples/hello/hello_radiobutton.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+class HelloRadiobutton
+  class Person
+    attr_accessor :male, :female, :child, :teen, :adult, :senior
+    
+    def initialize
+      reset!
+    end
+    
+    def reset!
+      self.male = true
+      self.female = nil
+      self.child = nil
+      self.teen = nil
+      self.adult = true
+      self.senior = nil
+    end
+  end
+  
+  include Glimmer
+  
+  def initialize
+    @person = Person.new
+  end
+  
+  def launch
+    root {
+      title 'Hello, Radio!'
+      background '#ececec' if OS.mac?
+      
+      label {
+        text 'Gender:'
+        font 'caption'
+      }
+      
+      frame {
+        radiobutton {
+          text 'Male'
+          variable <=> [@person, :male]
+        }
+        
+        radiobutton {
+          text 'Female'
+          variable <=> [@person, :female]
+        }
+      }
+      
+      label {
+        text 'Age Group:'
+        font 'caption'
+      }
+      
+      frame {
+        radiobutton {
+          text 'Child'
+          variable <=> [@person, :child]
+        }
+
+        radiobutton {
+          text 'Teen'
+          variable <=> [@person, :teen]
+        }
+
+        radiobutton {
+          text 'Adult'
+          variable <=> [@person, :adult]
+        }
+
+        radiobutton {
+          text 'Senior'
+          variable <=> [@person, :senior]
+        }
+      }
+      
+      button {
+        text 'Reset'
+        
+        command do
+          @person.reset!
+        end
+      }
+    }.open
+  end
+end
+
+HelloRadiobutton.new.launch
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_radiobutton'"
+```
+
+Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_radiobutton.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello radiobutton](images/glimmer-dsl-tk-screenshot-sample-hello-radiobutton.png)
+
 ### Hello, Frame!
 
 Glimmer code (from [samples/hello/hello_frame.rb](samples/hello/hello_frame.rb)):
@@ -805,7 +1082,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_frame'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_frame.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_frame.rb
 ```
 
 Glimmer app:
@@ -855,7 +1132,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_root'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_root.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_root.rb
 ```
 
 Glimmer app:
@@ -909,7 +1186,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_notebook'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_notebook.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_notebook.rb
 ```
 
 Glimmer app:
@@ -1022,7 +1299,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_label'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_label.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_label.rb
 ```
 
 Glimmer app:
@@ -1124,7 +1401,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_message_box'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_message_box.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_message_box.rb
 ```
 
 Glimmer app:
@@ -1141,12 +1418,12 @@ Glimmer code (from [samples/hello/hello_combobox.rb](samples/hello/hello_combobo
 root {
   title 'Hello, Combobox!'
   
-  combobox { |proxy|
-    state 'readonly'
+  combobox {
+    readonly true # this applies to text editing only (item selection still triggers a write to model)
     text <=> [person, :country]
   }
   
-  button { |proxy|
+  button {
     text "Reset Selection"
     command {
       person.reset_country
@@ -1165,7 +1442,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_combobox'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_combobox.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_combobox.rb
 ```
 
 Glimmer app:
@@ -1205,7 +1482,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_list_single_selection'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_list_single_selection.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_list_single_selection.rb
 ```
 
 Glimmer app:
@@ -1243,13 +1520,302 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_list_multi_selection'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_list_multi_selection.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_list_multi_selection.rb
 ```
 
 Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello list multi selection](images/glimmer-dsl-tk-screenshot-sample-hello-list-multi-selection.png)
 
+### Hello, Entry!
+
+Glimmer code (from [samples/hello/hello_entry.rb](samples/hello/hello_entry.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+class HelloEntry
+  include Glimmer
+  
+  attr_accessor :default, :password, :telephone, :read_only
+  
+  def initialize
+    self.default = 'default'
+    self.password = 'password'
+    self.telephone = '555-555-5555'
+    self.read_only = 'Telephone area code is 555'
+  end
+  
+  def launch
+    root {
+      title 'Hello, Entry!'
+      
+      label {
+        grid sticky: 'ew'
+        text 'default entry'
+      }
+      entry {
+        grid sticky: 'ew'
+        text <=> [self, :default]
+      }
+      
+      label {
+        grid sticky: 'ew'
+        text 'password entry'
+      }
+      entry {
+        grid sticky: 'ew'
+        show '*'
+        text <=> [self, :password]
+      }
+
+      @validated_entry_label = label {
+        grid sticky: 'ew'
+        text 'entry with event handlers'
+      }
+      entry {
+        grid sticky: 'ew'
+        text <=> [self, :telephone]
+        validate 'key'
+
+        ## this event kicks in just after the user typed and before modifying the text variable
+        on('validate') do |new_text_variable|
+          telephone?(new_text_variable.value)
+        end
+
+        ## this event kicks in just after the text variable is validated and before it is modified
+        on('invalid') do |validate_args|
+          @validated_entry_label.text = "#{validate_args.string} is not valid!"
+          @validated_entry_label.foreground = 'red'
+        end
+
+        ## this event kicks in just after the text variable is validated and modified
+        on('change') do |new_text_variable|
+          self.read_only = "Telephone area code is #{new_text_variable.value.gsub(/[^0-9]/, '')[0...3]}"
+          @validated_entry_label.text = 'entry with event handlers'
+          @validated_entry_label.foreground = nil
+        end
+      }
+
+      label {
+        grid sticky: 'ew'
+        text 'read-only entry'
+      }
+      entry {
+        grid sticky: 'ew'
+        text <=> [self, :read_only]
+        readonly true
+      }
+    }.open
+  end
+  
+  def telephone?(text)
+    !!text.match(/^\d{0,3}[-.\/]?\d{0,3}[-.\/]?\d{0,4}$/)
+  end
+end
+
+HelloEntry.new.launch
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_entry'"
+```
+
+Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_entry.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello entry](images/glimmer-dsl-tk-screenshot-sample-hello-entry.png)
+![glimmer dsl tk screenshot sample hello entry validated](images/glimmer-dsl-tk-screenshot-sample-hello-entry-validated.png)
+
+### Hello, Text!
+
+[Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk) automatically provides a `text` attribute for the `text` widget that enables updating its content simply without worrying about whether to manually insert by index, delete, or append.
+
+Glimmer code (from [samples/hello/hello_text.rb](samples/hello/hello_text.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+class HelloText
+  include Glimmer
+  
+  COLOR_OPTIONS = %w[black purple blue green orange yellow red white].map(&:capitalize)
+  FOREGROUND_PROMPT = '<select foreground>'
+  BACKGROUND_PROMPT = '<select background>'
+  
+  def initialize
+    @foreground = FOREGROUND_PROMPT
+    @background = BACKGROUND_PROMPT
+  end
+  
+  attr_accessor :foreground
+  
+  def foreground_options
+    [FOREGROUND_PROMPT] + COLOR_OPTIONS
+  end
+  
+  attr_accessor :background
+  
+  def background_options
+    [BACKGROUND_PROMPT] + COLOR_OPTIONS
+  end
+  
+  def launch
+    root {
+      title 'Hello, Text!'
+      
+      frame {
+        grid row: 0, column: 0
+        
+        combobox {
+          grid row: 0, column: 0, column_weight: 1
+          readonly true
+          text <=> [self, :foreground, after_write: ->(value) { @text.add_selection_format('foreground', value == FOREGROUND_PROMPT ? 'black' : value) }]
+        }
+        
+        combobox {
+          grid row: 0, column: 1, column_weight: 1
+          readonly true
+          text <=> [self, :background, after_write: ->(value) { @text.add_selection_format('background', value == BACKGROUND_PROMPT ? 'black' : value) }]
+        }
+      }
+      
+      @text = text {
+        grid row: 1, column: 0, row_weight: 1
+        text <<~MULTI_LINE_STRING
+          According to the National Post, a heavy metal-loving high school principal in Canada will be allowed to keep her job, days after a public campaign to oust her made headlines around the globe.
+          
+          Parents at Eden High School in St. Catharines, Ontario launched a petition to remove principal Sharon Burns after discovering she's an IRON MAIDEN fan.
+          
+          The petition, titled "Eden High School Principal, Sharon Burns, Needs to Be Transferred Immediately!" read, "We are deeply disturbed that the principal assigned to the school blatantly showed Satanic symbols and her allegiance to Satanic practices on her public social media platforms where all the students can see them under @edenprincipal (not her personal account)."
+          
+          More than 500 people signed the petition to transfer Burns after she posted a picture of herself flashing the "devil horns" hand sign with a doll of the MAIDEN zombie mascot Eddie behind her as well as a personalized license plate reading "IRNMADEN" and a handwritten note that reads "Eddie 666" on a car's dashboard.
+          
+          
+          The number 666 is used to represent the devil, and is featured prominently in MAIDEN's artwork by the band, whose classic third album is titled "The Number Of The Beast".
+          
+          The petition was later updated to state that the demand for her transfer is not because of her love for metal, but for "openly displaying her own handmade sign with the 666 clearly displayed on it".
+          
+          The creator of the original petition wrote: "Sharon knows full well what she did was simply inappropriate, unnecessary and not professional but has yet to publicly admit so and is willing to allow people to believe a completely different story, making very real concerns seem petty."
+          
+          Meanwhile, a counter-petition supporting Burns garnered over 20,000 signatures.
+          
+          "It is ridiculous that a couple of parents judge her role as a principal only based on an Instagram post. (About liking the band IRON MAIDEN. That's it.) Eden High School is a public school. Not a Christian school," the petition titled "We need Mrs Burns" stated. "She has made Eden a safe space for so many people. She spreads nothing but love and kindness."
+          
+          After the complaints were aired, the District School Board of Niagara spoke with Burns and the parents who launched the petition, and the issue is over as far as the board is concerned, Kim Sweeney, the board's chief communications officer, told the National Post. No disciplinary action or policy changes were needed.
+          
+          "Our belief is that taste in music is subjective and we support that both students and staff enjoy a wide variety of genres," Sweeney said.
+          
+          The original petition has since been removed.
+        MULTI_LINE_STRING
+      }
+    }.open
+  end
+end
+
+HelloText.new.launch
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_text'"
+```
+
+Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_text.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello text](images/glimmer-dsl-tk-screenshot-sample-hello-text.png)
+
+### Hello, Spinbox!
+
+Glimmer code (from [samples/hello/hello_spinbox.rb](samples/hello/hello_spinbox.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+class HelloSpinbox
+  class Person
+    attr_accessor :donation
+  end
+  
+  include Glimmer
+  
+  def initialize
+    @person = Person.new
+    @person.donation = 5.0 # in dollars
+  end
+  
+  def launch
+    root {
+      title 'Hello, Spinbox!'
+      
+      label {
+        text 'Please select the amount you would like to donate to the poor:'
+      }
+      
+      frame {
+        label {
+          grid row: 0, column: 0
+          text 'Amount:'
+          font 'caption'
+        }
+        
+        label {
+          grid row: 0, column: 1
+          text '$'
+        }
+        
+        spinbox { |sb|
+          grid row: 0, column: 2
+          from 1.0 # minimum value
+          to 150.0 # maximum value
+          increment 5.0 # increment on up and down
+          format '%0.2f'
+          text <=> [@person, :donation]
+        }
+        
+        label {
+          grid row: 1, column: 0, columnspan: 3
+          text <=> [@person, :donation, on_read: ->(value) { "Thank you for your donation of $#{"%.2f" % value.to_f}"}]
+        }
+
+      }
+    }.open
+  end
+end
+
+HelloSpinbox.new.launch
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_spinbox'"
+```
+
+Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_spinbox.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello spinbox](images/glimmer-dsl-tk-screenshot-sample-hello-spinbox.png)
+
 ### Hello, Computed!
 
 Glimmer code (from [samples/hello/hello_computed.rb](samples/hello/hello_computed.rb)):
@@ -1323,7 +1889,7 @@ ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_computed'"
 Alternatively, run from cloned project without [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
 
 ```
-ruby -r ./lib/glimmer-dsl-tk.rb ./samples/hello/hello_computed.rb
+ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_computed.rb
 ```
 
 Glimmer app: