glimmer 0.8.1 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c6aff23e9890326138ca130e2e7bb80d2ff62d9586d3ff9e62cfcb97dab0c18
-  data.tar.gz: '038211b85b37a102b05006b5961ec60ad20c62eca31bd15f833065170d9b6b20'
+  metadata.gz: 6255c2aed0be3512fb9e8e1892232ee9f8ad35efb308ea2dc814f5ff86e69265
+  data.tar.gz: 1c6a024b3ddfed3e296644ec54ce57f38816feb2656a05f2c6daf557cde22b16
 SHA512:
-  metadata.gz: 7fea559224aa5069c03dfebdcbd4981ed7c6296d171098077164019e9c3fa8fd053fcfe0fcaf7161b03d0ad3a1dbda0af4c719629fd55a9af9868760a9b398e4
-  data.tar.gz: 2abec0e6d750fc5ed6417ea79c18aa102c8d2d75ee3c253a2ecec1f0e01c22793e03dc7ff25b10a99c4b81d1a907712e7f558e85158ffa675bcfe24928ec7ff7
+  metadata.gz: f39bf5895a97510fe0e40b463b0e77224b7ff09bd695686cf1f38fecdf0e01c1ff86a23ab25a4dbcc3b297906b905be1ad6eb5e8e9fb3fe8e985b39fbda0f80e
+  data.tar.gz: 44068213c246dacc1763868175aba950a9bf78dc803dcb4b0269d3dd9b1ad76c9efd373cb35977b60d7bfcfbe03e8bd07b46ac32595cb89a796e6c9444ff6b0e

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Andy Maleh
+Copyright (c) 2011-2020 Andy Maleh
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,14 +1,23 @@
-# Glimmer 0.8.1 Beta (Ruby Desktop Development GUI Library)
+# <img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 /> Glimmer (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)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/38fbc278022862794414/test_coverage)](https://codeclimate.com/github/AndyObtiva/glimmer/test_coverage)
-[![Maintainability](https://api.codeclimate.com/v1/badges/38fbc278022862794414/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer/maintainability)
+[![Travis CI](https://travis-ci.com/AndyObtiva/glimmer.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer) 
+[![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+**[Contributors Wanted!](#contributing)**
+
+(The Original Glimmer Library Since 2007. Beware of Imitators!)
 
 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)
 
+Glimmer DSL gems:
+- [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
+- [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
+- [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
+- [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
+
 ## Examples
 
 ### Hello, World!
@@ -69,13 +78,13 @@ glimmer samples/elaborate/tic_tac_toe.rb
 
 Glimmer app:
 
-![Tic Tac Toe](images/glimmer-tic-tac-toe.png)
+![Tic Tac Toe](images/glimmer-tic-tac-toe-in-progress.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
 
-- [Glimmer 0.8.1 Beta (Ruby Desktop Development GUI Library)](#glimmer-081-beta-ruby-desktop-development-gui-library)
+- [Glimmer - Ruby Desktop Development GUI Library](#-glimmer---ruby-desktop-development-gui-library)
   - [Examples](#examples)
     - [Hello, World!](#hello-world)
     - [Tic Tac Toe](#tic-tac-toe)
@@ -89,23 +98,57 @@ 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)
+      - [Lifecycle Hook Example](#lifecycle-hook-example)
+      - [Custom Widget API](#custom-widget-api)
+      - [Content/Options Example](#contentoptions-example)
+      - [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
+      - [Gotcha](#gotcha)
     - [Custom Shells](#custom-shells)
     - [Miscellaneous](#miscellaneous)
+      - [Multi-DSL Support](#multi-dsl-support)
+      - [Application Menu Items (About/Preferences)](#application-menu-items-aboutpreferences)
+      - [App Name and Version](#app-name-and-version)
+      - [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)
@@ -122,7 +165,7 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
   - [Resources](#resources)
   - [Help](#help)
     - [Issues](#issues)
-    - [IRC Channel](#irc-channel)
+    - [Chat](#chat)
   - [Feature Suggestions](#feature-suggestions)
   - [Change Log](#change-log)
   - [Contributing](#contributing)
@@ -154,7 +197,7 @@ https://www.eclipse.org/swt/faq.php
 
 - 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](https://www.jruby.org/download))
-- Java SE Runtime Environment 7 or higher (find at [https://www.oracle.com/java/technologies/javase-downloads.html](https://www.oracle.com/java/technologies/javase-downloads.html))
+- 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:
@@ -167,13 +210,13 @@ Glimmer might still work on lower versions of Java, JRuby and SWT, but there are
 
 ## Setup
 
-Please follow these instructions to make the `glimmer` command available on your system.
+Please follow these instructions to make the `glimmer` command available on your system via the [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem.
 
 ### Option 1: Direct Install
 
 Run this command to install directly:
 ```
-jgem install glimmer -v 0.8.1
+jgem install glimmer-dsl-swt -v 0.1.3
 ```
 
 `jgem` is JRuby's version of `gem` command. 
@@ -184,7 +227,7 @@ Otherwise, you may also run `jruby -S gem install ...`
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.8.1'
+gem 'glimmer-dsl-swt', '~> 0.1.3'
 ```
 
 And, then run:
@@ -192,6 +235,8 @@ And, then run:
 jruby -S bundle install
 ```
 
+You may learn more about other Glimmer related gems ([`glimmer-dsl-opal`](https://github.com/AndyObtiva/glimmer-dsl-opal), [`glimmer-dsl-xml`](https://github.com/AndyObtiva/glimmer-dsl-xml), and [`glimmer-dsl-css`](https://github.com/AndyObtiva/glimmer-dsl-css)) at [Multi-DSL Support](#multi-dsl-support)
+
 ## Glimmer Command
 
 ### Basic Usage
@@ -387,13 +432,13 @@ Example: [https://github.com/AndyObtiva/glimmer-cw-video](https://github.com/And
 
 ## Girb (Glimmer irb) Command
 
-With Glimmer installed, you may want to run `girb` instead of standard `irb` to have SWT preloaded and the Glimmer library required and included for quick Glimmer coding/testing.
+With `glimmer-dsl-swt` installed, you may want to run `girb` instead of standard `irb` to have SWT preloaded and the Glimmer library required and included for quick Glimmer coding/testing.
 
 ```
 girb
 ```
 
-If you cloned this project locally, you may run `bin/girb` instead.
+If you cloned [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) project locally, you may run `bin/girb` instead.
 
 ```
 bin/girb
@@ -401,6 +446,8 @@ bin/girb
 
 Watch out for hands-on examples in this README indicated by "you may copy/paste in [`girb`](#girb-glimmer-irb-command)"
 
+Keep in mind that all samples live under [https://github.com/AndyObtiva/glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt)
+
 ## Glimmer DSL Syntax
 
 Glimmer DSL syntax consists of static keywords and dynamic keywords to build and bind user-interface objects.
@@ -504,22 +551,22 @@ Check out the [samples](samples) directory for more examples.
 
 Example from [hello_tab.rb](samples/hello/hello_tab.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
-![Hello Tab 1](images/glimmer-hello-tab1.png)
+![Hello Tab English](images/glimmer-hello-tab-english.png)
 
-![Hello Tab 2](images/glimmer-hello-tab2.png)
+![Hello Tab French](images/glimmer-hello-tab-french.png)
 
 ```ruby
 shell {
-  text "SWT"
+  text "Hello, Tab!"
   tab_folder {
     tab_item {
-      text "Tab 1"
+      text "English"
       label {
         text "Hello, World!"
       }
     }
     tab_item {
-      text "Tab 2"
+      text "French"
       label {
         text "Bonjour Univers!"
       }
@@ -956,6 +1003,9 @@ composite {
 ```
 
 Here is a more sophisticated example taken from [hello_computed.rb](samples/hello/hello_computed.rb) sample:
+
+![Hello Computed](images/glimmer-hello-computed.png)
+
 ```ruby
 shell {
   text "Hello Computed"
@@ -1099,7 +1149,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)`
 
@@ -1270,7 +1320,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
 
@@ -1486,7 +1591,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
@@ -1512,7 +1619,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)):
+#### Lifecycle Hook Example
+
+(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
 
 Definition:
 ```ruby
@@ -1545,10 +1654,12 @@ shell {
 }.open
 ```
 
-Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention. Additionally, `before_body` hook was utilized to set a `@color` variable and use inside the `body`.
+Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention. Additionally, the `before_body` lifecycle hook was utilized to set a `@color` variable and use inside the `body`.
 
 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 Widget API
+
 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
@@ -1561,7 +1672,9 @@ Additionally, custom widgets can call the following class methods:
 - `::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
@@ -1601,7 +1714,9 @@ 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'`
 
-Last but not least, these are the available hooks:
+#### 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.
 
@@ -1702,92 +1817,19 @@ shell { |app_shell|
 
 ### Miscellaneous
 
-#### Application Menu Items (About/Preferences)
-
-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
-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
-      }
-      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
-      }
-    }
-    @shell_proxy = shell {
-      text 'Application Menu Items'
-      fill_layout {
-        margin_width 15
-        margin_height 15
-      }
-      label {
-        text 'Application Menu Items'
-        font height: 30
-      }
-    }
-    @shell_proxy.open
-  end
-end
-
-Example.new
-```
-
-#### App Name and Version
-
-Application name (shows up on the Mac in top menu bar) and version may be specified upon [packaging](#packaging--distribution) by specifying "-Bmac.CFBundleName" and "-Bmac.CFBundleVersion" options.
-
-Still, if you would like proper application name to show up on the Mac top menu bar during development, you may do so by invoking the SWT Display.setAppName method before any Display object has been instantiated (i.e. before any Glimmer widget like shell has been declared).
-
-Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
-
-```ruby
-Display.setAppName('Glimmer Demo')
-
-shell(:no_resize) {
-  text "Glimmer"
-  label {
-    text "Hello, World!"
-  }
-}.open
-```
+#### Multi-DSL Support
 
-Also, you may invoke `Display.setAppVersion('1.0.0')` if needed for OS app version identification reasons during development, replacing `'1.0.0'` with your application version.
+Glimmer is a DSL engine that supports multiple DSLs (Domain Specific Languages):
+- [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
+- [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
+- [XML](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML) - Useful with [SWT Browser Widget](#browser-widget)
+- [CSS](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets) - Useful with [SWT Browser Widget](#browser-widget)
 
-#### Multi-DSL Support
+Glimmer automatically recognizes top-level keywords in each DSL and activates DSL accordingly. Glimmer allows mixing DSLs, which comes in handy when doing things like using the SWT Browser widget with XML and CSS. Once done processing a nested DSL top-level keyword, Glimmer switches back to the prior DSL automatically.
 
-Glimmer supports two other DSLs in addition to the SWT DSL; that is Glimmer XML DSL and Glimmer CSS DSL. It also allows mixing DSLs, which comes in handy when doing things like using the `browser` widget. Glimmer automatically recognizes top-level keywords in each DSL
-and switches DSLs accordingly. Once done processing a top-level keyword, it switches back to the prior DSL automatically.
+##### SWT
 
-For example, the SWT DSL has the following top-level keywords:
+The SWT DSL was already covered in detail. However, for the sake of mixing DSLs, you need to know that the SWT DSL has the following top-level keywords:
 - `shell`
 - `display`
 - `color`
@@ -1795,7 +1837,13 @@ For example, the SWT DSL has the following top-level keywords:
 - `async_exec`
 - `sync_exec`
 
-##### XML DSL
+##### Opal
+
+Full instructions are found in the [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) DSL page.
+
+The [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) DSL is simply a web GUI adapter for desktop apps written in Glimmer. As such, it supports all the DSL keywords of the SWT DSL and shares the same top-level keywords.
+
+##### XML
 
 Simply start with `html` keyword and add HTML inside its block using Glimmer DSL syntax.
 Once done, you may call `to_s`, `to_xml`, or `to_html` to get the formatted HTML output.
@@ -1873,8 +1921,7 @@ Output:
 <DOCUMENT><document:body document:id="main"></document:body></DOCUMENT>
 ```
 
-
-##### CSS DSL
+##### CSS
 
 Simply start with `css` keyword and add stylesheet rule sets inside its block using Glimmer DSL syntax.
 Once done, you may call `to_s` or `to_css` to get the formatted CSS output.
@@ -1910,6 +1957,86 @@ Glimmer provides a number of methods on Glimmer::DSL::Engine to configure DSL su
 - `Glimmer::DSL::Engine.enable_dsl(dsl_name)`: Re-enables disabled DSL
 - `Glimmer::DSL::Engine.enabled_dsls=(dsl_names)`: Disables all DSLs except the ones specified.
 
+#### Application Menu Items (About/Preferences)
+
+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
+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
+      }
+      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
+      }
+    }
+    @shell_proxy = shell {
+      text 'Application Menu Items'
+      fill_layout {
+        margin_width 15
+        margin_height 15
+      }
+      label {
+        text 'Application Menu Items'
+        font height: 30
+      }
+    }
+    @shell_proxy.open
+  end
+end
+
+Example.new
+```
+
+#### App Name and Version
+
+Application name (shows up on the Mac in top menu bar) and version may be specified upon [packaging](#packaging--distribution) by specifying "-Bmac.CFBundleName" and "-Bmac.CFBundleVersion" options.
+
+Still, if you would like proper application name to show up on the Mac top menu bar during development, you may do so by invoking the SWT Display.setAppName method before any Display object has been instantiated (i.e. before any Glimmer widget like shell has been declared).
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+Display.setAppName('Glimmer Demo')
+
+shell(:no_resize) {
+  text "Glimmer"
+  label {
+    text "Hello, World!"
+  }
+}.open
+```
+
+Also, you may invoke `Display.setAppVersion('1.0.0')` if needed for OS app version identification reasons during development, replacing `'1.0.0'` with your application version.
+
 #### Video Widget
 
 ![Video Widget](images/glimmer-video-widget.png)
@@ -1920,6 +2047,8 @@ You may obtain via `glimmer-cw-video` gem.
 
 #### Browser Widget
 
+![Hello Browser](images/glimmer-hello-browser.png)
+
 Glimmer supports SWT Browser widget, which can load URLs or render HTML. It can even be instrumented with JavaScript when needed (though highly discouraged in Glimmer except for rare cases when leveraging a pre-existing web codebase in a desktop app).
 
 Example loading a URL (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
@@ -1933,7 +2062,7 @@ shell {
 }.open
 ```
 
-Example rendering HTML with JavaScript on document ready (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+Example rendering HTML with JavaScript on document ready (you may copy/paste in [`girb`](#girb-glimmer-irb-command) provided you install and require [glimmer-dsl-xml gem](https://github.com/AndyObtiva/glimmer-dsl-xml)):
 
 ```ruby
 shell {
@@ -1954,7 +2083,7 @@ shell {
 }.open
 ```
 
-This relies on Glimmer's [Multi-DSL Support](https://github.com/AndyObtiva/glimmer/tree/development#multi-dsl-support) for building the HTML text using Glimmer XML DSL.
+This relies on Glimmer's [Multi-DSL Support](#multi-dsl-support) for building the HTML text using [Glimmer XML DSL](https://github.com/AndyObtiva/glimmer-dsl-xml).
 
 ## Glimmer Style Guide
 
@@ -1973,9 +2102,9 @@ This relies on Glimmer's [Multi-DSL Support](https://github.com/AndyObtiva/glimm
 
 ## Samples
 
-Check the [samples](samples) directory 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`).
+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`).
 
-If you cloned the project and followed [CONTRIBUTING.md](CONTRIBUTING.md) instructions, you may run all samples at once via `samples/launch` command:
+If you cloned the project and followed [CONTRIBUTING.md](CONTRIBUTING.md) instructions, you may run all samples in [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) at once via `samples/launch` command:
 
 ```
 samples/launch
@@ -1999,33 +2128,85 @@ glimmer samples/hello/hello_computed.rb # demonstrates computed data-binding
 
 For more elaborate samples, check the following:
 
+#### Login
+
 ```
 glimmer samples/elaborate/login.rb # demonstrates basic data-binding
-glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
+```
+
+![Login](images/glimmer-login.png)
+![Login Filled In](images/glimmer-login-filled-in.png)
+![Login Logged In](images/glimmer-login-logged-in.png)
+
+#### Tic Tac Toe
+
+```
 glimmer samples/elaborate/tic_tac_toe.rb # demonstrates a full MVC application
 ```
 
+![Tic Tac Toe](images/glimmer-tic-tac-toe.png)
+![Tic Tac Toe In Progress](images/glimmer-tic-tac-toe-in-progress.png)
+![Tic Tac Toe Game Over](images/glimmer-tic-tac-toe-game-over.png)
+
+#### Contact Manager
+
+```
+glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
+```
+
+Contact Manager
+
+![Contact Manager](images/glimmer-contact-manager.png)
+
+Contact Manager - Find
+
+![Contact Manager](images/glimmer-contact-manager-find.png)
+
+Contact Manager - Edit Started
+
+![Contact Manager](images/glimmer-contact-manager-edit-started.png)
+
+Contact Manager - Edit In Progress
+
+![Contact Manager](images/glimmer-contact-manager-edit-in-progress.png)
+
+Contact Manager - Edit Done
+
+![Contact Manager](images/glimmer-contact-manager-edit-done.png)
+
 ### External Samples
 
-#### [Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator)
+#### Glimmer Calculator
 
-![Glimmer Calculator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/v1.0.0/glimmer-cs-calculator-screenshot.png)
+[<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](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+#### Gladiator
 
-![Gladiator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/v0.1.5/images/glimmer-gladiator.png)
+[<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.
 
+Gladiator is a good demonstration of:
+- MVP Pattern
+- Tree data-binding
+- List data-binding
+- Text selection data-binding
+- Tabs
+- Context menus
+- Custom Shell
+- Custom widget
+
 ## In Production
 
 The following production apps have been built with Glimmer:
 
 [<img alt="Math Bowling Logo" src="https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/images/math-bowling-logo.png" width="40" />Math Bowling](https://github.com/AndyObtiva/MathBowling): an educational math game for elementary level kids
 
+If you have a Glimmer app you would like referenced here, please mention in a Pull Request. 
+
 ## SWT Reference
 
 https://www.eclipse.org/swt/docs.php
@@ -2086,6 +2267,14 @@ You can learn more about importing Java packages into Ruby code at this JRuby WI
 
 https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
 
+## Infinite Loop Detection
+
+Glimmer can detect if an infinite loop occurs with method_missing by ensuring it does not loop with the same keyword and args more than 100 times.
+
+The max limit can be changed via the `Glimmer::Config::loop_max_count=(count)` method.
+
+Infinite loop detection may be disabled by setting `Glimmer::Config::loop_max_count` to `-1`
+
 ## Logging
 
 Glimmer comes with a Ruby Logger accessible via `Glimmer::Config.logger`
@@ -2200,6 +2389,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"'
 ```
 
@@ -2283,10 +2474,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
 
@@ -2296,16 +2488,18 @@ You may submit [issues](https://github.com/AndyObtiva/glimmer/issues) on [GitHub
 
 [Click here to submit an issue.](https://github.com/AndyObtiva/glimmer/issues)
 
-### IRC Channel
-
-If you need live help, try the [#glimmer](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer) IRC channel on [irc.mibbit.net](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer). If no one was available, you may [leave a GitHub issue](https://github.com/AndyObtiva/glimmer/issues) to schedule a meetup on IRC. 
+### Chat
 
-[Click here to connect to #glimmer IRC channel immediately via a web interface.](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer)
+If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 
 
 ## Feature Suggestions
 
 These features have been suggested. You might see them in a future version of Glimmer. You are welcome to contribute more feature suggestions.
 
+[glimmer-dsl-swt/TODO.md](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/TODO.md)
+
+Glimmer DSL Engine specific tasks are at:
+
 [TODO.md](TODO.md)
 
 ## Change Log
@@ -2314,6 +2508,10 @@ These features have been suggested. You might see them in a future version of Gl
 
 ## Contributing
 
+**Contributors Wanted!**
+
+If you would like to contribute to Glimmer, please study up on Glimmer and [SWT](#swt-reference), run all Glimmer [samples](#samples), and build a small sample app to add to [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) Hello or Elaborate samples via a Pull Request. Once done, contact me on [Chat](#chat).
+
 [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## Contributors
@@ -2327,3 +2525,5 @@ These features have been suggested. You might see them in a future version of Gl
 
 Copyright (c) 2007-2020 Andy Maleh.
 See LICENSE.txt for further details.
+
+Glimmer logo was made by <a href="https://www.flaticon.com/authors/freepik" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon"> www.flaticon.com</a>