glimmer 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 313a2b82012ccded3ec1eb15a190a75354e6528c4835c2d90d5139c30764558c
-  data.tar.gz: 1439d36f56bf10e99d6d0d6fd0582aefd86a07b82f1b82bd127ab5a0f12b5909
+  metadata.gz: 53c846877535c288cc80b8c2972b14f5fd961b6e3e51f744278e8c6da47cfe6d
+  data.tar.gz: 4be53a6c16f2a9ae9c6101ca4726b576bec5e17dae05f55d64c0714ab13ab6fd
 SHA512:
-  metadata.gz: b073d545dbdddb31ceb9cb543f76d2b05bc541f133234174dd56e7e492d1a44315df91135a215c91c0935f229fd4126a3e7b0e13c6bf1adcd765ae70e1b8be9c
-  data.tar.gz: d64203b4bb7c91078c802bf67cf5b52674b61f0ba41f1c1df3de684064e7cde7e9c5cf6bf6df5a1ffe43b2a924b43db86644a55dce08211c38b78700239e8530
+  metadata.gz: 8f717afdd64e347b706a3d909474b579031c4a235d4881c490958d7c743892f363b64ae29f40bf8401506f327764163c4d08660cb6a29d8507b7077f11e06c29
+  data.tar.gz: c2b5de327710faa1e6dde42e5ef011af9b5375b87c030edeea40a0e672c7abd8a848dd1f8f48da9deeee903be27c9cc8e79e4a8a404a31cbf522be11dad35ee3

data/README.markdown

@@ -1,4 +1,4 @@
-# Glimmer (The Original One And Only)
+# Glimmer (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.
@@ -83,10 +83,20 @@ 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
+
+The SWT FAQ has further details:
+
+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)
 
 On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
 
@@ -102,14 +112,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.5
+jgem install glimmer -v 0.4.6
 ```
 
 ### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.4.5'
+gem 'glimmer', '~> 0.4.6'
 ```
 
 And, then run:
@@ -137,21 +147,99 @@ This runs the Glimmer application hello_world.rb
 
 ### Widgets
 
-Glimmer UIs (user interfaces) are modeled with widgets (wrappers around the SWT library widgets found here: https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0).
+Glimmer UIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
+
+https://www.eclipse.org/swt/widgets/
+
+This screenshot taken from the link above should give a glimpse of how SWT widgets look and feel:
+
+![SWT Widgets](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-swt-widgets.png)
 
-In Glimmer DSL, widgets are declared with lowercase underscored naming (you may look at usage examples in the `samples` directory).
+In Glimmer DSL, widgets are declared with lowercase underscored names mirroring their SWT names minus the package name:
 
-The `shell` widget is always the outermost widget containing all others in a desktop windowed application. It is centered upon initial display and has a minimum width of 130 (can be re-centered when needed with `@shell.center` method)
+- `shell` instantiates `org.eclipse.swt.widgets.Shell`
+- `text` instantiates `org.eclipse.swt.widgets.Text`
+- `button` instantiates `org.eclipse.swt.widgets.Button`
+- `label` instantiates `org.eclipse.swt.widgets.Label`
+- `composite` instantiates `org.eclipse.swt.widgets.Composite`
+- `tab_folder` instantiates `org.eclipse.swt.widgets.TabFolder`
+- `tab_item` instantiates `org.eclipse.swt.widgets.TabItem`
+- `table` instantiates `org.eclipse.swt.widgets.Table`
+- `table_column` instantiates `org.eclipse.swt.widgets.TableColumn`
+- `tree` instantiates `org.eclipse.swt.widgets.Tree`
+- `combo` instantiates `org.eclipse.swt.widgets.Combo`
+- `list` instantiates `org.eclipse.swt.widgets.List`
 
-Other widget examples:
-- `button`: wrapper for `org.eclipse.swt.widgets.Button`
-- `label`: wrapper for `org.eclipse.swt.widgets.Label`
-- `tab_folder`: wrapper for `org.eclipse.swt.widgets.TabFolder`
-- `tab_item`: wrapper for `org.eclipse.swt.widgets.TabItem`
-- `table`: wrapper for `org.eclipse.swt.widgets.Table`
-- `table_column`: wrapper for `org.eclipse.swt.widgets.TableColumn`
-- `tree`: wrapper for `org.eclipse.swt.widgets.Tree`
+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).
 
+For example, if we were to revisit `hello_world.rb` above:
+
+```ruby
+include Glimmer
+
+shell {
+  text "Glimmer"
+  label {
+    text "Hello World!"
+  }
+}.open
+```
+
+Note that `shell` instantiates the outer shell **widget**, in other words, the window that houses all of the desktop graphical user interface.
+
+`shell` is then followed by a ***block*** that contains
+
+```ruby
+text "Glimmer" # text property of shell
+label { # label widget declaration
+  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 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.
+
+After it is declared, a `shell` must be opened with the `#open` method, which can be called on the block directly as in the example above, or by capturing `shell` in a `@shell` variable (shown in example below), and calling `#open` on it independently (recommended in actual apps)
+
+```ruby
+@shell = shell {
+  # properties and content
+}
+@shell.open
+```
+
+It is centered upon initial display and has a minimum width of 130 (can be re-centered when needed with `@shell.center` method after capturing `shell` in a `@shell` variable as per samples)
+
+Check out the [samples](https://github.com/AndyObtiva/glimmer/tree/master/samples) directory for more examples.
+
+Example from [hello_tab.rb](https://github.com/AndyObtiva/glimmer/blob/master/samples/hello_tab.rb) sample:
+
+![Hello Tab 1](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-tab1.png)
+
+![Hello Tab 2](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-tab2.png)
+
+```ruby
+shell {
+  text "SWT"
+  tab_folder {
+    tab_item {
+      text "Tab 1"
+      label {
+        text "Hello World!"
+      }
+    }
+    tab_item {
+      text "Tab 2"
+      label {
+        text "Bonjour Univers!"
+      }
+    }
+  }
+}.open
+```
 
 **Browser Widget**
 
@@ -281,6 +369,65 @@ button {
 
 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)
 
+#### Colors
+
+Colors make up a subset of widget properties. SWT accepts color objects created with RGB (Red Green Blue) or RGBA (Red Green Blue Alpha). Glimmer supports constructing color objects using the `rgb` and `rgba` DSL methods.
+
+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`)
+
+Glimmer accepts these constants as lowercase Ruby symbols with or without `color_` prefix.
+
+Example:
+
+```ruby
+label {
+  background :black
+  foreground :yellow
+}
+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
+
+#### Fonts
+
+Fonts are represented in Glimmer as a hash of name, height, and style keys.
+
+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.
+When passing multiple styles, they are included in an array.
+
+Example:
+
+```ruby
+label {
+  font style: [:bold, :italic]
+}
+```
+
 ### Layouts
 
 Glimmer lays widgets out visually using SWT layouts, which can only be set on composite widget and subclasses.
@@ -452,97 +599,206 @@ Also, for a reference, check the SWT API:
 
 https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
 
-### Colors
+### Data-Binding
 
-Colors make up a subset of widget properties. SWT accepts color objects created with RGB (Red Green Blue) or RGBA (Red Green Blue Alpha). Glimmer supports constructing color objects using the `rgb` and `rgba` DSL methods.
+Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
 
-Example:
+Data-binding examples:
+- `text bind(contact, :first_name)`
+- `text bind(contact, 'address.street')`
+- `text bind(contact, 'addresses[1].street')`
+- `text bind(contact, :age, computed_by: :date_of_birth)`
+- `text bind(contact, :name, computed_by: [:first_name, :last_name])`
+- `text bind(contact, 'profiles[0].name', computed_by: ['profiles[0].first_name', 'profiles[0].last_name'])`
 
-```ruby
-label {
-  background rgb(144, 240, 244)
-  foreground rgba(38, 92, 232, 255)
-}
-```
+The 1st example binds the text property of a widget like `label` to the first name of a contact model.
 
-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`)
+The 2nd example binds the text property of a widget like `label` to the nested street of
+the address of a contact. This is called nested property data binding.
 
-Glimmer accepts these constants as lowercase Ruby symbols with or without `color_` prefix.
+The 3rd example binds the text property of a widget like `label` to the nested indexed address street of a contact. This is called nested indexed property data binding.
 
-Example:
+The 4th example demonstrates computed value data binding whereby the value of `age` depends on changes to `date_of_birth`.
+
+The 5th example demonstrates computed value data binding whereby the value of `name` depends on changes to both `first_name` and `last_name`.
+
+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](https://github.com/AndyObtiva/glimmer/blob/master/samples/hello_combo.rb) sample:
+
+![Hello Combo](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-combo.png)
+
+![Hello Combo](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-combo-expanded.png)
 
 ```ruby
-label {
-  background :black
-  foreground :yellow
-}
-label {
-  background :color_white
-  foreground :color_red
-}
-```
+class Person
+  attr_accessor :country, :country_options
 
-You may check out all available standard colors in `SWT` over here (having `COLOR_` prefix):
+  def initialize
+    self.country_options=["", "Canada", "US", "Mexico"]
+    self.country = "Canada"
+  end
 
-https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
+  def reset_country
+    self.country = "Canada"
+  end
+end
 
-### Fonts
+class HelloCombo
+  include Glimmer
+  def launch
+    person = Person.new
+    shell {
+      composite {
+        combo(:read_only) {
+          selection bind(person, :country)
+        }
+        button {
+          text "Reset"
+          on_widget_selected do
+            person.reset_country
+          end
+        }
+      }
+    }.open
+  end
+end
 
-Fonts are represented in Glimmer as a hash of name, height, and style keys.
+HelloCombo.new.launch
+```
 
-The style can be one (or more) of 3 values: `:normal`, `:bold`, and `:italic`
+`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:
+Example from [hello_list_single_selection.rb](https://github.com/AndyObtiva/glimmer/blob/master/samples/hello_list_single_selection.rb) sample:
+
+![Hello List Single Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-single-selection.png)
 
 ```ruby
-label {
-  font name: 'Arial', height: 36, style: :normal
-}
+shell {
+  composite {
+    list {
+      selection bind(person, :country)
+    }
+    button {
+      text "Reset"
+      on_widget_selected do
+        person.reset_country
+      end
+    }
+  }
+}.open
 ```
 
-Keys are optional, so some of them may be left off.
-When passing multiple styles, they are included in an array.
+`list` widget is also data-bound to the country of a person similarly to the combo widget. Not much difference here (the rest of the code not shown is the same).
 
-Example:
+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.
+
+![Hello List Multi Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-multi-selection.png)
 
 ```ruby
-label {
-  font style: [:bold, :italic]
-}
+class Person
+  attr_accessor :provinces, :provinces_options
+
+  def initialize
+    self.provinces_options=[
+      "",
+      "Quebec",
+      "Ontario",
+      "Manitoba",
+      "Saskatchewan",
+      "Alberta",
+      "British Columbia",
+      "Nova Skotia",
+      "Newfoundland"
+    ]
+    self.provinces = ["Quebec", "Manitoba", "Alberta"]
+  end
+
+  def reset_provinces
+    self.provinces = ["Quebec", "Manitoba", "Alberta"]
+  end
+end
+
+class HelloListMultiSelection
+  include Glimmer
+  def launch
+    person = Person.new
+    shell {
+      composite {
+        list(:multi) {
+          selection bind(person, :provinces)
+        }
+        button {
+          text "Reset"
+          on_widget_selected do
+            person.reset_provinces
+          end
+        }
+      }
+    }.open
+  end
+end
+
+HelloListMultiSelection.new.launch
 ```
 
-### Data-Binding
+The Glimmer code is not much different from above except for passing the `:multi` style to the `list` widget. However, the model code behind the scenes is quite different as it is a `provinces` array bindable to the selection of multiple values on a `list` widget. `provinces_options` contains all available province values just as expected by a single selection `list` and `combo`.
 
-Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
+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).
 
-Data-binding examples:
-- `text bind(contact, :first_name)`
-- `text bind(contact, 'address.street')`
-- `text bind(contact, 'addresses[1].street')`
-- `text bind(contact, :age, computed_by: :date_of_birth)`
-- `text bind(contact, :name, computed_by: [:first_name, :last_name])`
-- `text bind(contact, 'profiles[0].name', computed_by: ['profiles[0].first_name', 'profiles[0].last_name'])`
+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](https://github.com/AndyObtiva/glimmer/tree/master/samples) directory.
 
-The 1st example binds the text property of a widget like `label` to the first name of a contact model.
+### Observer
 
-The 2nd example binds the text property of a widget like `label` to the nested street of
-the address of a contact. This is called nested property data binding.
+Glimmer comes with `Observer` module, which is used internally for data-binding, but can also be used externally for custom use of the Observer Pattern. It is hidden when observing widgets, and used explicitly when observing models.
 
-The 3rd example binds the text property of a widget like `label` to the nested indexed address street of a contact. This is called nested indexed property data binding.
+#### Observing Widgets
 
-The 4th example demonstrates computed value data binding whereby the value of `age` depends on changes to `date_of_birth`.
+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.
 
-The 5th example demonstrates computed value data binding whereby the value of `name` depends on changes to both `first_name` and `last_name`.
+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".
 
-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`.
+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
 
-You may learn more about Glimmer's syntax by reading the Eclipse Zone Tutorial mentioned in resources and opening up the samples under the [samples](https://github.com/AndyObtiva/glimmer/tree/master/samples) directory.
+It has `addSelectionListener`. Additionally, under its `Control` super class, it has `addControlListener`, `addDragDetectListener`, `addFocusListener`, `addGestureListener`, `addHelpListener`, `addKeyListener`, `addMenuDetectListener`, `addMouseListener`, `addMouseMoveListener`, `addMouseTrackListener`, `addMouseWheelListener`, `addPaintListener`, `addTouchListener`, and `addTraverseListener`
 
-### Observer
+Suppose, we select `addSelectionListener`, which is responsible for what happens when a user selects a button (clicks it). Then, open its argument `SelectionListener` SWT API, and you find the event (instance) methods: `widgetDefaultSelected` and `widgetSelected​`. Let's select the second one, which is what gets invoked when a button is clicked.
+
+Now, Glimmer simplifies the process of hooking into that listener (observer) by neither requiring you to call the `addSelectionListener` method nor requiring you to implement/extend the `SelectionListener` API.
+
+Instead, simply add a `on_widget_selected` followed by a Ruby block containing the logic to perform. Glimmer figures out the rest.
+
+Let's revisit the Tic Tac Toe example shown near the beginning of the page:
+
+```ruby
+shell {
+  text "Tic-Tac-Toe"
+  composite {
+    grid_layout 3, true
+    (1..3).each { |row|
+      (1..3).each { |column|
+        button {
+          layout_data :fill, :fill, true, true
+          text        bind(@tic_tac_toe_board[row, column], :sign)
+          enabled     bind(@tic_tac_toe_board[row, column], :empty)
+          on_widget_selected {
+            @tic_tac_toe_board.mark_box(row, column)
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Note that every Tic Tac Toe grid cell has its `text` and `enabled` properties data-bound to the `sign` and `empty` attributes on the `TicTacToeBoard` model respectively.
 
-Glimmer comes with `Observer` module, which is used internally for data-binding, but can also be used externally for custom use of the Observer Pattern.
+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.
 
-In summary, the class that needs to observe an object, must include Observer and implement `#call(new_value)` method. The class to be observed doesn't need to do anything. It will automatically be enhanced by Glimmer for observation.
+#### 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.
 
 To register observer, one has to call the `#observe` method and pass in the observable and the property(ies) to observe.
 
@@ -743,7 +999,11 @@ Here is the SWT API:
 
 https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
 
-Here is a list of SWT widgets:
+Here is a visual list of SWT widgets:
+
+https://www.eclipse.org/swt/widgets/
+
+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
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glimmer
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - AndyMaleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-25 00:00:00.000000000 Z
+date: 2020-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement