sweetgui 0.0.3 → 0.0.4

data/lib/apps/objecttree.rb

@@ -1,3 +1,6 @@
+# This file is an application of the SWT module. JRubyUtils::RubyObjectBrowser may be
+# used to show the contents of an object.
+#--
 #   The contents of this file are subject to the Mozilla Public License
 #   Version 1.1 (the "License"); you may not use this file except in
 #   compliance with the License. You may obtain a copy of the License at
@@ -15,9 +18,8 @@
 #   Contributor(s):
 #      Johannes Rudolph <johannes_rudolph@gmail.com>
 
-#require '../swt'
-
 class Method
+  # get the name of the method
   def name
     method_field=Java::JavaClass.for_name('org.jruby.RubyMethod').declared_field('methodName')
     method_field.accessible=true
@@ -36,9 +38,14 @@ class ::SWT::TreeBuilder
   end
 end
 
+# some JRuby utilities
 module JRubyUtils
+  # A Browser of objects for JRuby
+  #
+  # link:../docs/object-tree.jpg
   class RubyObjectBrowser
     class << self
+      # Builds a tree which shows the structure of the given object
       def object_tree(object)
         SWT::Builder.go do
           shell "JRuby Object Viewer by JR - visit http://virtual-void.net" do

data/lib/swt.rb

@@ -1,3 +1,5 @@
+# SWT::Builder and SWT::TreeBuilder implementation
+#--
 #   The contents of this file are subject to the Mozilla Public License
 #   Version 1.1 (the "License"); you may not use this file except in
 #   compliance with the License. You may obtain a copy of the License at
@@ -18,10 +20,12 @@
 require 'java'
 
 module SWT
+  # see JRubyUtils::RubyObjectBrowser#object_tree
   def self.object_tree(o)
     require 'apps/objecttree'
     JRubyUtils::RubyObjectBrowser.object_tree o
   end
+
   class TreeCommand
     def initialize(parent)
       @parent=parent
@@ -165,28 +169,8 @@ module SWT
     end
     def invoke(stack)
       lastobject=stack.last.getData("object")
-      #puts "Laststack: #{stack.last} id: #{stack.last.hashCode} object: #{lastobject} id: #{lastobject.hashCode}"
       newobject=@exp.call(lastobject)
-      #class <<newobject
-      #  def last
-      #    @last
-      #  end
-      #  def last=(last)
-      #    @last=last
-      #  end
-      #  alias :old_dup :dup
-      #  def dup
-      #    new=old_dup
-      #    new.last=@last
-      #    puts "Object gets dupd: #{self} #{self.id}"
-      #  end
-      #end
-      #newobject.last=lastobject
-      #test=Java.java_to_ruby(newobject)
       stack.last.setData("object",newobject)
-      #test2=stack.last.getData("object")
-      #puts "Test: #{test}, Test2: #{test2} test1==test2: #{test==test2} test1===test2 #{test===test2} id:#{test.id} lasttree: #{stack.last.hashCode}"
-#     puts "ObjectCommand.invoke lastobject: #{lastobject} newobject: #{newobject} newobject.last: #{newobject.last}"
     end
   end
   class ChildrenCommand<ContainerTreeCommand
@@ -221,18 +205,56 @@ module SWT
       super if condition
     end
   end
+
+  # Used to describe Trees
+  #
+  # Example:
+  #   SWT::Builder.go do
+  #     shell "Example" do
+  #       tree :horizontalFill=>true,:verticalFill=>true do
+  #         child "Father" do
+  #           child "Peter"
+  #           child "Paul"
+  #           child "Mary"
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # But most of it's power lies in its 'children' and 'link' constructs:
+  #
+  #   kids=%w[Peter Paul Mary] # define some children
+  #   SWT::Builder.go do
+  #     shell "Example" do
+  #       tree :horizontalFill=>true,:verticalFill=>true do # some display styles
+  #         object {"Fritz"}
+  #         @father=child do  # safe this tree command for later
+  #           label {|object| "Father #{object}"} # we'll call him Father X
+  #           children lambda{kids} do # children will evaluate the given lambda when appropriate ...
+  #             label {|child| "#{child} (age:#{child.length})"} # ... and execute every child command for each child
+  #             link{@father} # since every child is a maybe-father, link back to father command, see what happens...
+  #           end # ... yeah, recursive reproduction
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # Since every command is evaluated lazily, it's possible to construct
+  # such infinite trees easily.
+  #
+  # See JRubyUtils::RubyObjectBrowser#object_tree for a more complex example.
   class TreeBuilder
     def initialize(&block)
       @current=ContainerTreeCommand.new nil
       instance_eval(&block)
     end
+    # Command to create a new tree column in a tree table
     def column(text)
       cmd=SimpleCommand.new @current
       @current.accept cmd
       class <<cmd
         include_class 'org.eclipse.swt.widgets.TreeColumn'
         def invoke(stack)
-#          puts "column invoke stack:#{stack}, name:#{@name}"
           stack.last.setHeaderVisible true
           tc=TreeColumn.new stack.last,Builder::RealSWT::NONE
           tc.setText @name
@@ -244,6 +266,7 @@ module SWT
       end
       cmd.name=text
     end
+    # Command which creates a new child if invoked
     def child(label=nil,&block)
       cmd=ChildCommand.new @current
       @current and @current.accept cmd
@@ -254,24 +277,37 @@ module SWT
       @current=old
       cmd
     end
+    # Command which will set the text of a specific column
+    # when invoked
     def cell(i,&block)
       @current.accept(LabelCommand.new(@current,block,i))
     end
+    # Command which will set the label  of the item
     def label(labelExp=nil,&block)
       block=lambda{labelExp} if labelExp
       @current.accept(LabelCommand.new(@current,block))
     end
+    # Command to set the object property of the item
     def object(&block)
       @current.accept(ObjectCommand.new(@current,block))
     end
+    # Command to set the image of a tree item
     def image(&block)
       @current.accept(ImageCommand.new(@current,block))
     end
+    # Link back to command used before, if the link command is
+    # invoked it simply delegates to the cmd given
     def link(cmd=nil,&block)
       cmd=block unless cmd
       #puts "Creating link with cmd=#{cmd}"
       @current.accept(SimpleCommand.new(@current, cmd))
     end
+    # Command which expands child items from a collection
+    #
+    # The collection has to be given as lambda (exp).
+    # It will be invoked when the children command is invoked.
+    # You may define child commands in a block, these will
+    # be executed for each child of the computed collection/array.
     def children(exp,&block)
       cmd=ChildrenCommand.new @current,exp
       @current.accept cmd
@@ -281,11 +317,14 @@ module SWT
       @current=old
       cmd
     end
+    # A shortcut command for a child without children
     def leaf(&block)
       child do
         label &block
       end
     end
+    # Command which acts as a container for other commands.
+    # It has no semantics on its own but just invokes it child commands.
     def container(&block)
       cmd=ContainerTreeCommand.new @current
       @current and @current.accept cmd
@@ -295,6 +334,8 @@ module SWT
       @current=old
       cmd
     end
+    # Command that will execute only if the condition given as 'exp' evaluates
+    # to a non-nil value. It will then invoke its child commands given in a block.
     def conditional(exp,&block)
       cmd=ConditionalCommand.new @current,exp
       @current.accept cmd
@@ -311,16 +352,12 @@ module SWT
       @current
     end
   end
-  class Builder
-    #class <<self
-    #  alias :old_include_class :include_class
-    #def include_class (name,&block)
-    #  cl=old_include_class name,&block
-    #  JavaUtilities.get_proxy_class(name).compile
-    #end
-    #end
 
+  # The heart of the SWT module: You may build GUIs with the Builder class
+  #
+  class Builder
     include_class 'org.eclipse.swt.widgets.Shell'
+    include_class 'org.eclipse.swt.events.SelectionListener'
     include_class 'org.eclipse.swt.widgets.Group'
     include_class 'org.eclipse.swt.widgets.Text'
     include_class 'org.eclipse.swt.widgets.Label'
@@ -335,10 +372,7 @@ module SWT
       'RealSWT'
     end
 
- #   def initialize#(&block)
-
-#    end
-
+    # takes a block of Builder language code, builds the screen and shows it
     def self.go(&block)
       shell=Builder.new.instance_eval(&block)
       shell.pack
@@ -347,6 +381,7 @@ module SWT
       run shell
     end
 
+    private
     def init_control(c,opts={})
       if c.getParent.getLayout.class==GridLayout
         gd=GridData.new
@@ -376,6 +411,8 @@ module SWT
       end
     end
 
+    public
+    # Create a shell (a toplevel window)
     def shell(title,columns=1,style=RealSWT::SHELL_TRIM,&block)
       res=Shell.new(Display.getDefault,style)
       res.setText title
@@ -383,15 +420,13 @@ module SWT
       fl.marginHeight=5
       fl.marginWidth=5
       res.setLayout fl
-#      oldparent=@parent
       @parent=res
-#      instance_eval(&block) if block_given?
-#      @parent=oldparent
       container(columns,&block)
-      #init_composite res,columns
       return res
     end
 
+    # Create an empty container (does not show anything). It's
+    # only supposed for layouting elements
     def container(columns=1,opts={},&block)
       opts[:style] or opts[:style]=RealSWT::NONE
       res=Composite.new(@parent,opts[:style])
@@ -399,6 +434,7 @@ module SWT
       return res
     end
 
+    # Create a group element with the given title
     def group(title,columns=1,style=RealSWT::NONE,&block)
       res=Group.new(@parent,style)
       res.setText title
@@ -406,14 +442,16 @@ module SWT
       return res
     end
 
+    # Create a text box. Sets the text if supplied
     def text(text=nil,style=RealSWT::BORDER)
-      #puts "Text: #{text}"
       res=Text.new(@parent,style)
       text and res.setText text
       init_control res
       return res
     end
 
+    # Create a label and show the text supplied.
+    # You may use any form of 'labeledText', 'labeledButton'...
     def label(text,style=RealSWT::NONE)
       res=Label.new(@parent,style)
       res.setText text
@@ -421,19 +459,33 @@ module SWT
       return res
     end
 
-    def button(text,style=RealSWT::NONE)
+    # Create a push button with the specified text
+    # If block is given this block will be called if button is pressed
+    def button(text,style=RealSWT::NONE,&block)
       res=Button.new(@parent,style)
       res.setText text
       init_control res
+      if block_given?
+        lis=SelectionListener.new
+        lis.instance_eval do
+          def widgetDefaultSelected(event)
+          end
+          def widgetSelected (event)
+            @block.call event
+          end
+          @block=block
+        end
+        res.addSelectionListener lis
+      end
       return res
     end
 
+    # Create Tree if block is given it is evaluated as TreeBuilder commands
     def tree(opts={:style=>RealSWT::BORDER},&block)
       opts[:style] or opts[:style]=RealSWT::BORDER
       res=Tree.new(@parent,opts[:style])
       init_control res,opts
       builder=TreeBuilder.new &block
-      #puts builder.current
       builder.run res
       res.pack
       return res
@@ -443,16 +495,17 @@ module SWT
       alias :old_method_missing method_missing
     end
 
-    def method_missing(id,*args)
-      #puts "ID:#{id.class.inspect}\t\targs:#{args.join ','}\t#{id=~/labeled(\w+)/}"
+    def method_missing(id,*args,&block)
       if id.to_s=~/labeled(\w+)/
         label args.shift
-        method($1.downcase).call *args
+        method($1.downcase).call *args,&block
       else
-        old_method_missing id,args
+        old_method_missing id,args,&block
       end
     end
 
+    # A helper function for dispatching SWT events.
+    # Blocks as long as the given shell is not disposed.
     def Builder.run(shell)
       d=shell.getDisplay
       while(!shell.isDisposed&&shell.isVisible) do

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: sweetgui
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
-date: 2006-09-19 00:00:00 +02:00
+  version: 0.0.4
+date: 2006-10-12 00:00:00 +02:00
 summary: "SWeeTgui: Fast building of SWT GUI screens for JRuby"
 require_paths: 
 - lib
@@ -31,8 +31,8 @@ files:
 - tests/ts_swt.rb
 - lib/apps
 - lib/swt.rb
-- lib/test2.class
 - lib/apps/objecttree.rb
+- docs/object-tree.jpg
 - icons/action_back.gif
 - icons/action_forward.gif
 - icons/action_go.gif