glimmer-dsl-swt 4.18.1.1 → 4.18.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa85c5f6d4f5a71bbc9538f291fff86199d26219c7b919068b5be7f99fc4bfd
-  data.tar.gz: 4db3a940c06f112c309e822ce73b0a1e98317f87ae808c183f261d49d357c490
+  metadata.gz: 9e12bb24a84b93822013eef2122021cd5e6a8f90f9e450ac83f7bd5b5f0b7b55
+  data.tar.gz: dfdba626253a34506b99971821378e8579eac7f21a955ddbd7bc0543f770ad51
 SHA512:
-  metadata.gz: 96d95b883f011fc5d706382c4a8f1eea500ccd9ad15bf1fb3c82e9c7509348d0dcd16ef4c99ef963eb3bb4760e63aca217d0f4ab43d404ea6c8fa636bdfc8adc
-  data.tar.gz: a5182246e7825790b8c63ed8b7506d0e35e93af1f5a2e60c8ad6e015cee6fb092357ef2ca842d6f4bcf432b9cc5676b8167ec2bb42ef6dde47d007e50e1c2ba0
+  metadata.gz: d489317bc86659858e1215aca4f35441aa123f59affb4f35fe9fce1ec04f220f3856f5d203d686a1091a7a1652b746a9453ce598eb684910b1ded8717fc1552b
+  data.tar.gz: 10c31c53aab7d5a8905c6448f66dcacb01c98b952c9934ae1e5236437e583d37aa607161f38946754938c9fc655c876064cc268a93d73d8746667d69d69f684b

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Change Log
 
+### 4.18.2.4
+
+- Tetris scoring
+- Tetris eliminated Line tracking
+- Tetris level tracking and speed-ups
+- Tetris preview upcoming tetromino shape
+- Added parent_proxy to CustomWidget and CustomShell classes
+- Update CustomShell#center and ShellProxy#center to center_within_display to avoid clash with `row_layout` center property
+- Fixed issue with shell/dialog/custom-shell not maintaining parent when not passed
+- Fix Tetris sideways edge detection
+
+### 4.18.2.3
+
+- Added Tetris Elaborate Sample
+- Added support for CustomShell `::launch` and `::shutdown` class methods to treat a top-level custom shell as a self contained launchable app (saving you from writing boilerplate code for launching Glimmer applications)
+
+### 4.18.2.2
+
+- Fixed issue with processing shape color due to missing Color class package name
+
+### 4.18.2.1
+
+- Ensure drawing image works in Shape DSL
+- Support passing image as simply an image path or image proxy to Shape DSL image method
+
+### 4.18.2.0
+
+- Canvas animation start method (useful if animation had a frame count limit or cycle count limit and needed to be started again after it stopped)
+- Canvas animation stop method
+- Canvas animation restart method (restarts from frame 1)
+- Canvas animation started? # meaning it is animating
+- Canvas animation stopped? # meaning it has stopped animating
+- Canvas animation duration_limit option
+- Make gradient/round rectangles in Shape DSL receive an option of `gradient: true` and `round: true` instead of prefix
+- Canvas Shape DSL support for Background/Foreground Pattern (NOTE: not extensively tested yet)
+- Canvas Shape DSL smart defaults for background/foreground depending on shape being drawn
+- Canvas Shape DSL smart defaults for fill option depending on shape being drawn
+- Added fallback font "Courier" for `code_text` widget when "Consolas" is not available.
+
 ### 4.18.1.1
 
 - Add smart defaults for round rectangle angles (defaults to 60 degrees angles)

data/README.md

@@ -1,6 +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 SWT 4.18.1.1
-
-
+# [<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 SWT 4.18.2.4
 ## JRuby Desktop Development GUI Framework
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-swt.svg)](http://badge.fury.io/rb/glimmer-dsl-swt)
 [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer-dsl-swt.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt)
@@ -10,9 +8,7 @@
 
 **[Contributors Wanted! (Submit a Glimmer App Sample to Get Started)](#contributing)**
 
-(The Original Glimmer Library Since 2007. Beware of Imitators!)
-
-[Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://github.com/AndyObtiva/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models (test-first) afterwards. Not only does Glimmer provide a large set of GUI [widgets](#widgets), but also supports drawing Canvas Graphics like [Shapes](#canvas-shape-dsl) and [Animations](#canvas-animation-dsl). To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/), MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows), and [Gem Packaged Shell Scripts](#custom-shell-gem) on [Linux](https://www.linux.org/).
+[Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster JVM version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://github.com/AndyObtiva/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces by relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models (test-first) afterwards. Not only does Glimmer provide a large set of GUI [widgets](#widgets), but it also supports drawing Canvas Graphics like [Shapes](#canvas-shape-dsl) and [Animations](#canvas-animation-dsl). To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/), MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows), and [Gem Packaged Shell Scripts](#custom-shell-gem) on [Linux](https://www.linux.org/).
 
 [Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs. Please make [Glimmer](https://rubygems.org/gems/glimmer) even better by providing feedback and [contributing](#contributing) when possible.
 
@@ -230,6 +226,11 @@ Glimmer App:
 
 [![Math Bowling App Screenshot](https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/Math-Bowling-Screenshot.png)](https://github.com/AndyObtiva/MathBowling)
 
+**Note:** I offer Glimmer as an open-source project that represents my interests in Ruby Programming, Desktop GUI application development with SWT, Object Oriented Design, Design Patterns, and Software Architecture.
+Additionally, I am sharing my professional experience and expertise in Eclipse SWT given that I am an [EclipseCon](http://andymaleh.blogspot.com/2007/03/eclipsecon-2007-day-3.html)/[EclipseWorld](http://andymaleh.blogspot.com/2008/11/eclipseworld-2008-highlights.html) presenter and have built professional applications in SWT/JFace/RCP for Obtiva and the Pampered Chef in the past. This is also done in the hopes that it would indirectly bring me work in a field I am extremely passionate about.
+That said, please keep in mind that I myself am learning topics in Software Engineering too everyday, including newer editions of SWT and JRuby, which seem to pop up every quarter.
+If you see anything that needs to be improved, please do not hesitate to contact me on [Gitter](https://gitter.im/AndyObtiva/glimmer) or submit [Issues](https://github.com/AndyObtiva/glimmer-dsl-swt/issues)/[Pull-Requests](https://github.com/AndyObtiva/glimmer-dsl-swt/pulls).
+
 ## Table of contents
 
 - [Glimmer (JRuby Desktop Development GUI Framework)](#jruby-desktop-development-gui-framework)
@@ -305,7 +306,7 @@ Glimmer App:
       - [Custom Widget API](#custom-widget-api)
       - [Content/Options Example](#contentoptions-example)
       - [Gotcha](#gotcha)
-      - [Final Notes](#final-notes)
+      - [Custom Widget Final Notes](#custom-widget-final-notes)
     - [Custom Shells](#custom-shells)
     - [Drag and Drop](#drag-and-drop)
     - [Miscellaneous](#miscellaneous)
@@ -368,6 +369,7 @@ Glimmer App:
       - [Login](#login)
       - [Tic Tac Toe Sample](#tic-tac-toe-sample)
       - [Contact Manager Sample](#contact-manager-sample)
+      - [Tetris](#tetris)
     - [External Samples](#external-samples)
       - [Glimmer Calculator](#glimmer-calculator)
       - [Gladiator](#gladiator)
@@ -456,7 +458,7 @@ jgem install glimmer-dsl-swt
 
 Or this command if you want a specific version:
 ```
-jgem install glimmer-dsl-swt -v 4.18.1.1
+jgem install glimmer-dsl-swt -v 4.18.2.4
 
 
 ```
@@ -476,7 +478,7 @@ Note: if you're using activerecord or activesupport, keep in mind that Glimmer u
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer-dsl-swt', '~> 4.18.1.1
+gem 'glimmer-dsl-swt', '~> 4.18.2.4
 '
 ```
 
@@ -535,7 +537,7 @@ bin/glimmer samples
 Below are the full usage instructions that come up when running `glimmer` without args.
 
 ```
-Glimmer (JRuby Desktop Development GUI Framework) - JRuby Gem: glimmer-dsl-swt v4.18.1.1
+Glimmer (JRuby Desktop Development GUI Framework) - JRuby Gem: glimmer-dsl-swt v4.18.2.4
 
 
       
@@ -1016,7 +1018,7 @@ Output:
                                                                          
   Css    glimmer-dsl-css    1.1.0     AndyMaleh    Glimmer DSL for CSS
   Opal   glimmer-dsl-opal   0.10.2     AndyMaleh    Glimmer DSL for Opal
-  Swt    glimmer-dsl-swt    4.18.1.1
+  Swt    glimmer-dsl-swt    4.18.2.4
 
   AndyMaleh    Glimmer DSL for SWT
   Tk     glimmer-dsl-tk     0.0.6     AndyMaleh    Glimmer DSL for Tk
@@ -1084,6 +1086,8 @@ With `glimmer-dsl-swt` installed, you may want to run `girb` instead of standard
 girb
 ```
 
+![GIRB](images/glimmer-girb.png)
+
 If you cloned [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) project locally, you may run `bin/girb` instead.
 
 ```
@@ -1349,7 +1353,8 @@ This is not an exaustive list, but should give you a good start in learning Glim
 **Event loop:**
 - `display`: featured in [Tic Tac Toe](#tic-tac-toe)
 - `async_exec`: featured in [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Custom Shell!](#hello-custom-shell)
-
+- `sync_exec`: executes a block on the event loop synchronously (usually from another thread)
+- `timer_exec`: executes a block after a delay of time has passed
 
 #### SWT Proxies
 
@@ -2294,68 +2299,79 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
 
 ### Canvas Shape DSL
 
-(note: this is a very new feature of Glimmer. It may change a bit while getting battle tested. As always, you could default to basic SWT usage if needed.)
-
 Glimmer supports drawing graphics directly on a `canvas` widget via SWT (or any widget for that matter though `canvas` is recommended for drawing).
 
 This is accomplished via the Shape DSL a sub-DSL of the Glimmer GUI DSL, which makes it possible to draw graphics declaratively with very understandable and maintainable syntax.
 
 Shape keywords and their args (including defaults) are listed below (they basically match method names and arguments on [org.eclipse.swt.graphics.GC](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/GC.html) minus the `draw` or `fill` prefix in downcase):
-- `arc​(x, y, width, height, startAngle, arcAngle, fill: false)`
-- `focus​(x, y, width, height)`
-- `image(image, x, y)`
-- `line(x1, y1, x2, y2)`
-- `oval(x, y, width, height, fill: false)`
-- `point​(x, y)`
-- `polygon(pointArray, fill: false)`
-- `polyline(pointArray)`
-- `rectangle(x, y, width, height, fill: false)`
-- `round_rectangle(x, y, width, height, arcWidth = 60, arcHeight = 60, fill: false)`
-- `gradient_rectangle​(x, y, width, height, vertical = true, fill: false)`
-- `text(String string, x, y)`
+- `arc​(x, y, width, height, startAngle, arcAngle, fill: false)` arc is part of a circle within an oval area, denoted by start angle (degrees) and end angle (degrees)
+- `focus​(x, y, width, height)` this is just like rectangle but its foreground color is always that of the OS widget focus color (useful when capturing user interaction via a shape)
+- `image(image, x, y)` [image](#image)
+- `line(x1, y1, x2, y2)` line
+- `oval(x, y, width, height, fill: false)` oval if width does not match heigh and circle if width matches height. Can be optionally filled.
+- `point​(x, y)` point
+- `polygon(pointArray, fill: false)` polygon consisting of points, which close automatically to form a shape that can be optionally filled (when points only form a line, it does not show up as filled)
+- `polyline(pointArray)` polyline is just like a polygon, but it does not close up to form a shape, remaining open (unless the points close themselves by having the last point or an intermediate point match the first)
+- `rectangle(x, y, width, height, fill: false)` standard rectangle, which can be optionally filled
+- `rectangle(x, y, width, height, arcWidth = 60, arcHeight = 60, fill: false, round: true)` round rectangle, which can be optionally filled, and takes optional extra round angle arguments
+- `rectangle​(x, y, width, height, vertical = true, fill: true, gradient: true)` gradient rectangle, which is always filled, and takes an optional extra argument to specify true for vertical gradient (default) and false for horizontal gradient
+- `text(string, x, y, flags = nil)` text with optional flags (flag format is `swt(comma_separated_flags)` where flags can be :draw_delimiter (i.e. new lines), :draw_tab, :draw_mnemonic, and :draw_transparent as explained in [GC API](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/GC.html))
 
 Shape keywords that can be filled with color can take an keyword argument `fill: true` (defaults to false when not specified)
 
 Optionally, a shape keyword takes a block that can set any attributes from [org.eclipse.swt.graphics.GC](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/GC.html) (methods starting with `set`), which enable setting the `background` for filling and `foreground` for drawing.
 
 Here is a list of supported attributes nestable within a block under shapes:
-- `alpha` sets transparency (integer between 0 and 255)
-- `antialias` enables antialiasing (SWT style value of :default, :off, :on whereby :default applies OS default)
-- `background` sets fill color for fillable shapes (standard color symbol (e.g. :red), `rgb(red_integer, green_integer, blue_integer)` color, or Color/ColorProxy object directly)
-- `clipping​(x, y, width, height)` clips area of painting
-- `fill_rule` sets filling rule (SWT style value of :fill_even_odd or :fill_winding)
-- `font` sets font (Hash of :name, :height, and :style just like standard widget font property, or Font/FontProxy object directly)
-- `line_cap` sets line cap (SWT style value of :cap_flat, :cap_round, or :cap_square)
-- `line_dash` line dash float values (automatically sets `line_style` to SWT style value of :line_custom)
-- `line_join` line join style (SWT style value of :join_miter, :join_round, or :join_bevel)
-- `line_style` line join style (SWT style value of :line_solid, :line_dash, :line_dot, :line_dashdot, or :line_dashdotdot)
+- `advanced` enables advanced graphics subsystem (boolean value). Typically gets enabled automatically when setting alpha, antialias, patterns, interpolation, clipping. Rendering sometimes differs between advanced and non-advanced mode for basic graphics too, so you could enable manually if you prefer its look even for basic graphics.
+- `alpha` sets transparency (integer between `0` and `255`)
+- `antialias` enables antialiasing (SWT style value of `:default`, `:off`, `:on` whereby `:default` applies OS default, which varies per OS)
+- `background` sets fill color for fillable shapes (standard color symbol (e.g. `:red`), `rgb(red_integer, green_integer, blue_integer)` color, or Color/ColorProxy object directly)
+- `background_pattern` sets fill gradient/image pattern for fillable shape background (takes the same arguments as the SWT [Pattern](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/Pattern.html) class [e.g. `background_pattern 2.3, 4.2, 5.4, 7.2, :red, :blue`] / note: this feature isn't extensively tested yet)
+- `clipping` clips area of painting (​numeric values for `(x, y, width, height)`)
+- `fill_rule` sets filling rule (SWT style value of `:fill_even_odd` or `:fill_winding`)
+- `font` sets font (Hash of `:name`, `:height`, and `:style` just like standard widget font property, or Font/FontProxy object directly)
+- `foreground` sets draw color for drawable shapes (standard color symbol (e.g. `:red`), `rgb(red_integer, green_integer, blue_integer)` color, or Color/ColorProxy object directly)
+- `foreground_pattern` sets foreground gradient/image pattern for drawable shape lines (takes the same arguments as the SWT [Pattern](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/Pattern.html) class [e.g. `foreground_pattern 2.3, 4.2, 5.4, 7.2, :red, :blue`] / note: this feature isn't extensively tested yet)
+- `interpolation` sets the interpolation value (SWT style value of `:default`, `:none`, `:low`, `:high`)
+- `line_cap` sets line cap (SWT style value of `:cap_flat`, `:cap_round`, or `:cap_square`)
+- `line_dash` line dash float values (automatically sets `line_style` to SWT style value of `:line_custom`)
+- `line_join` line join style (SWT style value of `:join_miter`, `:join_round`, or `:join_bevel`)
+- `line_style` line join style (SWT style value of `:line_solid`, `:line_dash`, `:line_dot`, `:line_dashdot`, or `:line_dashdotdot`)
 - `line_width` line width in integer (used in draw operations)
-- `text_anti_alias` enables text antialiasing (SWT style value of :default, :off, :on whereby :default applies OS default)
+- `text_anti_alias` enables text antialiasing (SWT style value of `:default`, `:off`, `:on` whereby `:default` applies OS default, which varies per OS)
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
 include Glimmer
 
+# image object has to be declared outside the canvas and shell to avoid confusing with canvas image property
+image_object = image(File.expand_path('./icons/scaffold_app.png'), width: 100)
+
 shell {
   text 'Canvas Example'
   minimum_size 320, 400
 
   canvas {
-    background :yellow
+    background :dark_yellow
     rectangle(0, 0, 220, 400, fill: true) {
-      background :red
+      background :dark_red
     }
-    round_rectangle(50, 20, 300, 150, 30, 50, fill: true) {
-      background :magenta
+    rectangle(50, 20, 300, 150, 30, 50, round: true, fill: true) {
+      background :yellow
     }
-    gradient_rectangle(150, 200, 100, 70, true, fill: true) {
-      background :dark_magenta
+    rectangle(150, 200, 100, 70, true, gradient: true) {
+      background :dark_red
       foreground :yellow
     }
+    text('Glimmer', 208, 83) {
+      font height: 25, style: :bold
+    }
     rectangle(200, 80, 108, 36) {
-      foreground color(:dark_blue)
+      foreground :black
+      line_width 3
     }
+    image(image_object, 70, 50)
   }
 }.open
 ```
@@ -2366,6 +2382,43 @@ Screenshot:
 
 Learn more at the [Hello, Canvas! Sample](#hello-canvas).
 
+If you get extremely stuck, remember that you could always default to direct [SWT GC usage]([org.eclipse.swt.graphics.GC](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/GC.html) and learn more at the [SWT Graphics Guide](https://www.eclipse.org/articles/Article-SWT-graphics/SWT_graphics.html) and [SWT Image Guide](https://www.eclipse.org/articles/Article-SWT-images/graphics-resources.html#Saving%20Images).
+
+Example of manually doing the same things as in the above example without relying on the declarative Glimmer Shape DSL:
+
+```ruby
+include Glimmer
+
+shell {
+  text 'Canvas Manual Example'
+  minimum_size 320, 400
+
+  canvas {
+    background :yellow
+    
+    on_paint_control { |event|
+      event.gc.setBackground(color(:red).swt_color)
+      event.gc.fillRectangle(0, 0, 220, 400)
+      
+      event.gc.setBackground(color(:magenta).swt_color)
+      event.gc.fillRoundRectangle(50, 20, 300, 150, 30, 50)
+      
+      event.gc.setBackground(color(:dark_magenta).swt_color)
+      event.gc.fillGradientRectangle(150, 200, 100, 70, true)
+      
+      event.gc.setForeground(color(:dark_blue).swt_color)
+      event.gc.drawRectangle(200, 80, 108, 36)
+    }
+  }
+}.open
+```
+
+In any case, if there is anything missing you would like added to the Glimmer Shape DSL that you saw available in the SWT APIs, you may [report an issue](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) or implement yourself and [contribute](#contributing) via a [Pull Request](https://github.com/AndyObtiva/glimmer-dsl-swt/pulls).
+
+#### Shapes inside a Widget
+
+Keep in mind that the Shape DSL can be used inside any widget, not just `canvas`. Unlike shapes on a `canvas`, which are standalone graphics, when included in a widget, which already has its own look and feel, shapes are used as a decorative add-on that complements its look by getting painted on top of it. For example, shapes were used to decorate `composite` blocks in the [Tetris](#tetris) sample to have a more bevel look. In summary, Shapes can be used in a hybrid approach (shapes inside a widget), not just standalone in a `canvas`.
+
 ### Canvas Animation DSL
 
 (note: this is a very new feature of Glimmer. It may change a bit while getting battle tested. As always, you could default to basic SWT usage if needed.)
@@ -2374,7 +2427,7 @@ Glimmer additionally provides built-in support for animations via a declarative
 
 Animations take advantage of multi-threading, each animation runs in its own independent thread of execution while updating the GUI asynchronously.
 
-This example says it all (it moves a tiny red square across a blue background):
+This example says it all (it moves a tiny red square across a blue background) (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
 include Glimmer
@@ -2411,12 +2464,23 @@ Keywords:
 - `frame_count` an optional frame count limit after which the animation stops
 - `started` a boolean indicating if the animation is started right away or stopped waiting for manual startup via `#start` method
 
-API:
-- `#start` starts animation as a method on the animation object (returned from `animation` keyword)
-- `#stop` stops animation gracefully as a method on the animation object (returned from `animation` keyword)
+API of Animation Object (returned from `animation` keyword):
+- `#start` starts an animation that is indefinite or has never been started before (i.e. having `started: false` option). Otherwise, resumes a stopped animation that has not been completed.
+- `#stop` stops animation. Maintains progress when `frame_count`, `cycle_count`, or `duration_limit` are set and haven't finished. That way, if `#start` is called, animation resumes from where it stopped exactly to completion.
+- `#restart` restarts animation, restarting progress of `frame_count`, `cycle_count`, and `duration_limit` if set.
+- `#started?` returns whether animation started
+- `#stopped?` returns whether animation stopped
+- `#indefinite?` (alias `infinite?`) returns true if animation does not have `frame_count`, `cycle_count`, or `duration_limit`
+- `#finite?` returns true if animation has `frame_count`, `cycle_count` (with `cycle`), or `duration_limit`
+- `#frame_count_limited?` returns true if `frame_count` is specified
+- `#cycle_enabled?` returns true if `cycle` is specified
+- `#cycle_limited?` returns true if `cycle_count` is specified
+- `#duration_limited?` returns true if `duration_limit` is specified
 
 Learn more at the [Hello, Canvas Animation! Sample](#hello-canvas-animation).
 
+If there is anything missing you would like added to the Glimmer Animation DSL that you saw available in the SWT APIs, you may [report an issue](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) or implement yourself and [contribute](#contributing) via a Pull Request.
+
 ### Data-Binding
 
 Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
@@ -2897,7 +2961,7 @@ If you need a better widget with the ability to customize the date format patter
 
 ### Observer
 
-Glimmer comes with `Observer` module, which is used internally for data-binding, but can also be used externally for custom use of the Observer Pattern. It is hidden when observing widgets, and used explicitly when observing models.
+Glimmer comes with the `Observer` mixin module, which is used internally for data-binding, but can also be used externally for custom use of the Observer Pattern. It is hidden when observing widgets, and used explicitly when observing models. In bidirectional data-binding, `Observer` is automatically unregistered from models once a widget is disposed to avoid memory leaks and worrying about managing them yourself.
 
 #### Observing Widgets
 
@@ -3263,7 +3327,7 @@ body {
 
 The `text` method invoked in the custom widget body will call the one you defined above it. To avoid this gotcha, simply name the text property above something else, like `custom_text`.
 
-#### Final Notes
+#### Custom Widget Final Notes
 
 This [Eclipse guide](https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm) for how to write custom SWT widgets is also applicable to Glimmer Custom Widgets written in Ruby. I recommend reading it:
 [https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm](https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm)
@@ -4587,6 +4651,18 @@ Contact Manager - Edit Done
 
 ![Contact Manager](images/glimmer-contact-manager-edit-done.png)
 
+#### Tetris
+
+This sample demonstrates how to build an interactive animated game with MVC architecture, custom-shell/custom-widgets, multi-threading, asynchronous programming, data-binding, canvas shape graphic decorations, and keyboard events.
+
+Code:
+
+[samples/elaborate/tetris.rb](samples/elaborate/tetris.rb)
+
+![Tetris](images/glimmer-tetris.png)
+
+![Tetris Game Over](images/glimmer-tetris-game-over.png)
+
 ### External Samples
 
 #### Glimmer Calculator
@@ -4614,7 +4690,7 @@ Gladiator is a good demonstration of:
 
 #### Timer
 
-[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding, multi-threading, and Java (Sound) library integration in a desktop application.
+[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding, multi-threading, and JSound (Java Sound) library integration in a desktop application.
 
 [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/glimmer-timer-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-timer)
 
@@ -4640,6 +4716,8 @@ If you have a Glimmer app you would like referenced here, please mention in a Pu
 
 Note: this section mostly applies to Mac and Windows. On Linux, you can just run `glimmer package:gem` and after installing the gem, you get an executable matching the name of the app/custom-shell-gem you are building (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem)
 
+Note 2: Glimmer packaging has a strong dependency on JDK8 at the moment. JDK9 & JDK10 might work, but JDK11 and onward definitely won't since they dropped javapackager, which later came back as jpackage in JDK14, but it's not ready for prime time yet. Just stick to JDK8 for now, strongly supported by Oracle for the next 6 years at least.
+
 Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
 
 ```
@@ -4707,6 +4785,8 @@ require_relative '../app/my_application.rb'
 
 ### javapackager Extra Arguments
 
+(note: currently `Glimmer::RakeTask::Package.javapackager_extra_args` is only honored when packaging from bash, not zsh)
+
 In order to explicitly configure javapackager, Mac package attributes, or sign your Mac app to distribute on the App Store, you can follow more advanced instructions for `javapackager` here:
 - https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
 - https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html
@@ -4815,6 +4895,16 @@ By the way, keep in mind that during normal operation, it does also indicate a f
 Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1sw__tx6mjdgyh3mky7vydc0000gp/T/fxbundler4076750801763032201/images/MathBowling/.VolumeIcon.icns] in unspecified directory
 ```
 
+3. Zsh (Z Shell)
+
+Currently, `Glimmer::RakeTask::Package.javapackager_extra_args` is only honored when packaging from bash, not zsh.
+
+You can get around that in zsh by running glimmer package commands with `bash -c` prefix:
+
+```
+bash -c 'glimmer package'
+```
+
 ## App Updates
 
 Glimmer already supports automatic (and manual) app updates via the Mac App Store for Mac apps. Simply run the `glimmer package` command with the Mac App Store keys configured as per [Mac Application Distribution](mac-application-distribution) instructions and you get automatic (and manual) app update support courtesy of the Mac App Store.

data/VERSION

@@ -1 +1 @@
-4.18.1.1
+4.18.2.4

data/glimmer-dsl-swt.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: glimmer-dsl-swt 4.18.1.1 ruby lib
+# stub: glimmer-dsl-swt 4.18.2.4 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "glimmer-dsl-swt".freeze
-  s.version = "4.18.1.1"
+  s.version = "4.18.2.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["AndyMaleh".freeze]
-  s.date = "2021-01-20"
-  s.description = "Glimmer DSL for SWT (JRuby Desktop Development GUI Framework) is a native-GUI cross-platform desktop development library written in JRuby, an OS-threaded faster version of Ruby. Glimmer's main innovation is a declarative Ruby DSL that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models (test-first) afterwards. To get started quickly, Glimmer offers scaffolding options for Apps, Gems, and Custom Widgets. Glimmer also includes native-executable packaging support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in Ruby as truly native DMG/PKG/APP files on the Mac + App Store, MSI/EXE files on Windows, and Gem Packaged Shell Scripts on Linux.".freeze
+  s.date = "2021-01-24"
+  s.description = "Glimmer DSL for SWT (JRuby Desktop Development GUI Framework) is a native-GUI cross-platform desktop development library written in JRuby, an OS-threaded faster JVM version of Ruby. Glimmer's main innovation is a declarative Ruby DSL that enables productive and efficient authoring of desktop application user-interfaces by relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models (test-first) afterwards. Not only does Glimmer provide a large set of GUI widgets, but it also supports drawing Canvas Graphics like Shapes and Animations. To get started quickly, Glimmer offers scaffolding options for Apps, Gems, and Custom Widgets. Glimmer also includes native-executable packaging support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in Ruby as truly native DMG/PKG/APP files on the Mac + App Store, MSI/EXE files on Windows, and Gem Packaged Shell Scripts on Linux.".freeze
   s.email = "andy.am@gmail.com".freeze
   s.executables = ["glimmer".freeze, "girb".freeze]
   s.extra_rdoc_files = [
@@ -132,6 +132,14 @@ Gem::Specification.new do |s|
     "samples/elaborate/contact_manager/contact_repository.rb",
     "samples/elaborate/login.rb",
     "samples/elaborate/meta_sample.rb",
+    "samples/elaborate/tetris.rb",
+    "samples/elaborate/tetris/model/block.rb",
+    "samples/elaborate/tetris/model/game.rb",
+    "samples/elaborate/tetris/model/tetromino.rb",
+    "samples/elaborate/tetris/view/block.rb",
+    "samples/elaborate/tetris/view/game_over_dialog.rb",
+    "samples/elaborate/tetris/view/playfield.rb",
+    "samples/elaborate/tetris/view/score_lane.rb",
     "samples/elaborate/tic_tac_toe.rb",
     "samples/elaborate/tic_tac_toe/board.rb",
     "samples/elaborate/tic_tac_toe/cell.rb",