glimmer-dsl-swt 4.18.4.10 → 4.18.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f06f3cbda7f10f81702dcdff893c91f4b7e381d5e7309c34786993e7000d8fc0
-  data.tar.gz: d08c04bababf1eb91a6a137ca725a082d66ec2479c71e0ef3f093dd472c68616
+  metadata.gz: acf07c3a7c6f534f4082330369a0bacac2593675506da814ec68e70446ec02b9
+  data.tar.gz: ff2983c28283b30b4f7f9e6bdf9cc0bad3768331014ef281ff5397726851b39d
 SHA512:
-  metadata.gz: 95fbd9e1be14bf90eb36fd92b6e0d86c3a4a3848c1451f1b17234a8fb3521e544c0893d423c04f32bf750c538b6972969407a8ab6fa84e6a3d9ff0181c3fb144
-  data.tar.gz: 32ddd1acf980524c63fef1722ad1f006cf84d08bd1496b387cd0e6a180dd517b920fc458df34c58b2ac489f2c9b48b6a430a1891a21d9789219e965dc86c8f2b
+  metadata.gz: d89da48eb352e555e861032de5b5fee9c1e1ad3e7796c920e354b61b5fb1e2522fa1eafd89e363259ee9c3961ab4207a51ea483ef670e072c869fb1671fecccb
+  data.tar.gz: d267615568ac7e20ef8b5778df77cfe36f3de061ab9dd5c4e227b2ef08d5323a27bc6742f07728a84b0760a11f64bdad822c4468f1cf24049ac536919816548e

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Change Log
 
+### 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.
+- `auto_exec` keyword to automatically use `sync_exec` with SWT code when needed (running from a thread other than GUI thread)
+- Implement `sync_exec:` option in `bind` keyword with table, tree, combo, and list data-binding (other data-binding types than the standard)
+- Add `async_exec` option to `bind` keyword (covering `data_binding_expression.rb` with `async_exec` properly)
+- Support tree multi-selection data-binding
+- Hello, Tree! sample
+- Enhance Hello, Canvas! with Shape Movement
+- Add Jars.lock to scaffold .gitignore file
+- Add Glimmer::GUI alias for Glimmer::UI module, thus permitting inclusion of Glimmer::GUI::CustomWidget, Glimmer::GUI::CustomShell, and Glimmer::GUI::CustomWindow
+- Provide a quick method for grabbing all available cursor/color options off of SWTProxy (SWTProxy.cursor_options, SWTProxy.cursor_styles, SWTProxy.color_options, SWTProxy.color_styles)
+- Remove explicit git gem dependency given that it is installed via juwelier during scaffolding and is not needed otherwise
+- Support partial image shape drawing by passing source and destination dimensions to `image` shape [documented in docs]
+- Support alternate Canvas Shape DSL syntax for `image` by passing nested properties
+- Canvas Shape DSL argument data-binding support for `image`
+- Support alternate Canvas Shape DSL syntax for `rectangle` by passing nested properties
+- Canvas Shape DSL argument data-binding support for `rectangle(x, y, width, height, fill: false)` standard rectangle, which can be optionally filled
+- Canvas Shape DSL argument data-binding support for `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
+- Canvas Shape DSL argument data-binding support for `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
+- Canvas Shape DSL argument data-binding support for `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)
+- Canvas Shape DSL argument data-binding support for `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)
+- Canvas Shape DSL argument data-binding support for `line(x1, y1, x2, y2)` line
+- Canvas Shape DSL argument data-binding support for `oval(x, y, width, height, fill: false)` oval if width does not match heigh and circle if width matches height. Can be optionally filled.
+- Canvas Shape DSL argument data-binding support for `point(x, y)` point
+- Canvas Shape DSL argument data-binding support for `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)
+- Canvas Shape DSL argument data-binding support for `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)
+- Canvas Shape DSL argument data-binding support for `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))
+- Update Hello, Button!, Hello, Table! sample, Hello, Checkbox Group! sample, Hello, Radio Group! sample, Hello, Combo! sample, Hello, List Single Selection! sample, Hello, List Multi Selection! sample to utilize a CustomShell
+- Refactor all samples to rely on Glimmer::UI::CustomShell given its new class launch method for productive app declaration
+- Fix issue with logging remaining async in debug mode
+- Fix issue with combo, list, radio group, and checkbox group not supporting nested data-binding
+
+### 4.18.4.11
+
+- Support creating images pixel by pixel with `image(width, height) {|x,y| [r, g, b]}` keyword, which takes a block with x, y coordinates based on the image width and height and returns a pixel foreground color per point
+- Add proper indentation in code_text upon hitting ENTER
+- Reset Canvas Shape DSL alpha value to 255 when not explicitly set on a shape (Apply in Hello, Canvas! Sample)
+- Provide terse syntax for building canvas objects (autodetecting its width and height)
+- Provide terse syntax for building `:image_double_buffered` canvas objects (autodetecting its width and height):
+- Center mandelbrot where mouse is clicked upon zoom
+- Fix issue with Mandelbrot sample off by one error on Cores selected via Menu
+- Fix use of on_events in code_text widget with lines mode true
+
 ### 4.18.4.10
 
 - Hello, Progress Bar!

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.4.10
+# [<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.3
 ## 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)
@@ -342,7 +342,7 @@ jgem install glimmer-dsl-swt
 
 Or this command if you want a specific version:
 ```
-jgem install glimmer-dsl-swt -v 4.18.4.10
+jgem install glimmer-dsl-swt -v 4.18.5.3
 ```
 
 `jgem` is JRuby's version of `gem` command.
@@ -360,7 +360,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.4.10'
+gem 'glimmer-dsl-swt', '~> 4.18.5.3'
 ```
 
 And, then run:
@@ -404,10 +404,19 @@ Glimmer configuration may be done via the `Glimmer::Config` module.
 
 ## Samples
 
-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` 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`).
+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 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)
+
 ## In Production
 
 The following production apps have been built with Glimmer.
@@ -432,7 +441,7 @@ If you have a Glimmer app you would like referenced here, please mention in a Pu
 
 ### Connector
 
-[<img alt="Connector Logo" src="https://raw.githubusercontent.com/AndyObtiva/connector/master/package/linux/Connector.png" height=40 /> Connector](https://github.com/AndyObtiva/connector): A minimalist open-source web browser
+[<img alt="Connector Logo" src="https://raw.githubusercontent.com/AndyObtiva/connector/master/package/linux/Connector.png" height=40 /> Connector](https://github.com/AndyObtiva/connector): A minimalist open-source multi-engine web browser
 
 ## Packaging & Distribution
 

data/VERSION

@@ -1 +1 @@
-4.18.4.10
+4.18.5.3

data/bin/glimmer

@@ -1,7 +1,7 @@
 #!/usr/bin/env jruby
 
 # Copyright (c) 2007-2021 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
@@ -9,10 +9,10 @@
 # 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

data/docs/reference/GLIMMER_CONFIGURATION.md

@@ -170,11 +170,15 @@ This just tells Glimmer whether to log excluded keywords or not (at the debug le
 
 ### auto_sync_exec
 
-(default = false)
+(default = true)
+
+This automatically uses sync_exec on GUI calls from threads other than the main GUI thread instead of requiring users to manually use sync_exec.
 
-This automatically uses sync_exec on GUI calls from threads other than the main GUI thread instead of requiring users to manually use sync_exec. Default value to false.
+Keep in mind that this could cause redraws on every minor change in the models instead of applying large scope changes together.
+In rare cases where you need to avoid causing stutter in the GUI as a result, you can wrap large-scale GUI updates in `auto_exec` manually.
 
-Keep in mind the caveat that it would force redraws on every minor changein the models instead of applying large scope changes all together, thus causing too much drawing/stutter in the GUI. As such, this is a good fit for simpler GUIs, not ones used with highly sophisticated 2D graphics. It may be mitigated in the future by introducing the idea of large-scale observation events that wrap around smaller events. Until then, keep the caveat in mind or just use sync_exec manually as usually done with Java SWT apps.
+As such, this saves developers a lot of headache by not requiring wrapping every bit of GUI update in other threads with `sync_exec`, yet only
+large scale updates in the rare cases where optimization is needed.
 
 ## License
 

data/docs/reference/GLIMMER_GUI_DSL_SYNTAX.md

@@ -1,7 +1,96 @@
-## Glimmer GUI DSL Syntax
-
 This guide should help you get started with Glimmer DSL for SWT. For more advanced SWT details, please refer to the [SWT Reference](/README.md#swt-reference).
 
+- [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax)
+  - [DSL Auto-Expansion](#dsl-auto-expansion)
+  - [Widgets](#widgets)
+    - [Glimmer GUI DSL Keywords](#glimmer-gui-dsl-keywords)
+    - [SWT Proxies](#swt-proxies)
+      - [swt_widget](#swt_widget)
+      - [Shell widget proxy methods](#shell-widget-proxy-methods)
+      - [Widget Content Block](#widget-content-block)
+      - [Shell Icon](#shell-icon)
+        - [Shell Icon Tip for Packaging on Windows](#shell-icon-tip-for-packaging-on-windows)
+    - [Dialog](#dialog)
+      - [message_box](#message_box)
+    - [Display](#display)
+    - [Multi-Threading](#multi-threading)
+      - [async_exec](#async_exec)
+      - [sync_exec](#sync_exec)
+      - [timer_exec](#timer_exec)
+    - [Menus](#menus)
+    - [ScrolledComposite](#scrolledcomposite)
+    - [Sash Form Widget](#sash-form-widget)
+    - [Browser Widget](#browser-widget)
+  - [Widget Styles](#widget-styles)
+    - [Explicit SWT Style Bit](#explicit-swt-style-bit)
+    - [Negative SWT Style Bits](#negative-swt-style-bits)
+    - [Extra SWT Styles](#extra-swt-styles)
+      - [Non-resizable Window](#non-resizable-window)
+  - [Widget Properties](#widget-properties)
+    - [Color](#color)
+      - [`#swt_color`](#swt_color)
+    - [Font](#font)
+  - [Image](#image)
+    - [Image Options](#image-options)
+  - [Cursor](#cursor)
+  - [Layouts](#layouts)
+  - [Layout Data](#layout-data)
+  - [Canvas Shape DSL](#canvas-shape-dsl)
+    - [Shapes inside a Widget](#shapes-inside-a-widget)
+    - [Shapes inside an Image](#shapes-inside-an-image)
+    - [Canvas Shape API](#canvas-shape-api)
+    - [Pixel Graphics](#pixel-graphics)
+  - [Canvas Transform DSL](#canvas-transform-dsl)
+    - [Top-Level Transform Fluent Interface](#top-level-transform-fluent-interface)
+  - [Canvas Animation DSL](#canvas-animation-dsl)
+    - [Animation via Data-Binding](#animation-via-data-binding)
+  - [Data-Binding](#data-binding)
+    - [General Examples](#general-examples)
+    - [Combo](#combo)
+    - [List](#list)
+    - [Table](#table)
+      - [Table Selection](#table-selection)
+      - [Table Editing](#table-editing)
+      - [Table Sorting](#table-sorting)
+    - [Tree](#tree)
+    - [DateTime](#datetime)
+  - [Observer](#observer)
+    - [Observing Widgets](#observing-widgets)
+      - [Alternative Syntax](#alternative-syntax)
+    - [Observing Models](#observing-models)
+  - [Custom Widgets](#custom-widgets)
+    - [Simple Example](#simple-example)
+      - [Method-Based Custom Widget Example](#method-based-custom-widget-example)
+      - [Class-Based Custom Widget Example](#class-based-custom-widget-example)
+    - [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
+    - [Lifecycle Hooks Example](#lifecycle-hooks-example)
+    - [Custom Widget API](#custom-widget-api)
+    - [Content/Options Example](#contentoptions-example)
+    - [Custom Widget Gotchas](#custom-widget-gotchas)
+    - [Built-In Custom Widgets](#built-in-custom-widgets)
+      - [Checkbox Group Custom Widget](#checkbox-group-custom-widget)
+      - [Radio Group Custom Widget](#radio-group-custom-widget)
+      - [Code Text Custom Widget](#code-text-custom-widget)
+        - [Options](#options)
+      - [Video Custom Custom Widget](#video-custom-custom-widget)
+    - [Custom Widget Final Notes](#custom-widget-final-notes)
+  - [Custom Shells](#custom-shells)
+  - [Drag and Drop](#drag-and-drop)
+  - [Miscellaneous](#miscellaneous)
+    - [Multi-DSL Support](#multi-dsl-support)
+      - [SWT](#swt)
+      - [Opal](#opal)
+      - [XML](#xml)
+      - [CSS](#css)
+      - [Listing / Enabling / Disabling DSLs](#listing--enabling--disabling-dsls)
+    - [Application Menu Items (About/Preferences)](#application-menu-items-aboutpreferences)
+    - [App Name and Version](#app-name-and-version)
+    - [Performance Profiling](#performance-profiling)
+      - [SWT Browser Style Options](#swt-browser-style-options)
+- [License](#license)
+
+## Glimmer GUI DSL Syntax
+
 Glimmer's core is a GUI DSL with a lightweight visual syntax that makes it easy to visualize the nesting of widgets in the GUI hierarchy tree.
 
 It is available through mixing in the `Glimmer` module, which makes [Glimmer GUI DSL Keywords](#glimmer-gui-dsl-keywords) available to both the instance scope and class scope:
@@ -257,6 +346,7 @@ This is not an exaustive list, but should give you a good start in learning Glim
 - `async_exec`: featured in [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#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
+- `auto_exec`: executes a block on the event loop synchronously only when needed (when running from a thread other than GUI thread)
 
 #### SWT Proxies
 
@@ -342,7 +432,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
 
@@ -411,6 +501,15 @@ Although SWT Display is not technically a widget, it has similar APIs and DSL su
 
 [JRuby](https://www.jruby.org/) supports [truly parallel multi-threading](https://github.com/jruby/jruby/wiki/Concurrency-in-jruby) since it relies on the JVM (Java Virtual Machine). As such, it enables development of highly-interactive desktop applications that can do background work while the user is interacting with the GUI. However, any code that interacts with the GUI from a thread other than the main (first) GUI thread must do so only through sync_exec (if it is standard synchronous code) or async_exec.
 
+Most of the time, you simply get away with Ruby [Threads](https://ruby-doc.org/core-2.5.7/Thread.html) and [Mutexes](https://ruby-doc.org/core-2.5.7/Mutex.html).
+
+Otherwise, if you need more advanced concurrency, Glimmer includes the [concurrent-ruby gem](https://rubygems.org/gems/concurrent-ruby), which supports many helpful concurrency techniques such as [Thread Pools](http://ruby-concurrency.github.io/concurrent-ruby/master/file.thread_pools.html) (used in the [Mandelbrot Fractal](GLIMMER_SAMPLES.md#mandelbrot-fractal) sample).
+
+One thing Glimmer DSL for SWT innovates over plain old SWT is not requiring developers to explicitly use `Display.syncExec` from threads other than the GUI threads.
+Glimmer automatically detects if you're running in a different thread and uses `Display.syncExec` automatically using its own enhanced `auto_exec`
+
+In any case, Glimmer still allows developers to manually use `sync_exec`, `async_exec`, `timer_exec`, and `auto_exec` when needed. M
+
 ##### async_exec
 
 `async_exec {}` is a Glimmer DSL keyword in addition to being a method on `display`. It accepts a block and when invoked, adds the block to the end of a queue of GUI events scheduled to run on the SWT event loop, executing asynchronously.
@@ -441,7 +540,11 @@ Thread.new {
 
 ##### sync_exec
 
-`sync_exec {}` works just like `async_exec` except it executes the block synchronously at the earliest opportunity possible, waiting for the block to be finished.
+`sync_exec {}` is required by SWT when running GUI update from a thread other than the GUI thread. In Glimmer, it is automatically invoked for you so that you wouldn't have to worry about it. It works just like `async_exec` except it executes the block synchronously at the earliest opportunity possible, waiting for the block to be finished.
+
+##### auto_exec
+
+`auto_exec(override_sync_exec:, override_async_exec) {}` only executes code block with `sync_exec` when necessary (running from a thread other than the GUI thread). It is used automatically all over the Glimmer DSL for SWT codebase, so you wouldn't need it unless you grab a direct handle on `swt_widget` from a widget proxy.
 
 ##### timer_exec
 
@@ -792,7 +895,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)
 
@@ -1282,16 +1385,15 @@ 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)
 - `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 = 0, y = 0)` sets [image](#image), which could be an [org.eclipse.swt.graphics.Image](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/Image.html) object or just a file path string
+- `image(image, source_x, source_y, source_width, source_height, destination_x, destination_y, destination_width, destination_height)` sets part of an [image](#image) and scales it to fit destination dimensions on parent canvas/widget
 - `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
@@ -1300,9 +1402,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.
@@ -1369,7 +1472,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 :black
+      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
+      x 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).
 
@@ -1411,6 +1622,149 @@ 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](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
+
+You can build an image using the Canvas Shape DSL (including setting the icon of the application).
+
+Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+
+```
+include Glimmer
+
+shell {
+  text 'Image Shape DSL Example'
+  label {
+    bevel_constant = 20
+    icon_block_size = 64
+    icon_bevel_size = icon_block_size.to_f / 25.to_f
+    icon_bevel_pixel_size = 0.16*icon_block_size.to_f
+    icon_size = 8
+    icon_pixel_size = icon_block_size * icon_size
+    image(icon_pixel_size, icon_pixel_size) {
+      icon_size.times { |row|
+        icon_size.times { |column|
+          colored = row >= 1 && column.between?(1, 6)
+          color = colored ? color([:white, :red, :blue, :green, :yellow, :magenta, :cyan, :dark_blue].sample) : color(:white)
+          x = column * icon_block_size
+          y = row * icon_block_size
+          rectangle(x, y, icon_block_size, icon_block_size) {
+            background color
+          }
+          polygon(x, y, x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
+            background rgb(color.red + 4*bevel_constant, color.green + 4*bevel_constant, color.blue + 4*bevel_constant)
+          }
+          polygon(x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size, y + icon_block_size) {
+            background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
+          }
+          polygon(x + icon_block_size, y + icon_block_size, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size) {
+            background rgb(color.red - 2*bevel_constant, color.green - 2*bevel_constant, color.blue - 2*bevel_constant)
+          }
+          polygon(x, y, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
+            background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
+          }
+        }
+      }
+    }
+  }
+}.open
+```
+
+![Image Shape DSL](/images/glimmer-example-image-shape-dsl.png)
+
+Example setting the icon of the application (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+
+```
+include Glimmer
+
+shell {
+  text 'Image Shape DSL Example'
+  label {
+    text 'Image Shape DSL Example'
+    font height: 30
+  }
+  bevel_constant = 20
+  icon_block_size = 64
+  icon_bevel_size = icon_block_size.to_f / 25.to_f
+  icon_bevel_pixel_size = 0.16*icon_block_size.to_f
+  icon_size = 8
+  icon_pixel_size = icon_block_size * icon_size
+  image(icon_pixel_size, icon_pixel_size) {
+    icon_size.times { |row|
+      icon_size.times { |column|
+        colored = row >= 1 && column.between?(1, 6)
+        color = colored ? color([:white, :red, :blue, :green, :yellow, :magenta, :cyan, :dark_blue].sample) : color(:white)
+        x = column * icon_block_size
+        y = row * icon_block_size
+        rectangle(x, y, icon_block_size, icon_block_size) {
+          background color
+        }
+        polygon(x, y, x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
+          background rgb(color.red + 4*bevel_constant, color.green + 4*bevel_constant, color.blue + 4*bevel_constant)
+        }
+        polygon(x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size, y + icon_block_size) {
+          background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
+        }
+        polygon(x + icon_block_size, y + icon_block_size, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size) {
+          background rgb(color.red - 2*bevel_constant, color.green - 2*bevel_constant, color.blue - 2*bevel_constant)
+        }
+        polygon(x, y, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
+          background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
+        }
+      }
+    }
+  }
+}.open
+```
+
+![Image Shape DSL](/images/glimmer-example-image-shape-dsl-app-switcher-icon.png)
+
+#### Canvas Shape API
+
+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#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
+
+Check [Hello, Canvas!](GLIMMER_SAMPLES.md#hello-canvas) for an example.
+
 #### Pixel Graphics
 
 **(Early Alpha Feature)**
@@ -1440,6 +1794,21 @@ Result:
 
 ![glimmer example pixel graphics](/images/glimmer-example-pixel-graphics.png)
 
+If you are strictly dealing with pixels (no other shapes), you could even avoid the `pixel` keyword altogether and just provide direct foreground colors by passing a block that receives x, y coordinates:
+
+```ruby
+include Glimmer
+ 
+shell {
+  minimum_size 250, 265
+  text 'Pixel Graphics Example'
+   
+  canvas { |x, y|
+    [y%255, x%255, (x+y)%255]
+  }
+}.open
+```
+
 Remember that 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) too for even faster performance when needed in rare circumstances. 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 previous example without relying on the declarative Glimmer Shape DSL (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
@@ -1465,6 +1834,8 @@ shell {
 }.open
 ```
 
+(the code could be optimized further if you are repeating colors by simply reusing `Color` objects instead of re-constructing them)
+
 The only downside with the approach above is that it repaints all pixels on repaints to the window (e.g. during window resize). To get around that, we can rely on a technique called **Image Double-Buffering**. That is to buffer the graphics on an Image first and then set it on the Canvas so that resizes of the shell dont cause a repaint of all the pixels. Additionally, this gives us the added benefit of being able to use the image as a Shell icon via its `image` property.
 
 Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
@@ -1501,127 +1872,80 @@ If you need a transparent background for the image, replace the image constructi
 
 That way, wherever you don't draw a point, you get transparency (seeing what is behind the image).
 
-If you don't need a `shell` image icon and `pixel` performance is enough, you can automatically apply **Image Double-Buffering** with the `:image_double_buffered` SWT style (custom Glimmer style not available in SWT itself)
-
-Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+Alternatively, with a very minor performance penalty, Glimmer enables you to build the image pixel by pixel with a friendly Ruby syntax by passing a block that takes the x and y coordinates and returns a foreground color rgb array or Color/ColorProxy object.
 
 ```ruby
 include Glimmer
 
+@the_image = image(250, 250) {|x, y|
+  [y%255, x%255, (x+y)%255]
+}
+
 shell {
   minimum_size 250, 265
   text 'Pixel Graphics Example'
+  image @the_image
   
-  canvas(:image_double_buffered) {
-    250.times {|y|
-      250.times {|x|
-        pixel(x, y, foreground: [y%255, x%255, (x+y)%255])
-      }
-    }
+  canvas {
+    image @the_image
   }
 }.open
 ```
 
-#### Shapes inside a Widget
+If you don't need a `shell` image (icon), you can nest the image directly under the canvas by passing in the `top_level` keyword to treat `image` as a top-level keyword (pretending it is built outside the shell).
 
-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`.
+```ruby
+include Glimmer
 
-#### Shapes inside an Image
+shell {
+  minimum_size 250, 265
+  text 'Pixel Graphics Example'
+  
+  canvas {
+    image image(250, 250, top_level: true) {|x, y|
+      [y%255, x%255, (x+y)%255]
+    }
+  }
+}.open
+```
 
-You can build an image using the Canvas Shape DSL (including setting the icon of the application).
+If you don't need a `shell` image (icon) and `pixel` performance is enough, you can automatically apply **Image Double-Buffering** with the `:image_double_buffered` SWT style (custom Glimmer style not available in SWT itself)
 
 Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
 
-```
+```ruby
 include Glimmer
 
 shell {
-  text 'Image Shape DSL Example'
-  label {
-    bevel_constant = 20
-    icon_block_size = 64
-    icon_bevel_size = icon_block_size.to_f / 25.to_f
-    icon_bevel_pixel_size = 0.16*icon_block_size.to_f
-    icon_size = 8
-    icon_pixel_size = icon_block_size * icon_size
-    image(icon_pixel_size, icon_pixel_size) {
-      icon_size.times { |row|
-        icon_size.times { |column|
-          colored = row >= 1 && column.between?(1, 6)
-          color = colored ? color([:white, :red, :blue, :green, :yellow, :magenta, :cyan, :dark_blue].sample) : color(:white)
-          x = column * icon_block_size
-          y = row * icon_block_size
-          rectangle(x, y, icon_block_size, icon_block_size) {
-            background color
-          }
-          polygon(x, y, x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
-            background rgb(color.red + 4*bevel_constant, color.green + 4*bevel_constant, color.blue + 4*bevel_constant)
-          }
-          polygon(x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size, y + icon_block_size) {
-            background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
-          }
-          polygon(x + icon_block_size, y + icon_block_size, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size) {
-            background rgb(color.red - 2*bevel_constant, color.green - 2*bevel_constant, color.blue - 2*bevel_constant)
-          }
-          polygon(x, y, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
-            background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
-          }
-        }
+  minimum_size 250, 265
+  text 'Pixel Graphics Example'
+  
+  canvas(:image_double_buffered) {
+    250.times {|y|
+      250.times {|x|
+        pixel(x, y, foreground: [y%255, x%255, (x+y)%255])
       }
     }
   }
 }.open
 ```
 
-![Image Shape DSL](/images/glimmer-example-image-shape-dsl.png)
+Of course, you could also take advantage of the pixel-less terser syntax:
 
-Example setting the icon of the application (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
-
-```
+```ruby
 include Glimmer
 
 shell {
-  text 'Image Shape DSL Example'
-  label {
-    text 'Image Shape DSL Example'
-    font height: 30
-  }
-  bevel_constant = 20
-  icon_block_size = 64
-  icon_bevel_size = icon_block_size.to_f / 25.to_f
-  icon_bevel_pixel_size = 0.16*icon_block_size.to_f
-  icon_size = 8
-  icon_pixel_size = icon_block_size * icon_size
-  image(icon_pixel_size, icon_pixel_size) {
-    icon_size.times { |row|
-      icon_size.times { |column|
-        colored = row >= 1 && column.between?(1, 6)
-        color = colored ? color([:white, :red, :blue, :green, :yellow, :magenta, :cyan, :dark_blue].sample) : color(:white)
-        x = column * icon_block_size
-        y = row * icon_block_size
-        rectangle(x, y, icon_block_size, icon_block_size) {
-          background color
-        }
-        polygon(x, y, x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
-          background rgb(color.red + 4*bevel_constant, color.green + 4*bevel_constant, color.blue + 4*bevel_constant)
-        }
-        polygon(x + icon_block_size, y, x + icon_block_size - icon_bevel_pixel_size, y + icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size, y + icon_block_size) {
-          background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
-        }
-        polygon(x + icon_block_size, y + icon_block_size, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_block_size - icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size) {
-          background rgb(color.red - 2*bevel_constant, color.green - 2*bevel_constant, color.blue - 2*bevel_constant)
-        }
-        polygon(x, y, x, y + icon_block_size, x + icon_bevel_pixel_size, y + icon_block_size - icon_bevel_pixel_size, x + icon_bevel_pixel_size, y + icon_bevel_pixel_size) {
-          background rgb(color.red - bevel_constant, color.green - bevel_constant, color.blue - bevel_constant)
-        }
-      }
-    }
+  minimum_size 250, 265
+  text 'Pixel Graphics Example'
+  
+  canvas(:image_double_buffered) { |x, y|
+    [y%255, x%255, (x+y)%255]
   }
 }.open
 ```
 
-![Image Shape DSL](/images/glimmer-example-image-shape-dsl-app-switcher-icon.png)
-
+As they say, there are many ways to skin a cat! This is in line with the Ruby way of providing more ways than one. Pick and choose the right tool for the job just like true software engineers.
 
 ### Canvas Transform DSL
 
@@ -1705,7 +2029,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
 
@@ -1771,7 +2095,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.
 
@@ -1779,7 +2103,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
 
@@ -1802,11 +2126,15 @@ This example adds on the one above it by specifying converters on read and write
 
 `text bind(contact, 'address.street', sync_exec: true)`
 
-This example adds does GUI updates via [sync_exec](#sync_exec) assuming they are coming from another thread (different from the GUI thread)
+**(ALPHA FEATURE)**
+
+This example forces GUI updates via [sync_exec](#sync_exec) assuming they are coming from another thread (different from the GUI thread)
 
 `text bind(contact, 'address.street', async_exec: true)`
 
-This example adds does GUI updates via [async_exec](#async_exec) assuming they are coming from another thread (different from the GUI thread)
+**(ALPHA FEATURE)**
+
+This example forces GUI updates via [async_exec](#async_exec) assuming they are coming from another thread (different from the GUI thread)
 
 `text bind(contact, 'address.street', on_read: lambda { |s| s[0..10] })`
 
@@ -2136,7 +2464,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.
 
@@ -2144,7 +2472,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.
@@ -2243,6 +2571,8 @@ This finds the root node. The array is a Java array. This enables easy passing o
 To edit a tree, you must invoke `TreeProxy#edit_selected_tree_item` or `TreeProxy#edit_tree_item`. This automatically leverages the SWT TreeEditor custom class behind the scenes, displaying
 a text widget to the user to change the selected or passed tree item text into something else. It automatically persists the change to `items` data-bound model on ENTER/FOCUS-OUT or cancels on ESC/NO-CHANGE.
 
+Learn more at the [Hello, Tree!](GLIMMER_SAMPLES.md#hello-tree) and [Gladiator](GLIMMER_SAMPLES.md#gladiator) samples.
+
 #### DateTime
 
 `date_time` represents the SWT DateTime widget.
@@ -2264,7 +2594,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)
 
@@ -2650,7 +2980,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)
 
@@ -2685,7 +3015,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
 
@@ -2715,6 +3045,8 @@ To use, simply use `code_text` in place of the `text` or `styled_text` widget. I
 **lines**
 (default: `false`)
 
+**(BETA FEATURE)**
+
 Shows line numbers when set to true.
 
 If set to a hash like `{width: 4}`, it sets the initial width of the line numbers lane in character count (default: 4)
@@ -2724,6 +3056,8 @@ Keep in mind that if the text grows and required a wider line numbers area, it g
 **theme**
 (default: `'glimmer'`)
 
+**(BETA FEATURE)**
+
 Changes syntax color highlighting theme. Can be one of the following:
 - glimmer
 - github
@@ -2732,6 +3066,8 @@ Changes syntax color highlighting theme. Can be one of the following:
 **language**
 (default: `'ruby'`)
 
+**(BETA FEATURE)**
+
 Sets the code language, which can be one of the following [rouge gem](#https://rubygems.org/gems/rouge) supported languages:
 - abap
 - actionscript
@@ -2941,14 +3277,17 @@ Sets the code language, which can be one of the following [rouge gem](#https://r
 **default_behavior**
 (default: true)
 
+**(BETA FEATURE)**
+
 This adds some default keyboard shortcuts:
 - CMD+A (CTRL+A on Windows/Linux) to select all
 - CTRL+A on Mac to jump to beginning of line
 - CTRL+E on Mac to jump to end of line
+- Attempts to add proper indentation upon adding a new line when hitting ENTER (currently supporting Ruby only)
 
 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
 
@@ -2963,7 +3302,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
 
@@ -3034,7 +3373,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
 
@@ -3048,7 +3387,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