glimmer-dsl-tk 0.0.25 → 0.0.29

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.25
+# [<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.29
 ## 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)
@@ -10,11 +10,9 @@
 
 [Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [Tk](https://www.tcl.tk/) enables desktop development with [Glimmer](https://github.com/AndyObtiva/glimmer) in [Ruby](https://github.com/ruby/ruby).
 
-[Tcl/Tk](https://www.tcl.tk/) has recently improved by gaining native looking themed widgets on Mac, Windows, and Linux in [Tk version 8.5](https://www.tcl.tk/software/tcltk/8.5.html#:~:text=Highlights%20of%20Tk%208.5&text=Font%20rendering%3A%20Now%20uses%20anti,and%20window%20layout%2C%20and%20more.).
+[Tcl/Tk](https://www.tcl.tk/) has recently improved by gaining native looking themed widgets on Mac, Windows, and Linux in [Tk version 8.5](https://www.tcl.tk/software/tcltk/8.5.html#:~:text=Highlights%20of%20Tk%208.5&text=Font%20rendering%3A%20Now%20uses%20anti,and%20window%20layout%2C%20and%20more.). Additionally, [Ruby](https://www.ruby-lang.org/en/) 3.0 Ractor (formerly known as [Guilds](https://olivierlacan.com/posts/concurrency-in-ruby-3-with-guilds/)) supports truly parallel multi-threading, making both [MRI](https://github.com/ruby/ruby) and [Tk](https://www.tcl.tk/) finally viable for support in [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library) as an alternative to [JRuby on SWT](https://github.com/AndyObtiva/glimmer-dsl-swt).
 
-Additionally, [Ruby](https://www.ruby-lang.org/en/) 3.0 Ractor (formerly known as [Guilds](https://olivierlacan.com/posts/concurrency-in-ruby-3-with-guilds/)) supports truly parallel multi-threading, making both [MRI](https://github.com/ruby/ruby) and [Tk](https://www.tcl.tk/) finally viable for support in [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library) as an alternative to [JRuby on SWT](https://github.com/AndyObtiva/glimmer-dsl-swt).
-
-The trade-off is that while [SWT](https://www.eclipse.org/swt/) provides a plethora of high quality reusable widgets for the Enterprise (such as [Nebula](https://www.eclipse.org/nebula/)), [Tk](https://www.tcl.tk/) enables very fast app startup time and a small memory footprint via [MRI Ruby](https://www.ruby-lang.org/en/).
+The trade-off is that while [SWT](https://www.eclipse.org/swt/) provides a plethora of high quality reusable widgets for the Enterprise (such as [Nebula](https://github.com/AndyObtiva/glimmer-cw-nebula)), [Tk](https://www.tcl.tk/) has a very fast app startup time and a small memory footprint courtesy of [MRI Ruby](https://www.ruby-lang.org/en/).
 
 [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk) aims to provide a DSL similar to the [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) to enable more productive desktop development in Ruby with:
 - Declarative DSL syntax that visually maps to the GUI widget hierarchy
@@ -76,11 +74,16 @@ 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)
+      - [Text API](#text-api)
+      - [Drag and Drop API](#drag-and-drop-api)
+    - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
       - [Grid Layout](#grid-layout)
-      - [Label/Button Image](#labelbutton-image)
+      - [Image Attribute](#image-attribute)
+      - [Frame Padding](#frame-padding)
       - [Notebook Frame](#notebook-frame)
       - [Icon Photo](#icon-photo)
+      - [Root Background](#root-background)
+      - [Text Defaults](#text-defaults)
   - [The Grid Geometry Manager](#the-grid-geometry-manager)
   - [Data-Binding](#data-binding)
     - [Label Data-Binding](#label-data-binding)
@@ -88,8 +91,8 @@ Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
     - [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)
-    - [Spinbox Data-Binding](#spinbox-data-binding)
     - [Text Data-Binding](#text-data-binding)
+    - [Spinbox Data-Binding](#spinbox-data-binding)
     - [Checkbutton Data-Binding](#checkbutton-data-binding)
     - [Radiobutton Data-Binding](#radiobutton-data-binding)
   - [Command Callback](#command-callback)
@@ -108,8 +111,12 @@ Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
     - [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)
+    - [Hello, Drag and Drop!](#hello-drag-and-drop)
+    - [Hello, Built-in Dialog!](#hello-built-in-dialog)
+    - [Hello, Separator!](#hello-separator)
   - [Help](#help)
     - [Issues](#issues)
     - [Chat](#chat)
@@ -146,7 +153,7 @@ gem install glimmer-dsl-tk
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer-dsl-tk', '~> 0.0.25'
+gem 'glimmer-dsl-tk', '~> 0.0.29'
 ```
 
 And, then run:
@@ -257,8 +264,14 @@ 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'`), `onvalue` (default: `1`), `offvalue` (default: `0`) | `command {}`
+`choose_color(options = nil)` | None | None
+`choose_directory(options = nil)` | None | None
+`choose_font(options = nil) {|font| ... }` | None | None
 `combobox` | `state`, `text` | `'ComboboxSelected'`
 `entry` | `width`, `text`, `validate`, `show` (`'none', 'focus', 'focusin', 'focusout', 'key', or 'all'`) | `'validate'`, `'invalid'`, `'change'`, `validatecommand {}`, `invalidcommand {}`
+`get_multiple_open_file(options = nil)` | None | None
+`get_open_file(options = nil)` | None | None
+`get_save_file(options = nil)` | None | None
 `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
@@ -269,6 +282,9 @@ keyword(args) | attributes | event bindings & callbacks
 `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'`
 
+Options for `get_open_file` and `get_multiple_open_file` include:
+- `filetypes`: `Hash` of `'Group Name' => '.ext'` entries (e.g. `filetypes: {'PNG Images' => '.png'}`
+
 #### Common Attributes
 
 - `grid`: `Hash` of `:row`, `:column`, `:padx`, `:pady`, `:sticky` (`'e', 'w', 'n', 's'` or any combination of direction letters)
@@ -317,7 +333,81 @@ keyword(args) | attributes | event bindings & callbacks
 - `invalid?`
 - `hover?`
 
-### Smart Defaults and Convensions
+#### Text API
+
+The `text` widget is enhanced by [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk) to enable simpler manipulation of text options without dealing with [tags](https://tkdocs.com/tutorial/text.html) directly. Simply specify region to mutate and option/value or font_option/value, and [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk) takes care of the rest by automating work of adding/removing [tags](https://tkdocs.com/tutorial/text.html) behind the scenes.
+
+- `add_format(region_start, region_end, option, value)`
+- `remove_format(region_start, region_end, option, value)`
+- `toggle_format(region_start, region_end, option, value)`
+- `add_font_format(region_start, region_end, font_option, value)`
+- `remove_font_format(region_start, region_end, font_option, value)`
+- `toggle_font_format(region_start, region_end, font_option, value)`
+- `add_selection_format(region_start, region_end, option, value)`
+- `remove_selection_format(region_start, region_end, option, value)`
+- `toggle_selection_format(region_start, region_end, option, value)`
+- `add_selection_font_format(region_start, region_end, font_option, value)`
+- `remove_selection_font_format(region_start, region_end, font_option, value)`
+- `toggle_selection_font_format(region_start, region_end, font_option, value)`
+- `text#insert_image(text_index, *image_args)`: inserts image into `text` `value` content at `text_index` location (e.g. `'insert'`)
+- `text#get_open_file_to_insert_image(text_index = 'insert')`: opens a file dialog to select one of the available image formats and then inserts image into `text` `value` content
+
+Available options:
+
+- `background`
+- `bgstipple`
+- `borderwidth`
+- `elide`
+- `fgstipple`
+- `foreground`
+- `justify`
+- `lmargin1`
+- `lmargin2`
+- `offset`
+- `overstrike`
+- `relief`
+- `rmargin`
+- `spacing1`
+- `spacing2`
+- `spacing3`
+- `tabs`
+- `tabstyle`
+- `underline`
+- `wrap`
+
+Available font options:
+
+- `family` (default: `'Courier New'`)
+- `size` (default: `13`)
+- `weight` (default: `'normal'`) (e.g. `'bold'`)
+- `slant` (default: `'roman'`) (e.g. `'italic`')
+- `underline` (default: `false`)
+- `overstrike` (default: `false`)
+
+Other useful built-in API methods:
+
+- `text_cut`
+- `text_copy`
+- `text_paste`
+- `text_edit_undo`
+- `text_edit_redo`
+
+Check out the [Hello, Text!](#hello-text) sample for a good demonstration of the `text` widget features.
+
+#### Drag and Drop API
+
+Drag and drop works by simply designating a widget as a drag source with attribute `drag_source true`
+
+Alternatively, add listeners:
+- `on_drag_start {|event| ...}`: fires on drag start receiving an `event` arg to set `data` and configure `source`
+- `on_drag_motion {|event| ...}`: fires on drag motion receiving an `event` arg to check `event#drop_accepted`, and configure `source` and `tooltip`
+
+On the drop target, you simply define:
+- `on_drop { |event| ...}`: fires on drop, receiving an `event` arg with `event#target` and `event#data` (set during drag). You can even destroy the `event#source` if you want to get rid of the dragged widget.
+
+Learn more at the [Hello, Drag and Drop!](#hello-drag-and-drop) sample.
+
+### Smart Defaults and Conventions
 
 #### Event Bindings
 
@@ -325,11 +415,25 @@ Any events that normally can be accepted by the Tk `bind` or `protocol` methods
 
 #### 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).
+
+#### Image Attribute
+
+Widget `image` attribute (e.g. `label` `image`) can accept image path directly as an alternative to `TkPhotoImage` object in addition to key values for automatic processing of image:
+- `subsample(x_divider, y_divider)`: Specifies that the source image should be reduced in size by using only every xth pixel in the X direction and yth pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If y is not given, the default value is the same as x.
+- `zoom(x_multiplier, y_multiplier)`:  Specifies that the source region should be magnified by a factor of x in the X direction and y in the Y direction. If y is not given, the default value is the same as x. With this option, each pixel in the source image will be expanded into a block of x x y pixels in the destination image, all the same color. x and y must be greater than 0.
+- `from(x1, y1, x2, y2)`: Specifies a rectangular sub-region of the source image to be copied. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the :from option is not given, the default is the whole source image.
+- `to(x1, y1, x2, y2)`: Specifies a rectangular sub-region of the destination image to be affected. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is (x1,y1) plus the size of the source region (after subsampling and zooming, if specified). If x2 and  y2 are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion.
+- `shrink`: Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the :width or :height configuration option, respectively.
+- `compositingrule` (can be `'overlay'` or `'set'`): Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of <tt>overlay</tt> is set, the old  contents of the destination image are visible, as if the source image were  printed on a piece of transparent film and placed over the top of the  destination. When a compositing rule of <tt>set</tt> is set, the old contents of  the destination image are discarded and the source image is used as-is. The default compositing rule is <tt>overlay</tt>.
 
-#### Label/Button Image
+#### Frame Padding
 
-Label and Button `image` attribute can accept image path directly as an alternative to `TkPhotoImage` object in addition to key values for automatic processing of image (`subsample`, `zoom`, `from`, `to`, `shrink`, `compositingrule`)
+Frames have a padding of `15` all around by default to produce more user-friendly graphical user interfaces.
 
 #### Notebook Frame
 
@@ -359,6 +463,16 @@ 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.
+
+#### Text Defaults
+
+`text` widget has these defaults:
+- `wrap = 'none'`
+- `font = {family: 'Courier New'}`
+
 ## 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.
@@ -377,9 +491,19 @@ Example:
         }
 ```
 
+Extra convenience options may be passed to `grid` when using [Glimmer DSL for Tk](https://rubygems.org/gems/glimmer-dsl-tk):
+- `column_span`: alias for `columnspan` keyword arg
+- `row_span`: alias for `rowspan` keyword arg
+- `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).
 
@@ -409,7 +533,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]
   }
 ```
@@ -482,45 +606,45 @@ It automatically handles all the Tk plumbing behind the scenes.
 
 More details can be found in [Hello, Entry!](#hello-entry) and [Hello, Computed!](#hello-computed) samples below.
 
-### Spinbox Data-Binding
+### Text Data-Binding
 
 Example:
 
-This assumes a `Person` model with a `donation` attribute.
+This assumes a `Person` model with a `biography` 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]
+  text {
+    value <=> [person, :biography]
   }
 ```
 
-That code binds the `textvariable` value of the `spinbox` to the `donation` attribute on the `person` model.
+That code binds the `value` of `text` to the `biography` 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.
+More details can be found in [Hello, Text!](#hello-text) sample below.
 
-### Text Data-Binding
+### Spinbox Data-Binding
 
 Example:
 
-This assumes a `Person` model with a `address` attribute.
+This assumes a `Person` model with a `donation` attribute.
 
 ```ruby
-  text {
-    text <=> [person, :address]
+  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 text content of `text` to the `address` attribute on the `person` model.
+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 (including fine-grained inserts and deletes, abstracting them all away).
+It automatically handles all the Tk plumbing behind the scenes.
 
-More details can be found in [Glimmer Meta-Sample](#samples) below.
+More details can be found in [Hello, Spinbox!](#hello-spinbox) sample below.
 
 ### Checkbutton Data-Binding
 
@@ -570,7 +694,7 @@ More details can be found in the [Hello, Radiobutton!](#hello-radiobutton) sampl
 
 ## 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:
 
@@ -584,6 +708,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
@@ -608,6 +744,128 @@ 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)
 
+Code:
+
+```ruby
+require 'glimmer-dsl-tk'
+require 'facets'
+require 'fileutils'
+
+class MetaSample
+  include Glimmer
+  
+  attr_accessor :selected_sample_index
+  
+  def initialize
+    @selected_sample_index = 0
+  end
+  
+  def samples
+    if @samples.nil?
+      sample_files = Dir.glob(File.join(File.expand_path('../hello', __dir__), '**', 'hello_*.rb'))
+      sample_file_names = sample_files.map { |f| File.basename(f, '.rb') }
+      sample_file_names = sample_file_names.reject { |f| f == 'meta_sample' || f.match(/\d$/) }
+      @samples = sample_file_names.map { |f| f.underscore.titlecase }
+    end
+    @samples
+  end
+  
+  def file_path_for(sample)
+    File.join(File.expand_path('../hello', __dir__), "#{sample.underscore}.rb")
+  end
+  
+  def glimmer_dsl_tk_file
+    File.expand_path('../../lib/glimmer-dsl-tk', __dir__)
+  end
+  
+  def selected_sample
+    samples[@selected_sample_index]
+  end
+  
+  def run_sample(sample)
+    Thread.new do
+      command = "ruby -r #{glimmer_dsl_tk_file} #{sample} 2>&1"
+      result = ''
+      IO.popen(command) do |f|
+        f.each_line do |line|
+          result << line
+          puts line
+          $stdout.flush
+        end
+      end
+      ::Tk.after(100) do
+        message_box(parent: @root, title: 'Error Running Sample', message: result) if result.downcase.include?('error')
+      end
+    end
+  end
+  
+  def launch
+    @root = root {
+      title 'Glimmer Meta-Sample'
+      width 1280
+      height 720
+      
+      frame {
+        grid row: 0, column: 0, column_weight: 0, row_weight: 1
+        
+        samples.each_with_index do |sample, index|
+          radiobutton {
+            text sample
+            variable <=> [self, :selected_sample_index, on_write: ->(v) {v ? index : selected_sample_index}, on_read: ->(v) {v == index}]
+            
+            on('command') do
+              @selected_sample_index = index
+              @code_text.value = File.read(file_path_for(selected_sample))
+            end
+          }
+        end
+        
+        frame {
+          button {
+            grid row: 0, column: 0
+            text 'Launch'
+            
+            on('command') do
+              begin
+                parent_dir = File.join(Dir.home, '.glimmer-dsl-tk', 'samples', 'hello')
+                FileUtils.mkdir_p(parent_dir)
+                sample_file = File.join(parent_dir, "#{selected_sample.underscore}.rb")
+                File.write(sample_file, @code_text.value)
+                FileUtils.cp_r(File.expand_path('../../icons', __dir__), File.dirname(File.dirname(parent_dir)))
+                FileUtils.cp_r(File.expand_path('../hello/images', __dir__), parent_dir)
+                sample_namespace_directory = File.expand_path("../hello/#{selected_sample.underscore}", __dir__)
+                FileUtils.cp_r(sample_namespace_directory, parent_dir) if Dir.exist?(sample_namespace_directory)
+                run_sample(sample_file)
+              rescue => e
+                puts e.full_message
+                puts 'Unable to write code changes! Running original sample...'
+                run_sample(file_path_for(selected_sample))
+              end
+            end
+          }
+          button {
+            grid row: 0, column: 1
+            text 'Reset'
+            
+            on('command') do
+              @code_text.value = File.read(file_path_for(selected_sample))
+            end
+          }
+        }
+      }
+      
+      @code_text = text {
+        grid row: 0, column: 1, column_weight: 1
+        value File.read(file_path_for(selected_sample))
+      }
+    }
+    @root.open
+  end
+end
+
+MetaSample.new.launch
+```
+
 ### Hello, World!
 
 Glimmer code (from [samples/hello/hello_world.rb](samples/hello/hello_world.rb)):
@@ -1168,6 +1426,8 @@ Glimmer app:
 
 ### Hello, Label!
 
+Icons used in this sample were made by <a href="https://www.flaticon.com/authors/freepik" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon"> www.flaticon.com</a>
+
 Glimmer code (from [samples/hello/hello_label.rb](samples/hello/hello_label.rb)):
 
 ```ruby
@@ -1297,8 +1557,6 @@ root { |r|
   title 'Hello, Message Box!'
   
   frame {
-    grid sticky: 'nsew', padx: 15, pady: 15
-    
     button {
       text 'Please Click To Win a Surprise'
       
@@ -1350,8 +1608,6 @@ root { |r|
   }
   
   frame {
-    grid sticky: 'nsew', padx: 15, pady: 15
-    
     label {
       grid row: 0, column: 0
       text 'Result:'
@@ -1379,7 +1635,6 @@ ruby -r ./lib/glimmer-dsl-tk.rb samples/hello/hello_message_box.rb
 Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello message box](images/glimmer-dsl-tk-screenshot-sample-hello-message-box.png)
-![glimmer dsl tk screenshot sample hello message box open](images/glimmer-dsl-tk-screenshot-sample-hello-message-box-open.png)
 
 ### Hello, Combobox!
 
@@ -1390,12 +1645,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
@@ -1499,86 +1754,6 @@ Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello list multi selection](images/glimmer-dsl-tk-screenshot-sample-hello-list-multi-selection.png)
 
-### Hello, Computed!
-
-Glimmer code (from [samples/hello/hello_computed.rb](samples/hello/hello_computed.rb)):
-
-```ruby
-# ... more code precedes
-    root {
-      title 'Hello, Computed!'
-      
-      frame {
-        grid column: 0, row: 0, padx: 5, pady: 5
-        
-        label {
-          grid column: 0, row: 0, sticky: 'w'
-          text 'First Name: '
-        }
-        entry {
-          grid column: 1, row: 0
-          width 15
-          text <=> [@contact, :first_name]
-        }
-        
-        label {
-          grid column: 0, row: 1, sticky: 'w'
-          text 'Last Name: '
-        }
-        entry {
-          grid column: 1, row: 1
-          width 15
-          text <=> [@contact, :last_name]
-        }
-        
-        label {
-          grid column: 0, row: 2, sticky: 'w'
-          text 'Year of Birth: '
-        }
-        entry {
-          grid column: 1, row: 2
-          width 15
-          text <=> [@contact, :year_of_birth]
-        }
-        
-        label {
-          grid column: 0, row: 3, sticky: 'w'
-          text 'Name: '
-        }
-        label {
-          grid column: 1, row: 3, sticky: 'w'
-          text <=> [@contact, :name, computed_by: [:first_name, :last_name]]
-        }
-        
-        label {
-          grid column: 0, row: 4, sticky: 'w'
-          text 'Age: '
-        }
-        label {
-          grid column: 1, row: 4, sticky: 'w'
-          text <=> [@contact, :age, on_write: :to_i, computed_by: [:year_of_birth]]
-        }
-      }
-    }.open
-# ... more code follows
-```
-
-Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
-
-```
-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
-```
-
-Glimmer app:
-
-![glimmer dsl tk screenshot sample hello computed](images/glimmer-dsl-tk-screenshot-sample-hello-computed.png)
-
 ### Hello, Entry!
 
 Glimmer code (from [samples/hello/hello_entry.rb](samples/hello/hello_entry.rb)):
@@ -1603,7 +1778,7 @@ class HelloEntry
       title 'Hello, Entry!'
       
       label {
-        grid sticky: 'ew', column_weight: 1
+        grid sticky: 'ew'
         text 'default entry'
       }
       entry {
@@ -1686,6 +1861,234 @@ 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!
+
+Icons used in this sample were made by <a href="https://www.flaticon.com/authors/freepik" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon"> www.flaticon.com</a>
+
+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)
+  FONT_FAMILY_OPTIONS = ::TkFont.families
+  FOREGROUND_PROMPT = '<foreground>'
+  BACKGROUND_PROMPT = '<background>'
+  FONT_FAMILY_PROMPT = '<font family>'
+  FONT_SIZE_PROMPT = '<font size>'
+  
+  def initialize
+    @foreground = FOREGROUND_PROMPT
+    @background = BACKGROUND_PROMPT
+    @font_family = FONT_FAMILY_PROMPT
+    @font_size = FONT_SIZE_PROMPT
+  end
+  
+  attr_accessor :foreground
+  
+  def foreground_options
+    [FOREGROUND_PROMPT] + COLOR_OPTIONS
+  end
+  
+  attr_accessor :background
+  
+  def background_options
+    [BACKGROUND_PROMPT] + COLOR_OPTIONS
+  end
+  
+  attr_accessor :font_family
+  
+  def font_family_options
+    [FONT_FAMILY_PROMPT] + FONT_FAMILY_OPTIONS
+  end
+  
+  attr_accessor :font_size
+  
+  def font_size_options
+    [FONT_SIZE_PROMPT] + (9..64).to_a.map(&:to_s)
+  end
+  
+  def launch
+    root {
+      title 'Hello, Text!'
+      
+      frame {
+        grid row: 0, column: 0
+        
+        column_index = -1
+        
+        combobox {
+          grid row: 0, column: column_index += 1, column_weight: 1
+          readonly true
+          text <=> [self, :font_family, after_write: ->(value) { @text.toggle_selection_font_format('family', value == FONT_FAMILY_PROMPT ? 'Courier New' : value) }]
+        }
+        
+        combobox {
+          grid row: 0, column: column_index += 1, column_weight: 1
+          readonly true
+          text <=> [self, :font_size, after_write: ->(value) { @text.toggle_selection_font_format('size', value == FONT_SIZE_PROMPT ? 13 : value) }]
+        }
+        
+        combobox {
+          grid row: 0, column: column_index += 1, 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: column_index += 1, column_weight: 1
+          readonly true
+          text <=> [self, :background, after_write: ->(value) { @text.add_selection_format('background', value == BACKGROUND_PROMPT ? 'white' : value) }]
+        }
+        
+        separator {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          orient 'vertical'
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          text 'B'
+          style font: {weight: 'bold'}
+          
+          on('command') do
+            @text.toggle_selection_font_format('weight', 'bold')
+          end
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          text 'I'
+          style font: {slant: 'italic'}
+          
+          on('command') do
+            @text.toggle_selection_font_format('slant', 'italic')
+          end
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          text 'U'
+          style font: {underline: true}
+          
+          on('command') do
+            @text.toggle_selection_font_format('underline', true)
+          end
+        }
+        
+        separator {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          orient 'vertical'
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          image File.expand_path("images/cut.png", __dir__), subsample: 32
+          
+          on('command') do
+            @text.text_cut
+          end
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          image File.expand_path("images/copy.png", __dir__), subsample: 32
+          
+          on('command') do
+            @text.text_copy
+          end
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          image File.expand_path("images/paste.png", __dir__), subsample: 32
+          
+          on('command') do
+            @text.text_paste
+          end
+        }
+        
+        separator {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          orient 'vertical'
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          image File.expand_path("images/undo.png", __dir__), subsample: 32
+          
+          on('command') do
+            @text.edit_undo
+          end
+        }
+        
+        button {
+          grid row: 0, column: column_index += 1, column_weight: 0
+          image File.expand_path("images/redo.png", __dir__), subsample: 32
+          
+          on('command') do
+            @text.edit_redo
+          end
+        }
+      }
+      
+      @text = text {
+        grid row: 1, column: 0, row_weight: 1
+        wrap 'word'
+        undo true
+        value <<~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)):
@@ -1843,6 +2246,315 @@ Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello computed](images/glimmer-dsl-tk-screenshot-sample-hello-computed.png)
 
+### Hello, Drag and Drop!
+
+Glimmer code (from [samples/hello/hello_drag_and_drop.rb](samples/hello/hello_drag_and_drop.rb)):
+
+```ruby
+require "glimmer-dsl-tk"
+require "glimmer/tk/drag_and_drop_extension"
+
+include Glimmer
+
+root {
+  title "Hello, Drag and Drop!"
+  frame {
+    padding 5
+    labelframe {
+      text "Drag sources"
+      padding 5
+      label {
+        text "Entry"
+        grid :row => 0, :column => 0
+      }
+      entry {
+        text "Drag entry text"
+        width 30
+        grid :row => 0, :column => 1, :pady => 5, :sticky => "e"
+        on_drag_start { |event|
+          event.data = event.source.textvariable&.value
+          event.source.configure(:cursor => "hand2")
+          TkLabel.new(event.tooltip) {
+            text event.data + " "
+            bg "yellow"
+            bitmap "warning"
+            compound "right"
+          }.pack
+        }
+        on_drag_motion { |event|
+          if event.drop_accepted
+            event.source.configure(:cursor => "hand1")
+          else
+            event.source.configure(:cursor => "hand2")
+          end
+          event.tooltip.geometry("+#{event.x_root + 10}+#{event.y_root - 4}")
+        }
+      }
+      label {
+        text "Label"
+        grid :row => 1, :column => 0
+      }
+      label {
+        text "Drag label text"
+        width 30
+        grid :row => 1, :column => 1, :pady => 10, :sticky => "e"
+        drag_source true
+      }
+      label {
+        text "Combobox"
+        grid :row => 2, :column => 0
+      }
+      combobox {
+        text "Spain"
+        values %w[USA Canada Mexico Columbia UK Australia Germany Italy Spain]
+        width 27
+        grid :row => 2, :column => 1, :pady => 5, :sticky => "e"
+        on_drag_start { |event|
+          event.data = event.source.textvariable&.value
+        }
+      }
+      label {
+        text "Button"
+        grid :row => 3, :column => 0
+      }
+      button {
+        text "Drag it"
+        grid :row => 3, :column => 1, :pady => 5, :sticky => "w"
+        drag_source true
+      }
+    }
+
+    labelframe {
+      text "Drop targets"
+      grid :sticky => "nsew", :pady => 15
+      padding 5
+      label {
+        text "Entry"
+        grid :row => 0, :column => 0
+      }
+      entry {
+        width 30
+        grid :row => 0, :column => 1, :pady => 5, :sticky => "e"
+        on_drop { |event|
+          event.target.textvariable.value = event.data
+        }
+      }
+      label {
+        text "Label"
+        grid :row => 1, :column => 0
+      }
+      label {
+        width 30
+        grid :row => 1, :column => 1, :pady => 10, :sticky => "e"
+        borderwidth 2
+        relief "solid"
+        on_drop { |event|
+          event.target.textvariable.value = event.data
+        }
+      }
+      label {
+        text "Combobox"
+        grid :row => 2, :column => 0
+      }
+      combobox {
+        width 27
+        grid :row => 2, :column => 1, :pady => 5, :sticky => "e"
+        on_drop { |event|
+          event.target.textvariable.value = event.data
+        }
+      }
+      label {
+        text "Button"
+        grid :row => 3, :column => 0
+      }
+      button {
+        text "Drop here"
+        grid :row => 3, :column => 1, :pady => 5, :sticky => "w"
+        on_drop { |event|
+          event.target.text = event.data
+        }
+      }
+      label {
+        text "Checkbutton"
+        grid :row => 4, :column => 0
+      }
+      checkbutton {
+        text "Drop here to destroy a widget\n(except button)"
+        grid :row => 4, :column => 1, :pady => 5, :sticky => "w"
+        on_drop { |event|
+          event.target.text = event.data
+          event.source.destroy unless event.source.is_a? Tk::Button
+        }
+      }
+    }
+  }
+}.open
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_drag_and_drop'"
+```
+
+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_drag_and_drop.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello drag and drop](images/glimmer-dsl-tk-screenshot-sample-hello-drag-and-drop.png)
+
+### Hello, Built-in Dialog!
+
+Glimmer code (from [samples/hello/hello_built_in_dialog.rb](samples/hello/hello_built_in_dialog.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+include Glimmer
+
+root { |w|
+  title 'Hello, Built-in Dialog!'
+  width 400
+  height 400
+  x 150
+  y 150
+  
+  frame {
+    %w[get_open_file get_multiple_open_file get_save_file choose_directory choose_color].each do |dialog|
+      button {
+        text dialog.split('_').map(&:capitalize).join(' ')
+        
+        on('command') do
+          result = send(dialog, parent: w)
+          @result_label.text = [result].flatten.join("\n")
+        end
+      }
+    end
+    
+    button {
+      text 'Choose Font'
+      
+      on('command') do
+        choose_font(family: 'Courier New', size: '30', weight: 'bold') do |chosen_font|
+          @result_label.text = chosen_font(parent: w)
+        end
+      end
+    }
+  }
+  
+  frame {
+    grid sticky: 'nsew', padx: 15, pady: 15
+    
+    label {
+      grid row: 0, column: 0
+      text 'Result:'
+    }
+    
+    @result_label = label {
+      grid row: 0, column: 1
+    }
+  }
+}.open
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_built_in_dialog'"
+```
+
+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_built_in_dialog.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello built in dialog 1](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-get-open-file.png)
+![glimmer dsl tk screenshot sample hello built in dialog 2](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-get-open-file-done.png)
+
+![glimmer dsl tk screenshot sample hello built in dialog 3](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-choose-color.png)
+![glimmer dsl tk screenshot sample hello built in dialog 4](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-choose-color-done.png)
+
+![glimmer dsl tk screenshot sample hello built in dialog 5](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-choose-font.png)
+![glimmer dsl tk screenshot sample hello built in dialog 6](images/glimmer-dsl-tk-screenshot-sample-hello-built-in-dialog-choose-font-done.png)
+
+### Hello, Separator!
+
+Glimmer code (from [samples/hello/hello_separator.rb](samples/hello/hello_separator.rb)):
+
+```ruby
+require 'glimmer-dsl-tk'
+
+include Glimmer
+
+root {
+  title 'Hello, Separator!'
+  width 200
+  height 200
+  
+  label {
+    grid row: 0, column: 0, min_width: 100, min_height: 100, column_weight: 0, sticky: 'nsew'
+    text 'Label 1'
+    anchor 'center'
+  }
+  
+  separator {
+    grid row: 0, column: 1
+    orient 'vertical'
+  }
+  
+  label {
+    grid row: 0, column: 2, min_width: 100, min_height: 100, sticky: 'nsew'
+    text 'Label 2'
+    anchor 'center'
+  }
+  
+  separator {
+    grid row: 1, column: 0, column_span: 3
+    orient 'horizontal'
+  }
+  
+  label {
+    grid row: 2, column: 0, min_width: 100, min_height: 100, sticky: 'nsew'
+    text 'Label 3'
+    anchor 'center'
+  }
+  
+  separator {
+    grid row: 2, column: 1
+    orient 'vertical'
+  }
+  
+  label {
+    grid row: 2, column: 2, min_width: 100, min_height: 100, sticky: 'nsew'
+    text 'Label 4'
+    anchor 'center'
+  }
+}.open
+```
+
+Run with [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed:
+
+```
+ruby -r glimmer-dsl-tk -e "require 'samples/hello/hello_separator'"
+```
+
+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_separator.rb
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello separator](images/glimmer-dsl-tk-screenshot-sample-hello-separator.png)
+
 ## Help
 
 ### Issues
@@ -1876,6 +2588,7 @@ These features have been planned or suggested. You might see them in a future ve
 ## Contributors
 
 * [Andy Maleh](https://github.com/AndyObtiva) (Founder)
+* [vin1antme](https://github.com/vin1antme)
 
 [Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer-dsl-tk/graphs/contributors)