glimmer-dsl-libui 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7787d307fad4098e8f050a94c6477e9fca1f6cc8a2af4f2c16126a0a118dbc59
-  data.tar.gz: 0cc3d91a91ec96fa4bfecebef3829f4dc384f51aae7a81157385812d1aac2e8b
+  metadata.gz: 979ea7d60d873acdbe09e6ae2ceb48318798fa41ed13bb3a6bc8dcb642933165
+  data.tar.gz: 7cc05757477a0a42b85a20a6b298c147b5fba948f9e1eedd21701ab392a2d78a
 SHA512:
-  metadata.gz: 89d886d203a00b83b7a1b5640dfb83f256b6514586b254bb4b00157c88df29acaa80b30194909f62858d6c79eba1782a7d4deda143d5406bd5048899f3d9835c
-  data.tar.gz: c94709151900aac23b7148422ee96d484413437b57a78aca7ece2948b6a48a3db3cca7c64827ade37037f9d4af27cce0e6f0bf0a2498358afd07a279595dec12
+  metadata.gz: 8feb498d6d9eae22df82c9c9e2b0bd12ef11eb1ec9e4f90ac94f7151be28225f7dce775b8352b25ef98e4bc36f2aedd56370a1265a313f0997161396034f16d0
+  data.tar.gz: f76393bfebc577d9ce5e5add450ee70e337b67e7a63be24f5f91e4180d65c0d72c7236680f5843c446161710961ec51aa6520f037fcdcc0fc617d21ac182b850

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## 0.4.1
+
+- Document `observe` keyword
+- Document unidirectional data-binding in more detail (like `:before_read`, `:on_read`, and `:after_read` options)
+- Simplify examples/tetris.rb with `observe` keyword
+- Simplify examples/method_based_custom_keyword.rb with `observe` keyword
+- Simplify examples/color_the_circles.rb with `observe` keyword
+- Simplify examples/snake.rb with `observe` keyword
+
 ## 0.4.0
 
 - Upgrade to LibUI 0.0.13

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.4.0
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.4.1
 ## 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)
@@ -233,6 +233,7 @@ Other [Glimmer](https://rubygems.org/gems/glimmer) DSL gems you might be interes
       - [Area Transform Matrix](#area-transform-matrix)
     - [Smart Defaults and Conventions](#smart-defaults-and-conventions)
     - [Custom Keywords](#custom-keywords)
+    - [Observer Pattern](#observer-pattern)
     - [Data-Binding](#data-binding)
     - [API Gotchas](#api-gotchas)
     - [Original API](#original-api)
@@ -371,7 +372,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.4.0'
+gem 'glimmer-dsl-libui', '~> 0.4.1'
 ```
 
 Add `require 'glimmer-dsl-libui'` at the top, and then `include Glimmer` into the top-level main object for testing or into an actual class for serious usage.
@@ -1321,34 +1322,66 @@ window('Method-Based Custom Keyword') {
 
 ![glimmer-dsl-libui-mac-method-based-custom-keyword.png](images/glimmer-dsl-libui-mac-method-based-custom-keyword.png)
 
+### Observer Pattern
+
+The [Observer Design Pattern](https://en.wikipedia.org/wiki/Observer_pattern) (a.k.a. Observer Pattern) is fundamental to building GUIs (Graphical User Interfaces) following the [MVC (Model View Controller) Architectural Pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) or any of its variations like [MVP (Model View Presenter)](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter). In the original Smalltalk-MVC, the View observes the Model for changes and updates itself accordingly.
+
+![MVC - Model View Controller](https://www.researchgate.net/profile/Danny-Weyns/publication/269303611/figure/fig2/AS:858133056462866@1581606272800/Smalltalk80-MVC-pattern-View-and-Controller-work-as-a-pair-allowing-the-user-to-interact.ppm)
+
+[Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) supports the [Observer Design Pattern](https://en.wikipedia.org/wiki/Observer_pattern) via the `observe(model, attribute=nil)` keyword, which can observe `Object` models with attributes, `Hash`es, and `Array`s. It automatically enhances objects as needed to support automatically notifying observers of changes via `observable#notify_observers(attribute)` method:
+- `Object` becomes `Glimmer::DataBinding::ObservableModel`, which supports observing specified `Object` model attributes.
+- `Hash` becomes `Glimmer::DataBinding::ObservableHash`, which supports observing all `Hash` keys or a specific `Hash` key
+- `Array` becomes `Glimmer::DataBinding::ObservableArray`, which supports observing `Array` changes like those done with `push`, `<<`, `delete`, and `map!` methods (all mutation methods).
+
+Example:
+
+```ruby
+  observe(person, :name) do |new_name|
+    @name_label.text = new_name
+  end
+```
+
+That observes a person's name attribute for changes and updates the name `label` `text` property accordingly.
+
+[Learn about Glimmer's Observer Pattern capabilities and options in more detail at the Glimmer project page.](https://github.com/AndyObtiva/glimmer#data-binding-library)
+
+See examples of the `observe` keyword at [Color The Circles](#color-the-circles), [Method-Based Custom Keyword](#method-based-custom-keyword), [Snake](#snake), and [Tetris](#tetris).
+
 ### Data-Binding
 
 [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) supports unidirectional (one-way) data-binding of any control/shape/attributed-string property via the `<=` symbol (indicating data is moving from the right side, which is the model, to the left side, which is the GUI view object).
 
+The data-binding API is more precisely: `view_property <= [model, attribute, *options]`
+
 This is also known as the [Glimmer Shine](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#shine) syntax for data-binding, a [Glimmer](https://github.com/AndyObtiva/glimmer)-only unique innovation.
 
 Example:
 
 ```ruby
-window {
-  title <= [@game, :score, on_read: -> (score) {"Glimmer Snake (Score: #{@game.score})"}]
+square(0, 0, CELL_SIZE) {
+  fill <= [@grid.cells[row][column], :color]
 }
 ```
 
-That is data-binding the `window` `title` property to the `score` attribute of a `@game`, but converting on read from the Model to a `String`.
+That is data-binding a grid cell color to a `square` shape's `fill` property. That means if the `color` attribute of the grid cell is updated, the `fill` property of the `square` shape is automatically updated accordingly.
 
 Another Example:
 
 ```ruby
-square(0, 0, CELL_SIZE) {
-  fill <= [@grid.cells[row][column], :color]
+window {
+  title <= [@game, :score, on_read: -> (score) {"Glimmer Snake (Score: #{@game.score})"}]
 }
 ```
 
-That is data-binding a grid cell color to a `square` shape's `fill` property. That means if the `color` attribute of the grid cell is updated, the `fill` property of the `square` shape is automatically updated accordingly.
+That is data-binding the `window` `title` property to the `score` attribute of a `@game`, but converting on read from the Model to a `String`.
 
 Data-binding enables writing very expressive, terse, and declarative code to synchronize View properties with Model attributes instead of pages of imperative code doing the same thing.
 
+Options include:
+- `before_read {|value| ...}`: performs an operation before reading data from Model to update the View.
+- `on_read {|value| ...}`: converts value read from Model to update the View.
+- `after_read {|converted_value| ...}`: performs an operation after read from Model and updating the View.
+
 Learn more from data-binding usage in [Snake](#snake) and [Tic Tac Toe](#tic_tac_toe) examples.
 
 ### API Gotchas
@@ -4451,7 +4484,8 @@ class ColorTheCircles
   end
   
   def register_observers
-    observer = Glimmer::DataBinding::Observer.proc do |new_score|
+    # observe automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer block of score attribute changes
+    observe(self, :score) do |new_score|
       Glimmer::LibUI.queue_main do
         @score_label.text = new_score.to_s
         if new_score == -20
@@ -4465,7 +4499,6 @@ class ColorTheCircles
         end
       end
     end
-    observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
   end
   
   def setup_circle_factory
@@ -6282,9 +6315,9 @@ def label_pair(model, attribute, value)
     name_label = label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
     value_label = label(value.to_s)
   }
-  Glimmer::DataBinding::Observer.proc do
+  observe(model, attribute) do
     value_label.text = model.send(attribute)
-  end.observe(model, attribute)
+  end
 end
 
 def address(address)
@@ -6591,14 +6624,14 @@ New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version
 
 ```ruby
 require 'glimmer-dsl-libui'
-require 'glimmer/data_binding/observer'
 
 require_relative 'snake/presenter/grid'
 
 class Snake
+  include Glimmer
+  
   CELL_SIZE = 15
   SNAKE_MOVE_DELAY = 0.1
-  include Glimmer
   
   def initialize
     @game = Model::Game.new
@@ -6644,7 +6677,7 @@ class Snake
             @game.width.times do |column|
               area {
                 square(0, 0, CELL_SIZE) {
-                  fill <= [@grid.cells[row][column], :color]
+                  fill <= [@grid.cells[row][column], :color] # data-bind square fill to grid cell color
                 }
                 
                 on_key_up do |area_key_event|
@@ -6739,7 +6772,7 @@ class Tetris
   end
   
   def register_observers
-    Glimmer::DataBinding::Observer.proc do |game_over|
+    observe(@game, :game_over) do |game_over|
       if game_over
         @pause_menu_item.enabled = false
         show_game_over_dialog
@@ -6747,11 +6780,11 @@ class Tetris
         @pause_menu_item.enabled = true
         start_moving_tetrominos_down
       end
-    end.observe(@game, :game_over)
+    end
     
     Model::Game::PLAYFIELD_HEIGHT.times do |row|
       Model::Game::PLAYFIELD_WIDTH.times do |column|
-        Glimmer::DataBinding::Observer.proc do |new_color|
+        observe(@game.playfield[row][column], :color) do |new_color|
           Glimmer::LibUI.queue_main do
             color = Glimmer::LibUI.interpret_color(new_color)
             block = @playfield_blocks[row][column]
@@ -6762,13 +6795,13 @@ class Tetris
             block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
             block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
           end
-        end.observe(@game.playfield[row][column], :color)
+        end
       end
     end
     
     Model::Game::PREVIEW_PLAYFIELD_HEIGHT.times do |row|
       Model::Game::PREVIEW_PLAYFIELD_WIDTH.times do |column|
-        Glimmer::DataBinding::Observer.proc do |new_color|
+        observe(@game.preview_playfield[row][column], :color) do |new_color|
           Glimmer::LibUI.queue_main do
             color = Glimmer::LibUI.interpret_color(new_color)
             block = @preview_playfield_blocks[row][column]
@@ -6779,27 +6812,27 @@ class Tetris
             block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
             block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
           end
-        end.observe(@game.preview_playfield[row][column], :color)
+        end
       end
     end
 
-    Glimmer::DataBinding::Observer.proc do |new_score|
+    observe(@game, :score) do |new_score|
       Glimmer::LibUI.queue_main do
         @score_label.text = new_score.to_s
       end
-    end.observe(@game, :score)
+    end
 
-    Glimmer::DataBinding::Observer.proc do |new_lines|
+    observe(@game, :lines) do |new_lines|
       Glimmer::LibUI.queue_main do
         @lines_label.text = new_lines.to_s
       end
-    end.observe(@game, :lines)
+    end
 
-    Glimmer::DataBinding::Observer.proc do |new_level|
+    observe(@game, :level) do |new_level|
       Glimmer::LibUI.queue_main do
         @level_label.text = new_level.to_s
       end
-    end.observe(@game, :level)
+    end
   end
   
   def menu_bar

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

data/examples/color_the_circles.rb

@@ -26,7 +26,8 @@ class ColorTheCircles
   end
   
   def register_observers
-    observer = Glimmer::DataBinding::Observer.proc do |new_score|
+    # observe automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer block of score attribute changes
+    observe(self, :score) do |new_score|
       Glimmer::LibUI.queue_main do
         @score_label.text = new_score.to_s
         if new_score == -20
@@ -40,7 +41,6 @@ class ColorTheCircles
         end
       end
     end
-    observer.observe(self, :score) # automatically enhances self to become Glimmer::DataBinding::ObservableModel and notify observer on score attribute changes
   end
   
   def setup_circle_factory

data/examples/method_based_custom_keyword.rb

@@ -34,9 +34,9 @@ def label_pair(model, attribute, value)
     name_label = label(attribute.to_s.underscore.split('_').map(&:capitalize).join(' '))
     value_label = label(value.to_s)
   }
-  Glimmer::DataBinding::Observer.proc do
+  observe(model, attribute) do
     value_label.text = model.send(attribute)
-  end.observe(model, attribute)
+  end
 end
 
 def address(address)

data/examples/snake/presenter/grid.rb

@@ -1,10 +1,12 @@
-require 'glimmer/data_binding/observer'
+require 'glimmer'
 require_relative '../model/game'
 require_relative 'cell'
 
 class Snake
   module Presenter
     class Grid
+      include Glimmer
+      
       attr_reader :game, :cells
       
       def initialize(game = Model::Game.new)
@@ -14,7 +16,7 @@ class Snake
             Cell.new(grid: self, row: row, column: column)
           end
         end
-        Glimmer::DataBinding::Observer.proc do |new_vertebrae|
+        observe(@game.snake, :vertebrae) do |new_vertebrae|
           occupied_snake_positions = @game.snake.vertebrae.map {|v| [v.row, v.column]}
           @cells.each_with_index do |row_cells, row|
             row_cells.each_with_index do |cell, column|
@@ -27,7 +29,7 @@ class Snake
               end
             end
           end
-        end.observe(@game.snake, :vertebrae)
+        end
       end
       
       def clear

data/examples/snake.rb

@@ -1,12 +1,12 @@
 require 'glimmer-dsl-libui'
-require 'glimmer/data_binding/observer'
 
 require_relative 'snake/presenter/grid'
 
 class Snake
+  include Glimmer
+  
   CELL_SIZE = 15
   SNAKE_MOVE_DELAY = 0.1
-  include Glimmer
   
   def initialize
     @game = Model::Game.new
@@ -52,7 +52,7 @@ class Snake
             @game.width.times do |column|
               area {
                 square(0, 0, CELL_SIZE) {
-                  fill <= [@grid.cells[row][column], :color]
+                  fill <= [@grid.cells[row][column], :color] # data-bind square fill to grid cell color
                 }
                 
                 on_key_up do |area_key_event|

data/examples/tetris.rb

@@ -42,7 +42,7 @@ class Tetris
   end
   
   def register_observers
-    Glimmer::DataBinding::Observer.proc do |game_over|
+    observe(@game, :game_over) do |game_over|
       if game_over
         @pause_menu_item.enabled = false
         show_game_over_dialog
@@ -50,11 +50,11 @@ class Tetris
         @pause_menu_item.enabled = true
         start_moving_tetrominos_down
       end
-    end.observe(@game, :game_over)
+    end
     
     Model::Game::PLAYFIELD_HEIGHT.times do |row|
       Model::Game::PLAYFIELD_WIDTH.times do |column|
-        Glimmer::DataBinding::Observer.proc do |new_color|
+        observe(@game.playfield[row][column], :color) do |new_color|
           Glimmer::LibUI.queue_main do
             color = Glimmer::LibUI.interpret_color(new_color)
             block = @playfield_blocks[row][column]
@@ -65,13 +65,13 @@ class Tetris
             block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
             block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
           end
-        end.observe(@game.playfield[row][column], :color)
+        end
       end
     end
     
     Model::Game::PREVIEW_PLAYFIELD_HEIGHT.times do |row|
       Model::Game::PREVIEW_PLAYFIELD_WIDTH.times do |column|
-        Glimmer::DataBinding::Observer.proc do |new_color|
+        observe(@game.preview_playfield[row][column], :color) do |new_color|
           Glimmer::LibUI.queue_main do
             color = Glimmer::LibUI.interpret_color(new_color)
             block = @preview_playfield_blocks[row][column]
@@ -82,27 +82,27 @@ class Tetris
             block[:left_bevel_edge].fill = {r: color[:r] - BEVEL_CONSTANT, g: color[:g] - BEVEL_CONSTANT, b: color[:b] - BEVEL_CONSTANT}
             block[:border_square].stroke = new_color == Model::Block::COLOR_CLEAR ? COLOR_GRAY : color
           end
-        end.observe(@game.preview_playfield[row][column], :color)
+        end
       end
     end
 
-    Glimmer::DataBinding::Observer.proc do |new_score|
+    observe(@game, :score) do |new_score|
       Glimmer::LibUI.queue_main do
         @score_label.text = new_score.to_s
       end
-    end.observe(@game, :score)
+    end
 
-    Glimmer::DataBinding::Observer.proc do |new_lines|
+    observe(@game, :lines) do |new_lines|
       Glimmer::LibUI.queue_main do
         @lines_label.text = new_lines.to_s
       end
-    end.observe(@game, :lines)
+    end
 
-    Glimmer::DataBinding::Observer.proc do |new_level|
+    observe(@game, :level) do |new_level|
       Glimmer::LibUI.queue_main do
         @level_label.text = new_level.to_s
       end
-    end.observe(@game, :level)
+    end
   end
   
   def menu_bar

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glimmer-dsl-libui
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Andy Maleh