glimmer-dsl-swt 4.18.5.0 → 4.18.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dae230b3e4a50ef2425a4b5155e98ff598e0bb0e3d1f7a5c15eaadcbf5688d41
-  data.tar.gz: 7ec51028f89ec3ff207aecbb2f91ad43b03e1e6db8d03885e681972cdd9fd1f9
+  metadata.gz: 8fb342869be74c6e592466ad89d26798dde5cf8f3d6beb52b5bcf6a6e8f221f6
+  data.tar.gz: c75442b7c5aeac5d77878d52e969669ea677877c12a43c97081155c5412c9c4c
 SHA512:
-  metadata.gz: '0954400586b6df73a08070b2f7bd0669b11dca0ecb9ba614e1719b0a41e9966dad2f7d16c5f3b344bb14cbc4074978b793d206d6034dc3ce5034aee98e9732de'
-  data.tar.gz: '086c20606c6319fa70c480b3633d60682723d246a46c7d4f3d2b2e8d3c9ed83f2d22a7e7f3288cc35fb38f11f0895ed3b98b8297ee607767094f179612aabbc2'
+  metadata.gz: d3e484674be4fa02ea232e1452a80c4fbb2f141bee407ef6ce922dd0f1e3616f6ee420fc57fdd3d9af6c9d993a88705d95e62d9a5573273e63638a5876bf53d9
+  data.tar.gz: 6a76ebd41db15abe32ae22b2c675199595e196251b03a84ddad99a3aa2b254b43b8e50e339579764de667e10e3673814fb4ab3886aa9f27a9f8c43a7ca16bdcd

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Change Log
 
+### 4.18.5.5
+
+- Automatically recalculate default size (width/height) to accomodate nested shapes when changing x/y/width/height sticking out of parent from right or bottom.
+- Support special case of centering a nested shape with default x/y within a parent with default width/height calculated from nested shape
+- Consider Canvas Shape DSL support for LineAttributes `line_dash_offset` and `line_miter_limit`
+- Canvas Shape DSL Polygon `include?` does an outer/inner check of edge detection only
+- Ensure all Canvas Shape DSL properties are restored upon painting a shape to what they were prior to painting that shape
+- Fix issue with bringing high score dialog up in Tetris caused by latest dialog changes for supporting the new `color_dialog` and `font_dialog`
+
+### 4.18.5.4
+
+- Support passing width, height as :default (or nil or not passed in if they are the last args) in all shapes that include other shapes to indicate they are calculated automatically from nested shapes, text/string extent, or otherwise defaulting to 0, 0
+- Support [:default, width_delta], [:default, height_delta] attributes for width and height, which add/subtract from defaults used for shape
+- Switch from use of `:default` with x_delta/y_delta to passing `[:default, x_delta]` or `[:default, y_delta]` (e.g. `image(file, [:default, -30], :default)` for x = default - 30 and y = default + 0)
+- Support a bounding box for all shapes, implementing `#bounds` (x, y, width, and height) and `#size` (width, height) for the ones that don't receive as parameters (like polygon)
+
+### 4.18.5.3
+
+- Support nesting shapes within shapes, with relative positioning (meaning x, y coordinates are assumed relative to parent's x, y in nested shapes)
+- Support passing x, y coordinates as :default (or nil or not passed in if they are the last args) in all shapes, meaning they are centered within parent taking their width and height into account
+- Support default_x_delta, y_delta attributes, which add/subtract from defaults used for shape
+
+### 4.18.5.2
+
+- Support checking if an `arc` shape accurately includes a point x,y coordinates within pie region only
+- Support checking if an `oval` shape includes a point x,y coordinates in oval region only (not its rectangular region)
+- Support checking if a `focus` shape includes a point x,y coordinates
+- Support checking point inclusion differently in drawed vs filled Rectangle (only check the drawn border when not filled)
+- Support checking point inclusion differently in drawed vs filled Oval (only check the drawn border when not filled)
+- Support checking point inclusion differently in drawed vs filled Arc (only check the drawn border when not filled)
+- Support `#include?(x, y)` and `#contain?(x, y)` methods in `text` shape
+- Fix point inclusion check for polyline
+- Fix issue with `polygon` check if it includes a point x,y coordinates (replace with available `java.awt` robust geometry algorithms)
+- Fix issue with transforms not working after the latest changes
+
+### 4.18.5.1
+
+- Hello, Color Dialog! Sample
+- Hello, Font Dialog! Sample
+- Handle SWT RGB color data objects when setting colors on widgets (e.g. background)
+- Enhance Hello, Canvas! with Color selector via right-click menu
+- Fixed issue with tree multi selection throwing an exception
+
 ### 4.18.5.0
 
 - Automatic `sync_exec` usage from threads other than the GUI thread, thus absolving software engineers from the need to use `sync_exec` explicitly anymore.

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 SWT 4.18.5.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 SWT 4.18.5.5
 ## 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)
@@ -8,17 +8,15 @@
 
 **[Contributors Wanted! (Submit a Glimmer App Sample to Get Started)](#contributing)**
 
-[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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#widgets), but it also supports drawing Canvas Graphics like [Shapes](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#canvas-shape-dsl) and [Animations](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#canvas-animation-dsl). To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](docs/reference/GLIMMER_COMMAND.md#scaffolding) options for [Apps](#in-production), [Gems](docs/reference/GLIMMER_COMMAND.md#custom-shell-gem), and [Custom Widgets](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](docs/reference/GLIMMER_PACKAGING_AND_DISTRIBUTION.md) 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](docs/reference/GLIMMER_COMMAND.md#packaging) 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.
-
-Gem version numbers are in sync with the SWT library versions. The first two digits represent the SWT version number. The last two digits represent the minor and patch versions of Glimmer DSL for SWT.
-
-[Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) versions 4.18.x.y come with [SWT 4.18](https://download.eclipse.org/eclipse/downloads/drops4/R-4.18-202012021800/), which was released on December 2, 2020.
+[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for SWT 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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#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](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#widgets), but it also supports drawing Canvas Graphics like [Shapes](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#canvas-shape-dsl) and [Animations](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#canvas-animation-dsl). To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](docs/reference/GLIMMER_COMMAND.md#scaffolding) options for [Apps](#in-production), [Gems](docs/reference/GLIMMER_COMMAND.md#custom-shell-gem), and [Custom Widgets](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](docs/reference/GLIMMER_PACKAGING_AND_DISTRIBUTION.md) 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](docs/reference/GLIMMER_COMMAND.md#packaging) on [Linux](https://www.linux.org/).
 
 [<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
 Featured in JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do) and [Chalmers/Gothenburg University Software Engineering Master's Lecture Material](http://www.cse.chalmers.se/~bergert/slides/guest_lecture_DSLs.pdf)
 
+[Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) 4.18.5.5 includes [SWT 4.18](https://download.eclipse.org/eclipse/downloads/drops4/R-4.18-202012021800/), which was released on December 2, 2020. Gem version numbers are in sync with the SWT library versions. The first two digits represent the SWT version number. The last two digits represent the minor and patch versions of Glimmer DSL for SWT.
+
+[Glimmer DSL for SWT receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) with your Ruby desktop GUI development needs! [Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) brings great ideas to the table, such as declarative programming via domain specific languages, currently under-utilized in the GUI domain. That said, it may not be feature complete enough for everybody's needs, so please help make [Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) even better by providing feedback and [contributing](#contributing) when possible. The project is very active, so any feature suggestions that are accepted could be implemented within weeks if not days. Also, you are welcome to [hire me](#hire-me) full-time if you want long-term development of [Glimmer DSL for SWT](https://rubygems.org/gems/glimmer-dsl-swt) for your project needs.
+
 Glimmer DSL gems:
 - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Framework)
 - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Pure Ruby Web GUI and Auto-Webifier of Desktop Apps)
@@ -342,7 +340,7 @@ jgem install glimmer-dsl-swt
 
 Or this command if you want a specific version:
 ```
-jgem install glimmer-dsl-swt -v 4.18.5.0
+jgem install glimmer-dsl-swt -v 4.18.5.5
 ```
 
 `jgem` is JRuby's version of `gem` command.
@@ -360,7 +358,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.5.0'
+gem 'glimmer-dsl-swt', '~> 4.18.5.5'
 ```
 
 And, then run:
@@ -404,9 +402,16 @@ Glimmer configuration may be done via the `Glimmer::Config` module.
 
 ## Samples
 
+See a listing of samples over here, including screenshots and explanations of what each sample demonstrates:
+
 [docs/reference/GLIMMER_SAMPLES.md](docs/reference/GLIMMER_SAMPLES.md)
 
-Check the [samples](samples) directory in [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) for examples on how to write Glimmer applications. To run a sample, make sure to install the `glimmer-dsl-swt` gem first and then use the `glimmer samples` command to run it (alternatively, you may clone the repo, follow [CONTRIBUTING.md](CONTRIBUTING.md) instructions, and run samples locally with development glimmer command: `bin/glimmer`).
+Check the [samples](samples) directory in [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) for examples on how to write Glimmer applications. To run a sample, make sure to install the `glimmer-dsl-swt` gem first and then run:
+```
+glimmer samples
+```
+ 
+(alternatively, you may clone the repo, follow [CONTRIBUTING.md](CONTRIBUTING.md) instructions, and run samples locally with development glimmer command: `bin/glimmer`)
 
 ![Glimmer Meta-Sample](/images/glimmer-meta-sample.png)
 

data/VERSION

@@ -1 +1 @@
-4.18.5.0
+4.18.5.5

data/docs/reference/GLIMMER_GUI_DSL_SYNTAX.md

@@ -36,6 +36,7 @@ This guide should help you get started with Glimmer DSL for SWT. For more advanc
   - [Layouts](#layouts)
   - [Layout Data](#layout-data)
   - [Canvas Shape DSL](#canvas-shape-dsl)
+    - [Shapes inside a Shape](#shapes-inside-a-shape)
     - [Shapes inside a Widget](#shapes-inside-a-widget)
     - [Shapes inside an Image](#shapes-inside-an-image)
     - [Canvas Shape API](#canvas-shape-api)
@@ -432,7 +433,7 @@ Dialog is a variation on Shell. It is basically a shell that is modal (blocks wh
 
 Glimmer facilitates building dialogs by using the `dialog` keyword, which automatically adds the SWT.DIALOG_TRIM and SWT.APPLICATION_MODAL [widget styles](#widget-styles) needed for a dialog.
 
-Check out [Hello, Dialog!](#hello-dialog) sample to learn more.
+Check out [Hello, Dialog!](GLIMMER_SAMPLES.md#hello-dialog) sample to learn more.
 
 ##### message_box
 
@@ -895,7 +896,7 @@ shell {
 }.open
 ```
 
-You may check out a more full-fledged example in [Hello, Sash Form!](#hello-sash-form)
+You may check out a more full-fledged example in [Hello, Sash Form!](GLIMMER_SAMPLES.md#hello-sash-form)
 
 ![Hello Sash Form](/images/glimmer-hello-sash-form.png)
 
@@ -1385,11 +1386,9 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
 
 **(ALPHA FEATURE)**
 
-Glimmer supports drawing graphics directly on a `canvas` widget via SWT (or any widget for that matter though `canvas` is recommended for drawing).
+While other GUI toolkits only offer a way to draw graphics imperatively (e.g. fill_rectangle, draw_point, etc...), Glimmer DSL for SWT breaks away from the mold by enabling software engineers to draw graphics declaratively. Simply declare all the shapes you want to see with their attributes, like background/foreground colors, and Glimmer DSL for SWT takes care of the rest, painting graphics on a blank `canvas` widget or amending/decorating an existing widget. This is accomplished through the Canvas Shape DSL, a sub-DSL of the Glimmer GUI DSL, which makes it possible to draw graphics declaratively with very understandable and maintainable syntax. Still, for the rare cases where imperative logic is needed, Glimmer DSL for SWT supports imperative painting of graphics through direct usage of SWT.
 
-`canvas` has the `:double_buffered` SWT style by default to ensure flicker-free rendering. If you need to disable it for whatever reason, just pass the `:none` SWT style instead (e.g. `canvas(:none)`)
-
-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.
+`canvas` has the `:double_buffered` SWT style by default on platforms that need it (Windows & Linux) to ensure flicker-free rendering. If you need to disable it for whatever reason, just pass the `:none` SWT style instead (e.g. `canvas(:none)`)
 
 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)` arc is part of a circle within an oval area, denoted by start angle (degrees) and end angle (degrees)
@@ -1404,9 +1403,10 @@ Shape keywords and their args (including defaults) are listed below (they basica
 - `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))
+- `text(string, x, y, is_transparent = true)` text with optional is_transparent to indicate if background is transparent (default is true)
+- `text(string, x, y, flags)` 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 unless background is set with no foreground (or foreground is set with no background), in which case a smart default is applied.
+Shape keywords that can be filled with color can take a keyword argument `fill: true`. Defaults to false when not specified unless background is set with no foreground (or foreground is set with no background), in which case a smart default is applied.
 Smart defaults can be applied to automatically infer `gradient: true` (rectangle with both foreground and background) and `round: true` (rectangle with more than 4 args, the extra args are numeric) as well.
 
 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.
@@ -1461,7 +1461,7 @@ shell {
       font height: 25, style: :bold
     }
     rectangle(200, 80, 108, 36) {
-      foreground :black
+      foreground rgb(0, 0, 0)
       line_width 3
     }
     image(image_object, 70, 50)
@@ -1473,7 +1473,115 @@ Screenshot:
 
 ![Canvas Animation Example](/images/glimmer-example-canvas.png)
 
-Learn more at the [Hello, Canvas! Sample](#hello-canvas).
+If you specify the x and y coordinates as `:default`, `nil`, or leave them out, they get calculated automatically by centering the shape within its parent `canvas`.
+
+Note that you could shift a shape off its centered position within its parent `canvas` by using `x_delta` and `y_delta` instead of `x` and `y`
+
+The round and gradient options could be dropped since Glimmer DSL for SWT supports auto-inference of them based on shape parameters.
+
+Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+
+```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 :dark_yellow
+    rectangle(0, 0, 220, 400) {
+      background :dark_red
+    }
+    rectangle(50, 20, 300, 150, 30, 50) {
+      background :yellow
+    }
+    rectangle(150, 200, 100, 70, true) {
+      background :dark_red
+      foreground :yellow
+    }
+    text('Glimmer', 208, 83) {
+      font height: 25, style: :bold
+    }
+    rectangle(200, 80, 108, 36) {
+      foreground rgb(0, 0, 0)
+      line_width 3
+    }
+    image(image_object, 70, 50)
+  }
+}.open
+```
+
+Notice how the shape declaration parameters perfectly match the method parameters in the [SWT org.eclipse.swt.graphics.GC API](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/GC.html). This is useful for developers coming to Glimmer DSL for SWT from SWT.
+
+Of course, Glimmer DSL for SWT still supports an alternative syntax that is more declarative and consistent with the rest of the Glimmer GUI DSL syntax. This syntax in fact offers the extra-benefit of data-binding for shape parameter values (meaning you could use `bind(...)` syntax with them instead of setting values directly)
+
+Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+
+```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 :dark_yellow
+    rectangle {
+      x 0
+      y 0
+      width 220
+      height 400
+      background :dark_red
+    }
+    rectangle {
+      x 50
+      y 20
+      width 300
+      height 150
+      arc_width 30
+      arc_height 50
+      background :yellow
+    }
+    rectangle {
+      x 150
+      y 200
+      width 100
+      height 70
+      vertical true
+      background :dark_red
+      foreground :yellow
+    }
+    text {
+      string 'Glimmer'
+      x 208
+      y 83
+      font height: 25, style: :bold
+    }
+    rectangle {
+      x 200
+      y 80
+      width 108
+      height 36
+      foreground :black
+      line_width 3
+    }
+    image {
+      image image_object
+      x 70
+      y 50
+    }
+  }
+}.open
+```
+
+Learn more at the [Hello, Canvas! Sample](GLIMMER_SAMPLES.md#hello-canvas).
 
 If you ever have special needs or optimizations, you could always default to direct SWT painting via [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) instead. 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).
 
@@ -1489,23 +1597,26 @@ shell {
   minimum_size 320, 400
 
   canvas {
-    background :yellow
+    background :dark_yellow
     
     on_paint_control { |paint_event|
       gc = paint_event.gc
-      gc.background = color(:red).swt_color
-      gc.fill_rectangle(0, 0, 220, 400)
       
-      gc.background = color(:magenta).swt_color
-      gc.fill_roundRectangle(50, 20, 300, 150, 30, 50)
+      gc.background = color(:dark_red).swt_color
+      gc.fill_rectangle(0, 0, 220, 400)
       
-      gc.background = color(:dark_magenta).swt_color
-      gc.fill_gradientRectangle(150, 200, 100, 70, true)
+      gc.background = color(:yellow).swt_color
+      gc.fill_round_rectangle(50, 20, 300, 150, 30, 50)
       
-      gc.foreground = color(:dark_blue).swt_color
-      gc.draw_rectangle(200, 80, 108, 36)
+      gc.background = color(:dark_red).swt_color
+      gc.foreground = color(:yellow).swt_color
+      gc.fill_gradient_rectangle(150, 200, 100, 70, true)
       
+      gc.font = font(height: 25, style: :bold).swt_font
       gc.foreground = color(:black).swt_color
+      gc.draw_text('Glimmer', 208, 83, true)
+      
+      gc.foreground = rgb(0, 0, 0).swt_color
       gc.line_width = 3
       gc.draw_rectangle(200, 80, 108, 36)
       
@@ -1515,9 +1626,39 @@ shell {
 }.open
 ```
 
+#### Shapes inside a Shape
+
+Shapes can be nested within each other. If you nest a shape within another, its coordinates are assumed to be relative to its parent.
+
+As such, if you move the parent, it moves all its children with it.
+
+If you specify the x and y coordinates as `:default`, `nil`, or leave them out, they get calculated automatically by centering the shape within its parent shape relatively.
+
+Note that you could shift a shape off its centered position within its parent shape by using `x_delta` and `y_delta` instead of `x` and `y`
+
+Check [Hello, Canvas!](GLIMMER_SAMPLES.md#hello-canvas) for an example that nests lines, points, a polyline, and an image within a drawn rectangle parent:
+
+```ruby
+        rectangle(205, 50, 88, 96) {
+          foreground :yellow
+          3.times { |n|
+            line(45, 70 + n*10, 65 + n*10, 30 + n*10) {
+              foreground :yellow
+            }
+          }
+          10.times {|n|
+            point(15 + n*5, 50 + n*5) {
+              foreground :yellow
+            }
+          }
+          polyline(45, 60, 55, 20, 65, 60, 85, 80, 45, 60)
+          image(@image_object, 0, 5)
+        }
+```
+
 #### 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`.
+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](GLIMMER_SAMPLES.md#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`.
 
 #### Shapes inside an Image
 
@@ -1619,9 +1760,14 @@ shell {
 
 These Canvas Shape API methods help with manipulating shapes upon user interaction, such as mouse clicking a specific shape.
 
+They are implemented with the help of the highly robust Java built-in shape geometry algorithms.
+
 - `WidgetProxy#shape_at_location(x, y)` : returns shape object at x, y location from a widget proxy like canvas
-- `Shape#include?(x, y)` : indicates if shape includes x, y point (`arc` and `oval` shapes currently include their entire rectangular region in their checks, `text` shapes always return false)
+- `Shape#contain?(x, y)` : indicates if shape contains x, y point
+- `Shape#include?(x, y)` : indicates if shape includes x, y point on the edge if drawn or inside if filled (include uses contain for filled shapes)
 - `Shape#move_by(x_delta, y_delta)` : moves shape object at x, y location
+- `Shape#size` : calculated size for shape bounding box (e.g. a polygon with an irregular shape will have its bounding box width and height calculated)
+- `Shape#bounds` : calculated bounds (x, y, width, height) for shape bounding box (e.g. a polygon with an irregular shape will have its bounding box top-left x, y, width and height calculated)
 
 Check [Hello, Canvas!](GLIMMER_SAMPLES.md#hello-canvas) for an example.
 
@@ -1889,7 +2035,7 @@ transform(1, 1, 4, 2, 2, 4).
   translate(3, 7)
 ```
 
-Learn more at the [Hello, Canvas Transform! Sample](#hello-canvas-transform).
+Learn more at the [Hello, Canvas Transform! Sample](GLIMMER_SAMPLES.md#hello-canvas-transform).
 
 ### Canvas Animation DSL
 
@@ -1955,7 +2101,7 @@ API of Animation Object (returned from `animation` keyword):
 - `#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).
+Learn more at the [Hello, Canvas Animation! Sample](GLIMMER_SAMPLES.md#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.
 
@@ -1963,7 +2109,7 @@ If there is anything missing you would like added to the Glimmer Animation DSL t
 
 Animation could be alternatively implemented without the `animation` keyword through a loop that invokes model methods inside `sync_exec {}` (or `async_exec {}`), which indirectly cause updates to the GUI via data-binding.
 
-The [Glimmer Tetris](#glimmer-tetris) sample provides a good example of that.
+The [Glimmer Tetris](GLIMMER_SAMPLES.md#tetris) sample provides a good example of that.
 
 ### Data-Binding
 
@@ -2324,7 +2470,7 @@ shell {
 }
 ```
 
-Check out [Hello, Table!](#hello-table) for an actual example including table editors.
+Check out [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) for an actual example including table editors.
 
 [Are We There Yet?](#are-we-there-yet) is an actual production Glimmer application that takes full advantage of table capabilities, storing model data in a database via ActiveRecord. As such, it's an excellent demonstration of how to use Glimmer DSL for SWT with a database.
 
@@ -2332,7 +2478,7 @@ Check out [Hello, Table!](#hello-table) for an actual example including table ed
 
 Glimmer automatically adds sorting support to the SWT `Table` widget.
 
-Check out the [Contact Manager](#contact-manager) sample for an example.
+Check out the [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) sample for an example.
 You may click on any column and it will sort by ascending order first and descending if you click again.
 
 Glimmer automatic table sorting supports `String`, `Integer`, and `Float` columns out of the box as well as any column data that is comparable.
@@ -2454,7 +2600,7 @@ You can data-bind any of these properties:
 - `minutes bind(model, :property)`: produces an integer
 - `seconds bind(model, :property)`: produces an integer
 
-Learn more at the [Hello, Date Time!](#hello-date-time) sample.
+Learn more at the [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) sample.
 
 If you need a better widget with the ability to customize the date format pattern, check out the [Nebula CDateTime Glimmer Custom Widget](https://github.com/AndyObtiva/glimmer-cw-cdatetime-nebula)
 
@@ -2840,7 +2986,7 @@ The `checkboxes` property returns the list of nested `checkbox` widgets.
 
 When data-binding `selection`, the model property should have a matching property with `_options` suffix (e.g. `activities_options` for `activities`) to provide an `Array` of `String` objects for `checkbox` buttons.
 
-You may see an example at the [Hello, Checkbox Group!](#hello-checkbox-group) sample.
+You may see an example at the [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) sample.
 
 ![Hello Checkbox Group](/images/glimmer-hello-checkbox-group.png)
 
@@ -2875,7 +3021,7 @@ radio_group { |radio_group_proxy|
 # ...
 ```
 
-You may see another example at the [Hello, Radio Group!](#hello-radio-group) sample.
+You may see another example at the [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) sample.
 
 ##### Code Text Custom Widget
 
@@ -3147,7 +3293,7 @@ This adds some default keyboard shortcuts:
 
 If you prefer it to be vanilla with no default key event listeners, then pass the `default_behavior: false` option.
 
-Learn more at [Hello, Code Text!](#hello-code-text)
+Learn more at [Hello, Code Text!](GLIMMER_SAMPLES.md#hello-code-text)
 
 ##### Video Custom Custom Widget
 
@@ -3162,7 +3308,7 @@ Simply install the [glimmer-cw-video](https://rubygems.org/gems/glimmer-cw-video
 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)
 
-Also, you may check out [Hello, Custom Widget!](#hello-custom-widget) for another example.
+Also, you may check out [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) for another example.
 
 ### Custom Shells
 
@@ -3233,7 +3379,7 @@ shell { |app_shell|
 
 If you use a Custom Shell as the top-level app shell, you may invoke the class method `::launch` instead to avoid building an app class yourself or including Glimmer into the top-level namespace (e.g. `Tetris.launch` instead of `include Glimmer; tetris.open`)
 
-You may check out [Hello, Custom Shell!](#hello-custom-shell) for another example.
+You may check out [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) for another example.
 
 ### Drag and Drop
 
@@ -3247,7 +3393,7 @@ To get started, simply follow these steps:
 1. On the drop target widget, add `on_drop` [DropTargetListener](https://help.eclipse.org/2020-03/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DropTargetListener.html) event handler block at minimum (you may also add `on_drag_enter` [must set [`event.detail`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DropTargetEvent.html#detail) if added], `on_drag_over`, `on_drag_leave`, `on_drag_operation_changed` and `on_drop_accept` if needed)
 1. Read `event.data` and consume it (e.g. change widget text) inside the `on_drop` event handler block.
 
-Example (taken from [samples/hello/hello_drag_and_drop.rb](#hello-drag-and-drop) / you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+Example (taken from [samples/hello/hello_drag_and_drop.rb](GLIMMER_SAMPLES.md#hello-drag-and-drop) / you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
 
 ```ruby
 class Location