glimmer-dsl-swt 4.17.1.0 → 4.17.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 881781afff00abf1690fde7bd43136ae6544e205b13af5c0cfb1e5120c01ab1a
-  data.tar.gz: 84542383d33bcff92b92bac03f30cbf2238872871feadec3d128efec75020423
+  metadata.gz: 72abd42bfd0a4074ba03517643ae4f560cc892d1d592cefd9d96b7a4990195de
+  data.tar.gz: 6479abb04a31e9bd5670a4de48c9c98a46f7b05783f4491082c4e0c127f5aa1c
 SHA512:
-  metadata.gz: f83516566007cb8043f91bbd2aea68395d862d0fe6795aa12b68b64324e4a2fe1d6b697786916288158738434e9799170eef1c56004e58f7d5e4e2189c80f9f0
-  data.tar.gz: 02dc757afa476a696006183e4b4d07022376db57abc3ae927683857c0ef5eafc8c4e4f336f78a07bbfeef18df0a8394016877c6a0db4a037b16aeea2947b148e
+  metadata.gz: 46ecd1fbe2700184f8b3ea5f447cd7d3e2209a777080d40a787821edee1d65d7525e28befd96bd4ec5dbd48f646371810470eeef8777388d60bd6fce823da525
+  data.tar.gz: 74ecccfa3cbb21712178fa695ddbd2eed4cb3cbb400aae3b3bf5b5dc5358ccba3ae2ff056d1992d7adfc0dcd173dcf77cf52a6f6e4ecabe961f5ece49c6b69d9

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Change Log
 
+### 4.17.2.3
+
+- Maintain image file path upon scaling an ImageProxy
+- Add a glimmer rake task that wraps the juwelier rake gemspec:generate task
+- Accept `ImageProxy` as arg for `image` and `background_image` property methods
+- (EXPERIMENTAL) Animate gif images when set as a `background_image` on a `composite`
+- Fix issue with table redraw after data-binding changes leaving old removed table items visible (even if user cannot interact with anymore)
+- Fix issue with running package rake task from `glimmer` command TUI
+
+### 4.17.2.2
+
+- Small updates/refactorings in samples
+- Fix issue with displaying `glimmer` command tasks on Windows
+
+### 4.17.2.1
+
+- Add `--bundler=group` option to `glimmer` command
+- Add `--pd` option to `glimmer` command
+- Hello, Custom Widget! sample
+- Hello, Custom Shell! sample
+
+### 4.17.2.0
+
+- `glimmer` command --bundler option to run with bundler/setup (instead of picking gems directly)
+- Remove Gemfile dependency on Juwelier since it does not relate to GUI (delaying install of it till scaffolding)
+- Remove Gemfile dependency on Warbler since it does not relate to GUI (delaying install of it till packaging)
+- Move Package and Scaffold classes under Glimmer::RakeTask (Glimmer::Package.javapackager_extra_args is now Glimmer::RakeTask::Package.javapackager_extra_args)
+- Fixed issue with scaffolding spec/spec_helper.rb with Juwelier (since it changed from Jeweler)
+
+### 4.17.1.1
+
+- Fixed issue with showing glimmer command tasks twice
+
 ### 4.17.1.0
 
 - Switch to Juwelier gem (from Jeweler)

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.17.1.0
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for SWT 4.17.2.3
 ## JRuby Desktop Development GUI Library
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-swt.svg)](http://badge.fury.io/rb/glimmer-dsl-swt)
 [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer-dsl-swt.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt)
@@ -10,11 +10,9 @@
 
 (The Original Glimmer Library Since 2007. Beware of Imitators!)
 
-[**Glimmer**](https://rubygems.org/gems/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://rubygems.org/gems/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns. To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/) and MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows).
+[**Glimmer**](https://rubygems.org/gems/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://rubygems.org/gems/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns. To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/), MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows), and [Gem Packaged Shell Scripts](#custom-shell-gem) on [Linux](https://www.linux.org/).
 
-[Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs.
-
-NOTE: Glimmer is in beta mode. Please make better by providing feedback and [contributing](#contributing) when possible. The more feedback and issues you report the better.
+[Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs. Please make [Glimmer](https://rubygems.org/gems/glimmer) even better by providing feedback and [contributing](#contributing) when possible.
 
 [<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br /> 
 Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
@@ -335,6 +333,8 @@ Glimmer App:
       - [Hello, Drag and Drop!](#hello-drag-and-drop)
       - [Hello, Menu Bar!](#hello-menu-bar)
       - [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu)
+      - [Hello, Custom Widget!](#hello-custom-widget)
+      - [Hello, Custom Shell!](#hello-custom-shell)
     - [Elaborate Samples](#elaborate-samples)
       - [User Profile](#user-profile)
       - [Login](#login)
@@ -416,6 +416,8 @@ If you intend to build a Glimmer app from scratch with [scaffolding](#scaffoldin
 
 Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](#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).
+
 ### Option 1: Direct Install 
 (Use for [Scaffolding](#scaffolding))
 
@@ -426,7 +428,7 @@ jgem install glimmer-dsl-swt
 
 Or this command if you want a specific version:
 ```
-jgem install glimmer-dsl-swt -v 4.17.1.0
+jgem install glimmer-dsl-swt -v 4.17.2.3
 ```
 
 Note: Gem version numbers are in sync with the SWT library versions. The first two digits represent the SWT version number. The last two digits represent the minor and patch versions of Glimmer DSL for SWT.
@@ -474,6 +476,8 @@ On Windows, it simply lists the available Glimmer tasks at the end (courtsey of
 
 If you are new to Glimmer, you may read the Basic Usage section and skip the rest until you have gone through [Girb (Glimmer irb) Command](#girb-glimmer-irb-command), [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax), and [Samples](#samples).
 
+Note: If you encounter an issue running the `glimmer` command, run `bundle exec glimmer` instead.
+
 ### Basic Usage
 
 ```
@@ -501,9 +505,9 @@ bin/glimmer sample:run[hello_world]
 Below are the full usage instructions that come up when running `glimmer` without args.
 
 ```
-Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.1.0
+Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.2.3
       
-Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
+Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
 
 Runs Glimmer applications and tasks.    
 
@@ -513,7 +517,9 @@ automatically preloading the glimmer Ruby gem and SWT jar dependency.
 Optionally, extra Glimmer options, JRuby options, and/or environment variables may be passed in.
 
 Glimmer options:
-- "--quiet"           : Does not announce file path of Glimmer application being launched
+- "--bundler=GROUP"   : Activates gems in Bundler default group in Gemfile
+- "--pd=BOOLEAN"      : Requires puts_debuggerer to enable pd method
+- "--quiet=BOOLEAN"   : Does not announce file path of Glimmer application being launched
 - "--debug"           : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
 - "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
 
@@ -528,6 +534,7 @@ Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and
   glimmer package[type]                                      # Package app for distribution (generating config, jar, and native files) (type is optional)
   glimmer package:clean                                      # Clean by removing "dist" and "packages" directories
   glimmer package:config                                     # Generate JAR config file
+  glimmer package:gemspec                                    # Generate gemspec  
   glimmer package:jar                                        # Generate JAR file
   glimmer package:lock_jars                                  # Lock JARs
   glimmer package:native[type]                               # Generate Native files
@@ -614,7 +621,7 @@ This will run the hello_tab sample and output its code:
 ```
 $ glimmer sample:run[hello_tab] 
 
-# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.0/samples/hello/hello_tab.rb
+# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.3/samples/hello/hello_tab.rb
 
 class HelloTab
   include Glimmer
@@ -659,7 +666,7 @@ Example:
 ```
 $ glimmer sample:code[tic_tac_toe] 
 
-# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.0/samples/elaborate/tic_tac_toe.rb
+# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.3/samples/elaborate/tic_tac_toe.rb
 
 require_relative "tic_tac_toe/board"
 
@@ -720,7 +727,7 @@ TicTacToe.new.open
 # # #
 
 
-# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.0/samples/elaborate/tic_tac_toe/cell.rb
+# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.3/samples/elaborate/tic_tac_toe/cell.rb
 
 class TicTacToe
   class Cell
@@ -753,7 +760,7 @@ end
 # # #
 
 
-# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.0/samples/elaborate/tic_tac_toe/board.rb
+# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.3/samples/elaborate/tic_tac_toe/board.rb
 
 require_relative 'cell'
 
@@ -938,7 +945,7 @@ $ glimmer scaffold[greeter]
 	create	spec/spec_helper.rb
 	create	spec/greeter_spec.rb
 	create	.rspec
-Jeweler has prepared your gem in ./greeter
+Juwelier has prepared your gem in ./greeter
 Created greeter/.gitignore
 Created greeter/.ruby-version
 Created greeter/.ruby-gemset
@@ -1009,7 +1016,7 @@ glimmer scaffold:cw[name]
 #### Custom Shell Gem
 
 Custom shell gems are self-contained Glimmer apps as well as reusable custom shells. 
-They have everything scaffolded Glimmer apps come with in addition to gem content like a [jeweler](https://github.com/technicalpickles/jeweler) Rakefile that can build gemspec and release gems. 
+They have everything scaffolded Glimmer apps come with in addition to gem content like a [Juwelier](https://rubygems.org/gems/juwelier) Rakefile that can build gemspec and release gems. 
 Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
 They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
 Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
@@ -1034,7 +1041,7 @@ Only official Glimmer gems created by the Glimmer project committers will have n
 
 Since custom shell gems are both an app and a gem, they provide two ways to run:
 - Run the `glimmer` command and pass it the generated script under the `bin` directory that matches the gem name (e.g. run `glimmer bin/glimmer-cs-calculator`)
-- Run the executable binary file that ships with the gem directly (without `glimmer`). It intentionally has a shorter name for convenience since it is meant to be used on the command line (not in a package), so you can leave out the `glimmer-cs-` prefix (e.g. run `bin/calculator` directly)
+- Run the executable shell script that ships with the gem directly (does not need the `glimmer` command). It intentionally has a shorter name for convenience since it is meant to be used on the command line (not in a package), so you can leave out the `glimmer-cs-` prefix (e.g. run `bin/calculator` directly). This is also used as the main way of running custom shell gems on Linux.
 
 Examples: 
 
@@ -1139,6 +1146,28 @@ Output:
                                                                                    
 ```
 
+Example:
+
+Check all custom widgets for Glimmer.
+
+```
+glimmer list:gems:cw
+```
+
+Output:
+
+```
+
+  Glimmer Custom Widget Gems at rubygems.org:
+                                                                                                                                
+         Name                      Gem                Version      Author                       Description                     
+                                                                                                                                
+  Browser (Chromium)   glimmer-cw-browser-chromium   1.0.0       Andy Maleh   Chromium Browser - Glimmer Custom Widget          
+  Cdatetime (Nebula)   glimmer-cw-cdatetime-nebula   1.5.0.0.1   Andy Maleh   Nebula CDateTime Widget - Glimmer Custom Widget   
+  Video                glimmer-cw-video              1.0.0       Andy Maleh   Glimmer Custom Widget - Video                                                                                   
+  
+```
+
 #### Listing DSL Gems
 
 The following command lists available Glimmer [DSL Gems](#multi-dsl-support) (prefixed with "glimmer-dsl-" by convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org):
@@ -1161,24 +1190,46 @@ Output:
                                                                          
   Name         Gem          Version    Author          Description       
                                                                          
-  Css    glimmer-dsl-css    0.2.0     AndyMaleh    Glimmer DSL for CSS    
-  Opal   glimmer-dsl-opal   0.1.0     AndyMaleh    Glimmer DSL for Opal   
-  Swt    glimmer-dsl-swt    4.17.1.0  AndyMaleh    Glimmer DSL for SWT    
+  Css    glimmer-dsl-css    1.1.0     AndyMaleh    Glimmer DSL for CSS    
+  Opal   glimmer-dsl-opal   0.3.0     AndyMaleh    Glimmer DSL for Opal   
+  Swt    glimmer-dsl-swt    4.17.2.3  AndyMaleh    Glimmer DSL for SWT    
   Tk     glimmer-dsl-tk     0.0.5     AndyMaleh    Glimmer DSL for Tk     
-  Xml    glimmer-dsl-xml    0.2.0     AndyMaleh    Glimmer DSL for XML                                                                         
+  Xml    glimmer-dsl-xml    1.1.0     AndyMaleh    Glimmer DSL for XML                                                                         
 ```
 
 ### Packaging
 
+Glimmer supports packaging applications as native files on Mac and Windows.
+
 Glimmer packaging tasks are detailed under [Packaging & Distribution](#packaging--distribution).
 
+On Linux, the Glimmer [Custom Shell Gem](#custom-shell-gem) approach provides a [Gem Packaged Shell Script](#custom-shell-gem) (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem)
+
 ### Raw JRuby Command
 
 If there is a need to run Glimmer directly via the `jruby` command, you
-may run the following:
+may run the following on Windows/Linux:
+
+```
+jruby -r glimmer-dsl-swt -S application.rb
+```
+
+Or, the following on Mac:
+
+```
+jruby -J-XstartOnFirstThread -r glimmer-dsl-swt -S application.rb
+```
+
+If you want to use a specific custom version of SWT, run the following on Windows/Linux:
+
+```
+jruby -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
+```
+
+Or, the following on Mac:
 
 ```
-jruby -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
+jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
 ```
 
 The `-J-classpath` option specifies the `swt.jar` file path, which can be a
@@ -1196,7 +1247,7 @@ However, if there is a reason to use the raw `jruby` command directly instead of
 
 Example:
 ```
-jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
+jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
 ```
 
 ## Girb (Glimmer irb) Command
@@ -1280,19 +1331,21 @@ Glimmer DSL syntax consists mainly of:
 
 ### DSL Auto-Expansion
 
-Glimmer supports a new and radical Ruby DSL concept called DSL Auto-Expansion. It is explained by first mentioning the two types of Glimmer GUI DSL keywords: static and dynamic.
+Glimmer supports a new and radical Ruby DSL concept called DSL Auto-Expansion. To explain, let's first mention the two types of Glimmer GUI DSL keywords: static and dynamic.
 
 Static keywords are pre-identified keywords in the Glimmer DSL, such as `shell`, `display`, `message_box`, `async_exec`, `sync_exec`, and `bind`.
 
-Dynamic keywords are dynamically figured out from currently imported (aka required/loaded) SWT widgets, custom widgets, and widget properties. Examples are: `label`, `combo`, and `list` for widgets and `enabled`, `text`, and `selection` for properties.
+Dynamic keywords are dynamically figured out from currently imported (aka required/loaded) SWT widgets and custom widgets. Examples are: `label`, `combo`, and `list` for SWT widgets and `c_date_time`, `video`, and `gantt_chart` for custom widgets.
+
+The only reason to distinguish between the two is to realize that importing new Glimmer [custom widgets](#custom-widgets) and Java SWT custom widget libraries automatically expands Glimmer's DSL vocabulary with new dynamic keywords. 
 
-The only reason to distinguish between the two types of Glimmer DSL keywords is to realize that importing new Glimmer [custom widgets](#custom-widgets) and Java SWT custom widget libraries automatically expands Glimmer's DSL vocabulary via new dynamic keywords. 
+For example, if a project adds this custom Java SWT library from the [Nebula Project](https://www.eclipse.org/nebula/):
 
-For example, if a project adds this custom Java SWT library:
+https://www.eclipse.org/nebula/widgets/gallery/gallery.php
 
-https://www.eclipse.org/nebula/widgets/cdatetime/cdatetime.php?page=operation
+Glimmer will automatically support using the keyword `gallery`
 
-Glimmer will automatically support using the keyword `c_date_time`
+This is what DSL Auto-Expansion is.
 
 You will learn more about widgets next.
 
@@ -1407,6 +1460,10 @@ shell {
 
 If you are new to Glimmer, you have learned enough to start running some [samples](#samples). Go ahead and run all Glimmer [samples](#samples), and come back to read the rest in any order you like since this material is more organized like a reference.
 
+If you are advanced and need more widgets, check out the [Nebula Project](https://www.eclipse.org/nebula/) for an extensive list of high quality custom widgets:
+
+https://www.eclipse.org/nebula/
+
 #### Display
 
 SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally 
@@ -2602,12 +2659,45 @@ end
 
 ### Custom Widgets
 
-Glimmer supports creating custom widgets with minimal code, which automatically extends Glimmer's DSL syntax with an underscored lowercase keyword.
+Custom widgets are brand new Glimmer DSL keywords that represent aggregates of existing widgets (e.g. `address_form`), customized existing widgets (e.g. `greeting_label`), or brand new widgets (e.g. `oscilloscope`)
 
-Simply create a new class that includes `Glimmer::UI::CustomWidget` and put Glimmer DSL code in its `#body` block (its return value is stored in `#body_root` attribute). Glimmer will then automatically recognize this class by convention when it encounters a keyword matching the class name converted to underscored lowercase (and namespace double-colons `::` replaced with double-underscores `__`)
+You can find out about [published Glimmer Custom Widgets](https://github.com/AndyObtiva/glimmer-dsl-swt#gem-listing) by running the `glimmer list:gems:customwidget` command
+
+Glimmer supports two ways of creating custom widgets with minimal code:
+1. Method-based Custom Widgets (for single-view-internal reuse): Extract a method containing Glimmer DSL widget syntax. Useful for quickly eliminating redundant code within a single view.
+2. Class-based Custom Widgets (for multiple-view-external reuse): Create a class that includes the `Glimmer::UI::CustomWidget` module and Glimmer DSL widget syntax in a `body {}` block. This will automatically extend Glimmer's DSL syntax with an underscored lowercase keyword matching the class name by convention. Useful in making a custom widget available in many views.
+
+Approach #1 is a casual Ruby-based approach. Approach #2 is the official Glimmer approach. Typically, when referring to Custom Widgets, we are talking about Class-based Custom Widgets.
+
+A developer might start with approach #1 to eliminate duplication in a view and later upgrade it to approach #2 when needing to export a custom widget to make it available in many views.
+
+Class-based Custom Widgets offer a number of benefits over method-based custom widgets, such as built-in support for passing SWT style, nested block of extra widgets and properties, and `before_body`/`after_body` hooks.
 
 #### Simple Example
 
+##### Method-Based Custom Widget Example
+
+(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
+
+Definition and usage in the same file:
+```ruby
+def red_label(label_text)
+  label {
+    text label_text
+    background :red
+  }
+end
+
+shell {
+  red_label('Red Label')
+}.open
+```
+
+
+##### Class-Based Custom Widget Example
+
+Simply create a new class that includes `Glimmer::UI::CustomWidget` and put Glimmer DSL code in its `#body` block (its return value is stored in `#body_root` attribute). Glimmer will then automatically recognize this class by convention when it encounters a keyword matching the class name converted to underscored lowercase (and namespace double-colons `::` replaced with double-underscores `__`)
+
 (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
 Definition:
@@ -2626,15 +2716,22 @@ end
 Usage:
 ```ruby
 shell {
-  red_label {
-    text 'Red Label'
+  red_label(:center) {
+    text 'Red Label'        
+    foreground :green
   }
 }.open
 ```
 
-As you can see, `RedLabel` became Glimmer DSL keyword: `red_label`
+As you can see, `RedLabel` became the Glimmer DSL keyword `red_label` and worked just like a standard label by taking in SWT style and nested properties. As such, it is a first-class citizen of the Glimmer GUI DSL.
+
+#### Custom Widget Lifecycle Hooks
 
-#### Lifecycle Hook Example
+You may execute code before or after evaluating the body with these lifecycle hooks:
+- `before_body`: takes a block that executes in the custom widget instance scope before calling `body`. Useful for initializing variables to later use in `body`
+- `after_body`: takes a block that executes in the custom widget instance scope after calling `body`. Useful for setting up observers on widgets built in `body` (set in instance variables) and linking to other shells.
+
+#### Lifecycle Hooks Example
 
 (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
@@ -2729,12 +2826,6 @@ shell {
 
 Notice how `:no_focus` was the `swt_style` value, followed by the `options` hash `{orientation: :horizontal, bg_color: :white}`, and finally the `content` block containing the label with `'SANDWICH CONTENT'`
 
-#### Custom Widget Lifecycle Hooks
-
-Last but not least, these are the available lifecycle hooks:
-- `before_body`: takes a block that executes in the custom widget instance scope before calling `body`. Useful for initializing variables to later use in `body`
-- `after_body`: takes a block that executes in the custom widget instance scope after calling `body`. Useful for setting up observers on widgets built in `body` (set in instance variables) and linking to other shells.
-
 #### Gotcha
 
 Beware of defining a custom attribute that is a common SWT widget property name.
@@ -2770,12 +2861,16 @@ The `text` method invoked in the custom widget body will call the one you define
 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.
+
 ### Custom Shells
 
 Custom shells are a kind of custom widgets that have shells only as the body root. They can be self-contained applications that may be opened and hidden/closed independently of the main app.
 
 They may also be chained in a wizard fashion.
 
+You can find out about [published Glimmer Custom Shells](https://github.com/AndyObtiva/glimmer-dsl-swt#gem-listing) by running the `glimmer list:gems:customshell` command
+
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
@@ -2835,6 +2930,8 @@ shell { |app_shell|
 }.open
 ```
 
+You may check out [Hello, Custom Shell!](#hello-custom-shell) for another example.
+
 ### Drag and Drop
 
 Glimmer offers Drag and Drop support, thanks to [SWT](https://www.eclipse.org/swt/) and Glimmer's lightweight [DSL syntax](#glimmer-dsl-syntax).
@@ -3393,6 +3490,10 @@ Here is an SWT Custom Widget guide:
 
 https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm
 
+Here is the Nebula Project (custom widget library) homepage:
+
+https://www.eclipse.org/nebula/
+
 ## 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` 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`).
@@ -3585,6 +3686,41 @@ glimmer sample:run[hello_pop_up_context_menu]
 ![Hello Pop Up Context Menu](images/glimmer-hello-pop-up-context-menu.png)
 ![Hello Pop Up Context Menu Popped Up](images/glimmer-hello-pop-up-context-menu-popped-up.png)
 
+#### Hello, Custom Widget!
+
+This sample demonstrates the use of a custom widget in Glimmer.
+
+Code:
+
+[samples/hello/hello_custom_widget.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_custom_widget.rb)
+
+Run:
+
+```
+glimmer sample:run[hello_custom_widget]
+```
+
+![Hello Custom Widget](images/glimmer-hello-custom-widget.gif)
+
+#### Hello, Custom Shell!
+
+This sample demonstrates the use of a custom shell (aka custom window) in Glimmer.
+
+Code:
+
+[samples/hello/hello_custom_shell.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_custom_shell.rb)
+
+Run:
+
+```
+glimmer sample:run[hello_custom_shell]
+```
+
+![Hello Custom Shell](images/glimmer-hello-custom-shell.png)
+![Hello Custom Shell Email1](images/glimmer-hello-custom-shell-email1.png)
+![Hello Custom Shell Email2](images/glimmer-hello-custom-shell-email2.png)
+![Hello Custom Shell Email3](images/glimmer-hello-custom-shell-email3.png)
+
 ### Elaborate Samples
 
 For more elaborate samples, check the following:
@@ -3706,7 +3842,7 @@ Gladiator is a good demonstration of:
 
 #### Timer
 
-[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding and multi-threading in a desktop application.
+[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding, multi-threading, and Java (Sound) library integration in a desktop application.
 
 [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/glimmer-timer-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-timer)
 
@@ -3730,6 +3866,8 @@ If you have a Glimmer app you would like referenced here, please mention in a Pu
 
 ## Packaging & Distribution
 
+Note: this section mostly applies to Mac and Windows. On Linux, the Glimmer [Custom Shell Gem](#custom-shell-gem) approach provides a [Gem Packaged Shell Script](#custom-shell-gem) (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem)
+
 Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
 
 ```
@@ -3754,8 +3892,8 @@ require 'glimmer/rake_task'
 ```
 
 The Glimmer packaging process done in the `glimmer package` command consists of the following steps:
-1. Generate gemspec via Jeweler (`rake gemspec:generate`): Having a gemspec is required by the [`jar-dependencies`](https://github.com/mkristian/jar-dependencies) JRuby gem, used by JRuby libraries to declare JAR dependencies.
-1. Lock JAR versions (`glimmer package:lock_jars`): This locks versions of JAR dependencies leveraged by the `jar-dependencies` JRuby gem, downloading them into the `./vendor` directory so they would get inside the top-level Glimmer app/gem JAR file.
+1. Generate gemspec via [Juwelier](https://rubygems.org/gems/juwelier) (`rake gemspec:generate`): Having a gemspec is required by the [`jar-dependencies`](https://github.com/mkristian/jar-dependencies) JRuby gem, used by JRuby libraries to declare JAR dependencies.
+1. Lock JAR versions (`glimmer package:4.17.2.3`): This locks versions of JAR dependencies leveraged by the `jar-dependencies` JRuby gem, downloading them into the `./vendor` directory so they would get inside the top-level Glimmer app/gem JAR file.
 1. Generate [Warbler](https://github.com/jruby/warbler) config (`glimmer package:config`): Generates initial Warbler config file (under `./config/warble.rb`) to use for generating JAR file.
 1. Generate JAR file using [Warbler](https://github.com/jruby/warbler) (`glimmer package:jar`): Enables bundling a Glimmer app into a JAR file under the `./dist` directory
 1. Generate native executable using [javapackager](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html) (`glimmer package:native`): Enables packaging a JAR file as a DMG/PKG/APP file on Mac, MSI/EXE/APP on Windows, and DEB/RPM/APP on Linux (Glimmer does not officially support Linux with the `glimmer package` command yet, but it generates the JAR file successfully, and you could use `javapackager` manually afterwards if needed).
@@ -3765,7 +3903,7 @@ The JAR file name will match your application local directory name (e.g. `MathBo
 The DMG file name will match the humanized local directory name + dash + application version (e.g. `Math Bowling-1.0.dmg` for `~/code/MathBowling` with version 1.0 or unspecified)
 
 The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}". 
-You may override by configuring as an extra argument for javapackger (e.g. Glimmer::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
+You may override by configuring as an extra argument for javapackger (e.g. Glimmer::RakeTask::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
 
 ### Packaging Defaults
 
@@ -3793,7 +3931,7 @@ require_relative '../app/my_application.rb'
 - Include DMG Background Icon (Optional): Simply place a .png file under `package/macosx/{HumanAppName}-background.png`
 - Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
 - Include License (Optional): Create a `LICENSE.txt` file in your application and fill it up with your license (e.g. MIT). It will show up to people when installing your app. Note that, you may optionally also specify license type, but you'd have to do so manually via `-BlicenseType=MIT` shown in an [example below](#javapackager-extra-arguments).
-- Extra args (Optional): You may optionally add the following to `Rakefile` to configure extra arguments for javapackager: `Glimmer::Packager.javapackager_extra_args = "..."` (Useful to avoid re-entering extra arguments on every run of rake task.). Read about them in [their section below](#javapackager-extra-arguments).
+- Extra args (Optional): You may optionally add the following to `Rakefile` to configure extra arguments for javapackager: `Glimmer::RakeTask::Package.javapackager_extra_args = "..."` (Useful to avoid re-entering extra arguments on every run of rake task.). Read about them in [their section below](#javapackager-extra-arguments).
 
 ### javapackager Extra Arguments
 
@@ -3805,7 +3943,7 @@ In order to explicitly configure javapackager, Mac package attributes, or sign y
 - https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
 
 The Glimmer rake task allows passing extra options to javapackager via:
-- `Glimmer::Packager.javapackager_extra_args="..."` in your application Rakefile
+- `Glimmer::RakeTask::Package.javapackager_extra_args="..."` in your application Rakefile
 - Environment variable: `JAVAPACKAGER_EXTRA_ARGS`
 
 Example (Rakefile):
@@ -3813,7 +3951,7 @@ Example (Rakefile):
 ```ruby
 require 'glimmer/rake_task'
 
-Glimmer::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"'
+Glimmer::RakeTask::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"'
 ```
 
 Note that `mac.category` defaults to "public.app-category.business", but can be overridden with one of the category UTI values mentioned here: 
@@ -3830,7 +3968,7 @@ That overrides the default application display name.
 
 ### Verbose Mode
 
-Pass `-v` to javapackager in `Glimmer::Package.javapackager_extra_args` or by running `glimmer package:native[type] -v` to learn more about further available customizations for the installer you are requesting to generate.
+Pass `-v` to javapackager in `Glimmer::RakeTask::Package.javapackager_extra_args` or by running `glimmer package:native[type] -v` to learn more about further available customizations for the installer you are requesting to generate.
 
 ### Windows Application Packaging
 
@@ -3844,7 +3982,7 @@ If you just want to test out packaging into a native Windows app that is not pac
 
 Recent macOS versions (starting with Catalina) have very stringent security requirements requiring all applications to be signed before running (unless the user goes to System Preferences -> Privacy -> General tab and clicks "Open Anyway" after failing to open application the first time they run it). So, to release a desktop application on the Mac, it is recommended to enroll in the [Apple Developer Program](https://developer.apple.com/programs/) to distribute on the [Mac App Store](https://developer.apple.com/distribute/) or otherwise request [app notarization from Apple](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) to distribute independently.
 
-Afterwards, you may add developer-id/signing-key arguments to `javapackager` via `Glimmer::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` according to this webpage: https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
+Afterwards, you may add developer-id/signing-key arguments to `javapackager` via `Glimmer::RakeTask::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` according to this webpage: https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
 
 DMG signing key argument:
 ```
@@ -3872,12 +4010,12 @@ To do so, you may follow these steps (abbreviated version from https://developer
 - Enter Name (referred to below as "CertificateName")
 - Set 'Certificate Type' to 'Code Signing'
 - Create (if you alternatively override defaults, make sure to enable all capabilities)
-- Add the following option to javapackager: `-Bmac.signing-key-developer-id-app="CertificateName"` via `Glimmer::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS`
+- Add the following option to javapackager: `-Bmac.signing-key-developer-id-app="CertificateName"` via `Glimmer::RakeTask::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS`
 
 Example:
 
 ```ruby
-Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
+Glimmer::RakeTask::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
 ```
 
 Now, when you run `glimmer package`, it builds a self-signed DMG file. When you make available online, and users download, upon launching application, they are presented with your certificate, which they have to sign if they trust you in order to use the application.
@@ -3892,7 +4030,7 @@ Keep that in mind if you are not going to rely on the default `LICENSE.txt` supp
 Example:
 
 ```ruby
-Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
+Glimmer::RakeTask::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
 ```
 
 2. Mounted DMG Residue
@@ -3912,7 +4050,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:
-- [jeweler](https://github.com/technicalpickles/jeweler): generates app gems during [Glimmer Scaffolding](#scaffolding)
+- [juwelier](https://rubygems.org/gems/juwelier): generates app gems during [Glimmer Scaffolding](#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