glimmer 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d35080737c8d31d9ede07328113372b4a79100d5ce2269f027e389923fbf93b5
-  data.tar.gz: c3d8e4852e4f36cb3de1adcb2552d4562c6460e68f49c33598de5c2e36c1e486
+  metadata.gz: d1c351e3623c60e0ae9e52ce1f33b1579b5a3bb1cfc161c1eb2b6883bfe905b6
+  data.tar.gz: 4bb0c04faf2a1a9c68ac58f2acb386112f3706c7fae34c2e1c7dba9c99783f60
 SHA512:
-  metadata.gz: 7a46acf87df92892d34477af6a0e69b8ec0fe3bfdbee4c45dd94f08a0eb6098724e785d2f2109c73663c278f7a1a5141d0b45ff26f5bfa6fd07f99653d1fc419
-  data.tar.gz: af7430e47c5d5875bf1314bbb77055be6927baffaf4435ee25241cda4955bb1bf9c5dab29d7c07a5dde158c09ad39c2bb55b46dba9fcdbe7bd86f3c4c293cf79
+  metadata.gz: 42f75cb443468b0b4f9487b333882c1517803b66ce326c63b28780c9c98e809b27ce6cd2ce9928c61dc9f399c9ac2bd859a4c1910040869963e912893f87ddca
+  data.tar.gz: 5b4bed4b26bc8aed20c996bf21b24bcc26860ea06433a053faf0ad011921fb63f84f963750a5a03e64b089602a27a28b6fcee72a08f09a21a4a5d26ed29b9575

data/README.markdown

@@ -1,4 +1,4 @@
-# Glimmer 0.5.8 Beta (JRuby Desktop UI DSL + Data-Binding)
+# Glimmer 0.5.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 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.
@@ -70,7 +70,7 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
 ## Table of Contents
 
 <!-- TOC START min:1 max:3 link:true asterisk:false update:true -->
-- [Glimmer 0.5.8 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding)
+- [Glimmer 0.5.9 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding)
   - [Examples](#examples)
     - [Hello World](#hello-world)
     - [Tic Tac Toe](#tic-tac-toe)
@@ -163,14 +163,14 @@ Please follow these instructions to make the `glimmer` command available on your
 
 Run this command to install directly:
 ```
-jgem install glimmer -v 0.5.8
+jgem install glimmer -v 0.5.9
 ```
 
 ### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.5.8'
+gem 'glimmer', '~> 0.5.9'
 ```
 
 And, then run:
@@ -367,84 +367,27 @@ shell {
 }.open
 ```
 
-#### Menus
-
-Glimmer DSL provides support for SWT Menu and MenuItem widgets.
-
-There are 2 main types of menus in SWT:
-- Menu Bar (shows up on top)
-- Pop Up Menu (shows up when right-clicking a widget)
-
-Underneath both types, there can be a 3rd menu type called Drop Down.
-
-Glimmer provides special support for Drop Down menus as it automatically instantiates associated Cascade menu items and wires together with proper parenting, swt styles, and calling setMenu.
+#### Display
 
-The ampersand symbol indicates the keyboard shortcut key for the menu item (e.g. '&Help' can be triggered on Windows by hitting ALT+H)
-
-Example [Menu Bar] (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage UI globally 
+and access available monitors. 
+It is automatically instantiated upon first instantiation of a `shell` widget. 
+Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
+automatically uses the display created earlier without having to explicitly hook it.
 
 ```ruby
-shell {
-  menu_bar {
-    menu {
-      text "&File"
-      menu_item {
-        text "E&xit"
-      }
-      menu_item(0) {
-        text "&New"
-      }
-      menu(1) {
-        text "&Options"
-        menu_item(:radio) {
-          text "Option 1"
-        }
-        menu_item(:separator)
-        menu_item(:check) {
-          text "Option 3"
-        }
-      }
-    }
-    menu {
-      text "&History"
-      menu {
-        text "&Recent"
-        menu_item {
-          text "File 1"
-        }
-        menu_item {
-          text "File 2"
-        }
-      }
-    }
-  }
-}.open
-```
-
-Example [Pop Up Menu] (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
-
-```ruby
-shell {
-  label {
-    text 'Right-Click Me'
-    menu {
-      menu {
-        text '&History'
-        menu {
-          text "&Recent"
-          menu_item {
-            text "File 1"
-          }
-          menu_item {
-            text "File 2"
-          }
-        }
-      }
-    }
+@display = display {
+  cursor_location 300, 300
+  on_event_keydown {
+    # ...
   }
-}.open
+  # ...
+}
+@shell = shell { # uses display created above
+}
 ```
-
+The benefit of instantiating an SWT Display explicitly is to set [Properties](#widget-properties) or [Observers](#observer). 
+Although SWT Display is not technically a widget, it has similar APIs in SWT and similar DSL support in Glimmer.
 
 #### SWT Proxies
 
@@ -461,7 +404,6 @@ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT o
 
 These proxy objects have an API and provide some convenience methods, some of which are mentioned below.
 
-
 ##### `#content { ... }`
 
 Glimmer allows re-opening any widget and adding properties or extra content after it has been constructed already by using the `#content` method.
@@ -521,6 +463,86 @@ Shell widget proxy has extra methods specific to SWT 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.
+- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
+- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
+
+#### Menus
+
+Glimmer DSL provides support for SWT Menu and MenuItem widgets.
+
+There are 2 main types of menus in SWT:
+- Menu Bar (shows up on top)
+- Pop Up Menu (shows up when right-clicking a widget)
+
+Underneath both types, there can be a 3rd menu type called Drop Down.
+
+Glimmer provides special support for Drop Down menus as it automatically instantiates associated Cascade menu items and wires together with proper parenting, swt styles, and calling setMenu.
+
+The ampersand symbol indicates the keyboard shortcut key for the menu item (e.g. '&Help' can be triggered on Windows by hitting ALT+H)
+
+Example [Menu Bar] (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+shell {
+  menu_bar {
+    menu {
+      text "&File"
+      menu_item {
+        text "E&xit"
+      }
+      menu_item(0) {
+        text "&New"
+      }
+      menu(1) {
+        text "&Options"
+        menu_item(:radio) {
+          text "Option 1"
+        }
+        menu_item(:separator)
+        menu_item(:check) {
+          text "Option 3"
+        }
+      }
+    }
+    menu {
+      text "&History"
+      menu {
+        text "&Recent"
+        menu_item {
+          text "File 1"
+        }
+        menu_item {
+          text "File 2"
+        }
+      }
+    }
+  }
+}.open
+```
+
+Example [Pop Up Menu] (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
+
+```ruby
+shell {
+  label {
+    text 'Right-Click Me'
+    menu {
+      menu {
+        text '&History'
+        menu {
+          text "&Recent"
+          menu_item {
+            text "File 1"
+          }
+          menu_item {
+            text "File 2"
+          }
+        }
+      }
+    }
+  }
+}.open
+```
 
 ### Widget Styles
 
@@ -1064,7 +1086,9 @@ Glimmer supports observing widgets with two main types of events:
 1. `on_{swt-listener-method-name}`: where {swt-listener-method-name} is replaced with the lowercase underscored event 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)
 
-Additionally, the `shell` widget supports a 3rd type on the Mac, application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
+Additionally, there are two more types of events:
+- SWT `display` supports global listeners called filters that run on any widget. They are hooked via `on_event_{swt-event-constant}`
+- the `shell` widget supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
 
 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.
 
@@ -1651,21 +1675,51 @@ shell {
 
 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:
+If you cloned the project and followed [CONTRIBUTING.md](CONTRIBUTING.md) instructions, you may run all samples at once via `samples/launch` command:
 
 ```
+samples/launch
+```
+
+### Hello Samples
+
+For "Hello, World!" type samples, check the following:
+
+```
+glimmer samples/hello_world.rb
+glimmer samples/hello_browser.rb
 glimmer samples/hello_tab.rb
 glimmer samples/hello_combo.rb
 glimmer samples/hello_list_single_selection.rb
 glimmer samples/hello_list_multi_selection.rb
-glimmer samples/contactmanager/contact_manager.rb
+glimmer samples/hellocomputed/hello_computed.rb
+glimmer samples/video/hello_video.rb
+glimmer samples/video/hello_looped_video_with_black_background.rb
+glimmer samples/video/hello_video_observers.rb
+```
+
+### Elaborate Samples
+
+For more elaborate samples, check the following:
+
 ```
+glimmer samples/login.rb # demonstrates basic data-binding
+glimmer samples/contactmanager/contact_manager.rb # demonstrates table data-binding
+glimmer samples/tictactoe/tic_tac_toe.rb # demonstrates a full MVC application
+glimmer samples/gladiator.rb # demonstrates a text editor with tree/list data-binding
+```
+
+![Gladiator](images/glimmer-gladiator.png)
 
-The last example (`contact_manager.rb`) is a good sample about how to build tables with Glimmer including data-binding, filtering, and sorting. It even comes with specs in `spec/samples/contactmanager/contact_manager_presenter_spec.rb` to demonstrate how Glimmer facilitates TDD (test-driven development) with the Model View Presenter pattern (a variation on MVC) by separating testable presentation logic from the view layer with data-binding.
+Gladiator (short for Glimmer Editor) is an on-going sample project with continuous development.
+It is also used as the main text editor for coding Glimmer.
+As such, it has been made available in [Glimmer's gem](https://rubygems.org/gems/glimmer) via the `gladiator` command should others find useful too.
+If you cloned this project and followed [CONTRIBUTING.md](CONTRIBUTING.md) instructions, you may invoke via `bin/gladiator` instead. 
 
-For a more elaborate project built with Glimmer, check out this educational game:
+## In Production
 
-[Math Bowling](https://github.com/AndyObtiva/MathBowling)
+The following production apps have been built with Glimmer:
+- [Math Bowling](https://github.com/AndyObtiva/MathBowling): an educational math game for elementary level kids
 
 ## SWT Reference
 

data/bin/gladiator

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/glimmer/launcher'
+
+gladiator = File.expand_path('../../samples/gladiator.rb', __FILE__)
+Glimmer::Launcher.new([gladiator, '-J-Xrs'] + ARGV).launch

data/lib/glimmer.rb

@@ -84,3 +84,4 @@ require 'glimmer/swt/packages'
 require 'glimmer/dsl'
 require 'glimmer/error'
 require 'glimmer/invalid_keyword_error'
+require 'glimmer/ui/video'

data/lib/glimmer/data_binding/list_selection_binding.rb

@@ -44,7 +44,7 @@ module Glimmer
       end
 
       def evaluate_property
-        selection_array = @widget_proxy.swt_widget.send('selection').to_a
+        selection_array = @widget_proxy.swt_widget.send('selection').to_a #TODO refactor send('selection') into proper method invocation
         PROPERTY_EVALUATORS[@property_type].call(selection_array)
       end
     end

data/lib/glimmer/data_binding/widget_binding.rb

@@ -1,33 +1,33 @@
-require 'glimmer'
-require_relative 'observable'
-require_relative 'observer'
-
-module Glimmer
-  module DataBinding
-    class WidgetBinding
-      include Glimmer
-      include Observable
-      include Observer
-
-      attr_reader :widget, :property
-      def initialize(model, property, translator = nil)
-        @widget = model
-        @property = property
-        @translator = translator || proc {|value| value}
-
-        if @widget.respond_to?(:dispose)
-          @widget.on_widget_disposed do |dispose_event|
-            unregister_all_observables
-          end
-        end
-      end
-      def call(value)
-        converted_value = translated_value = @translator.call(value)
-        @widget.set_attribute(@property, converted_value) unless evaluate_property == converted_value
-      end
-      def evaluate_property
-        @widget.get_attribute(@property)
-      end
-    end
-  end
-end
+require 'glimmer'
+require_relative 'observable'
+require_relative 'observer'
+
+module Glimmer
+  module DataBinding
+    class WidgetBinding
+      include Glimmer
+      include Observable
+      include Observer
+
+      attr_reader :widget, :property
+      def initialize(model, property, translator = nil)
+        @widget = model
+        @property = property
+        @translator = translator || proc {|value| value}
+
+        if @widget.respond_to?(:dispose)
+          @widget.on_widget_disposed do |dispose_event|
+            unregister_all_observables
+          end
+        end
+      end
+      def call(value)
+        converted_value = translated_value = @translator.call(value)
+        @widget.set_attribute(@property, converted_value) unless evaluate_property == converted_value
+      end
+      def evaluate_property
+        @widget.get_attribute(@property)
+      end
+    end
+  end
+end

data/lib/glimmer/dsl/custom_widget_expression.rb

@@ -3,7 +3,6 @@ require 'glimmer/dsl/expression'
 require 'glimmer/dsl/parent_expression'
 require 'glimmer/ui/custom_widget'
 require 'glimmer/ui/custom_shell'
-require 'glimmer/ui/video' # this is interpreted here since it's a custom widget
 
 module Glimmer
   module DSL

data/lib/glimmer/dsl/display_expression.rb

@@ -1,9 +1,11 @@
 require 'glimmer/dsl/static_expression'
+require 'glimmer/dsl/parent_expression'
 require 'glimmer/swt/display_proxy'
 
 module Glimmer
   module DSL
     class DisplayExpression < StaticExpression
+      include ParentExpression
       def interpret(parent, keyword, *args, &block)
         SWT::DisplayProxy.instance(*args)
       end

data/lib/glimmer/dsl/tree_items_data_binding_expression.rb

@@ -8,16 +8,15 @@ module Glimmer
       include_package 'org.eclipse.swt.widgets'
 
       def can_interpret?(parent, keyword, *args, &block)
-        keyword == "items" and
-          block.nil? and
-          widget?(parent) and
-          parent.swt_widget.is_a?(Tree) and
-          args.size == 2 and
-          args[0].is_a?(DataBinding::ModelBinding) and
-          !args[0].evaluate_property.is_a?(Array) and
-          args[1].is_a?(Array) and
-          !args[1].empty? and
-          args[1].first.is_a?(Hash)
+        initial_condition = ((keyword == "items") and block.nil? and widget?(parent) and parent.swt_widget.is_a?(Tree))
+        return false unless initial_condition
+        raise Glimmer::Error, 'Tree items args must be 2' unless args.size == 2
+        raise Glimmer::Error, 'Tree items first arg must be a bind expression' unless args[0].is_a?(DataBinding::ModelBinding)
+        raise Glimmer::Error, 'Tree items data-binding initial value must not be an array yet a single item representing tree root' unless !args[0].evaluate_property.is_a?(Array)
+        raise Glimmer::Error, 'Tree items second arg must be an array' unless args[1].is_a?(Array)
+        raise Glimmer::Error, 'Tree items second arg must not be empty' unless !args[1].empty?
+        raise Glimmer::Error, 'Tree items second arg array elements must be of type hash' unless args[1].first.is_a?(Hash)
+        true
       end
 
       def interpret(parent, keyword, *args, &block)

data/lib/glimmer/dsl/widget_listener_expression.rb

@@ -1,4 +1,5 @@
 require 'glimmer/dsl/expression'
+require 'glimmer/swt/display_proxy'
 
 module Glimmer
   module DSL
@@ -8,9 +9,9 @@ module Glimmer
       def can_interpret?(parent, keyword, *args, &block)
         Glimmer.logger&.debug "keyword starts with on_: #{keyword.start_with?('on_')}"
         return false unless keyword.start_with?('on_')
-        widget_parentage = widget?(parent)
-        Glimmer.logger&.debug "parent is a widget: #{widget_parentage}"
-        return false unless widget_parentage
+        widget_or_display_parentage = widget?(parent) || parent.is_a?(SWT::DisplayProxy)
+        Glimmer.logger&.debug "parent is a widget or display: #{widget_or_display_parentage}"
+        return false unless widget_or_display_parentage
         Glimmer.logger&.debug "block exists?: #{!block.nil?}"
         raise Glimmer::Error, "Listener is missing block for keyword: #{keyword}" unless block_given?
         Glimmer.logger&.debug "args are empty?: #{args.empty?}"