glimmer 0.4.8 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e11298f6aa21de3c113c3c9169df23a9181b2501e7d33e7fc62e3d18dec37f8
-  data.tar.gz: eca26276e4afebd498174332cc7360044afffe71d48663ca3d95feb657b17b57
+  metadata.gz: 218ad434685b90c53d096b5ebc117c4eb790f5e724f8bd59d91ea3cc57683b74
+  data.tar.gz: a4568fdf1521441848af186a804c54c6ac6c3d29ba6ccabb3c1726630d9067d1
 SHA512:
-  metadata.gz: cff2e454cdc6100893a100bdb5fd6e0b1b300f6c384f4c8a9722deb677d3cf83fd86f14462e7661b9523b06df43c93f6e1499bb5ab1ea77dfa0283a6c64537d2
-  data.tar.gz: 820f9b260ce6c068ccf69274c73074739b983047050c517b0c511d992d903ff66e904f283224a5b837d29da69cd03f5549e6d36434bbe8fe702edef67df5ea29
+  metadata.gz: f0f19afe707d602e34a8c47708b40660fb149061a56e00bf3404d100ee12aab2ac9baaaad8a6fd6247a91fafc818d154848feaab1d14b3fab10c1f0d55a4999c
+  data.tar.gz: 6f5b8ce1b0562fbef375699f919fbd5cfe3cf746c64f2ef55e4cc50162bfcc4ac33f0d520ec0e8192644ae43e2efaf9fd3155504a1d3140e6dce0b708f2964d6

data/README.markdown

@@ -1,4 +1,4 @@
-# Glimmer 0.4.8 Beta (JRuby Desktop UI DSL + Data-Binding)
+# Glimmer 0.4.9 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.
@@ -107,14 +107,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.8
+jgem install glimmer -v 0.4.9
 ```
 
 ### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.4.8'
+gem 'glimmer', '~> 0.4.9'
 ```
 
 And, then run:
@@ -169,9 +169,11 @@ In Glimmer DSL, widgets are declared with lowercase underscored names mirroring
 - `combo` instantiates `org.eclipse.swt.widgets.Combo`
 - `list` instantiates `org.eclipse.swt.widgets.List`
 
-A **widget** name is followed by a Ruby block that contains the widget **properties** and **content**. Optionally, an SWT **style** ***argument*** may also be passed (see [next section](#widget-styles) for details).
+Every **widget** is sufficiently declared by name, but may optionally be accompanied with:
+- SWT **style** ***argument*** wrapped by parenthesis according to [Glimmer coding style](#glimmer-coding-style) (see [next section](#widget-styles) for details).
+- Ruby block containing **properties** (widget attributes) and **content** (nested widgets)
 
-For example, if we were to revisit `samples/hello_world.rb` above:
+For example, if we were to revisit `samples/hello_world.rb` above (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
 shell {
@@ -189,13 +191,13 @@ Note that `shell` instantiates the outer shell **widget**, in other words, the w
 ```ruby
 # ...
   text "Glimmer" # text property of shell
-  label { # label widget declaration
+  label { # label widget declaration as content of shell
     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***, such as the text `"Glimmer"` in this case, and do **NOT** have a ***block***.
+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!"`
 
@@ -215,7 +217,7 @@ It is centered upon initial display and has a minimum width of 130 (can be re-ce
 
 Check out the [samples](samples) directory for more examples.
 
-Example from [hello_tab.rb](samples/hello_tab.rb) sample:
+Example from [hello_tab.rb](samples/hello_tab.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ![Hello Tab 1](images/glimmer-hello-tab1.png)
 
@@ -241,82 +243,25 @@ shell {
 }.open
 ```
 
-#### Video Widget
-
-![Video Widget](images/glimmer-video-widget.png)
-
-Glimmer comes with a video widget not in SWT. It comes with very basic video functionality at the moment, such as autoplay by default, displaying controls, looping, and setting background.
-
-Attributes (passed in an options hash as arguments to video widget):
-- `autoplay` (true [default] or false): plays video automatically as soon as loaded
-- `controls` (true [default] or false): displays controls
-- `looped` (true or false [default]): plays video in looped mode
-- `background` (Glimmer color [default: white]): sets background color just like with any other widget
-- `fit_to_width` (true [default] or false): fits video width to widget allotted width regardless of video's original size. Maintains video aspect ratio.
-- `fit_to_height` (true [default] or false): fits video height to widget allotted height regardless of video's original size. Maintains video aspect ratio.
-- `offset_x` (integer [default: 0]): offset from left border. Could be a negative number if you want to show only an area of the video. Useful when fit_to_width is false to pick an area of the video to display.
-- `offset_y` (integer [default: 0]): offset from top border. Could be a negative number if you want to show only an area of the video. Useful when fit_to_height is false to pick an area of the video to display.
-
-Methods:
-- `play`: plays video
-- `pause`: pauses video
-
-Example ([samples/video/hello_video.rb](samples/video/hello_video.rb)):
-
-```ruby
-# ...
-shell {
-  video(file: video_file)
-}.open
-```
-
-Example ([samples/video/hello_looped_video_with_black_background.rb](samples/video/hello_looped_video_with_black_background.rb)):
-
-```ruby
-# ...
-shell {
-  minimum_size 1024, 640
-  video(file: video_file, looped: true, background: :black)
-}.open
-```
+#### `#widget`
 
-#### Browser Widget
-
-Glimmer supports SWT Browser widget, which can load URLs (including media) or render HTML (useful in embedding videos). It can even be instrumented with JavaScript when needed (though highly discouraged except for rare cases when leveraging a pre-existing web codebase in a desktop app).
+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.
 
-Example loading a URL:
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ```ruby
-shell {
-  minimum_size 1024, 860
-  browser {
-    url 'http://brightonresort.com/about'
-  }
-}.open
-```
-
-Example rendering HTML with an embedded video:
-
-```ruby
-shell {
-  @browser = browser {
-    text <<~HTML
-      <html>
-        <head>
-        </head>
-        <body>
-          <video id="video" width="100%" height="100%">
-            <source src="file://#{video_file}" type="video/mp4">
-          Your browser does not support the video tag.
-          </video>
-        </body>
-      </html>
-    HTML
-    on_completed { # on load of the page execute this JavaScript
-      @browser.widget.execute("document.getElementById('video').play()")
+@shell = shell {
+  button {
+    text "Press Me"
+    on_widget_selected {
+      message_box = MessageBox.new(@shell.widget) # passing SWT Shell widget
+      message_box.setText("Surprise")
+      message_box.setMessage("You have won $1,000,000!")
+      message_box.open      
     }
   }
-}.open
+}
+@shell.open
 ```
 
 ### Widget Styles
@@ -325,34 +270,40 @@ SWT widgets receive `SWT` styles in their constructor as per this guide:
 
 https://wiki.eclipse.org/SWT_Widget_Style_Bits
 
-Glimmer DSL facilitates that by passing symbols representing `SWT` constants as widget method arguments (i.e. inside widget `()` parentheses. See example below) in lower case version (e.g. `SWT::MULTI` becomes `:multi`).
+Glimmer DSL facilitates that by passing symbols representing `SWT` constants as widget method arguments (i.e. inside widget `()` parentheses according to [Glimmer coding style](#glimmer-coding-style). See example below) in lower case version (e.g. `SWT::MULTI` becomes `:multi`).
 
 These styles customize widget look, feel, and behavior.
 
 Example:
+
 ```ruby
+# ...
 list(:multi) { # SWT styles go inside ()
   # ...
 }
+# ...
 ```
-
 Passing `:multi` to `list` widget enables list element multi-selection.
 
 ```ruby
+# ...
 composite(:border) { # SWT styles go inside ()
   # ...
 }
+# ...
 ```
-
 Passing `:border` to `composite` widget ensures it has a border.
 
 When you need to pass in **multiple SWT styles**, simply separate by commas.
 
 Example:
+
 ```ruby
+# ...
 text(:center, :border) { # Multiple SWT styles separated by comma
   # ...
 }
+# ...
 ```
 
 Glimmer ships with SWT style **smart defaults** so you wouldn't have to set them yourself most of the time (albeit you can always override them):
@@ -394,17 +345,21 @@ https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_wi
 Code examples:
 
 ```ruby
+# ...
 label {
   text "Hello World!" # SWT properties go inside {} block
 }
+# ...
 ```
 
 In the above example, the `label` widget `text` property was set to "Hello World!".
 
 ```ruby
+# ...
 button {
   enabled bind(@tic_tac_toe_board.box(row, column), :empty)
 }
+# ...
 ```
 
 In the above example, the `text` widget `enabled` property was data-bound to `#empty` method on `@tic_tac_toe_board.box(row, column)` (learn more about data-binding below)
@@ -416,10 +371,12 @@ Colors make up a subset of widget properties. SWT accepts color objects created
 Example:
 
 ```ruby
+# ...
 label {
   background rgb(144, 240, 244)
   foreground rgba(38, 92, 232, 255)
 }
+# ...
 ```
 
 SWT also supports standard colors available as constants under the `SWT` namespace with the `COLOR_` prefix (e.g. `SWT::COLOR_BLUE`, `SWT::COLOR_WHITE`, `SWT::COLOR_RED`)
@@ -429,6 +386,7 @@ Glimmer accepts these constants as lowercase Ruby symbols with or without `color
 Example:
 
 ```ruby
+# ...
 label {
   background :black
   foreground :yellow
@@ -437,12 +395,22 @@ label {
   background :color_white
   foreground :color_red
 }
+# ...
 ```
 
 You may check out all available standard colors in `SWT` over here (having `COLOR_` prefix):
 
 https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
 
+
+##### `#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.
+
+##### `GColor.color_for(display = nil, standard_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.
+
 #### Fonts
 
 Fonts are represented in Glimmer as a hash of name, height, and style keys.
@@ -452,9 +420,11 @@ The style can be one (or more) of 3 values: `:normal`, `:bold`, and `:italic`
 Example:
 
 ```ruby
+# ...
 label {
   font name: 'Arial', height: 36, style: :normal
 }
+# ...
 ```
 
 Keys are optional, so some of them may be left off.
@@ -463,9 +433,11 @@ When passing multiple styles, they are included in an array.
 Example:
 
 ```ruby
+# ...
 label {
   font style: [:bold, :italic]
 }
+# ...
 ```
 
 ### Layouts
@@ -482,6 +454,7 @@ In Glimmer DSL, just like widgets, layouts can be specified with lowercase under
 Example:
 
 ```ruby
+# ...
 composite {
   row_layout {
     wrap true
@@ -496,15 +469,18 @@ composite {
   }
   # ... widgets follow
 }
+# ...
 ```
 
 Alternatively, a layout may be constructed by following the SWT API for the layout object. For example, a `RowLayout` can be constructed by passing it an SWT style constant (Glimmer automatically accepts symbols (e.g. `:horizontal`) for SWT style arguments like `SWT::HORIZONTAL`.)
 
 ```ruby
+# ...
 composite {
   row_layout :horizontal
   # ... widgets follow
 }
+# ...
 ```
 
 Here is a more sophisticated example taken from [hello_computed.rb](samples/hellocomputed/hello_computed.rb) sample:
@@ -597,6 +573,7 @@ Glimmer also automatically accepts symbols (e.g. `:fill`) for SWT style argument
 Examples:
 
 ```ruby
+# ...
 composite {
   row_layout :horizontal
   label {
@@ -607,9 +584,11 @@ composite {
   }
   # ... more widgets follow
 }
+# ...
 ```
 
 ```ruby
+# ...
 composite {
   grid_layout 3, false # grid layout with 3 columns not of equal width
   label {
@@ -617,9 +596,11 @@ composite {
     layout_data :fill, :end, true, false
   }
 }
+# ...
 ```
 
 ```ruby
+# ...
 composite {
   grid_layout 3, false # grid layout with 3 columns not of equal width
   label {
@@ -627,6 +608,7 @@ composite {
     layout_data GridData.new(GSWT[:fill], GSWT[:end], true, false)
   }
 }
+# ...
 ```
 
 **NOTE**: Layout data must never be reused between widgets. Always specify or clone again for every widget.
@@ -664,7 +646,7 @@ The 5th example demonstrates computed value data binding whereby the value of `n
 
 The 6th example demonstrates nested indexed computed value data binding whereby the value of `profiles[0].name` depends on changes to both nested `profiles[0].first_name` and `profiles[0].last_name`.
 
-Example from [hello_combo.rb](samples/hello_combo.rb) sample:
+Example from [samples/hello_combo.rb](samples/hello_combo.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 ![Hello Combo](images/glimmer-hello-combo.png)
 
@@ -709,7 +691,7 @@ HelloCombo.new.launch
 
 `combo` widget is data-bound to the country of a person. Note that it expects `person` object to have `:country` attribute and `:country_options` attribute containing all available countries.
 
-Example from [hello_list_single_selection.rb](samples/hello_list_single_selection.rb) sample:
+Example from [samples/hello_list_single_selection.rb](samples/hello_list_single_selection.rb) sample:
 
 ![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
 
@@ -733,6 +715,8 @@ shell {
 
 Nonetheless, in the next example, a multi-selection list is declared instead allowing data-binding of multiple selection values to the bindable attribute on the model.
 
+Example from [samples/hello_list_multi_selection.rb](samples/hello_list_multi_selection.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
 ![Hello List Multi Selection](images/glimmer-hello-list-multi-selection.png)
 
 ```ruby
@@ -794,9 +778,13 @@ Glimmer comes with `Observer` module, which is used internally for data-binding,
 
 #### Observing Widgets
 
-Glimmer supports observing widgets with an `on_*event*` declaration where the '*event*' part is replaced with the lowercase underscored name of an SWT listener event method.
+Glimmer supports observing widgets with two types of syntax:
+1. `on_{swt-listener-method-name}`: where {swt-listener-method-name} is replaced with the lowercase underscored method name on an SWT listener class (e.g. `on_verify_text` for `org.eclipse.swt.events.VerifyListener#verifyText`).
+2. `on_event_{swt-event-constant}`: where {swt-event-constant} is replaced with an `org.eclipse.swt.SWT` event constant (e.g. `on_event_show` for `SWT.Show` to observe when widget becomes visible)
+
+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.
 
-To figure out what the available events for an SWT widget are, check out all of its API methods starting with `add` and ending with `Listener`, and then open the listener class to check its "event methods".
+**Regarding number 1**, to figure out what the available events for an SWT widget are, check out all of its `add***Listener` API methods, and then open the listener class argument to check its "event methods".
 
 For example, if you look at the `Button` SWT API:
 https://help.eclipse.org/2019-12/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fswt%2Fbrowser%2FBrowser.html
@@ -836,6 +824,64 @@ Note that every Tic Tac Toe grid cell has its `text` and `enabled` properties da
 
 Next however, each of these Tic Tac Toe grid cells, which are clickable buttons, have an `on_widget_selected` observer, which once triggered, marks the box (cell) on the `TicTacToeBoard` to make a move.
 
+**Regarding number 2**, you can figure out all available events by looking at the `org.eclipse.swt.SWT` API:
+
+https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+`SWT.Show` - hooks a listener for showing a widget (using `on_event_show` in Glimmer)
+`SWT.Hide` - hooks a listener for hiding a widget (using `on_event_hide` in Glimmer)
+
+```ruby
+shell {
+  @button1 = button {
+    text "Show 2nd Button"
+    visible true
+    on_event_show {
+      @button2.widget.setVisible(false)
+    }
+    on_widget_selected {
+      @button2.widget.setVisible(true)
+    }
+  }
+  @button2 = button {
+    text "Show 1st Button"
+    visible false
+    on_event_show {
+      @button1.widget.setVisible(false)
+    }
+    on_widget_selected {
+      @button1.widget.setVisible(true)        
+    }
+  }
+}.open
+```
+
+**Gotcha:** SWT.Resize event needs to be hooked using **`on_event_Resize`** because `org.eclipse.swt.SWT` has 2 constants for resize: `RESIZE` and `Resize`, so it cannot infer the right one automatically from the underscored version `on_event_resize`
+
+##### Alternative Syntax
+
+Instead of declaring a widget observer using `on_***` syntax inside a widget content block, you may also do so after the widget declaration by invoking directly on the widget object.
+
+Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```
+@shell = shell {
+  label {
+    text "Hello, World!"
+  }
+}
+@shell.on_shell_iconified {
+  @shell.close
+}  
+@shell.open
+```
+
+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.
+
 #### Observing Models
 
 The class that needs to observe a model object must include (mix in) the `Observer` module and implement the `#call(new_value)` method. The class to be observed doesn't need to do anything. It will automatically be enhanced by Glimmer for observation.
@@ -910,7 +956,7 @@ Glimmer supports creating custom widgets with minimal code, which automatically
 
 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 `__`)
 
-**Example:**
+#### Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 Definition:
 ```ruby
@@ -931,12 +977,12 @@ shell {
   red_label {
     text 'Red Label'
   }
-}
+}.open
 ```
 
 As you can see, `RedLabel` became Glimmer DSL keyword: `red_label`
 
-**Another Example:**
+#### Another Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 Definition:
 ```ruby
@@ -950,6 +996,7 @@ module Red
       }
     end
   end
+end
 ```
 
 Usage:
@@ -961,7 +1008,7 @@ shell {
       text 'This is showing inside a Red Composite'
     }
   }
-}
+}.open
 ```
 
 Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention.
@@ -976,7 +1023,7 @@ 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`)
 
-**Content/Options Example:**
+#### Content/Options Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
 
 Definition:
 ```ruby
@@ -989,7 +1036,7 @@ class Sandwich
   def body
     composite(swt_style) { # gets custom widget style
       fill_layout orientation # using orientation option
-      background container_background # using container_background option
+      background bg_color # using container_background option
       label {
         text 'SANDWICH TOP'
       }
@@ -1005,12 +1052,13 @@ end
 Usage:
 ```ruby
 shell {
-  sandwich(:no_focus, orientation: :horizontal, bg_color: :white) {
+  sandwich(:no_focus, orientation: :vertical, bg_color: :red) {
     label {
+      background :green
       text 'SANDWICH CONTENT'
     }
   }
-}
+}.open
 ```
 
 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'`
@@ -1019,6 +1067,97 @@ The following additional attributes may be called from outside a custom widget i
 - `#body_root`: top-most root Glimmer widget returned in `#body` method
 - `#widget`: actual SWT widget for `body_root`
 
+### Miscellaneous
+
+#### Video Widget
+
+![Video Widget](images/glimmer-video-widget.png)
+
+Glimmer comes with a video widget not in SWT. It comes with very basic video functionality at the moment, such as autoplay by default, displaying controls, looping, and setting background.
+
+Attributes (passed in an options hash as arguments to video widget):
+- `autoplay` (true [default] or false): plays video automatically as soon as loaded
+- `controls` (true [default] or false): displays controls
+- `looped` (true or false [default]): plays video in looped mode
+- `background` (Glimmer color [default: white]): sets background color just like with any other widget
+- `fit_to_width` (true [default] or false): fits video width to widget allotted width regardless of video's original size. Maintains video aspect ratio.
+- `fit_to_height` (true [default] or false): fits video height to widget allotted height regardless of video's original size. Maintains video aspect ratio.
+- `offset_x` (integer [default: 0]): offset from left border. Could be a negative number if you want to show only an area of the video. Useful when fit_to_width is false to pick an area of the video to display.
+- `offset_y` (integer [default: 0]): offset from top border. Could be a negative number if you want to show only an area of the video. Useful when fit_to_height is false to pick an area of the video to display.
+
+Methods:
+- `play`: plays video
+- `pause`: pauses video
+
+Example ([samples/video/hello_video.rb](samples/video/hello_video.rb)):
+
+```ruby
+# ...
+shell {
+  video(file: video_file)
+}.open
+```
+
+Example ([samples/video/hello_looped_video_with_black_background.rb](samples/video/hello_looped_video_with_black_background.rb)):
+
+```ruby
+# ...
+shell {
+  minimum_size 1024, 640
+  video(file: video_file, looped: true, background: :black)
+}.open
+```
+
+#### Browser Widget
+
+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)):
+
+```ruby
+shell {
+  minimum_size 1024, 860
+  browser {
+    url 'http://brightonresort.com/about'
+  }
+}.open
+```
+
+Example rendering HTML with JavaScript on document ready (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+shell {
+  minimum_size 130, 130
+  @browser = browser {
+    text <<~HTML
+      <html>
+        <head>
+        </head>
+        <body>
+          <h1>Hello, World!</h1>
+        </body>
+      </html>
+    HTML
+    on_completed { # on load of the page execute this JavaScript
+      @browser.widget.execute("alert('Hello, World!');")
+    }
+  }
+}.open
+```
+
+## Glimmer Coding Style
+
+- 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 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
+- Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
+- 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
 
@@ -1056,10 +1195,14 @@ Here is a textual list of SWT widgets:
 
 https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0
 
-Here is a list of SWT style bits:
+Here is a list of SWT style bits as used in widget declaration:
 
 https://wiki.eclipse.org/SWT_Widget_Style_Bits
 
+Here is a SWT style bit constant reference:
+
+https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
+
 ## SWT Packages
 
 Glimmer automatically imports all SWT Java packages upon adding `include Glimmer` to a class or module.