glimmer-dsl-swt 4.18.4.8 → 4.18.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ea3be1af753358a8beaffbf28c8dfd6602eae3903b01a884e6999f0dbf6cfb
-  data.tar.gz: 672422abf1637420ac51706373824ac821682eab77afe86b91e22b21f1e00eb6
+  metadata.gz: e3086c3823faac7765ca33e069111da2f027462fc9d09a2a9799a2ff094d6692
+  data.tar.gz: be7070377808b55cfa4bde48543b8a98fdff77205c9db0c07d0f4ac42078e00e
 SHA512:
-  metadata.gz: 7b502b353aa06f6b26e39487859ae8f4d9f8ee47d74a4a97a224b14dfa8b18acba6d8e48b6a66ee518a8075cd90a6303f1864726a22812edf98515f6a2754aa2
-  data.tar.gz: a5926f825b0247d4b521bfa2f857d1b1f88d731dba9651690960cf7c516ef2a1c5aca9c6cce86878162358fb416a0913b3ba945b0589be19f78f94454848d0b5
+  metadata.gz: 79e966ac5b7c342d8a9b936387e59f299f4895ae93c01600f8289cc06448b4d90beb0bd6e24073728d7a379172e1513b3cdf05fb3cdd4361ee08bd337870f491
+  data.tar.gz: 3c89781755c57a6cfc2990d85352bb37674e41a8d2f55f50c26c0d44f948ab26342b58bc98fcc9f93818cf19036ea0032a84b1565397abc7b7aa93a029b8c851

data/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Change Log
 
+### 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!
+- Alias shell as window, Glimmer::UI::CustomShell as Glimmer::UI::CustomWindow, on_shell_xyz events as on_window_xyz events, and :shell_trim SWT style as :window_trim SWT Glimmer custom style
+- `bind` option of `async_exec` or `sync_exec` (e.g. `bind(model, :property, async_exec: true)`) to perform GUI updates from another thread safely
+- Show progress bar for Mandelbrot calculation
+- Mandelbrot Cores menu options to switch the number of CPU cores being used for calculation on the next zoom calculation cycle
+
+### 4.18.4.9
+
+- Hello, Cursor! Sample
+- Log errors that occur in widget event listener blocks to help with troubleshooting
+- disposed? method for Shape objects
+- Add `dispose_images: false, dispose_patterns: false` options to `Shape#dispose` to avoid disposing images/patterns when needed
+- Mandelbrot background thread pre-calculation of future zoom levels
+- Mandelbrot menu bar menu items
+- Mandelbrot panning via scrollbars or dragging
+
 ### 4.18.4.8
 
 - Make `image` a top-level expression keyword

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.8
+# [<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.1
 ## 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)
@@ -326,14 +326,14 @@ Please follow these instructions to make the `glimmer` command available on your
 
 If you intend to learn the basics of Glimmer but are not ready to build a Glimmer app yet, pick Option 1 ([Direct Install](#option-1-direct-install)).
 
-If you intend to build a Glimmer app from scratch with [scaffolding](#scaffolding), pick Option 1 ([Direct Install](#option-1-direct-install)) as well.
+If you intend to build a Glimmer app from scratch with [scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_COMMAND.md#scaffolding), pick Option 1 ([Direct Install](#option-1-direct-install)) as well.
 
-Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](#scaffolding).
+Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_COMMAND.md#scaffolding).
 
 **Note:** if you encounter any [issues](https://github.com/AndyObtiva/glimmer-dsl-swt/issues), please [report](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) and then install a previous version instead from the list of [Glimmer Releases](https://rubygems.org/gems/glimmer-dsl-swt/versions) (keep looking back till you find one that works). Do not be disheartened as nearly everything is only a few days of work away. That said, keep in mind that this project is free and open source, meaning provided as is, so do not expect anything, but if you help with reporting and contributing, you could speed things up or even become part of the project.
 
 ### Option 1: Direct Install
-(Use for [Scaffolding](#scaffolding))
+(Use for [Scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_COMMAND.md#scaffolding))
 
 Run this command to install directly:
 ```
@@ -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.8
+jgem install glimmer-dsl-swt -v 4.18.5.1
 ```
 
 `jgem` is JRuby's version of `gem` command.
@@ -351,7 +351,7 @@ Otherwise, you may also run `jruby -S gem install ...`
 
 If you are new to Glimmer and would like to continue learning the basics, you may continue to the [Glimmer Command](https://github.com/AndyObtiva/glimmer#glimmer-command) section.
 
-Otherwise, if you are ready to build a Glimmer app, you can jump to the [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer#scaffolding) section next.
+Otherwise, if you are ready to build a Glimmer app, you can jump to the [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_COMMAND.md#scaffolding) section next.
 
 Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
 
@@ -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.8'
+gem 'glimmer-dsl-swt', '~> 4.18.5.1'
 ```
 
 And, then run:
@@ -386,11 +386,12 @@ You can use `girb` as an alternative to `irb` when prototyping Glimmer DSL for S
 
 ## 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](#swt-reference).
-
+This guide should help you get started with Glimmer DSL for SWT.
 
 [docs/reference/GLIMMER_GUI_DSL_SYNTAX.md](docs/reference/GLIMMER_GUI_DSL_SYNTAX.md)
 
+For more advanced SWT details, please refer to the [SWT Reference](#swt-reference).
+
 ## Glimmer Configuration
 
 Glimmer configuration may be done via the `Glimmer::Config` module.
@@ -403,10 +404,14 @@ 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 Glimmer DSL for SWT 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`).
+
+![Glimmer Meta-Sample](/images/glimmer-meta-sample.png)
+
 ## In Production
 
 The following production apps have been built with Glimmer.
@@ -425,6 +430,14 @@ If you have a Glimmer app you would like referenced here, please mention in a Pu
 
 [<img alt="Garderie Rainbow Daily Agenda Logo" src="https://github.com/AndyObtiva/garderie_rainbow_daily_agenda/raw/master/images/garderie_rainbow_daily_agenda_logo.png" width="40" />Garderie Rainbow Daily Agenda](https://github.com/AndyObtiva/garderie_rainbow_daily_agenda): A child nursery daily agenda reporting desktop app
 
+### Glimmer Gab
+
+[<img alt="Glimmer Gab Logo" src="https://raw.githubusercontent.com/AndyObtiva/glimmer_gab/master/package/linux/Glimmer%20Gab.png" height=40 /> Glimmer Gab](https://github.com/AndyObtiva/glimmer_gab): Desktop App for Gab.com
+
+### 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 multi-engine web browser
+
 ## Packaging & Distribution
 
 Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
@@ -438,7 +451,7 @@ Glimmer already supports automatic (and manual) app updates via the Mac App Stor
 ## Glimmer Supporting Libraries
 
 Here is a list of notable 3rd party gems used by Glimmer:
-- [juwelier](https://rubygems.org/gems/juwelier): generates app gems during [Glimmer Scaffolding](#scaffolding)
+- [juwelier](https://rubygems.org/gems/juwelier): generates app gems during [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_COMMAND.md#scaffolding)
 - [logging](https://github.com/TwP/logging): provides extra logging capabilities not available in Ruby Logger such as multi-threaded buffered asynchronous logging (to avoid affecting app performance) and support for multiple appenders such as stdout, syslog, and log files (the last one is needed on Windows where syslog is not supported)
 - [nested_inherited_jruby_include_package](https://github.com/AndyObtiva/nested_inherited_jruby_include_package): makes included [SWT](https://www.eclipse.org/swt/)/[Java](https://www.java.com/en/) packages available to all classes/modules that mix in the Glimmer module without having to manually reimport
 - [os](https://github.com/rdp/os): provides OS detection capabilities (e.g. `OS.mac?` or `OS.windows?`) to write cross-platform code inexpensively

data/VERSION

@@ -1 +1 @@
-4.18.4.8
+4.18.5.1

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:
@@ -201,62 +290,63 @@ https://www.eclipse.org/nebula/
 This is not an exaustive list, but should give you a good start in learning Glimmer GUI DSL keywords, keeping in mind that the full list can be derived from the [SWT documentation](https://www.eclipse.org/swt/widgets/). More will be explained in the following sections.
 
 **Widgets:**
-- `button`: featured in [Hello, Checkbox!](#hello-checkbox) / [Hello, Button!](#hello-button) / [Hello, Table!](#hello-table) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, Message Box!](#hello-message-box) / [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Hello, Group!](#hello-group) / [Hello, Combo!](#hello-combo) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Contact Manager](#contact-manager) / [Tic Tac Toe](#tic-tac-toe) / [Login](#login)
-- `browser`: featured in [Hello, Browser!](#hello-browser)
-- `calendar`: featured in [Hello, Date Time!](#hello-date-time)
-- `checkbox`: featured in [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox)
-- `checkbox_group`: featured in [Hello, Checkbox Group!](#hello-checkbox-group)
-- `combo`: featured in [Hello, Table!](#hello-table) / [Hello, Combo!](#hello-combo)
-- `composite`: featured in [Hello, Radio!](#hello-radio) / [Hello, Computed!](#hello-computed) / [Hello, Checkbox!](#hello-checkbox) / [Tic Tac Toe](#tic-tac-toe) / [Login](#login) / [Contact Manager](#contact-manager)
-- `date`: featured in [Hello, Table!](#hello-table) / [Hello, Date Time!](#hello-date-time) / [Hello, Custom Shell!](#hello-custom-shell) / [Tic Tac Toe](#tic-tac-toe)
-- `date_drop_down`: featured in [Hello, Table!](#hello-table) / [Hello, Date Time!](#hello-date-time)
-- `group`: featured in [Hello, Group!](#hello-group) / [Contact Manager](#contact-manager)
-- `label`: featured in [Hello, Computed!](#hello-computed) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox) / [Hello, World!](#hello-world) / [Hello, Table!](#hello-table) / [Hello, Tab!](#hello-tab) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Menu Bar!](#hello-menu-bar) / [Hello, Date Time!](#hello-date-time) / [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Custom Shell!](#hello-custom-shell) / [Contact Manager](#contact-manager) / [Login](#login)
-- `list` (w/ optional `:multi` SWT style): featured in [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Contact Manager](#contact-manager)
-- `menu`: featured in [Hello, Menu Bar!](#hello-menu-bar) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Table!](#hello-table)
-- `menu_bar`: featured in [Hello, Menu Bar!](#hello-menu-bar)
-- `menu_item`: featured in [Hello, Table!](#hello-table) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Menu Bar!](#hello-menu-bar)
-- `message_box`: featured in [Hello, Table!](#hello-table) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Message Box!](#hello-message-box) / [Hello, Menu Bar!](#hello-menu-bar)
-- `radio`: featured in [Hello, Radio!](#hello-radio) / [Hello, Group!](#hello-group)
-- `radio_group`: featured in [Hello, Radio Group!](#hello-radio-group)
+- `button`: featured in [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, Button!](GLIMMER_SAMPLES.md#hello-button) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Message Box!](GLIMMER_SAMPLES.md#hello-message-box) / [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe) / [Login](GLIMMER_SAMPLES.md#login)
+- `browser`: featured in [Hello, Browser!](GLIMMER_SAMPLES.md#hello-browser)
+- `calendar`: featured in [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time)
+- `checkbox`: featured in [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox)
+- `checkbox_group`: featured in [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group)
+- `combo`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo)
+- `composite`: featured in [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe) / [Login](GLIMMER_SAMPLES.md#login) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `date`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
+- `date_drop_down`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time)
+- `group`: featured in [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `label`: featured in [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, World!](GLIMMER_SAMPLES.md#hello-world) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Tab!](GLIMMER_SAMPLES.md#hello-tab) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Login](GLIMMER_SAMPLES.md#login)
+- `list` (w/ optional `:multi` SWT style): featured in [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `menu`: featured in [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table)
+- `menu_bar`: featured in [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar)
+- `menu_item`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar)
+- `message_box`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Message Box!](GLIMMER_SAMPLES.md#hello-message-box) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar)
+- `radio`: featured in [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group)
+- `radio_group`: featured in [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group)
 - `scrolled_composite`
-- `shell`: featured in [Hello, Checkbox!](#hello-checkbox) / [Hello, Button!](#hello-button) / [Hello, Table!](#hello-table) / [Hello, Tab!](#hello-tab) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Hello, Group!](#hello-group) / [Hello, Date Time!](#hello-date-time) / [Hello, Custom Shell!](#hello-custom-shell) / [Hello, Computed!](#hello-computed) / [Hello, Combo!](#hello-combo) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Contact Manager](#contact-manager) / [Tic Tac Toe](#tic-tac-toe) / [Login](#login)
-- `tab_folder`: featured in [Hello, Tab!](#hello-tab)
-- `tab_item`: featured in [Hello, Tab!](#hello-tab)
-- `table`: featured in [Hello, Custom Shell!](#hello-custom-shell) / [Hello, Table!](#hello-table) / [Contact Manager](#contact-manager)
-- `table_column`: featured in [Hello, Table!](#hello-table) / [Hello, Custom Shell!](#hello-custom-shell) / [Contact Manager](#contact-manager)
-- `text`: featured in [Hello, Computed!](#hello-computed) / [Login](#login) / [Contact Manager](#contact-manager)
-- `time`: featured in [Hello, Table!](#hello-table) / [Hello, Date Time!](#hello-date-time)
-- Glimmer::UI::CustomWidget: ability to define any keyword as a custom widget - featured in [Hello, Custom Widget!](#hello-custom-widget)
-- Glimmer::UI::CustomShell: ability to define any keyword as a custom shell (aka custom window) that opens in a new browser window (tab) automatically unless there is no shell open in the current browser window (tab) - featured in [Hello, Custom Shell!](#hello-custom-shell)
+- `shell`: featured in [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, Button!](GLIMMER_SAMPLES.md#hello-button) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Tab!](GLIMMER_SAMPLES.md#hello-tab) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe) / [Login](GLIMMER_SAMPLES.md#login)
+- `tab_folder`: featured in [Hello, Tab!](GLIMMER_SAMPLES.md#hello-tab)
+- `tab_item`: featured in [Hello, Tab!](GLIMMER_SAMPLES.md#hello-tab)
+- `table`: featured in [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `table_column`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `text`: featured in [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Login](GLIMMER_SAMPLES.md#login) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `time`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time)
+- Glimmer::UI::CustomWidget: ability to define any keyword as a custom widget - featured in [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget)
+- Glimmer::UI::CustomShell: ability to define any keyword as a custom shell (aka custom window) that opens in a new browser window (tab) automatically unless there is no shell open in the current browser window (tab) - featured in [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell)
 
 **Layouts:**
-- `grid_layout`: featured in [Hello, Custom Shell!](#hello-custom-shell) / [Hello, Computed!](#hello-computed) / [Hello, Table!](#hello-table) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Menu Bar!](#hello-menu-bar) / [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Contact Manager](#contact-manager) / [Login](#login) / [Tic Tac Toe](#tic-tac-toe)
-- `row_layout`: featured in [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, Group!](#hello-group) / [Hello, Date Time!](#hello-date-time) / [Hello, Combo!](#hello-combo) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox) / [Contact Manager](#contact-manager)
-- `fill_layout`: featured in [Hello, Custom Widget!](#hello-custom-widget)
-- `layout_data`: featured in [Hello, Table!](#hello-table) / [Hello, Custom Shell!](#hello-custom-shell) / [Hello, Computed!](#hello-computed) / [Tic Tac Toe](#tic-tac-toe) / [Contact Manager](#contact-manager)
+- `grid_layout`: featured in [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar) / [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Login](GLIMMER_SAMPLES.md#login) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
+- `row_layout`: featured in [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
+- `fill_layout`: featured in [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget)
+- `layout_data`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
 
 **Graphics/Style:**
-- `color`: featured in [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Menu Bar!](#hello-menu-bar)
-- `font`: featured in [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox) / [Hello, Table!](#hello-table) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Menu Bar!](#hello-menu-bar) / [Hello, Group!](#hello-group) / [Hello, Date Time!](#hello-date-time) / [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Custom Shell!](#hello-custom-shell) / [Contact Manager](#contact-manager) / [Tic Tac Toe](#tic-tac-toe)
+- `color`: featured in [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar)
+- `font`: featured in [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
 - `Point` class used in setting location on widgets
-- `swt` and `SWT` class to set SWT styles on widgets - featured in [Hello, Custom Shell!](#hello-custom-shell) / [Login](#login) / [Contact Manager](#contact-manager)
+- `swt` and `SWT` class to set SWT styles on widgets - featured in [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Login](GLIMMER_SAMPLES.md#login) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
 
 **Data-Binding/Observers:**
-- `bind`: featured in [Hello, Computed!](#hello-computed) / [Hello, Combo!](#hello-combo) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox) / [Hello, Button!](#hello-button) / [Hello, Table!](#hello-table) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Hello, Group!](#hello-group) / [Hello, Date Time!](#hello-date-time) / [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Custom Shell!](#hello-custom-shell) / [Login](#login) / [Contact Manager](#contact-manager) / [Tic Tac Toe](#tic-tac-toe)
-- `observe`: featured in [Hello, Table!](#hello-table) / [Tic Tac Toe](#tic-tac-toe)
-- `on_widget_selected`: featured in [Hello, Combo!](#hello-combo) / [Hello, Checkbox Group!](#hello-checkbox-group) / [Hello, Checkbox!](#hello-checkbox) / [Hello, Button!](#hello-button) / [Hello, Table!](#hello-table) / [Hello, Radio Group!](#hello-radio-group) / [Hello, Radio!](#hello-radio) / [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu) / [Hello, Message Box!](#hello-message-box) / [Hello, Menu Bar!](#hello-menu-bar) / [Hello, List Single Selection!](#hello-list-single-selection) / [Hello, List Multi Selection!](#hello-list-multi-selection) / [Hello, Group!](#hello-group) / [Contact Manager](#contact-manager) / [Login](#login) / [Tic Tac Toe](#tic-tac-toe)
+- `bind`: featured in [Hello, Computed!](GLIMMER_SAMPLES.md#hello-computed) / [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, Button!](GLIMMER_SAMPLES.md#hello-button) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Hello, Date Time!](GLIMMER_SAMPLES.md#hello-date-time) / [Hello, Custom Widget!](GLIMMER_SAMPLES.md#hello-custom-widget) / [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Login](GLIMMER_SAMPLES.md#login) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
+- `observe`: featured in [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
+- `on_widget_selected`: featured in [Hello, Combo!](GLIMMER_SAMPLES.md#hello-combo) / [Hello, Checkbox Group!](GLIMMER_SAMPLES.md#hello-checkbox-group) / [Hello, Checkbox!](GLIMMER_SAMPLES.md#hello-checkbox) / [Hello, Button!](GLIMMER_SAMPLES.md#hello-button) / [Hello, Table!](GLIMMER_SAMPLES.md#hello-table) / [Hello, Radio Group!](GLIMMER_SAMPLES.md#hello-radio-group) / [Hello, Radio!](GLIMMER_SAMPLES.md#hello-radio) / [Hello, Pop Up Context Menu!](GLIMMER_SAMPLES.md#hello-pop-up-context-menu) / [Hello, Message Box!](GLIMMER_SAMPLES.md#hello-message-box) / [Hello, Menu Bar!](GLIMMER_SAMPLES.md#hello-menu-bar) / [Hello, List Single Selection!](GLIMMER_SAMPLES.md#hello-list-single-selection) / [Hello, List Multi Selection!](GLIMMER_SAMPLES.md#hello-list-multi-selection) / [Hello, Group!](GLIMMER_SAMPLES.md#hello-group) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager) / [Login](GLIMMER_SAMPLES.md#login) / [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
 - `on_modify_text`
-- `on_key_pressed` (and SWT alias `on_swt_keydown`) - featured in [Login](#login) / [Contact Manager](#contact-manager)
+- `on_key_pressed` (and SWT alias `on_swt_keydown`) - featured in [Login](GLIMMER_SAMPLES.md#login) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
 - `on_key_released` (and SWT alias `on_swt_keyup`)
 - `on_mouse_down` (and SWT alias `on_swt_mousedown`)
-- `on_mouse_up` (and SWT alias `on_swt_mouseup`) - featured in [Hello, Custom Shell!](#hello-custom-shell) / [Contact Manager](#contact-manager)
+- `on_mouse_up` (and SWT alias `on_swt_mouseup`) - featured in [Hello, Custom Shell!](GLIMMER_SAMPLES.md#hello-custom-shell) / [Contact Manager](GLIMMER_SAMPLES.md#contact-manager)
 
 **Event loop:**
-- `display`: featured in [Tic Tac Toe](#tic-tac-toe)
-- `async_exec`: featured in [Hello, Custom Widget!](#hello-custom-widget) / [Hello, Custom Shell!](#hello-custom-shell)
+- `display`: featured in [Tic Tac Toe](GLIMMER_SAMPLES.md#tic-tac-toe)
+- `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
 
@@ -284,7 +374,7 @@ Shell widget proxy has extra methods specific to SWT Shell:
 - `#show`: Alias for `#open`
 - `#hide`: Hides a shell setting "visible" property to false
 - `#close`: Closes the shell
-- `#center`: Centers the shell within monitor it is in
+- `#center_within_display`: Centers the shell within monitor it is in
 - `#start_event_loop`: (happens as part of `#open`) Starts SWT Event Loop (you may learn more about it here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/Display.html). This method is not needed except in rare circumstances where there is a need to start the SWT Event Loop before opening the shell.
 - `#visible?`: Returns whether a shell is visible
 - `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
@@ -334,7 +424,7 @@ shell {
 
 ###### Shell Icon Tip for Packaging on Windows
 
-When setting shell icon for a [packaged](#packaging--distribution) app, which has a JAR file at its core, you can reference the `ico` file that ships with the app by going one level up (e.g. `'../AppName.ico'`)
+When setting shell icon for a [packaged](GLIMMER_PACKAGING_AND_DISTRIBUTION.md#packaging--distribution) app, which has a JAR file at its core, you can reference the `ico` file that ships with the app by going one level up (e.g. `'../AppName.ico'`)
 
 #### Dialog
 
@@ -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)
 
@@ -800,7 +903,7 @@ You may check out a more full-fledged example in [Hello, Sash Form!](#hello-sash
 
 ![Hello Browser](/images/glimmer-hello-browser.png)
 
-Glimmer supports the SWT Browser widget, which can load URLs or render HTML. It can even be instrumented with JavaScript when needed (though highly discouraged since it defeats the purpose of using Ruby except in very rare cases like leveraging a pre-existing web codebase in a desktop app).
+Glimmer supports the [SWT Browser widget](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/browser/Browser.html), which can load URLs or render HTML. It can even be instrumented with JavaScript when needed (though highly discouraged since it defeats the purpose of using Ruby except in very rare cases like leveraging a pre-existing web codebase in a desktop app).
 
 Example loading a URL (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
 
@@ -834,6 +937,8 @@ shell {
 }.open
 ```
 
+Learn more at the [SWT Browser widget](https://help.eclipse.org/2020-12/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/browser/Browser.html) API.
+
 ### Widget Styles
 
 SWT widgets receive `SWT` styles in their constructor as per this guide:
@@ -1290,6 +1395,7 @@ Shape keywords and their args (including defaults) are listed below (they basica
 - `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
@@ -1367,7 +1473,7 @@ Screenshot:
 
 ![Canvas Animation Example](/images/glimmer-example-canvas.png)
 
-Learn more at the [Hello, Canvas! Sample](#hello-canvas).
+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).
 
@@ -1409,6 +1515,116 @@ shell {
 }.open
 ```
 
+#### 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.
+
+- `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#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)**
@@ -1438,6 +1654,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)):
@@ -1463,6 +1694,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)):
@@ -1471,11 +1704,10 @@ Example (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
 include Glimmer
 
 @the_image = image(250, 250)
-gc = org.eclipse.swt.graphics.GC.new(@the_image)
 250.times {|y|
   250.times {|x|
-    gc.foreground = Color.new(y%255, x%255, (x+y)%255)
-    gc.draw_point(x, y)
+    @the_image.gc.foreground = Color.new(y%255, x%255, (x+y)%255)
+    @the_image.gc.draw_point(x, y)
   }
 }
 
@@ -1500,127 +1732,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)
-
-Example setting the icon of the application (you may copy/paste in [`girb`](GLIMMER_GIRB.md)):
+Of course, you could also take advantage of the pixel-less terser syntax:
 
-```
+```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
 
@@ -1704,7 +1889,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
 
@@ -1770,7 +1955,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.
 
@@ -1778,7 +1963,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](#tetris) sample provides a good example of that.
 
 ### Data-Binding
 
@@ -1799,6 +1984,18 @@ the address of a contact. This is called nested property data binding.
 
 This example adds on the one above it by specifying converters on read and write of the model property, like in the case of a `text` widget. The text widget will then displays the street upper case and the model will store it lower case. When specifying converters, read and write operations must be symmetric (to avoid an infinite update loop between the widget and the model since the widget checks first if value changed before updating)
 
+`text bind(contact, 'address.street', sync_exec: true)`
+
+**(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)`
+
+**(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] })`
 
 This example also specifies a converter on read of the model property, but via a lambda, which truncates the street to 10 characters only. Note that the read and write operations are assymetric. This is fine in the case of formatting data for a read-only widget like `label`
@@ -2234,6 +2431,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.
@@ -2706,6 +2905,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)
@@ -2715,6 +2916,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
@@ -2723,6 +2926,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
@@ -2932,10 +3137,13 @@ 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.
 
@@ -2954,7 +3162,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
 
@@ -3025,7 +3233,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
 
@@ -3039,7 +3247,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