glimmer 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '039508d9d31dec60207c13aa5ab20abe07af71d5e1d06fa2e26694151e06a124'
-  data.tar.gz: 402f7855f32fa23a157d044dd5f080b7ab4a9c16c353ed209a14d46565ab2c9b
+  metadata.gz: cb4ee177a1d05942e3d76fd1af52f2d182a8141ffe70c2d15edb868d1c117f4c
+  data.tar.gz: 26302fbf093855d4c789431752d79b7bfd07e9a763538215cf8aebacbf3bb51f
 SHA512:
-  metadata.gz: 07ae480ae5c8807d663bead2005fd303f53238c3b8684e70b8e87c30341c119faf2a3420e25fa75037cd44019fc8ed7f09f7d0bb58bbe395e8fa353b29a5bbbf
-  data.tar.gz: cf4866df36d0fcd4dd75192e246edbf77bde8c63bd741adb5fc5969202415e22430b15091bac5b53a4dd9778f0f15679666d52f2cee2648b49836d1ac8ad4ee0
+  metadata.gz: c182686702c73057df5d04454804950002a63e58f9be27aeab6142bec34ae6aad35306390ed9d4978a9d235ee1cbb7b7b465126f4986163139d2e8781127bb6e
+  data.tar.gz: 4a6137b7b492595072795dcd641d7d1c9d1e9ef5da42e66397604249ab021d24645dc73faa321d645d2d51507899235134ab3eaa2b39d342b3514f6111d30e52

data/README.markdown

@@ -102,14 +102,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.0
+jgem install glimmer -v 0.4.1
 ```
 
 ### Option 2: Bundler
 
 Add the following to `Gemfile`:
 ```
-gem 'glimmer', '~> 0.4.0'
+gem 'glimmer', '~> 0.4.1'
 ```
 
 And, then run:
@@ -231,6 +231,118 @@ 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)
 
+### Layouts
+
+Glimmer lays widgets out visually using SWT layouts, which can only be set on composite widget and subclasses.
+
+The most common SWT layouts are:
+- `FillLayout`: lays widgets out in equal proportion horizontally or vertically with spacing/margin options
+- `RowLayout`: lays widgets out horizontally or vertically in varying proportions with advanced spacing/margin/justify options
+- `GridLayout`(**default**): lays widgets out in a grid with advanced spacing/margin/alignment/indentation options. This is the **default** layout in Glimmer. It is important to master.
+
+In Glimmer DSL, just like widgets, layouts can be specified with lowercase underscored names followed by a block containing properties (e.g. `RowLayout` is `row_layout`).
+
+Example:
+
+```ruby
+composite {
+  row_layout {
+    wrap true
+    pack false
+    justify true
+    type :vertical
+    margin_left 1
+    margin_top 2
+    margin_right 3
+    margin_bottom 4
+    spacing 5
+  }
+  # ... 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.
+
+```ruby
+composite {
+  row_layout(:horizontal)
+  # ... widgets follow
+}
+```
+
+Check out the samples directory for more advanced examples of layouts in Glimmer.
+
+**Defaults**:
+
+Glimmer composites always come with grid_layout by default, but you can still specify explicitly if you'd like to set specific properties on it.
+
+Glimmer shell always comes containing one composite by default that wraps around specified shell content. That specific composite (the one directly under shell) has fill_layout with :horizontal type.
+
+This is a great guide for learning more about SWT layouts:
+
+https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
+
+Also, for a reference, check the SWT API:
+
+https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
+
+### Layout Data
+
+Layouts organize widgets following common rules for all widgets directly under a composite. But, what if a specific widget needs its own rules. That's where layout data comes into play.
+
+By convention, SWT layouts expect widgets to set layout data with a class matching their class name with the word "Data" replacing "Layout":
+- `GridLayout` on a composite demands `GridData` on contained widgets
+- `RowLayout` on a composite demands `RowData` on contained widgets
+
+Not all layouts support layout data to further customize widget layouts. For example, `FillLayout` supports no layout data.
+
+Unlike widgets and layouts in Glimmer DSL, layout data is simply specified with `layout_data` keyword nested inside a widget block body, and followed by arguments and/or a block of its own properties. Glimmer automatically deduces layout data class name by convention as per rule above, with the assumption that the layout data class lives under the same exact Java package as the layout (one can set custom layout data that breaks convention if needed in rare cases. See code below for an example)
+
+Examples:
+
+```ruby
+composite {
+  row_layout(:horizontal)
+  label {
+    layout_data { # followed by properties
+      width 50
+      height 30
+    }
+  }
+  # ... more widgets follow
+}
+```
+
+```ruby
+composite {
+  grid_layout(3, false) # grid layout with 3 columns not of equal width
+  label {
+    # layout data followed by arguments passed to SWT constructor
+    layout_data(GSWT[:fill], GSWT[:end], true, false)
+  }
+}
+```
+
+```ruby
+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)
+  }
+}
+```
+
+**NOTE**: Layout data must never be reused between widgets. Always specify or clone again for every widget.
+
+This is a great guide for learning more about SWT layouts:
+
+https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
+
+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
 
 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.
@@ -410,7 +522,7 @@ https://wiki.eclipse.org/SWT_Widget_Style_Bits
 
 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 import a SWT Java package using `include_package`:
+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'
@@ -419,7 +531,7 @@ include_package 'org.eclipse.swt.layout'
 include_package 'org.eclipse.swt.graphics'
 ```
 
-Or only import a specific SWT Java class using `java_import`:
+To import a specific SWT Java class using `java_import`, add the following:
 
 ```ruby
 java_import 'org.eclipse.swt.SWT'
@@ -427,7 +539,7 @@ java_import 'org.eclipse.swt.SWT'
 
 This allows you to call SWT Java classes from Ruby without mentioning package namespaces.
 
-For example, after imports, `org.eclipse.swt.graphics.Color` can be referred to by just `Color`
+For example, after imports, `org.eclipse.swt.graphics.Color` can be referenced by just `Color`
 
 ## Girb (Glimmer irb)
 
@@ -488,41 +600,15 @@ jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer -S applic
 
 These features have been suggested. You might see them in a future version of Glimmer. You are welcome to contribute more feature suggestions.
 
-- Glimmer Application: provide a standard structure for building a Glimmer app
-- Glimmer Component: Glimmer already supports components by externalizing to objects, but it would be good if there is a module to include so Glimmer would automatically register
-a new component and extend the DSL with it
-- Glimmer Wizard: provide a standard structure for building a Glimmer wizard (multi-step/multi-screen process)
-- bind_collection: an iterator that enables spawning widgets based on a variable collection (e.g. `bind_collection('user.addresses') { |address| address_widget {...} }` spawns 3 `AddressWidget`s if `user.addresses` is set with 3 addresses; and replaces with 2 `AddressWidget`s if `user.addresses` is reset with 2 addresses only). Needs further thought on naming and functionality.
-- Automatic relayout of "glimmer components" when disposing one or as an option
-- Consider using Ruby Refinements for Glimmer
-- Add 'font' to Glimmer DSL to build font objects easily
-- Add grid layout support to Glimmer DSL to layout grid components easily
-- Add rerendering support to Glimmer to rerender any widget easily
-- Avoid disposing display when disposing a shell to allow recycling
-- Provide a display builder method to use independently of shell
-- Supported a single computed data binding as a string (not array)
-- Support data binding translator option via a block
-- Center windows upon launching
-- Add TruffleRuby support
-- Make Shell automatically use last instantiated Display if not disposed
-- Allow ability to instantiate Display independently of Shell
-
-## Release Notes
-
-[RELEASE.md](https://github.com/AndyObtiva/glimmer/blob/master/RELEASE.md)
+[TODO.md](https://github.com/AndyObtiva/glimmer/blob/master/TODO.md)
 
-## Contributing
+## Change Log
+
+[CHANGELOG.md](https://github.com/AndyObtiva/glimmer/blob/master/CHANGELOG.md)
 
-- Clone repo
-- Setup pre-requisites (installing JRuby via RVM on the Mac)
-- cd into project again to activiate RVM glimmer gemset
-- gem install bundler
-- bundle
-- rake # runs specs (ensure they finish successfully)
-- rake install # builds/installs glimmer gem to be able to run samples via (glimmer samples/**)
+## Contributing
 
-To run a specific spec, run:
-`rake SPEC=spec_file_path`
+[CONTRIBUTING.md](https://github.com/AndyObtiva/glimmer/blob/master/CONTRIBUTING.md)
 
 ## Contributors
 

data/lib/glimmer/command_handlers/layout_command_handler.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + "/../command_handler"
+require File.dirname(__FILE__) + "/models/g_layout"
+
+module Glimmer
+  class LayoutCommandHandler
+    include CommandHandler
+
+    include_package 'org.eclipse.swt.widgets'
+    include_package 'org.eclipse.swt.layout'
+
+    def can_handle?(parent, command_symbol, *args, &block)
+      parent.is_a?(GWidget) and
+        parent.widget.is_a?(Composite) and
+        command_symbol.to_s.end_with?('_layout') and
+        GLayout.layout_exists?(command_symbol.to_s)
+    end
+
+    def do_handle(parent, command_symbol, *args, &block)
+      Glimmer.logger.debug "Layout #{command_symbol} args are: #{args.inspect}"
+      GLayout.new(command_symbol.to_s, parent.widget, args)
+    end
+  end
+end

data/lib/glimmer/command_handlers/layout_data_command_handler.rb

@@ -0,0 +1,22 @@
+require File.dirname(__FILE__) + "/../command_handler"
+require File.dirname(__FILE__) + "/models/g_widget"
+require File.dirname(__FILE__) + "/models/g_layout_data"
+
+module Glimmer
+  class LayoutDataCommandHandler
+    include CommandHandler
+
+    include_package 'org.eclipse.swt.widgets'
+    include_package 'org.eclipse.swt.layout'
+
+    def can_handle?(parent, command_symbol, *args, &block)
+      parent.is_a?(GWidget) and
+        command_symbol.to_s == 'layout_data'
+    end
+
+    def do_handle(parent, command_symbol, *args, &block)
+      Glimmer.logger.debug "Layout Data args are: #{args.inspect}"
+      GLayoutData.new(parent.widget, args)
+    end
+  end
+end

data/lib/glimmer/command_handlers/models/g_layout.rb

@@ -0,0 +1,71 @@
+require_relative '../../parent'
+require_relative 'g_swt'
+
+module Glimmer
+  class GLayout
+    include_package 'org.eclipse.swt.layout'
+
+    include Parent
+
+    attr_reader :composite
+    attr_reader :layout
+
+    class << self
+      include_package 'org.eclipse.swt.layout'
+
+      def layout_exists?(underscored_layout_name)
+        begin
+          swt_layout_class_for(underscored_layout_name)
+          true
+        rescue NameError => e
+          false
+        end
+      end
+
+      # This supports layouts in and out of basic SWT
+      def swt_layout_class_for(underscored_layout_name)
+        swt_layout_name = underscored_layout_name.camelcase(:upper)
+        swt_layout_class = eval(swt_layout_name)
+        unless swt_layout_class.ancestors.include?(org.eclipse.swt.widgets.Layout)
+          raise NameError, "Class #{swt_layout_class} matching #{underscored_layout_name} is not a subclass of org.eclipse.swt.widgets.Layout"
+        end
+        swt_layout_class
+      rescue => e
+        Glimmer.logger.debug "#{e.message}\n#{e.backtrace.join("\n")}"
+        raise e
+      end
+    end
+
+    def initialize(underscored_layout_name, composite, args)
+      @underscored_layout_name = underscored_layout_name
+      @composite = composite
+      args = args.map {|arg| GSWT.constant(arg)}
+      @layout = self.class.swt_layout_class_for(underscored_layout_name).new(*args)
+      @composite.setLayout(@layout)
+    end
+
+    def process_block(block)
+      block.call(@layout)
+    end
+
+    def has_attribute?(attribute_name, *args)
+      @layout.respond_to?(attribute_setter(attribute_name), args)
+    end
+
+    def set_attribute(attribute_name, *args)
+      apply_property_type_converters(attribute_name, args)
+      @layout.send(attribute_setter(attribute_name), *args)
+    end
+
+    def apply_property_type_converters(attribute_name, args)
+      if args.count == 1 && GSWT.has_constant?(args.first)
+        args[0] = GSWT.constant(args.first)
+      end
+    end
+
+    def attribute_setter(attribute_name)
+      "#{attribute_name.to_s.camelcase(:lower)}="
+    end
+
+  end
+end

data/lib/glimmer/command_handlers/models/g_layout_data.rb

@@ -0,0 +1,55 @@
+require_relative '../../parent'
+require_relative 'g_swt'
+
+module Glimmer
+  class GLayoutData
+    include_package 'org.eclipse.swt.layout'
+
+    include Parent
+
+    attr_reader :widget
+    attr_reader :layout_data
+
+    def initialize(widget, args)
+      @widget = widget
+      args = args.map {|arg| GSWT.constant(arg)}
+      begin
+        @layout_data = swt_layout_data_class.new(*args)
+      rescue => e
+        Glimmer.logger.debug "#{e.message}\n#{e.backtrace.join("\n")}"
+        @layout_data = args.first if args.count == 1 
+      end
+      @widget.setLayoutData(@layout_data)
+    end
+
+    def process_block(block)
+      block.call(@layout)
+    end
+
+    def swt_layout_data_class
+      parent_layout_class_name = @widget.getParent.getLayout.class.name
+      layout_data_class_name = parent_layout_class_name.sub(/Layout$/, 'Data')
+      eval(layout_data_class_name)
+    end
+
+    def has_attribute?(attribute_name, *args)
+      @layout_data.respond_to?(attribute_setter(attribute_name), args)
+    end
+
+    def set_attribute(attribute_name, *args)
+      apply_property_type_converters(attribute_name, args)
+      @layout_data.send(attribute_setter(attribute_name), *args)
+    end
+
+    def apply_property_type_converters(attribute_name, args)
+      if args.count == 1 && GSWT.has_constant?(args.first)
+        args[0] = GSWT.constant(args.first)
+      end
+    end
+
+    def attribute_setter(attribute_name)
+      "#{attribute_name.to_s.camelcase(:lower)}="
+    end
+
+  end
+end

data/lib/glimmer/command_handlers/models/g_swt.rb

@@ -10,13 +10,20 @@ module Glimmer
       end
 
       def constant(symbol)
-        return symbol if symbol.is_a?(Integer)
+        return symbol unless symbol.is_a?(Symbol) || symbol.is_a?(String)
         swt_constant_symbol = symbol.to_s.upcase.to_sym
         SWT.const_get(swt_constant_symbol)
       rescue
         swt_constant_symbol = SWT.constants.find {|c| c.to_s.upcase == swt_constant_symbol.to_s}
         SWT.const_get(swt_constant_symbol)
       end
+
+      def has_constant?(symbol)
+        return false unless symbol.is_a?(Symbol) || symbol.is_a?(String)
+        !!constant(symbol)
+      rescue
+        false
+      end
     end
   end
 end

data/lib/glimmer/command_handlers/models/g_widget.rb

@@ -3,6 +3,7 @@ require_relative 'g_runnable'
 require_relative 'g_color'
 require_relative 'g_font'
 require_relative 'g_swt'
+require_relative '../../parent'
 
 module Glimmer
   class GWidget

data/lib/glimmer/command_handlers/{widget_method_command_handler.rb → property_command_handler.rb}

@@ -1,15 +1,15 @@
 require File.dirname(__FILE__) + "/../command_handler"
-require File.dirname(__FILE__) + "/models/g_widget"
 
 module Glimmer
-  class WidgetMethodCommandHandler
+  class PropertyCommandHandler
     include CommandHandler
 
     def can_handle?(parent, command_symbol, *args, &block)
-      parent.is_a?(GWidget) and
-      args.size > 0 and
-      block == nil and
-      parent.has_attribute?(command_symbol, *args)
+      parent.respond_to?(:set_attribute) and
+        parent.respond_to?(:has_attribute?) and
+        args.size > 0 and
+        block == nil and
+        parent.has_attribute?(command_symbol, *args)
     end
 
     def do_handle(parent, command_symbol, *args, &block)

data/lib/glimmer/command_handlers.rb

@@ -2,6 +2,8 @@ require_relative "command_handler_chain_factory"
 require_relative "command_handlers/color_command_handler"
 require_relative "command_handlers/display_command_handler"
 require_relative "command_handlers/shell_command_handler"
+require_relative "command_handlers/layout_command_handler"
+require_relative "command_handlers/layout_data_command_handler"
 require_relative "command_handlers/widget_listener_command_handler"
 require_relative "command_handlers/bind_command_handler"
 require_relative "command_handlers/tab_item_command_handler"
@@ -12,7 +14,7 @@ require_relative "command_handlers/tree_properties_data_binding_command_handler"
 require_relative "command_handlers/table_items_data_binding_command_handler"
 require_relative "command_handlers/table_column_properties_data_binding_command_handler"
 require_relative "command_handlers/data_binding_command_handler"
-require_relative "command_handlers/widget_method_command_handler"
+require_relative "command_handlers/property_command_handler"
 require_relative "command_handlers/widget_command_handler"
 
 module Glimmer
@@ -20,6 +22,8 @@ module Glimmer
   CommandHandlerChainFactory.def_dsl(:swt,
     DisplayCommandHandler.new,
     ShellCommandHandler.new,
+    LayoutDataCommandHandler.new,
+    LayoutCommandHandler.new,
     WidgetListenerCommandHandler.new,
     BindCommandHandler.new,
     TabItemCommandHandler.new,
@@ -31,7 +35,7 @@ module Glimmer
     TableColumnPropertiesDataBindingCommandHandler.new,
     DataBindingCommandHandler.new,
     ColorCommandHandler.new,
-    WidgetMethodCommandHandler.new,
+    PropertyCommandHandler.new,
     WidgetCommandHandler.new
   )
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glimmer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - AndyMaleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-16 00:00:00.000000000 Z
+date: 2020-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -161,10 +161,14 @@ files:
 - lib/glimmer/command_handlers/combo_selection_data_binding_command_handler.rb
 - lib/glimmer/command_handlers/data_binding_command_handler.rb
 - lib/glimmer/command_handlers/display_command_handler.rb
+- lib/glimmer/command_handlers/layout_command_handler.rb
+- lib/glimmer/command_handlers/layout_data_command_handler.rb
 - lib/glimmer/command_handlers/list_selection_data_binding_command_handler.rb
 - lib/glimmer/command_handlers/models/g_color.rb
 - lib/glimmer/command_handlers/models/g_display.rb
 - lib/glimmer/command_handlers/models/g_font.rb
+- lib/glimmer/command_handlers/models/g_layout.rb
+- lib/glimmer/command_handlers/models/g_layout_data.rb
 - lib/glimmer/command_handlers/models/g_runnable.rb
 - lib/glimmer/command_handlers/models/g_shell.rb
 - lib/glimmer/command_handlers/models/g_swt.rb
@@ -180,6 +184,7 @@ files:
 - lib/glimmer/command_handlers/models/table_items_binding.rb
 - lib/glimmer/command_handlers/models/tree_items_binding.rb
 - lib/glimmer/command_handlers/models/widget_binding.rb
+- lib/glimmer/command_handlers/property_command_handler.rb
 - lib/glimmer/command_handlers/shell_command_handler.rb
 - lib/glimmer/command_handlers/tab_item_command_handler.rb
 - lib/glimmer/command_handlers/table_column_properties_data_binding_command_handler.rb
@@ -188,7 +193,6 @@ files:
 - lib/glimmer/command_handlers/tree_properties_data_binding_command_handler.rb
 - lib/glimmer/command_handlers/widget_command_handler.rb
 - lib/glimmer/command_handlers/widget_listener_command_handler.rb
-- lib/glimmer/command_handlers/widget_method_command_handler.rb
 - lib/glimmer/parent.rb
 - lib/glimmer/shine.rb
 - lib/glimmer/swt_packages.rb