glimmer 0.4.9 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 218ad434685b90c53d096b5ebc117c4eb790f5e724f8bd59d91ea3cc57683b74
-  data.tar.gz: a4568fdf1521441848af186a804c54c6ac6c3d29ba6ccabb3c1726630d9067d1
+  metadata.gz: 3a01513e043e5d19086d90cb571aa4043235a2753b3164413e680591073f6644
+  data.tar.gz: 56949c7c670c1864804e5ed28d33f7efddcdca7b0b50d465011b149ca7585969
 SHA512:
-  metadata.gz: f0f19afe707d602e34a8c47708b40660fb149061a56e00bf3404d100ee12aab2ac9baaaad8a6fd6247a91fafc818d154848feaab1d14b3fab10c1f0d55a4999c
-  data.tar.gz: 6f5b8ce1b0562fbef375699f919fbd5cfe3cf746c64f2ef55e4cc50162bfcc4ac33f0d520ec0e8192644ae43e2efaf9fd3155504a1d3140e6dce0b708f2964d6
+  metadata.gz: dce0753c615d6c148d7065741463dc3eb95fa3bd437082c757be5ec8569ae812af8ef993fa726a43cdda99e32b748f4201b709c46b10666f78866f27317809f7
+  data.tar.gz: 3a764178e11e57d1b8ac15b5089decdc4933846b3392b0e7904511114c2dab1ae0635f77ac6be644e3151723350caee7f248bc9c19ce36c018879deb302a7a38

data/README.markdown

@@ -1,7 +1,7 @@
-# Glimmer 0.4.9 Beta (JRuby Desktop UI DSL + Data-Binding)
+# Glimmer 0.5.0 Beta (JRuby Desktop UI DSL + Data-Binding)
 [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer?branch=master)
 
-Glimmer is a cross-platform Ruby desktop development library. Glimmer's main innovation is a JRuby DSL that enables easy and efficient authoring of desktop application user-interfaces while relying on the robust platform-independent Eclipse SWT library. Glimmer additionally innovates by having built-in desktop UI 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 components test-first afterward.
+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 platform-native 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 components test-first afterwards.
 
 ## Examples
 
@@ -14,7 +14,7 @@ include Glimmer
 shell {
   text "Glimmer"
   label {
-    text "Hello World!"
+    text "Hello, World!"
   }
 }.open
 ```
@@ -78,27 +78,31 @@ Glimmer runs on the following platforms:
 - Windows
 - Linux
 
-SWT uses Win32 on Windows, Cocoa on Mac, and GTK on Linux according to Eclipse WIKI:
-
-https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
+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:
+- Win32 on Windows
+- Cocoa on Mac
+- GTK on Linux
 
-The SWT FAQ has further details:
+More info about the SWT UI 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
 
 * Java SE Runtime Environment 7 or higher (find at https://www.oracle.com/java/technologies/javase-downloads.html)
-* JRuby 9.2.10.0 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
-* SWT 4.14 (comes included in Glimmer)
+* JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
+* SWT 4.15 (comes included in Glimmer gem)
 
 On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
 
 ```bash
-rvm install jruby-9.2.10.0
+rvm install jruby-9.2.11.1
 ```
 
+Glimmer might still work on lower versions of Java, JRuby and SWT, but there are no guarantees, so it is best to stick to the pre-requisites outlined above.
+
 ## Setup
 
 Please follow these instructions to make the `glimmer` command available on your system.
@@ -107,14 +111,14 @@ Please follow these instructions to make the `glimmer` command available on your
 
 Run this command to install directly:
 ```
-jgem install glimmer -v 0.4.9
+jgem install glimmer -v 0.5.0
 ```
 
 ### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.4.9'
+gem 'glimmer', '~> 0.5.0'
 ```
 
 And, then run:
@@ -124,7 +128,8 @@ bundle install
 
 ## Glimmer Command
 
-Usage:
+### Basic Usage
+
 ```
 glimmer application.rb
 ```
@@ -136,14 +141,69 @@ Example:
 ```
 glimmer samples/hello_world.rb
 ```
-This runs the Glimmer application hello_world.rb
+This runs the Glimmer "Hello, World!" sample.
+
+If you cloned this project locally, you may run `bin/glimmer` instead.
+
+Example:
+```
+bin/glimmer samples/hello_world.rb
+```
+
+### Advanced Usage
+
+```
+glimmer [[-jruby-option]...] application.rb [[application2.rb]...]
+```
+
+Accepts JRuby options and multiple Glimmer applications to run simultaneously, each in a JRuby thread.
+
+Example (JRuby option):
+```
+glimmer --debug samples/hello_world.rb
+```
+
+Runs Glimmer application with JRuby debug option to enable JRuby debugging.
+
+Example (Multiple apps):
+```
+glimmer samples/hello_world.rb samples/hello_tab.rb
+```
+
+Launches samples/hello_world.rb and samples/hello_tab.rb at the same time, each in a separate JRuby thread.
 
 ## 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.
 
+```
+girb
+```
+
+If you cloned this project locally, you may run `bin/girb` instead.
+
+```
+bin/girb
+```
+
 ## Glimmer DSL Syntax
 
+Glimmer DSL syntax consists of static keywords and dynamic keywords to build and bind user-interface objects.
+
+Static keywords are pre-identified keywords in the Glimmer DSL, such as `shell`, `rgb`, and `bind`.
+
+Dynamic keywords are dynamically figured out from available SWT widgets, custom widgets, and properties. Examples are: `label`, `combo`, and `text`.
+
+The only reason to distinguish between both types of Glimmer DSL keywords is to realize that importing new Java SWT custom widget libraries and Ruby custom widgets automatically expands Glimmer's available DSL syntax via new dynamic keywords.
+
+For example, if a project adds this custom SWT library:
+
+https://www.eclipse.org/nebula/widgets/cdatetime/cdatetime.php?page=operation
+
+Glimmer will automatically support using the keyword `c_date_time`
+
+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:
@@ -179,7 +239,7 @@ For example, if we were to revisit `samples/hello_world.rb` above (you may copy/
 shell {
   text "Glimmer"
   label {
-    text "Hello World!"
+    text "Hello, World!"
   }
 }.open
 ```
@@ -192,14 +252,14 @@ Note that `shell` instantiates the outer shell **widget**, in other words, the w
 # ...
   text "Glimmer" # text property of shell
   label { # label widget declaration as content of shell
-    text "Hello World!" # text property of label
+    text "Hello, World!" # text property of label
   }
 # ...
 ```
 
 The first line declares a **property** called `text`, which sets the title of the shell (window) to `"Glimmer"`. **Properties** always have ***arguments*** (not wrapped by parenthesis according to [Glimmer coding style](#glimmer-coding-style)), such as the text `"Glimmer"` in this case, and do **NOT** have a ***block*** (this distinguishes them from **widget** declarations).
 
-The second line declares the `label` **widget**, which is followed by a Ruby **content** ***block*** that contains its `text` **property** with value `"Hello World!"`
+The second line declares the `label` **widget**, which is followed by a Ruby **content** ***block*** that contains its `text` **property** with value `"Hello, World!"`
 
 Note that The `shell` widget is always the outermost widget containing all others in a Glimmer desktop windowed application.
 
@@ -230,7 +290,7 @@ shell {
     tab_item {
       text "Tab 1"
       label {
-        text "Hello World!"
+        text "Hello, World!"
       }
     }
     tab_item {
@@ -243,9 +303,51 @@ shell {
 }.open
 ```
 
-#### `#widget`
+#### SWT Proxies
+
+Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT objects:
+- `Glimmer::SWT:WidgetProxy` wraps all descendants of `org.eclipse.swt.widgets.Widget` except the ones that have their own wrappers.
+- `Glimmer::SWT::ShellProxy` wraps `org.eclipse.swt.widgets.Shell`
+- `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:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
+- `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
+- `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
+
+These proxy objects have an API and provide some convenience methods, some of which are mentioned below.
+
+
+##### `#content { ... }`
 
-Glimmer widget objects come with an instance method `#widget` that returns the actual SWT `Widget` object wrapped by the Glimmer widget object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
+Glimmer allows re-opening any widget and adding properties or extra content after it has been constructed already by using the `#content` method.
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+@shell = shell {
+  text "Application"
+  row_layout
+  @label1 = label {
+    text "Hello,"
+  }
+}
+@shell.content {
+  minimum_size 130, 130
+  label {
+    text "World!"
+  }
+}
+@label1.content {
+  foreground :red
+}
+@shell.open
+```
+
+##### `#swt_widget`
+
+Glimmer widget objects come with an instance method `#swt_widget` that returns the actual SWT `Widget` object wrapped by the Glimmer widget object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
 
 Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
@@ -264,6 +366,19 @@ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 @shell.open
 ```
 
+##### Shell widget proxy methods
+
+Shell widget proxy has extra methods specific to SWT Shell:
+- `#open`: Opens the shell, making it visible and active, and starting the SWT Event Loop (you may learn more about it here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/Display.html). If shell was already open, but hidden, it makes the shell visible.
+- `#show`: Alias for `#open`
+- `#hide`: Hides a shell setting "visible" property to false
+- `#close`: Closes the shell
+- `#center`: Centers the shell within monitor it is in
+- `#start_event_loop`: (happens as part of `#open`) Starts SWT Event Loop (you may learn more about it here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/Display.html). This method is not needed except in rare circumstances where there is a need to start the SWT Event Loop before opening the shell.
+- `#visible?`: Returns whether a shell is visible
+- `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
+- `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
+
 ### Widget Styles
 
 SWT widgets receive `SWT` styles in their constructor as per this guide:
@@ -322,11 +437,11 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
 
 When building a widget-related SWT object manually (e.g. `GridData.new(...)`), you are expected to use `SWT::CONSTANT` directly or BIT-OR a few SWT constants together like `SWT::BORDER | SWT::V_SCROLL`.
 
-Glimmer facilitates that with `GSWT` class by allowing you to pass multiple styles as an argument array of symbols instead of dealing with BIT-OR. For example: `GSWT[:border, :v_scroll]`
+Glimmer facilitates that with `SWTProxy` class by allowing you to pass multiple styles as an argument array of symbols instead of dealing with BIT-OR. For example: `SWTProxy[:border, :v_scroll]`
 
 #### Non-resizable Window
 
-SWT Shell widget by default is resizable. To make it non-resizable, one must pass a complicated style bit concoction like `GSWT[:shell_trim] & (~GSWT[:resize]) & (~GSWT[:max])`.
+SWT Shell widget by default is resizable. To make it non-resizable, one must pass a complicated style bit concoction like `SWTProxy[:shell_trim] & (~SWTProxy[:resize]) & (~SWTProxy[:max])`.
 
 Glimmer makes this easier by alternatively offering `:no_resize` extra SWT style, added for convenience. This makes declaring an non-resizable window as easy as:
 ```ruby
@@ -347,12 +462,12 @@ Code examples:
 ```ruby
 # ...
 label {
-  text "Hello World!" # SWT properties go inside {} block
+  text "Hello, World!" # SWT properties go inside {} block
 }
 # ...
 ```
 
-In the above example, the `label` widget `text` property was set to "Hello World!".
+In the above example, the `label` widget `text` property was set to "Hello, World!".
 
 ```ruby
 # ...
@@ -403,13 +518,13 @@ You may check out all available standard colors in `SWT` over here (having `COLO
 https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
 
 
-##### `#color`
+##### `#swt_color`
 
-Glimmer color objects come with an instance method `#color` that returns the actual SWT `Color` object wrapped by the Glimmer color object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
+Glimmer color objects come with an instance method `#swt_color` that returns the actual SWT `Color` object wrapped by the Glimmer color object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
 
-##### `GColor.color_for(display = nil, standard_color)`
+##### `Glimmer::SWT::ColorProxy.new(display = nil, standard_color).swt_color`
 
-Glimmer `GColor` class comes with `.color_for` method that builds an actual SWT `Color` object from a standard color string or symbol. Passing a `display` is optional. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
+Glimmer `ColorProxy` class comes with `.color_for` method that builds an actual SWT `Color` object from a standard color string or symbol. Passing a `display` is optional. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
 
 #### Fonts
 
@@ -605,7 +720,7 @@ composite {
   grid_layout 3, false # grid layout with 3 columns not of equal width
   label {
     # layout data set explicitly via an object (helps in rare cases that break convention)
-    layout_data GridData.new(GSWT[:fill], GSWT[:end], true, false)
+    layout_data GridData.new(SWTProxy[:fill], SWTProxy[:end], true, false)
   }
 }
 # ...
@@ -906,7 +1021,7 @@ class TicTacToe
 end
 ```
 
-Alternatively, one can use a default Observer::Proc implementation via Observer.proc method:
+Alternatively, one can use a default Observer.proc implementation via Observer.proc method:
 ```ruby
 observer = Observer.proc { |new_value| puts new_value }
 observer.observe(@tic_tac_toe_board, :game_status)
@@ -954,20 +1069,20 @@ end
 
 Glimmer supports creating custom widgets with minimal code, which automatically extends Glimmer's DSL syntax with an underscored lowercase keyword.
 
-Simply create a new class that includes `Glimmer::SWT::CustomWidget` and put Glimmer DSL code in its `#body` method (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 `__`)
+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)):
 
 Definition:
 ```ruby
 class RedLabel
-  include Glimmer::SWT::CustomWidget
+  include Glimmer::UI::CustomWidget
 
-  def body
+  body {
     label(swt_style) {
       background :red
     }
-  end
+  }
 end
 ```
 
@@ -988,13 +1103,17 @@ Definition:
 ```ruby
 module Red
   class Composite
-    include Glimmer::SWT::CustomWidget
+    include Glimmer::UI::CustomWidget
+
+    before_body {
+      @color = :red
+    }
 
-    def body
+    body {
       composite(swt_style) {
-        background :red
+        background @color
       }
-    end
+    }
   end
 end
 ```
@@ -1011,13 +1130,15 @@ shell {
 }.open
 ```
 
-Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention.
+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`.
 
 Custom Widgets have the following attributes (attribute readers) 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)
 - `#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)
@@ -1028,12 +1149,12 @@ Additionally, custom widgets can call the following class methods:
 Definition:
 ```ruby
 class Sandwich
-  include Glimmer::SWT::CustomWidget
+  include Glimmer::UI::CustomWidget
 
   options :orientation, :bg_color
   option :fg_color, :black
 
-  def body
+  body {
     composite(swt_style) { # gets custom widget style
       fill_layout orientation # using orientation option
       background bg_color # using container_background option
@@ -1045,7 +1166,7 @@ class Sandwich
         text 'SANDWICH BOTTOM'
       }
     }
-  end
+  }
 end
 ```
 
@@ -1063,9 +1184,139 @@ 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'`
 
-The following additional attributes may be called from outside a custom widget in addition to the attributes mentioned above, assuming it's been captured in a variable:
-- `#body_root`: top-most root Glimmer widget returned in `#body` method
-- `#widget`: actual SWT widget for `body_root`
+Last but not least, these are the available 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.
+
+### 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.
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+class WizardStep
+  include Glimmer::UI::CustomShell
+
+  options :number, :step_count
+
+  before_body {
+    @title = "Step #{number}"
+  }
+
+  body {
+    shell {
+      text "Wizard - #{@title}"
+      minimum_size 200, 100
+      fill_layout :vertical
+      label(:center) {
+        text @title
+        font height: 30
+      }
+      if number < step_count
+        button {
+          text "Go To Next Step"
+          on_widget_selected {
+            body_root.hide
+          }
+        }
+      end
+    }
+  }
+end
+
+shell { |app_shell|
+  text "Wizard"
+  minimum_size 200, 100
+  @current_step_number = 1
+  @wizard_steps = 5.times.map { |n|
+    wizard_step(number: n+1, step_count: 5) {
+      on_event_hide {
+        if @current_step_number < 5
+          @current_step_number += 1
+          app_shell.hide
+          @wizard_steps[@current_step_number - 1].open
+        end
+      }      
+    }
+  }
+  button {
+    text "Start"
+    font height: 40
+    on_widget_selected {
+      app_shell.hide
+      @wizard_steps[@current_step_number - 1].open
+    }
+  }
+}.open
+```
+
+### 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.
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+class WizardStep
+  include Glimmer::UI::CustomShell
+
+  options :number, :step_count
+
+  before_body {
+    @title = "Step #{number}"
+  }
+
+  body {
+    shell {
+      text "Wizard - #{@title}"
+      minimum_size 200, 100
+      fill_layout :vertical
+      label(:center) {
+        text @title
+        font height: 30
+      }
+      if number < step_count
+        button {
+          text "Go To Next Step"
+          on_widget_selected {
+            body_root.hide
+          }
+        }
+      end
+    }
+  }
+end
+
+shell { |app_shell|
+  text "Wizard"
+  minimum_size 200, 100
+  @current_step_number = 1
+  @wizard_steps = 5.times.map { |n|
+    wizard_step(number: n+1, step_count: 5) {
+      on_event_hide {
+        if @current_step_number < 5
+          @current_step_number += 1
+          app_shell.hide
+          @wizard_steps[@current_step_number - 1].open
+        end
+      }      
+    }
+  }
+  button {
+    text "Start"
+    font height: 40
+    on_widget_selected {
+      app_shell.hide
+      @wizard_steps[@current_step_number - 1].open
+    }
+  }
+}.open
+```
 
 ### Miscellaneous
 
@@ -1149,19 +1400,20 @@ shell {
 
 - Widgets are declared with underscored lowercase versions of their SWT names minus the SWT package name.
 - Widget declarations may optionally have arguments and be followed by a block (to contain properties and content)
-- Widget blocks are always declared with curly brackets
+- Widget blocks are always declared with curly braces
 - Widget arguments are always wrapped inside parentheses
 - Widget properties are declared with underscored lowercase versions of the SWT properties
 - 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 brackets
+- 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)
 - 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.
 
 ## 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 --dev`).
+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`).
 
 Examples:
 
@@ -1207,24 +1459,37 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
 
 Glimmer automatically imports all SWT Java packages upon adding `include Glimmer` to a class or module.
 
-Still, if you'd like to import manually elsewhere, you may add the following lines to your code (in the class or module body) to import SWT Java packages using `include_package`:
-
-```ruby
-include_package 'org.eclipse.swt'
-include_package 'org.eclipse.swt.widgets'
-include_package 'org.eclipse.swt.layout'
-include_package 'org.eclipse.swt.graphics'
+Here are the Java packages imported:
+```
+org.eclipse.swt.*
+org.eclipse.swt.widgets.*
+org.eclipse.swt.layout.*
+org.eclipse.swt.graphics.*
+org.eclipse.swt.browser.*
+org.eclipse.swt.custom.*
 ```
 
-To import a specific SWT Java class using `java_import`, add the following:
+This allows you to call SWT Java classes from Ruby without mentioning Java package references.
+
+For example, after imports, `org.eclipse.swt.graphics.Color` can be referenced by just `Color`
+
+Nonetheless, you can disable automatic import if needed via this Glimmer configuration option:
 
 ```ruby
-java_import 'org.eclipse.swt.SWT'
+Glimmer.import_swt_packages = false
 ```
 
-This allows you to call SWT Java classes from Ruby without mentioning package namespaces.
+To import SWT Java packages manually instead, you have 2 options:
 
-For example, after imports, `org.eclipse.swt.graphics.Color` can be referenced by just `Color`
+1. `include Glimmer::SwtPackages`: lazily imports all SWT Java packages to your class, lazy-loading SWT Java class constants on first reference.
+
+2. `java_import swt_package_class_string`: immediately imports a specific Java class where `swt_package_class_string` is the Java full package reference of a Java class (e.g. `java_import 'org.eclipse.swt.SWT'`)
+
+Note: Glimmer relies on [`nested_imported_jruby_include_package`](https://github.com/AndyObtiva/nested_inherited_jruby_include_package), which automatically brings packages to nested-modules/nested-classes and sub-modules/sub-classes.
+
+You can learn more about importing Java packages into Ruby code at this JRuby WIKI page:
+
+https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
 
 ## Logging