glimmer 0.7.6 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94497522f529a193db5b827f739dcf4eab4a23c0c0ac583d7352cd7bd8270a83
-  data.tar.gz: a7a6a6ff9816f5be2422b5bd53c020f8152b47a436cd2cc805690e3af3cb5612
+  metadata.gz: fbe97823fd25586221485191db661a4cb6fe71d8d9be9e89b60d617d5f496540
+  data.tar.gz: d81b11d52ce3f0fe1fdb46d9f1a6c286ccd95c3021118f71b4f72d7724cd0f41
 SHA512:
-  metadata.gz: '095cae0665dbdb73713608a2b2ba9029e0693a33796e4e61ee8463f7f4dcdb385ef04f6fa5f1b3ef2cc48db11492b6bb1c6adff6eeb9de89639a7a1993c3ae1a'
-  data.tar.gz: 5513aac74d33b07ee14dbc430938e1f059a5a76a842d6dbbfef2b29c5fede52f2c57a3aea2053835b411da346bd3c7dca9bdddea385742363a6bf6ed8dbb7d40
+  metadata.gz: 930a0914fc83db952df2eba9321779ee34a3d2819a0dabb05a31615b97b1eb57ff222321bd9db9fa4d6950e0f4e68f6455a66223ac1a1126a1c72be75a8a8b46
+  data.tar.gz: 5ab308d9b3403a9876d8f40f8a51d277cf0c88527f257977f87a21fc530a95a0d3e92d64a6b4025a56b2ed857f3d6b1c4d0d3df10bed7999c25cf90e589d6934

data/README.md

@@ -1,9 +1,9 @@
-# Glimmer 0.7.6 Beta (Desktop Development Library for Ruby)
+# Glimmer 0.8.2 Beta (Ruby Desktop Development GUI Library)
 [![Gem Version](https://badge.fury.io/rb/glimmer.svg)](http://badge.fury.io/rb/glimmer)
 [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer)
-<!-- [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer?branch=master) -->
+[![Maintainability](https://api.codeclimate.com/v1/badges/38fbc278022862794414/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer/maintainability)
 
-Glimmer is a native-UI cross-platform desktop development library written in Ruby. Glimmer's main innovation is a JRuby DSL that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support to greatly facilitate synchronizing the UI with domain models. As a result, that achieves true decoupling of object oriented components, enabling developers to solve business problems without worrying about UI concerns, or alternatively drive development UI-first, and then write clean business models test-first afterwards.
+Glimmer is a native-GUI cross-platform desktop development library written in Ruby. Glimmer's main innovation is a JRuby DSL that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support to greatly facilitate synchronizing the GUI with domain models. As a result, that achieves true decoupling of object oriented components, enabling developers to solve business problems without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models test-first afterwards.
 
 [<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)
@@ -70,11 +70,11 @@ Glimmer app:
 
 ![Tic Tac Toe](images/glimmer-tic-tac-toe.png)
 
-NOTE: Glimmer is in beta mode. Please help make better by adopting for small or low risk projects and providing feedback.
+NOTE: Glimmer is in beta mode. Please help make better by [contributing](#contributing), adopting for small or low risk projects, and providing feedback.
 
-## Table of Contents
+## Table of contents
 
-- [Glimmer 0.7.6 Beta (Desktop Development Library for Ruby)](#glimmer-075-beta-desktop-development-library-for-ruby)
+- [Glimmer 0.8.2 Beta (Ruby Desktop Development GUI Library)](#glimmer-082-beta-ruby-desktop-development-gui-library)
   - [Examples](#examples)
     - [Hello, World!](#hello-world)
     - [Tic Tac Toe](#tic-tac-toe)
@@ -88,22 +88,55 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
     - [Basic Usage](#basic-usage)
     - [Advanced Usage](#advanced-usage)
     - [Scaffolding](#scaffolding)
+      - [App](#app)
+      - [Custom Shell](#custom-shell)
+      - [Custom Widget](#custom-widget)
+      - [Custom Shell Gem](#custom-shell-gem)
+      - [Custom Widget Gem](#custom-widget-gem)
   - [Girb (Glimmer irb) Command](#girb-glimmer-irb-command)
   - [Glimmer DSL Syntax](#glimmer-dsl-syntax)
     - [Widgets](#widgets)
+      - [Display](#display)
+      - [SWT Proxies](#swt-proxies)
+      - [Dialog](#dialog)
+      - [Menus](#menus)
     - [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)
     - [Widget Properties](#widget-properties)
+      - [Colors](#colors)
+      - [Fonts](#fonts)
     - [Layouts](#layouts)
     - [Layout Data](#layout-data)
     - [Data-Binding](#data-binding)
+      - [General Examples](#general-examples)
+      - [Combo](#combo)
+      - [List](#list)
+      - [Table](#table)
+      - [Tree](#tree)
     - [Observer](#observer)
+      - [Observing Widgets](#observing-widgets)
+      - [Observing Models](#observing-models)
     - [Custom Widgets](#custom-widgets)
+      - [Simple Example](#simple-example)
+      - [Hook Example](#hook-example)
+      - [Content/Options Example](#contentoptions-example)
+      - [Gotcha](#gotcha)
     - [Custom Shells](#custom-shells)
     - [Miscellaneous](#miscellaneous)
+      - [Application Menu Items (About/Preferences)](#application-menu-items-aboutpreferences)
+      - [App Name and Version](#app-name-and-version)
+      - [Multi-DSL Support](#multi-dsl-support)
+      - [Video Widget](#video-widget)
+      - [Browser Widget](#browser-widget)
   - [Glimmer Style Guide](#glimmer-style-guide)
   - [Samples](#samples)
     - [Hello Samples](#hello-samples)
     - [Elaborate Samples](#elaborate-samples)
+    - [External Samples](#external-samples)
+      - [Glimmer Calculator](#glimmer-calculator)
+      - [Gladiator](#gladiator)
   - [In Production](#in-production)
   - [SWT Reference](#swt-reference)
   - [SWT Packages](#swt-packages)
@@ -111,7 +144,8 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
   - [Raw JRuby Command](#raw-jruby-command)
     - [Mac Support](#mac-support)
   - [Packaging & Distribution](#packaging--distribution)
-    - [Defaults](#defaults)
+    - [Packaging Defaults](#packaging-defaults)
+    - [Packaging Configuration](#packaging-configuration)
     - [javapackager Extra Arguments](#javapackager-extra-arguments)
     - [Mac Application Distribution](#mac-application-distribution)
     - [Self Signed Certificate](#self-signed-certificate)
@@ -125,6 +159,7 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
   - [Contributing](#contributing)
   - [Contributors](#contributors)
   - [License](#license)
+
 ## Background
 
 Ruby is a dynamically-typed object-oriented language, which provides great productivity gains due to its powerful expressive syntax and dynamic nature. While it is proven by the Ruby on Rails framework for web development, it currently lacks a robust platform-independent framework for building desktop applications. Given that Java libraries can now be utilized in Ruby code through JRuby, Eclipse technologies, such as SWT, JFace, and RCP can help fill the gap of desktop application development with Ruby.
@@ -136,22 +171,22 @@ Glimmer runs on the following platforms:
 - Windows
 - Linux
 
-Glimmer's UI has the native look and feel of each operating system it runs on since it uses SWT behind the scenes, which leverages the following native libraries:
+Glimmer's GUI has the native look and feel of each operating system it runs on since it uses SWT behind the scenes, which leverages the following native libraries:
 - Win32 on Windows
 - Cocoa on Mac
 - GTK on Linux
 
-More info about the SWT UI on various platforms can be found on the Eclipse WIKI and SWT FAQ:
+More info about the SWT GUI on various platforms can be found on the Eclipse WIKI and SWT FAQ:
 
 https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
 https://www.eclipse.org/swt/faq.php
 
-
 ## Pre-requisites
 
 - SWT 4.15 (comes included in Glimmer gem)
-- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
-- Java SE Runtime Environment 7 or higher (find at https://www.oracle.com/java/technologies/javase-downloads.html)
+- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at [https://www.jruby.org/download](https://www.jruby.org/download))
+- JDK 8 - 10 (find at [https://www.oracle.com/java/technologies/javase-downloads.html](https://www.oracle.com/java/technologies/javase-downloads.html))
+- (Optional) RVM is needed for [Scaffolding](#scaffolding) only (find at [https://rvm.io/](https://rvm.io/))
 
 On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
 
@@ -169,7 +204,7 @@ Please follow these instructions to make the `glimmer` command available on your
 
 Run this command to install directly:
 ```
-jgem install glimmer -v 0.7.6
+jgem install glimmer -v 0.8.2
 ```
 
 `jgem` is JRuby's version of `gem` command. 
@@ -180,7 +215,7 @@ Otherwise, you may also run `jruby -S gem install ...`
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.7.6'
+gem 'glimmer', '~> 0.8.2'
 ```
 
 And, then run:
@@ -217,7 +252,7 @@ bin/glimmer samples/hello/hello_world.rb
 Below are the full usage instructions that come up when running `glimmer` without args.
 
 ```
-Usage: glimmer [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
+Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
 
 Runs Glimmer applications/tasks.
 
@@ -232,7 +267,7 @@ glimmer package:jar                                               # Generate JAR
 glimmer package:native                                            # Generate Native files (DMG/PKG/APP on the Mac)
 glimmer scaffold[app_name]                                        # Scaffold a Glimmer application directory structure to begin building a new app
 glimmer scaffold:custom_shell[custom_shell_name,namespace]        # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under app/views (namespace is optional)
-glimmer scaffold:custom_shell_gem[custom_widget_name,namespace]   # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under its own Ruby gem project (namespace is required)
+glimmer scaffold:custom_shell_gem[custom_shell_name,namespace]    # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under its own Ruby gem + app project (namespace is required)
 glimmer scaffold:custom_widget[custom_widget_name,namespace]      # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under app/views (namespace is optional)
 glimmer scaffold:custom_widget_gem[custom_widget_name,namespace]  # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under its own Ruby gem project (namespace is required)
 
@@ -242,8 +277,9 @@ automatically preloading the glimmer Ruby gem and SWT jar dependency.
 Optionally, extra Glimmer options, JRuby options and environment variables may be passed in.
 
 Glimmer options:
-- "--debug"           : Displays extra debugging information and passes "--debug" to JRuby
-- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is "WARN")
+- "--quiet"           : 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)
 
 Example: glimmer samples/hello_world.rb
 
@@ -275,7 +311,7 @@ getting you to a running and delivered state of an advanced "Hello, World!" Glim
 This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while 
 letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
 - Main application class that includes Glimmer
-- Main application view that houses main window content
+- Main application view that houses main window content, about dialog, and preferences dialog
 - View and Model directories
 - Rakefile including Glimmer tasks
 - Version
@@ -283,7 +319,7 @@ letting Glimmer scaffolding take care of initial app file structure concerns, su
 - Icon
 - Bin file for starting application
 
-NOTE: Scaffolding currently supports Mac packaging only at the moment. 
+NOTE: Scaffolding requires RVM and currently supports Mac packaging only at the moment. 
 
 #### App
 
@@ -341,9 +377,13 @@ glimmer scaffold:custom_widget[custom_widget_name]
 
 #### Custom Shell Gem
 
-Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
+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 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.
 
-To scaffold a Glimmer custom shell gem (full window view externalized into a gem) for an existing Glimmer app, run the following command:
+To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
 
 ```
 glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
@@ -351,15 +391,18 @@ glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
 
 It is important to specify a namespace to avoid having your gem clash with existing gems.
 
-The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell)
+The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
 
 Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. [glimmer-cs-gladiator](https://rubygems.org/gems/glimmer-cs-gladiator) Ruby gem)
 
-Example: [https://github.com/AndyObtiva/glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+Examples: 
+
+- [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
+- [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
 
 #### Custom Widget Gem
 
-To scaffold a Glimmer custom widget gem (part of a view externalized into a gem) for an existing Glimmer app, run the following command:
+To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
 
 ```
 glimmer scaffold:custom_widget_gem[custom_widget_name, namespace]
@@ -409,7 +452,7 @@ You will learn more about widgets next.
 
 ### Widgets
 
-Glimmer UIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
+Glimmer GUIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
 
 https://www.eclipse.org/swt/widgets/
 
@@ -518,7 +561,7 @@ shell {
 
 #### Display
 
-SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage UI globally 
+SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally 
 and access available monitors. 
 It is automatically instantiated upon first instantiation of a `shell` widget. 
 Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
@@ -546,7 +589,7 @@ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT o
 - `Glimmer::SWT:TabItemProxy` wraps `org.eclipse.swt.widget.TabItem` (also adds a composite to enable adding content under tab items directly in Glimmer)
 - `Glimmer::SWT:LayoutProxy` wraps all descendants of `org.eclipse.swt.widget.Layout`
 - `Glimmer::SWT:LayoutDataProxy` wraps all layout data objects
-- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying UI)
+- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying GUI)
 - `Glimmer::SWT:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
 - `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
 - `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
@@ -615,6 +658,12 @@ Shell widget proxy has extra methods specific to SWT Shell:
 - `#pack`: Packs contained widgets using SWT's `Shell#pack` method
 - `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
 
+#### Dialog
+
+Dialog is a variation on Shell. It is basically a shell that is modal (blocks what's behind it) and belongs to another shell. It only has a close button.
+
+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.
+
 #### Menus
 
 Glimmer DSL provides support for SWT Menu and MenuItem widgets.
@@ -1081,7 +1130,7 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
 
 Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
 
-#### General data-binding examples:
+#### General Examples
 
 `text bind(contact, :first_name)`
 
@@ -1252,7 +1301,62 @@ The Glimmer code is not much different from above except for passing the `:multi
 
 Note that in all the data-binding examples above, there was also an observer attached to the `button` widget to trigger an action on the model, which in turn triggers a data-binding update on the `list` or `combo`. Observers will be discussed in more details in the [next section](#observer).
 
-You may learn more about Glimmer's data-binding syntax by reading the [Eclipse Zone Tutorial](http://eclipse.dzone.com/articles/an-introduction-glimmer) mentioned in resources and opening up the samples under the [samples](samples) directory.
+You may learn more about Glimmer's data-binding syntax by reading the code under the [samples](samples) directory.
+
+#### Table
+
+The SWT Tree widget renders a multi-column data table, such as a contact listing or a sales report.
+
+To data-bind a Table, you need the main model, the collection property, and the text display attribute for each table column.
+
+This involves using the `bind` keyword mentioned above in addition to a special `column_properties` keyword that takes the table column text attribute methods.
+
+It assumes you have defined the table columns via `table_column` widget.
+
+Example:
+
+```ruby
+shell {      
+  @table = table {
+    table_column {
+      text "Name"
+      width 120
+    }
+    table_column {
+      text "Age"
+      width 120
+    }
+    table_column {
+      text "Adult"
+      width 120
+    }
+    items bind(group, :people), column_properties(:name, :age, :adult)
+    selection bind(group, :selected_person)
+  }
+}
+```
+
+The code above includes two data-bindings:
+- Table `items`, which first bind to the model collection property (group.people), and then maps each column property (name, age, adult) for displaying each table item column. 
+- Table `selection`, which binds the single table item selected by the user to the attribute denoted by the `bind` keyword (or binds multiple table items selected for a table with `:multi` SWT style)
+
+Additionally, Table `items` data-binding automatically stores each node model unto the SWT TableItem object via `setData` method. This enables things like searchability.
+
+The table widget in Glimmer is represented by a subclass of `WidgetProxy` called `TableProxy`.
+TableProxy includes a `search` method that takes a block to look for a table item.
+
+Example:
+
+```ruby
+found_array = @table.search { |table_item| table_item.getData == company.owner }
+```
+
+This finds a person. The array is a Java array. This enables easy passing of it to SWT `Table#setSelection` method, which expects a Java array of `TableItem` objects.
+
+To edit a table, you must invoke `TableProxy#edit_selected_table_item(column_index, before_write: nil, after_write: nil, after_cancel: nil)` or `TableProxy#edit_table_item(table_item, column_index, before_write: nil, after_write: nil, after_cancel: nil)`. 
+This automatically leverages the SWT TableEditor custom class behind the scenes, displaying a text widget to the user to change the selected or 
+passed table 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.
 
 #### Tree
 
@@ -1305,7 +1409,7 @@ Glimmer supports observing widgets with two main types of events:
 
 Additionally, there are two more types of events:
 - SWT `display` supports global listeners called filters that run on any widget. They are hooked via `on_event_{swt-event-constant}`
-- the `shell` widget supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
+- SWT `display` supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
 
 Number 1 is more commonly used in SWT applications, so make it your starting point. Number 2 covers events not found in number 1, so look into it if you don't find an SWT listener you need in number 1.
 
@@ -1405,7 +1509,7 @@ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 The shell declared above has been modified so that the minimize button works just like the close button. Once you minimize the shell (iconify it), it closes.
 
-The alternative syntax can be helpful if you prefer to separate Glimmer observer declarations from Glimmer UI declarations, or would like to add observers dynamically based on some logic later on.
+The alternative syntax can be helpful if you prefer to separate Glimmer observer declarations from Glimmer GUI declarations, or would like to add observers dynamically based on some logic later on.
 
 #### Observing Models
 
@@ -1468,7 +1572,9 @@ Glimmer supports creating custom widgets with minimal code, which automatically
 
 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 `__`)
 
-#### Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+#### Simple Example
+
+(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
 Definition:
 ```ruby
@@ -1494,7 +1600,9 @@ shell {
 
 As you can see, `RedLabel` became Glimmer DSL keyword: `red_label`
 
-#### Another Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+#### Hook Example
+
+(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
 Definition:
 ```ruby
@@ -1531,19 +1639,21 @@ Notice how `Red::Composite` became `red__composite` with double-underscore, whic
 
 Keep in mind that namespaces are not needed to be specified if the Custom Widget class has a unique name, not clashing with a basic SWT widget or another custom widget name.
 
-Custom Widgets have the following attributes (attribute readers) available to call from inside the `#body` method:
+Custom Widgets have the following attributes available to call from inside the `#body` method:
 - `#parent`: Glimmer object parenting custom widget
 - `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
-- `#options`: a hash of options passed in parentheses when declaring a custom widget (useful for passing in model data) (e.g. `calendar(events: events)`). Custom widget class can declare option names (array) with `.options` method as shown below, which generates attribute readers for every option (not to be confused with `#options` instance method for retrieving options hash containing names & values)
+- `#options`: a hash of options passed in parentheses when declaring a custom widget (useful for passing in model data) (e.g. `calendar(events: events)`). Custom widget class can declare option names (array) with `::options` class method as shown below, which generates attribute accessors for every option (not to be confused with `#options` instance method for retrieving options hash containing names & values)
 - `#content`: nested block underneath custom widget. It will be automatically called at the end of processing the custom widget body. Alternatively, the custom widget body may call `content.call` at the place where the content is needed to show up as shown in the following example.
 - `#body_root`: top-most (root) widget returned from `#body` method.
 - `#swt_widget`: actual SWT widget for `body_root`
 
 Additionally, custom widgets can call the following class methods:
-- `.options`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute readers (e.g. `options :orientation, :bg_color` generates `#orientation` and `#bg_color` attribute readers)
-- `.option`: declares a single option taking option name and default value as arguments (also generates an attribute reader just like `.options`)
+- `::options(*option_names)`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute accessors (e.g. `options :orientation, :bg_color` generates `#orientation`, `#orientation=(v)`, `#bg_color`, and `#bg_color=(v)` attribute accessors)
+- `::option(option_name, default: nil)`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `::options`)
 
-#### Content/Options Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+#### Content/Options Example 
+
+(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
 Definition:
 ```ruby
@@ -1551,7 +1661,7 @@ class Sandwich
   include Glimmer::UI::CustomWidget
 
   options :orientation, :bg_color
-  option :fg_color, :black
+  option :fg_color, default: :black
 
   body {
     composite(swt_style) { # gets custom widget style
@@ -1686,52 +1796,61 @@ shell { |app_shell|
 
 #### Application Menu Items (About/Preferences)
 
-Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `shell` widget:
+Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `display`:
 - `on_about`: executes code when user selects App Name -> About
 - `on_preferences`: executes code when user selects App Name -> Preferences or hits 'CMD+,' on the Mac
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
-shell { |shell_proxy|
-  text 'Application Menu Items'
-  fill_layout {
-    margin_width 15
-    margin_height 15
-  }
-  label {
-    text 'Application Menu Items'
-    font height: 30
-  }
-  on_about {
-    message_box = MessageBox.new(shell_proxy.swt_widget)
-    message_box.setText("About")
-    message_box.setMessage("About Application")
-    message_box.open
-  }
-  on_preferences {
-    preferences_dialog = shell(:dialog_trim, :application_modal) {
-      text 'Preferences'
-      row_layout {
-        type :vertical
-        margin_left 15
-        margin_top 15
-        margin_right 15
-        margin_bottom 15
+class Example
+  def initialize
+    display {
+      on_about {
+        message_box = MessageBox.new(@shell_proxy.swt_widget)
+        message_box.setText("About")
+        message_box.setMessage("About Application")
+        message_box.open
       }
-      label {
-        text 'Check one of these options:'
+      on_preferences {
+        preferences_dialog = dialog {
+          text 'Preferences'
+          row_layout {
+            type :vertical
+            margin_left 15
+            margin_top 15
+            margin_right 15
+            margin_bottom 15
+          }
+          label {
+            text 'Check one of these options:'
+          }
+          button(:radio) {
+            text 'Option 1'
+          }
+          button(:radio) {
+            text 'Option 2'
+          }
+        }
+        preferences_dialog.open
       }
-      button(:radio) {
-        text 'Option 1'
+    }
+    @shell_proxy = shell {
+      text 'Application Menu Items'
+      fill_layout {
+        margin_width 15
+        margin_height 15
       }
-      button(:radio) {
-        text 'Option 2'
+      label {
+        text 'Application Menu Items'
+        font height: 30
       }
     }
-    preferences_dialog.open
-  }
-}.open
+    @shell_proxy.open
+  end
+end
+
+Example.new
 ```
 
 #### App Name and Version
@@ -1939,7 +2058,7 @@ This relies on Glimmer's [Multi-DSL Support](https://github.com/AndyObtiva/glimm
 - Widget property declarations always have arguments and never take a block
 - Widget property arguments are never wrapped inside parentheses
 - Widget listeners are always declared starting with `on_` prefix and affixing listener event method name afterwards in underscored lowercase form
-- Widget listeners are always followed by a block using curly braces (Only when declared in DSL. When invoked on widget object directly outside of UI declarations, standard Ruby conventions apply)
+- Widget listeners are always followed by a block using curly braces (Only when declared in DSL. When invoked on widget object directly outside of GUI declarations, standard Ruby conventions apply)
 - Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
 - Custom widget body, before_body, and after_body blocks open their blocks and close them with curly braces.
 - Custom widgets receive additional arguments to SWT style called options. These are passed as the last argument inside the parentheses, a hash of option names pointing to values.
@@ -1973,12 +2092,22 @@ glimmer samples/hello/hello_computed.rb # demonstrates computed data-binding
 For more elaborate samples, check the following:
 
 ```
-glimmer samples/elaborate/login.rb # demonstrates general data-binding
+glimmer samples/elaborate/login.rb # demonstrates basic data-binding
 glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
 glimmer samples/elaborate/tic_tac_toe.rb # demonstrates a full MVC application
 ```
 
-![Gladiator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/v0.1.5/images/glimmer-gladiator.png)
+### External Samples
+
+#### Glimmer Calculator
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/v1.0.0/glimmer-cs-calculator-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-calculator)
+
+[Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) is a basic calculator sample project demonstrating data-binding and TDD (test-driven-development) with Glimmer following the MVP pattern (Model-View-Presenter).
+
+#### Gladiator
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/v0.1.5/images/glimmer-gladiator.png" />](https://github.com/AndyObtiva/glimmer-cs-gladiator)
 
 [Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator) (short for Glimmer Editor) is a Glimmer sample project under on-going development.
 You may check it out to learn how to build a Glimmer Custom Shell gem.
@@ -2107,33 +2236,20 @@ Glimmer apps may be packaged and distributed on the Mac, Windows, and Linux via
 - Warbler (https://github.com/jruby/warbler): Enables bundling a Glimmer app into a JAR file
 - javapackager (https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html): Enables packaging a JAR file as a DMG file on Mac, EXE on Windows, and multiple Linux supported formats on Linux.
 
-Glimmer simplifies the process for Mac packaging by providing a rake task.
-
-To use:
-- Create `Rakefile` in your app root directory
-- Add the following line to it: `require 'glimmer/rake_task'`
-- Create a Ruby script under bin (e.g. `bin/math_bowling`) to require the application file that uses Glimmer (e.g. `'../app/my_application.rb'`):
-```ruby
-require_relative '../app/my_application.rb'
-```
-- Include Icon (Optional): If you'd like to include an icon for your app (.icns format on the Mac), place it under `package/macosx` matching the humanized application local directory name (e.g. 'Math Bowling.icns' [containing space] for MathBowling or math_bowling). You may generate your Mac icon easily using tools like Image2Icon (http://www.img2icnsapp.com/) or manually using the Mac terminal command `iconutil` (iconutil guide: https://applehelpwriter.com/tag/iconutil/)
-- 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).
+Glimmer simplifies the process of Mac packaging via the `glimmer package` command. It works out of the box for any application generated by [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer/blob/master/README.md#scaffolding):
 
-Now, you can run the following rake command to package your app into a Mac DMG file (using both Warbler and javapackager):
 ```
-rake glimmer:package
+glimmer package
 ```
 
-This will generate a JAR file under `./dist` directory, which is then used to generate a DMG file (and pkg/app) under `./packages/bundles`. 
+This will automatically generate a JAR file under `./dist` directory using Warbler, which is then used to automatically generate a DMG file (and pkg/app) under `./packages/bundles` using `javapackager`. 
 JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
 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 rake task will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}". 
+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")
 
-### Defaults
+### Packaging Defaults
 
 Glimmer employs smart defaults in packaging.
 
@@ -2141,13 +2257,24 @@ The package application name (shows up in top menu bar on the Mac) will be a hum
 
 Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
 
-After running once, you will find a `config/warble.rb` file. It has the JAR packaging configuration. You may adjust included directories in it if needed, and then rerun `rake glimmer:package` and it will pick up your custom configuration. Alternatively, if you'd like to customize the included directories to begin with, don't run `rake glimmer:package` right away. Run this command first:
+After running once, you will find a `config/warble.rb` file. It has the JAR packaging configuration. You may adjust included directories in it if needed, and then rerun `glimmer package` and it will pick up your custom configuration. Alternatively, if you'd like to customize the included directories to begin with, don't run `glimmer package` right away. Run this command first:
 
 ```
-rake glimmer:package:config
+glimmer package:config
 ```
 
-This will generate `config/warble.rb`, which you may configure and then run `rake glimmer:package` afterwards.
+This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
+
+### Packaging Configuration
+
+- Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
+```ruby
+require_relative '../app/my_application.rb'
+```
+- Include Icon (Optional): If you'd like to include an icon for your app (.icns format on the Mac), place it under `package/macosx` matching the humanized application local directory name (e.g. 'Math Bowling.icns' [containing space] for MathBowling or math_bowling). You may generate your Mac icon easily using tools like Image2Icon (http://www.img2icnsapp.com/) or manually using the Mac terminal command `iconutil` (iconutil guide: https://applehelpwriter.com/tag/iconutil/)
+- 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).
 
 ### javapackager Extra Arguments
 
@@ -2165,6 +2292,8 @@ The Glimmer rake task allows passing extra options to javapackager via:
 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"'
 ```
 
@@ -2175,7 +2304,7 @@ https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMac
 Example (env var):
 
 ```
-JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' rake glimmer:package
+JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
 ```
 
 That overrides the default application display name.
@@ -2220,7 +2349,7 @@ Example:
 Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
 ```
 
-Now, when you run `rake 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.
+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.
 
 ### Gotchas
 
@@ -2237,7 +2366,7 @@ Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="
 
 2. Mounted DMG Residue
 
-If you run `rake glimmer:package` multiple times, sometimes it leaves a mounted DMG project in your finder. Unmount before you run the command again or it might fail with an error saying: "Error: Bundler "DMG Installer" (dmg) failed to produce a bundle."
+If you run `glimmer package` multiple times, sometimes it leaves a mounted DMG project in your finder. Unmount before you run the command again or it might fail with an error saying: "Error: Bundler "DMG Installer" (dmg) failed to produce a bundle."
 
 By the way, keep in mind that during normal operation, it does also indicate a false-negative while completing successfully similar to the following (please ignore): 
 
@@ -2248,10 +2377,11 @@ Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1
 ## Resources
 
 * [Code Master Blog](http://andymaleh.blogspot.com/search/label/Glimmer)
-* [Eclipse Zone Tutorial](http://eclipse.dzone.com/articles/an-introduction-glimmer)
-* [InfoQ Article](http://www.infoq.com/news/2008/02/glimmer-jruby-swt)
-* [RubyConf 2008 Video](https://confreaks.tv/videos/rubyconf2008-desktop-development-with-glimmer)
 * [JRuby Cookbook by Justin Edelson & Henry Liu](http://shop.oreilly.com/product/9780596519650.do)
+* [MountainWest RubyConf 2011 Video](https://confreaks.tv/videos/mwrc2011-whatever-happened-to-desktop-development-in-ruby)
+* [RubyConf 2008 Video](https://confreaks.tv/videos/rubyconf2008-desktop-development-with-glimmer)
+* [InfoQ Article](http://www.infoq.com/news/2008/02/glimmer-jruby-swt)
+* [DZone Tutorial](https://dzone.com/articles/an-introduction-glimmer)
 
 ## Help
 
@@ -2283,8 +2413,10 @@ These features have been suggested. You might see them in a future version of Gl
 
 ## Contributors
 
-* Andy Maleh (Founder)
-* Dennis Theisen
+* [Andy Maleh](https://github.com/AndyObtiva) (Founder)
+* [Dennis Theisen](https://github.com/Soleone) (Contributor)
+
+[Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer/graphs/contributors)
 
 ## License