glimmer-dsl-libui 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 186c49fc28b9767289f398563e727a564aec12ccadee63ef1ef8b8337b186c34
-  data.tar.gz: 45b1ea94ca10b26f52146270c40cd4cf43567ff8142aecda6b1f46c528418882
+  metadata.gz: 48926d5aab22eec664c80bc9ebe5a94a841e4b6173cca343ad9876fb33924b03
+  data.tar.gz: 890dba3f171225448aad354ec767819faaf3cb59e48764adc63b0f35bcbc0fe3
 SHA512:
-  metadata.gz: 253f2335dc985e7e25481f27fb78d78b9ce2a77b1c86cbd513c1e3d289d6204155e72512cbb72994329d905e4906bdf7905e3e070487d19c22605092ce249a70
-  data.tar.gz: 33633220d46d61a1428c9e0cfad06ea6a0706a44bc537006802f4f24210bbb415a04c7332c4f7fd020e1fb68adce28edf81946ea88eb4652a44fce847725c5fe
+  metadata.gz: 94650e60ccb1ed496dd682f937e4a91a3cffad37cfc3da17c462fd2db7349e06af9572c425f1b90d8a3a522c09eddd2b7eed6b4982c31a77fff97322aff6bbed
+  data.tar.gz: fc41c1e9882b42155729547ee2d83e43a40a64ae56c2523ff880cd2f818357fb42328a72b79810ccfb75fc7356ac70910e1d4202249488cb4f8aef9d3a8034fe

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 0.5.6
+
+- Upgrade to glimmer 2.7.1 and document its support for keyed data-binding
+- Support class-based custom controls
+- examples/class_based_custom_controls.rb example
+- Rename examples/method_based_custom_keyword.rb example to examples/method_based_custom_controls.rb
+
 ## 0.5.5
 
 - Upgrade to libui 0.0.15 (with official Mac ARM64 support)

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.5.5
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.5.6
 ## Prerequisite-Free Ruby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -19,7 +19,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - [Declarative DSL syntax](#glimmer-gui-dsl-concepts) that visually maps to the GUI control hierarchy
 - [Convention over configuration](#smart-defaults-and-conventions) via smart defaults and automation of low-level details
 - Requiring the [least amount of syntax](#glimmer-gui-dsl-concepts) possible to build GUI
-- [Custom Keyword](#custom-keywords) support
+- [Custom Control](#custom-keywords) support
 - [Bidirectional/Unidirectional Data-Binding](#data-binding) to declaratively wire and automatically synchronize GUI Views with Models
 - [Far Future Plan] Scaffolding for new custom controls, apps, and gems
 - [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
@@ -419,7 +419,8 @@ DSL | Platforms | Native? | Vector Graphics? | Pros | Cons | Prereqs
       - [Grid](#grid)
       - [Histogram](#histogram)
       - [Login](#login)
-      - [Method-Based Custom Keyword](#method-based-custom-keyword)
+      - [Method-Based Custom Controls](#method-based-custom-controls)
+      - [Class-Based Custom Controls](#class-based-custom-controls)
       - [Area-Based Custom Controls](#area-based-custom-controls)
       - [Midi Player](#midi-player)
       - [Snake](#snake)
@@ -454,7 +455,7 @@ The Glimmer GUI DSL follows these simple concepts in mapping from [LibUI](https:
 
 **Keyword(args)**: [LibUI](https://github.com/kojix2/LibUI) controls may be declared by lower-case underscored name (aka keyword from list of [supported keywords](#supported-keywords)) (e.g. `window` or `button`). Behind the scenes, they are represented by keyword methods that map to corresponding `LibUI.new_keyword` methods receiving args (e.g. `window('hello world', 300, 200, true)`).
 
-**Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls. 
+**Content Block** (Properties/Listeners/Controls): Any keyword may be optionally followed by a Ruby curly-brace multi-line content block containing properties (attributes), listeners, and/or nested controls.
 
 Example:
 
@@ -464,7 +465,7 @@ window {
   
   on_closing do # listener (always has a do; end block to signify logic)
     puts 'Bye'
-  end 
+  end
   
   button('greet') { # nested control
     on_clicked do
@@ -474,13 +475,13 @@ window {
 }
 ```
 
-Content block optionally receives one arg representing the controll 
+Content block optionally receives one arg representing the controll
 
 Example:
 
 ```ruby
-button('greet') { |b| 
-  on_clicked do 
+button('greet') { |b|
+  on_clicked do
     puts b.text
   end
 }
@@ -488,7 +489,7 @@ button('greet') { |b|
 
 **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
 
-**Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (always followed by a `do; end` style block to signify logic). 
+**Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (always followed by a `do; end` style block to signify logic).
 
 Example:
 
@@ -500,11 +501,11 @@ button('click') {
 }
 ```
 
-Optionally, the listener block can receive an arg representing the control. 
+Optionally, the listener block can receive an arg representing the control.
 
 ```ruby
 button('click') {
-  on_clicked do |btn| 
+  on_clicked do |btn|
     puts btn.text
   end
 }
@@ -567,7 +568,7 @@ window('hello world', 300, 200) {
 
 ## Usage
 
-Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly:
+Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly into a [maintained Ruby version](https://www.ruby-lang.org/en/downloads/):
 
 ```
 gem install glimmer-dsl-libui
@@ -576,7 +577,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.5.5'
+gem 'glimmer-dsl-libui', '~> 0.5.6'
 ```
 
 Test that installation worked by running the [Meta-Example](#examples):
@@ -1598,15 +1599,15 @@ SpinnerExample.new.launch
 
 Custom keywords can be defined to represent custom controls (components) that provide new features or act as composites of [existing controls](#supported-keywords) that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
 
-For example, you can define a custom `address` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
+For example, you can define a custom `address_view` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
 
-To define custom keywords, simply define a method representing the custom control you want (e.g. `address`) with any arguments needed (e.g. `address(address_model)`).
+There are two ways to define custom keywords:
+- Method-Based: simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
+- Class-Based: define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
 
-To make custom keywords externally reusable, you can define in modules and simply include the modules in the view classes that need them.
+It is OK to use the terms "custom keyword" and "custom control" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
 
-It is OK to use terms "custom keyword" and "custom control" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
-
-Example that defines `form_field`, `address_form`, `label_pair`, and `address` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
+Example that defines `form_field`, `address_form`, `label_pair`, and `address_view` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
 require 'glimmer-dsl-libui'
@@ -1643,7 +1644,7 @@ def label_pair(model, attribute, value)
   }
 end
 
-def address(address_model)
+def address_view(address_model)
   vertical_box {
     address_model.each_pair do |attribute, value|
       label_pair(address_model, attribute, value)
@@ -1673,7 +1674,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -1695,7 +1696,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -1978,6 +1979,7 @@ Data-bound model attribute can be:
 - **Direct:** `Symbol` representing attribute reader/writer (e.g. `[person, :name`])
 - **Nested:** `String` representing nested attribute path (e.g. `[company, 'address.street']`). That results in "nested data-binding"
 - **Indexed:** `String` containing array attribute index (e.g. `[customer, 'addresses[0].street']`). That results in "indexed data-binding"
+- **Keyed:** `String` containing hash attribute key (e.g. `[customer, 'addresses[:main].street']`). That results in "keyed data-binding"
 
 Data-binding options include:
 - `before_read {|value| ...}`: performs an operation before reading data from Model to update View.
@@ -8580,26 +8582,26 @@ window('Login') {
 }.show
 ```
 
-#### Method-Based Custom Keyword
+#### Method-Based Custom Controls
 
 [Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
   
-This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom control keywords.
+This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
 
 The custom keywords are defined via methods (thus are "method-based").
 
-[examples/method_based_custom_keyword.rb](examples/method_based_custom_keyword.rb)
+[examples/method_based_custom_controls.rb](examples/method_based_custom_controls.rb)
 
 Run with this command from the root of the project if you cloned the project:
 
 ```
-ruby -r './lib/glimmer-dsl-libui' examples/method_based_custom_keyword.rb
+ruby -r './lib/glimmer-dsl-libui' examples/method_based_custom_controls.rb
 ```
 
 Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
 
 ```
-ruby -r glimmer-dsl-libui -e "require 'examples/method_based_custom_keyword'"
+ruby -r glimmer-dsl-libui -e "require 'examples/method_based_custom_controls'"
 ```
 
 Mac | Windows | Linux
@@ -8624,13 +8626,13 @@ def form_field(model, attribute)
   }
 end
 
-def address_form(address)
+def address_form(address_model)
   form {
-    form_field(address, :street)
-    form_field(address, :p_o_box)
-    form_field(address, :city)
-    form_field(address, :state)
-    form_field(address, :zip_code)
+    form_field(address_model, :street)
+    form_field(address_model, :p_o_box)
+    form_field(address_model, :city)
+    form_field(address_model, :state)
+    form_field(address_model, :zip_code)
   }
 end
 
@@ -8643,10 +8645,10 @@ def label_pair(model, attribute, value)
   }
 end
 
-def address(address)
+def address_view(address_model)
   vertical_box {
-    address.each_pair do |attribute, value|
-      label_pair(address, attribute, value)
+    address_model.each_pair do |attribute, value|
+      label_pair(address_model, attribute, value)
     end
   }
 end
@@ -8654,7 +8656,7 @@ end
 address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
 address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
 
-window('Method-Based Custom Keyword') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -8673,7 +8675,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8695,7 +8697,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show
@@ -8723,13 +8725,13 @@ def form_field(model, property)
   }
 end
 
-def address_form(address)
+def address_form(address_model)
   form {
-    form_field(address, :street)
-    form_field(address, :p_o_box)
-    form_field(address, :city)
-    form_field(address, :state)
-    form_field(address, :zip_code)
+    form_field(address_model, :street)
+    form_field(address_model, :p_o_box)
+    form_field(address_model, :city)
+    form_field(address_model, :state)
+    form_field(address_model, :zip_code)
   }
 end
 
@@ -8745,10 +8747,10 @@ def label_pair(model, attribute, value)
   end
 end
 
-def address(address)
+def address_view(address_model)
   vertical_box {
-    address.each_pair do |attribute, value|
-      label_pair(address, attribute, value)
+    address_model.each_pair do |attribute, value|
+      label_pair(address_model, attribute, value)
     end
   }
 end
@@ -8756,7 +8758,7 @@ end
 address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
 address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
 
-window('Method-Based Custom Keyword') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -8775,7 +8777,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -8797,7 +8799,151 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
+    }
+  }
+}.show
+```
+
+#### Class-Based Custom Controls
+
+[Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
+  
+This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
+
+The custom keywords are defined via classes that include `Glimmer::LibUI::CustomControl` (thus are "class-based"), thus enabling offloading each custom control into its own file when needed for better code organization.
+
+[examples/class_based_custom_controls.rb](examples/class_based_custom_controls.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/class_based_custom_controls.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/class_based_custom_controls'"
+```
+
+Mac | Windows | Linux
+----|---------|------
+![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png) | ![glimmer-dsl-libui-windows-method-based-custom-keyword.png](images/glimmer-dsl-libui-windows-method-based-custom-keyword.png) | ![glimmer-dsl-libui-linux-method-based-custom-keyword.png](images/glimmer-dsl-libui-linux-method-based-custom-keyword.png)
+
+New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version (with [data-binding](#data-binding)):
+
+```ruby
+require 'glimmer-dsl-libui'
+require 'facets'
+
+include Glimmer
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+class FormField
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute
+  
+  body {
+    entry { |e|
+      label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+      text <=> [model, attribute]
+    }
+  }
+end
+
+class AddressForm
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    form {
+      form_field(model: address, attribute: :street)
+      form_field(model: address, attribute: :p_o_box)
+      form_field(model: address, attribute: :city)
+      form_field(model: address, attribute: :state)
+      form_field(model: address, attribute: :zip_code)
+    }
+  }
+end
+
+class LabelPair
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute, :value
+  
+  body {
+    horizontal_box {
+      label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+      label(value.to_s) {
+        text <= [model, attribute]
+      }
+    }
+  }
+end
+
+class AddressView
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    vertical_box {
+      address.each_pair do |attribute, value|
+        label_pair(model: address, attribute: attribute, value: value)
+      end
+    }
+  }
+end
+
+address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+
+window('Class-Based Custom Keyword') {
+  margined true
+  
+  horizontal_box {
+    vertical_box {
+      label('Address 1') {
+        stretchy false
+      }
+      
+      address_form(address: address1)
+      
+      horizontal_separator {
+        stretchy false
+      }
+      
+      label('Address 1 (Saved)') {
+        stretchy false
+      }
+      
+      address_view(address: address1)
+    }
+    
+    vertical_separator {
+      stretchy false
+    }
+    
+    vertical_box {
+      label('Address 2') {
+        stretchy false
+      }
+      
+      address_form(address: address2)
+      
+      horizontal_separator {
+        stretchy false
+      }
+      
+      label('Address 2 (Saved)') {
+        stretchy false
+      }
+      
+      address_view(address: address2)
     }
   }
 }.show
@@ -9514,6 +9660,8 @@ Snake provides an example of building a desktop application [test-first](/spec/e
 
 Use arrows to move and spacebar to pause/resume.
 
+Note that Snake relies on the new [Ruby Pattern Matching feature](https://docs.ruby-lang.org/en/3.0/doc/syntax/pattern_matching_rdoc.html) available starting in Ruby 2.7 experimentally and in Ruby 3.0 officially.
+
 [examples/snake.rb](examples/snake.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -9738,6 +9886,8 @@ Snake.new.launch
 
 Glimmer Tetris utilizes many small areas to represent Tetromino blocks because this ensures smaller redraws per tetromino block color change, thus achieving higher performance than redrawing one large area on every little change.
 
+Note that Tetris relies on the new [Ruby Pattern Matching feature](https://docs.ruby-lang.org/en/3.0/doc/syntax/pattern_matching_rdoc.html) available starting in Ruby 2.7 experimentally and in Ruby 3.0 officially.
+
 [examples/tetris.rb](examples/tetris.rb)
 
 Run with this command from the root of the project if you cloned the project:

data/VERSION

@@ -1 +1 @@
-0.5.5
+0.5.6

data/examples/class_based_custom_controls.rb

@@ -0,0 +1,113 @@
+require 'glimmer-dsl-libui'
+require 'facets'
+
+include Glimmer
+
+Address = Struct.new(:street, :p_o_box, :city, :state, :zip_code)
+
+class FormField
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute
+  
+  body {
+    entry { |e|
+      label attribute.to_s.underscore.split('_').map(&:capitalize).join(' ')
+      text <=> [model, attribute]
+    }
+  }
+end
+
+class AddressForm
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    form {
+      form_field(model: address, attribute: :street)
+      form_field(model: address, attribute: :p_o_box)
+      form_field(model: address, attribute: :city)
+      form_field(model: address, attribute: :state)
+      form_field(model: address, attribute: :zip_code)
+    }
+  }
+end
+
+class LabelPair
+  include Glimmer::LibUI::CustomControl
+  
+  options :model, :attribute, :value
+  
+  body {
+    horizontal_box {
+      label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
+      label(value.to_s) {
+        text <= [model, attribute]
+      }
+    }
+  }
+end
+
+class AddressView
+  include Glimmer::LibUI::CustomControl
+  
+  options :address
+  
+  body {
+    vertical_box {
+      address.each_pair do |attribute, value|
+        label_pair(model: address, attribute: attribute, value: value)
+      end
+    }
+  }
+end
+
+address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
+address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
+
+window('Class-Based Custom Keyword') {
+  margined true
+  
+  horizontal_box {
+    vertical_box {
+      label('Address 1') {
+        stretchy false
+      }
+      
+      address_form(address: address1)
+      
+      horizontal_separator {
+        stretchy false
+      }
+      
+      label('Address 1 (Saved)') {
+        stretchy false
+      }
+      
+      address_view(address: address1)
+    }
+    
+    vertical_separator {
+      stretchy false
+    }
+    
+    vertical_box {
+      label('Address 2') {
+        stretchy false
+      }
+      
+      address_form(address: address2)
+      
+      horizontal_separator {
+        stretchy false
+      }
+      
+      label('Address 2 (Saved)') {
+        stretchy false
+      }
+      
+      address_view(address: address2)
+    }
+  }
+}.show

data/examples/{method_based_custom_keyword.rb → method_based_custom_controls.rb}

@@ -32,7 +32,7 @@ def label_pair(model, attribute, value)
   }
 end
 
-def address(address_model)
+def address_view(address_model)
   vertical_box {
     address_model.each_pair do |attribute, value|
       label_pair(address_model, attribute, value)
@@ -43,7 +43,7 @@ end
 address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
 address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
 
-window('Method-Based Custom Keyword') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -62,7 +62,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -84,7 +84,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show

data/examples/{method_based_custom_keyword2.rb → method_based_custom_controls2.rb}

@@ -39,7 +39,7 @@ def label_pair(model, attribute, value)
   end
 end
 
-def address(address_model)
+def address_view(address_model)
   vertical_box {
     address_model.each_pair do |attribute, value|
       label_pair(address_model, attribute, value)
@@ -50,7 +50,7 @@ end
 address1 = Address.new('123 Main St', '23923', 'Denver', 'Colorado', '80014')
 address2 = Address.new('2038 Park Ave', '83272', 'Boston', 'Massachusetts', '02101')
 
-window('Method-Based Custom Keyword') {
+window('Method-Based Custom Controls') {
   margined true
   
   horizontal_box {
@@ -69,7 +69,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address1)
+      address_view(address1)
     }
     
     vertical_separator {
@@ -91,7 +91,7 @@ window('Method-Based Custom Keyword') {
         stretchy false
       }
       
-      address(address2)
+      address_view(address2)
     }
   }
 }.show

data/lib/glimmer/dsl/libui/custom_control_expression.rb

@@ -0,0 +1,58 @@
+# Copyright (c) 2021-2022 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'glimmer'
+require 'glimmer/dsl/expression'
+require 'glimmer/dsl/parent_expression'
+require 'glimmer/dsl/top_level_expression'
+require 'glimmer/libui/custom_control'
+
+module Glimmer
+  module DSL
+    module Libui
+      class CustomControlExpression < Expression
+        # TODO Consider making custom controls automatically generate static expressions
+        include ParentExpression
+        include TopLevelExpression
+
+        def can_interpret?(parent, keyword, *args, &block)
+          LibUI::CustomControl.for(keyword)
+        end
+  
+        def interpret(parent, keyword, *args, &block)
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          LibUI::CustomControl.for(keyword).new(keyword, parent, args, options, &block)
+        end
+  
+        def add_content(custom_control, keyword, *args, &block)
+          options = args.last.is_a?(Hash) ? args.last : {post_add_content: true}
+          # TODO consider avoiding source_location
+          if block.source_location == custom_control.content&.__getobj__&.source_location
+            custom_control.content.call(custom_control) unless custom_control.content.called?
+          else
+            super
+          end
+          custom_control.post_add_content if options[:post_add_content]
+        end
+      end
+    end
+  end
+end

data/lib/glimmer/dsl/libui/dsl.rb

@@ -43,6 +43,7 @@ module Glimmer
           string
           operation
           control
+          custom_control
           shape
         ]
       )

data/lib/glimmer/dsl/libui/property_expression.rb

@@ -32,7 +32,8 @@ module Glimmer
           (
             parent.is_a?(Glimmer::LibUI::ControlProxy) or
               parent.is_a?(Glimmer::LibUI::Shape) or
-              parent.is_a?(Glimmer::LibUI::AttributedString)
+              parent.is_a?(Glimmer::LibUI::AttributedString) or
+              parent.is_a?(Glimmer::LibUI::CustomControl)
           ) and
             block.nil? and
             parent.respond_to?("#{keyword}=", *args)

data/lib/glimmer/libui/custom_control.rb

@@ -0,0 +1,249 @@
+# Copyright (c) 2021-2022 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'super_module'
+require 'glimmer'
+require 'glimmer/proc_tracker'
+require 'glimmer/data_binding/observer'
+require 'glimmer/data_binding/observable_model'
+
+module Glimmer
+  module LibUI
+    module CustomControl
+      include SuperModule
+      include DataBinding::ObservableModel
+
+      super_module_included do |klass|
+        # TODO clear memoization of WidgetProxy.libui_class_for for a keyword if a custom control was defined with that keyword
+        klass.include(Glimmer)
+        Glimmer::LibUI::CustomControl.add_custom_control_namespaces_for(klass)
+      end
+    
+      class << self
+        def for(keyword)
+          unless flyweight_custom_control_classes.keys.include?(keyword)
+            begin
+              extracted_namespaces = keyword.
+                to_s.
+                split(/__/).map do |namespace|
+                  namespace.camelcase(:upper)
+                end
+              custom_control_namespaces.each do |base|
+                extracted_namespaces.reduce(base) do |result, namespace|
+                  if !result.constants.include?(namespace)
+                    namespace = result.constants.detect {|c| c.to_s.upcase == namespace.to_s.upcase } || namespace
+                  end
+                  begin
+                    flyweight_custom_control_classes[keyword] = constant = result.const_get(namespace)
+                    return constant if constant.ancestors.include?(Glimmer::LibUI::CustomControl)
+                    flyweight_custom_control_classes[keyword] = constant
+                  rescue => e
+                    # Glimmer::Config.logger.debug {"#{e.message}\n#{e.backtrace.join("\n")}"}
+                    flyweight_custom_control_classes[keyword] = result
+                  end
+                end
+              end
+              raise "#{keyword} has no custom control class!"
+            rescue => e
+              Glimmer::Config.logger.debug {e.message}
+              Glimmer::Config.logger.debug {"#{e.message}\n#{e.backtrace.join("\n")}"}
+              flyweight_custom_control_classes[keyword] = nil
+            end
+          end
+          flyweight_custom_control_classes[keyword]
+        end
+        
+        # Flyweight Design Pattern memoization cache. Can be cleared if memory is needed.
+        def flyweight_custom_control_classes
+          @flyweight_custom_control_classes ||= {}
+        end
+        
+        # Returns keyword to use for this custom control
+        def keyword
+          self.name.underscore.gsub('::', '__')
+        end
+        
+        # Returns shortcut keyword to use for this custom control (keyword minus namespace)
+        def shortcut_keyword
+          self.name.underscore.gsub('::', '__').split('__').last
+        end
+        
+        def add_custom_control_namespaces_for(klass)
+          Glimmer::LibUI::CustomControl.namespaces_for_class(klass).drop(1).each do |namespace|
+            Glimmer::LibUI::CustomControl.custom_control_namespaces << namespace
+          end
+        end
+
+        def namespaces_for_class(m)
+          return [m] if m.name.nil?
+          namespace_constants = m.name.split(/::/).map(&:to_sym)
+          namespace_constants.reduce([Object]) do |output, namespace_constant|
+            output += [output.last.const_get(namespace_constant)]
+          end[1..-1].uniq.reverse
+        end
+
+        def custom_control_namespaces
+          @custom_control_namespaces ||= reset_custom_control_namespaces
+        end
+
+        def reset_custom_control_namespaces
+          @custom_control_namespaces = Set[Object, Glimmer::LibUI]
+        end
+
+        # Allows defining convenience option accessors for an array of option names
+        # Example: `options :color1, :color2` defines `#color1` and `#color2`
+        # where they return the instance values `options[:color1]` and `options[:color2]`
+        # respectively.
+        # Can be called multiple times to set more options additively.
+        # When passed no arguments, it returns list of all option names captured so far
+        def options(*new_options)
+          new_options = new_options.compact.map(&:to_s).map(&:to_sym)
+          if new_options.empty?
+            @options ||= {} # maps options to defaults
+          else
+            new_options = new_options.reduce({}) {|new_options_hash, new_option| new_options_hash.merge(new_option => nil)}
+            @options = options.merge(new_options)
+            def_option_attr_accessors(new_options)
+          end
+        end
+
+        def option(new_option, default: nil)
+          new_option = new_option.to_s.to_sym
+          new_options = {new_option => default}
+          @options = options.merge(new_options)
+          def_option_attr_accessors(new_options)
+        end
+
+        def def_option_attr_accessors(new_options)
+          new_options.each do |option, default|
+            class_eval <<-end_eval, __FILE__, __LINE__
+              def #{option}
+                options[:#{option}]
+              end
+              
+              def #{option}=(option_value)
+                self.options[:#{option}] = option_value
+              end
+            end_eval
+          end
+        end
+
+        def before_body(&block)
+          @before_body_block = block
+        end
+
+        def body(&block)
+          @body_block = block
+        end
+
+        def after_body(&block)
+          @after_body_block = block
+        end
+      end
+
+      attr_reader :body_root, :libui, :parent, :parent_proxy, :args, :keyword, :content, :options
+
+      def initialize(keyword, parent, args, options, &content)
+        @parent_proxy = @parent = parent
+        options ||= {}
+        @options = self.class.options.merge(options)
+        @content = ProcTracker.new(content) if content
+        execute_hook('before_body')
+        body_block = self.class.instance_variable_get("@body_block")
+        raise Glimmer::Error, 'Invalid custom control for having no body! Please define body block!' if body_block.nil?
+        @body_root = instance_exec(&body_block)
+        raise Glimmer::Error, 'Invalid custom control for having an empty body! Please fill body block!' if @body_root.nil?
+        @libui = @body_root.libui
+        execute_hook('after_body')
+        # TODO deregister all observer_registrations on destroy of the control once that listener is supported
+        # (on_destroy) unless it is the last window closing, in which case exit faster
+        post_add_content if content.nil?
+      end
+      
+      # Subclasses may override to perform post initialization work on an added child
+      def post_initialize_child(child)
+        # No Op by default
+      end
+
+      def post_add_content
+        # No Op by default
+      end
+      
+      def observer_registrations
+        @observer_registrations ||= []
+      end
+
+      def can_handle_listener?(listener)
+        body_root&.can_handle_listener?(listener.to_s)
+      end
+
+      def handle_listener(listener, &block)
+        body_root.handle_listener(listener.to_s, &block)
+      end
+      
+      # This method ensures it has an instance method not coming from Glimmer DSL
+      def has_instance_method?(method_name)
+        respond_to?(method_name) and
+          !@body_root.respond_to_libui?(method_name) and
+          (method(method_name) rescue nil) and
+          !method(method_name)&.source_location&.first&.include?('glimmer/dsl/engine.rb') and
+          !method(method_name)&.source_location&.first&.include?('glimmer/libui/control_proxy.rb')
+      end
+
+      # Returns content block if used as an attribute reader (no args)
+      # Otherwise, if a block is passed, it adds it as content to this custom control
+      def content(&block)
+        if block_given?
+          Glimmer::DSL::Engine.add_content(self, Glimmer::DSL::Libui::CustomControlExpression.new, self.class.keyword, &block)
+        else
+          @content
+        end
+      end
+
+      def method_missing(method_name, *args, &block)
+        # TODO Consider supporting a glimmer error silencing option for methods defined here
+        # but fail the glimmer DSL for the right reason to avoid seeing noise in the log output
+        if block && can_handle_listener?(method_name)
+          handle_listener(method_name, &block)
+        else
+          @body_root.send(method_name, *args, &block)
+        end
+      end
+
+      def respond_to?(method_name, *args, &block)
+        super or
+          can_handle_listener?(method_name) or
+          @body_root.respond_to?(method_name, *args, &block)
+      end
+      
+      private
+
+      def execute_hook(hook_name)
+        hook_block = self.class.instance_variable_get("@#{hook_name}_block")
+        return if hook_block.nil?
+        temp_method_name = "#{hook_name}_block_#{hook_block.hash.abs}_#{(Time.now.to_f * 1_000_000).to_i}"
+        singleton_class.define_method(temp_method_name, &hook_block)
+        send(temp_method_name)
+        singleton_class.send(:remove_method, temp_method_name)
+      end
+    end
+  end
+end

data/lib/glimmer/proc_tracker.rb

@@ -0,0 +1,39 @@
+# Copyright (c) 2007-2022 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'delegate'
+
+module Glimmer
+  class ProcTracker < DelegateClass(Proc)
+    def initialize(proc)
+      super(proc)
+    end
+    
+    def call(*args)
+      __getobj__.call(*args)
+      @called = true
+    end
+    
+    def called?
+      !!@called
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glimmer-dsl-libui
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Andy Maleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-12 00:00:00.000000000 Z
+date: 2022-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: glimmer
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 2.7.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 2.7.1
 - !ruby/object:Gem::Dependency
   name: perfect-shape
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.0.1
+- !ruby/object:Gem::Dependency
+  name: super_module
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.1
 - !ruby/object:Gem::Dependency
   name: os
   requirement: !ruby/object:Gem::Requirement
@@ -281,6 +295,7 @@ files:
 - examples/basic_window.rb
 - examples/basic_window2.rb
 - examples/button_counter.rb
+- examples/class_based_custom_controls.rb
 - examples/color_button.rb
 - examples/color_button2.rb
 - examples/color_the_circles.rb
@@ -314,8 +329,8 @@ files:
 - examples/login4.rb
 - examples/login5.rb
 - examples/meta_example.rb
-- examples/method_based_custom_keyword.rb
-- examples/method_based_custom_keyword2.rb
+- examples/method_based_custom_controls.rb
+- examples/method_based_custom_controls2.rb
 - examples/midi_player.rb
 - examples/midi_player2.rb
 - examples/midi_player3.rb
@@ -345,6 +360,7 @@ files:
 - lib/glimmer-dsl-libui.rb
 - lib/glimmer/dsl/libui/bind_expression.rb
 - lib/glimmer/dsl/libui/control_expression.rb
+- lib/glimmer/dsl/libui/custom_control_expression.rb
 - lib/glimmer/dsl/libui/data_binding_expression.rb
 - lib/glimmer/dsl/libui/dsl.rb
 - lib/glimmer/dsl/libui/file_expression.rb
@@ -426,6 +442,7 @@ files:
 - lib/glimmer/libui/control_proxy/transformable.rb
 - lib/glimmer/libui/control_proxy/triple_column.rb
 - lib/glimmer/libui/control_proxy/window_proxy.rb
+- lib/glimmer/libui/custom_control.rb
 - lib/glimmer/libui/data_bindable.rb
 - lib/glimmer/libui/image_path_renderer.rb
 - lib/glimmer/libui/parent.rb
@@ -440,6 +457,7 @@ files:
 - lib/glimmer/libui/shape/polyline.rb
 - lib/glimmer/libui/shape/rectangle.rb
 - lib/glimmer/libui/shape/square.rb
+- lib/glimmer/proc_tracker.rb
 - sounds/AlanWalker-Faded.mid
 - sounds/AlanWalker-SingMeToSleep.mid
 - sounds/CalvinHarris-Blame.mid