glimmer-dsl-tk 0.0.3 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f57063e358754b89fbd0a57cb118fb9764595a8965eba5884aeb2988ab2d6b1
-  data.tar.gz: f55e3fc96a9388dd218d7c674cdf1585831c44a3f6412741e0e65f53185e2d98
+  metadata.gz: 7048451aa588f11c433d93073beb1a3eda6d03877e076ed9a3c23d432746e492
+  data.tar.gz: 4797910066441f8d0bf8960ca5bc3732ea39d6b0bd4103a3246349921a133bde
 SHA512:
-  metadata.gz: 272ea64f1a285ebcef28edb4bc2092f1c8ac78bf9ea36e086f1555ba47a454cb09b8c698e06d5ed0aa76abab1fb7946535bae139e9d444663de8185483bba7f4
-  data.tar.gz: e6fa9a29aa2b6a7c096007489a0b0e07d0658f6c79ef836a4cbd4d2fc1300330ef19b97bb6ea62e5d7cac9e00f5a2fca32ee745b167cc8f0d826cacd98a13b1c
+  metadata.gz: 3d25ea1d5a2c22ecc11fcc526cf264c207e21bbb018a1e05627aee01d6ce50aa8f9ce94a7fc57f0546221c0db9ab9bba46dc91a10c9ab0329de73bf7c9d56241
+  data.tar.gz: eccf58d86c03fb9b0383180025a7cc30d31f9b2dd98cfa36d422592170fbe01266d4a0487e020e241e69637e17754361207524a51a487b62494cd963fc6fb829

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Change Log
 
+## 0.0.7
+
+- Upgraded to tk 0.4.0
+- Fixed `girb` by changing to a pure Ruby script
+
+## 0.0.6
+
+- Upgraded to tk 0.3.0
+
+## 0.0.5
+
+- Label text data-binding
+- Entry text data-binding
+- The `grid` geometry manager
+- Hello, Computed! sample
+
+## 0.0.4
+
+- `list` custom widget (since listbox is not tile themed yet in Tk)
+- `girb` (Glimmer IRB)
+- Hello, List Single Selection! sample
+- Hello, List Multi Selection! sample
+
+## 0.0.3
+
+- Combobox support
+- Button command event observer support
+- Combobox text data-binding
+- Hello, Combo! sample
+
 ## 0.0.2
 
 - Notebook/frame support

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Andy Maleh
+Copyright (c) 2020-2021 Andy Maleh
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,24 +1,29 @@
-# [<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.3 (Desktop GUI)
+# [<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.7
+## MRI Ruby Desktop Development GUI Library
+GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-tk.svg)](http://badge.fury.io/rb/glimmer-dsl-tk)
+[![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer-dsl-tk/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer-dsl-tk?branch=master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ce2853efdbecf6ebdc73/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-tk/maintainability)
 [![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)
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [Tk](https://www.tcl.tk/) enables desktop development with [Glimmer](https://github.com/AndyObtiva/glimmer).
+**[Contributors Wanted! (Submit a Glimmer App Sample to Get Started)](CONTRIBUTING.md)**
 
-[Tcl/Tk](https://www.tcl.tk/) has evolved into a practical desktop GUI toolkit due to gaining true native 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.).
+[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 evolved into a practical desktop GUI toolkit due to gaining truly 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).
 
-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 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://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/).
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) provides a DSL to enable more productive desktop development in Ruby with:
+[Glimmer](https://github.com/AndyObtiva/glimmer) 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
 - Convention over configuration via smart defaults and automation of low-level details
 - Requiring the least amount of syntax possible to build GUI
 - Bidirectional Data-Binding to declaratively wire and automatically synchronize GUI with Business Models
+- Custom Widget support
 - Scaffolding for new custom widgets, apps, and gems
 - Native-Executable packaging on Mac, Windows, and Linux
-- Custom Widget support
 
 **Hello, World!**
 
@@ -42,9 +47,11 @@ Glimmer app:
 
 ![glimmer dsl tk screenshot sample hello world](images/glimmer-dsl-tk-screenshot-sample-hello-world.png)
 
+NOTE: Glimmer DSL for Tk is in alpha mode. Please help make better by contributing, adopting for small or low risk projects, and providing feedback. It is still an early alpha, so the more feedback and issues you report the better.
+
 Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
-- [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop GUI)
-- [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
+- [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Framework)
+- [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Pure Ruby Web GUI and Auto-Webifier of Desktop Apps)
 - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
 - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
 
@@ -53,7 +60,7 @@ Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
 - [Tcl/Tk](https://www.tcl.tk/): Follow the [install instructions](https://tkdocs.com/tutorial/install.html)
 - [Ruby](https://www.ruby-lang.org/en/): On Windows, obtain from the Ruby [download page](https://www.ruby-lang.org/en/downloads/). On the Mac and Linux, it is more convenient to just use [RVM](http://rvm.io) and follow the [RVM Tk instructions](https://rvm.io/integration/tk).
 
-For example, on the Mac, you can: 
+For example, on the Mac, you can:
 - Install the ActiveTcl Mac package from [ActiveState.com](ActiveState.com)
 - Install [RVM](https://rvm.io/) by running `\curl -sSL https://get.rvm.io | bash -s stable` (and run `curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -` if needed for mentioned security reasons)
 - Run: `rvm install 2.7.1 --enable-shared --enable-pthread --with-tk --with-tcl`
@@ -66,18 +73,14 @@ Afterwards, if you open `irb`, you should be able to run `require 'tk'` successf
 
 Run this command to install directly:
 ```
-gem install logging
-gem install super_module
 gem install glimmer-dsl-tk
 ```
 
-### Option 2: Bundler 
+### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'logging'
-gem 'super_module'
-gem 'glimmer-dsl-tk', '~> 0.0.3'
+gem 'glimmer-dsl-tk', '~> 0.0.7'
 ```
 
 And, then run:
@@ -85,6 +88,16 @@ And, then run:
 bundle
 ```
 
+## Girb (Glimmer IRB)
+
+You can run the `girb` command (`bin/girb` if you cloned the project locally):
+
+```
+girb
+```
+
+This gives you `irb` with the `glimmer-dsl-tk` gem loaded and the `Glimmer` module mixed into the main object for easy experimentation with GUI.
+
 ## Tk Concepts
 
 Here is a summary taken from the official [Tk Concepts Tutorial](https://tkdocs.com/tutorial/concepts.html)
@@ -134,7 +147,7 @@ root.mainloop
 Example of the same app written in [Glimmer](https://github.com/AndyObtiva/glimmer) declarative syntax:
 
 ```ruby
-root {      
+root {
   title 'Hello, Tab!'
    
   notebook {
@@ -153,35 +166,137 @@ root {
 }.open
 ```
 
-### Bidirectional Data-Binding
+## 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.
+
+Example:
+
+```ruby
+        label {
+          grid column: 0, row: 2, sticky: 'w'
+          text 'Year of Birth: '
+        }
+        entry {
+          grid column: 1, row: 2
+          width 15
+          text bind(@contact, :year_of_birth)
+        }
+```
+
+More details can be found in the [Hello, Computed!](#hello-computed) sample below.
+
+## Bidirectional Data-Binding
 
 Glimmer supports bidirectional data-binding via the `bind` keyword, which takes a model and an attribute.
 
+### Combo Data-Binding
+
 Example:
 
 This assumes a `Person` model with a `country` attribute representing their current country and a `country_options` attribute representing available options for the country attribute.
 
 ```ruby
-  combobox { |proxy|
-    state 'readonly'       
+  combobox {
+    state 'readonly'
     text bind(person, :country)
   }
 ```
 
-That binds the `text` selection of the `combobox` to the `country` property on the `person` model.
+That code sets the `values` of the `combobox` to the `country_options` property on the `person` model (data-binding attribute + "_options" by convention).
+It also binds the `text` selection of the `combobox` to the `country` property on the `person` model.
 
 It automatically handles all the Tk plumbing behind the scenes, such as using `TkVariable` and setting `combobox` `values` from `person.country_options` by convention (attribute_name + "_options").
 
 More details can be found in the [Hello, Combo!](#hello-combo) sample below.
 
-### Command
+### List Single Selection Data-Binding
+
+Tk does not support a native themed listbox, so Glimmer implements its own `list` widget on top of `Tk::Tile::Treeview`. It is set to single selection via selectmode 'browse'.
+
+Example:
+
+This assumes a `Person` model with a `country` attribute representing their current country and a `country_options` attribute representing available options for the country attribute.
+
+```ruby
+  list {
+    selectmode 'browse'
+    text bind(person, :country)
+  }
+```
+
+That code binds the `items` text of the `list` to the `country_options` property on the `person` model (data-binding attribute + "_options" by convention).
+It also binds the `selection` text of the `list` to the `country` property on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes.
+
+More details can be found in the [Hello, List Single Selection!](#hello-list-single-selection) sample below.
+
+### List Multi Selection Data-Binding
+
+Tk does not support a native themed listbox, so Glimmer implements its own `list` widget on top of `Tk::Tile::Treeview`. It is set to multi selection by default.
+
+Example:
+
+This assumes a `Person` model with a `provinces` attribute representing their current country and a `provinces_options` attribute representing available options for the provinces attribute.
+
+```ruby
+  list {
+    text bind(person, :provinces)
+  }
+```
+
+That code binds the `items` text of the `list` to the `provinces_options` property on the `person` model (data-binding attribute + "_options" by convention).
+It also binds the `selection` text of the `list` to the `provinces` property on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes.
+
+More details can be found in the [Hello, List Multi Selection!](#hello-list-multi-selection) sample below.
+
+### Label Data-Binding
+
+Example:
+
+This assumes a `Person` model with a `country` attribute.
+
+```ruby
+  label {
+    text bind(person, :country)
+  }
+```
+
+That code binds the `textvariable` value of the `label` to the `country` property on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes.
+
+More details can be found in the [Hello, Computed!](#hello-computed) sample below.
+
+### Entry Data-Binding
+
+Example:
+
+This assumes a `Person` model with a `country` attribute.
+
+```ruby
+  entry {
+    text bind(person, :country)
+  }
+```
+
+That code binds the `textvariable` value of the `entry` to the `country` property on the `person` model.
+
+It automatically handles all the Tk plumbing behind the scenes.
+
+More details can be found in the [Hello, Computed!](#hello-computed) sample below.
+
+## Command Observer
 
 Buttons can set a `command` option to trigger when the user clicks the button. This may be done with the `command` keyword, passing in a block directly (no need for `proc` as per Tk)
 
 Example:
 
 ```ruby
-  button { |proxy|
+  button {
     text "Reset Selection"
     command {
       person.reset_country
@@ -226,7 +341,7 @@ Glimmer code (from [samples/hello/hello_tab.rb](samples/hello/hello_tab.rb)):
 ```ruby
 include Glimmer
 
-root {      
+root {
   title 'Hello, Tab!'
    
   notebook {
@@ -266,7 +381,7 @@ root {
   title 'Hello, Combo!'
   
   combobox { |proxy|
-    state 'readonly'       
+    state 'readonly'
     text bind(person, :country)
   }
   
@@ -291,6 +406,145 @@ Glimmer app:
 ![glimmer dsl tk screenshot sample hello combo](images/glimmer-dsl-tk-screenshot-sample-hello-combo.png)
 ![glimmer dsl tk screenshot sample hello combo dropdown](images/glimmer-dsl-tk-screenshot-sample-hello-combo-dropdown.png)
 
+### Hello, List Single Selection!
+
+Glimmer code (from [samples/hello/hello_list_single_selection.rb](samples/hello/hello_list_single_selection.rb)):
+
+```ruby
+# ... more code precedes
+root {
+  title 'Hello, List Single Selection!'
+  
+  list {
+    selectmode 'browse'
+    selection bind(person, :country)
+  }
+  
+  button {
+    text "Reset Selection To Default Value"
+    
+    command { person.reset_country }
+  }
+}.open
+# ... more code follows
+```
+
+Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
+
+```
+ruby -r glimmer-dsl-tk -e "require '../samples/hello/hello_list_single_selection.rb'"
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello list single selection](images/glimmer-dsl-tk-screenshot-sample-hello-list-single-selection.png)
+
+### Hello, List Multi Selection!
+
+Glimmer code (from [samples/hello/hello_list_multi_selection.rb](samples/hello/hello_list_multi_selection.rb)):
+
+```ruby
+# ... more code precedes
+root {
+  title 'Hello, List Multi Selection!'
+  
+  list {
+    selection bind(person, :provinces)
+  }
+  
+  button {
+    text "Reset Selection To Defaults"
+    
+    command { person.reset_provinces }
+  }
+}.open
+# ... more code follows
+```
+
+Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
+
+```
+ruby -r glimmer-dsl-tk -e "require '../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, 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 bind(@contact, :first_name)
+        }
+        
+        label {
+          grid column: 0, row: 1, sticky: 'w'
+          text 'Last Name: '
+        }
+        entry {
+          grid column: 1, row: 1
+          width 15
+          text bind(@contact, :last_name)
+        }
+        
+        label {
+          grid column: 0, row: 2, sticky: 'w'
+          text 'Year of Birth: '
+        }
+        entry {
+          grid column: 1, row: 2
+          width 15
+          text bind(@contact, :year_of_birth)
+        }
+        
+        label {
+          grid column: 0, row: 3, sticky: 'w'
+          text 'Name: '
+        }
+        label {
+          grid column: 1, row: 3, sticky: 'w'
+          text bind(@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 bind(@contact, :age, on_write: :to_i, computed_by: [:year_of_birth])
+        }
+      }
+    }.open
+# ... more code follows
+```
+
+Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
+
+```
+ruby -r glimmer-dsl-tk -e "require '../samples/hello/hello_computed.rb'"
+```
+
+Glimmer app:
+
+![glimmer dsl tk screenshot sample hello computed](images/glimmer-dsl-tk-screenshot-sample-hello-computed.png)
+
 ## Help
 
 ### Issues
@@ -307,9 +561,9 @@ If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/g
 
 [Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
 
-## Feature Suggestions
+## Planned Features and Feature Suggestions
 
-These features have been suggested. You might see them in a future version of Glimmer DSL for Tk. You are welcome to contribute more feature suggestions.
+These features have been planned or suggested. You might see them in a future version of Glimmer DSL for Tk. You are welcome to contribute more feature suggestions.
 
 [TODO.md](TODO.md)
 
@@ -331,8 +585,8 @@ These features have been suggested. You might see them in a future version of Gl
 
 [MIT](LICENSE.txt)
 
-Copyright (c) 2020 - Andy Maleh. 
+Copyright (c) 2020-2021 - Andy Maleh.
 
 --
 
-[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=40 />](https://github.com/AndyObtiva/glimmer) Built for [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library).
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=40 />](https://github.com/AndyObtiva/glimmer) Built for [Glimmer](https://github.com/AndyObtiva/glimmer) (DSL Framework).