profligacy 0.4.1-jruby → 1.0-jruby

data/README

@@ -8,10 +8,6 @@ The project is hosted at:
 
 Where you can file bugs and other things, as well as download gems manually.
 
-== Motivation
-
-== Installing
-
 == License
 
 See the COPYING file included with the source.  It's the same license as Ruby but
@@ -19,4 +15,5 @@ Copyright Zed A. Shaw 2007 All Right Reserved.
 
 == Source Code
 
-Source is available from the ihate project page.
+Source is available from the ihate project page in the Files section as a .tgz
+source tarball.

data/Rakefile

@@ -13,9 +13,9 @@ setup_clean ["pkg", "lib/*.bundle", "lib/profligacy/*.class", "*.gem", ".config"
 setup_rdoc ['README', 'LICENSE', 'COPYING', 'lib/**/*.rb', 'doc/**/*.rdoc']
 
 desc "Does a full compile, test run"
-task :default => [:ragel, :test]
+task :default => ["lib/profligacy/parser.jar", :test]
 
-version="0.4.1"
+version="1.0"
 name="profligacy"
 
 setup_gem(name, version) do |spec|
@@ -30,9 +30,15 @@ setup_gem(name, version) do |spec|
   spec.platform = "jruby"
 end
 
-task :ragel do
+file "lib/profligacy/LELParser.java" => ["lib/profligacy/LELParser.rl"] do
   sh %{/usr/local/bin/ragel -J lib/profligacy/LELParser.rl | /usr/local/bin/rlgen-java -o lib/profligacy/LELParser.java}
+end
+
+file "lib/profligacy/LELParser.class" => ["lib/profligacy/LELParser.java"] do
   sh %{javac -target 1.5 lib/profligacy/LELParser.java}
+end
+
+file "lib/profligacy/parser.jar" => ["lib/profligacy/LELParser.class"] do
   Dir.chdir("lib") do 
     sh %{jar -cf profligacy/parser.jar profligacy/*.class}
   end
@@ -51,4 +57,4 @@ task :site do
   sh %{rsync -av doc/rdoc doc/site/output/* rubyforge.org:/var/www/gforge-projects/ihate/profligacy}
 end
 
-task :project => [:clean, :ragel, :default, :test, :rdoc, :package, :site]
+task :project => [:clean, :default, :test, :rdoc, :package, :site]

data/examples/layout_test.rb

@@ -1,4 +1,3 @@
-require 'profligacy/swing'
 require 'profligacy/lel'
 
 module Test

data/examples/utu_main.rb

@@ -9,7 +9,6 @@ require 'profligacy/lel'
 class ChatInterface
   include_package 'javax.swing'
   include_package 'java.awt'
-
   include Profligacy
 
   def initialize
@@ -110,4 +109,5 @@ class ChatInterface
   end
 end
 
-ChatInterface.new
+
+SwingUtilities.invoke_later proc { ChatInterface.new }.to_runnable

data/lib/profligacy/lel.rb

@@ -1,9 +1,14 @@
+require 'profligacy/swing'
 require 'profligacy/parser'
 require 'profligacy/swing-layout'
 
 module Profligacy
   include_package 'profligacy'
 
+  # This is passed to the parser to scan over the LEL expression
+  # initially and pull out the list of cell names that are going
+  # to be used.  The result of this scan is then used to create
+  # the contents and interactions structs.
   class LELNameScanner
     include Profligacy::LELParser::LELEventListener
     attr_reader :children
@@ -21,12 +26,16 @@ module Profligacy
     end
   end
 
+  # Used by Swing::Build as the listener for LELParser which configures
+  # a GroupLayout from the LEL expression.  See http://ihate.rubyforge.org/profligacy/lel.html
+  # for instructions on how to use LEL.
   class LELGroupLayout 
     include Profligacy::LELParser::LELEventListener
 
     include_package 'org.jdesktop.layout'
     include_class 'java.lang.Short'
 
+    # Takes a GroupLayout and the list of components to organize inside it.
     def initialize(layout, components)
       @layout = layout
       @hgroup = @layout.createSequentialGroup
@@ -41,15 +50,18 @@ module Profligacy
       horizontals_reset
     end
 
+    # Called when a '|' token is hit by the LELParser.
     def col
       horizontals_push; alignments_reset ; widths_reset
     end
 
+    # Called when a '[' token is hit by the LELParser.
     def ltab
       horizontals_reset
       @vertical = @layout.createBaselineGroup(true, false)
     end
 
+    # Called when a '^' or '.' token is hit by the LELParser.
     def valign(dir)
       case dir
       when "^" then @valign = GroupLayout::LEADING
@@ -59,6 +71,7 @@ module Profligacy
       end
     end
 
+    # Called when a name/id for a cell token is hit by the LELParser.
     def id(name)
       h = horizontals_cur
       component = @components[name]
@@ -71,11 +84,13 @@ module Profligacy
       end
     end
 
+    # Called when a ']' token is hit by the LELParser.
     def row
       @vgroup.add(@vertical);
       alignments_reset ; widths_reset ; heights_reset
     end
 
+    # Called when a '>' or '<' token is hit by the LELParser.
     def align(direction)
       case direction
       when "<" then @halign = GroupLayout::LEADING
@@ -85,18 +100,22 @@ module Profligacy
       end
     end
 
+    # Called when a '(#)' is hit (with # being some number) by the LELParser.
     def setwidth(width)
       @width = width
     end
 
+    # Called when a height is added to '(#,#)' expressions in the LELParser.
     def setheight(height)
       @height = height
     end
 
+    # Called when the cell should expand via a '*' token.
     def expand
       @max = Short::MAX_VALUE
     end
 
+    # Called when it's done parsing, and whether there was an error.
     def finished(error)
       if !error
         @layout.setHorizontalGroup(@hgroup);
@@ -106,28 +125,39 @@ module Profligacy
 
     private
 
+    # Resets the vertical and horizontal alignments when the end of a or row is
+    # passed.
     def alignments_reset
       @valign = GroupLayout::CENTER
       @halign = GroupLayout::CENTER
     end
 
+    # Same as alignments_reset but for the widths.
     def widths_reset
       @width = GroupLayout::DEFAULT_SIZE
       @max = GroupLayout::DEFAULT_SIZE
     end
 
+    # Resets the heights when the current row ends.
     def heights_reset
       @height = GroupLayout::DEFAULT_SIZE
     end
 
+    # The horizontal cells are organized in a dynamic array that's expanded as
+    # more are encountered.  Just like an old typewriter, when the current row
+    # ends the next column to work on is "reset" by starting at the first one.
+    # This method just resets it to be the next one.
     def horizontals_reset
       @htop = 0
     end
 
+    # Adds a new horizontal cell onto the list of cells being worked on.
     def horizontals_push
       @htop += 1
     end
 
+    # Either makes a new horizontal cell for the curent operation to work on,
+    # or just returns the existing one.
     def horizontals_cur
       if !@horizontals[@htop]
         @horizontals[@htop] = @layout.createParallelGroup()
@@ -141,12 +171,29 @@ module Profligacy
 
 
   module Swing
+
+    # Layout Expression Language is a small regex like wiki language used to
+    # specify complex layouts in a tiny amount of space.  The language is based on
+    # a Ragel based parser that configures a Swing GroupLayout with the right
+    # options to produce the desired effect.  An example of LEL is:
+    #
+    # 
+    #  @layout = "
+    #   [ label_1         | label3      ]
+    #   [ (300,300)*text1 | (150)people ]
+    #   [ <label2         | _           ]
+    #   [ .message        | ^buttons    ]"
+    #
+    # Which will produce a panel where you can place components.  Otherwise it works
+    # exactly like Swing::Build except you pass the LEL expression in to the constructor
+    # instead of an array of symbols.
+    #
+    # See http://ihate.rubyforge.org/profligacy/lel.html for more instructions.
     class LEL < Build
       include_package 'org.jdesktop.layout'
       attr_reader :prefs
 
       def initialize(type, expr)
-
         @expr = expr
         @container_class = type
         @parser = LELParser.new
@@ -196,6 +243,5 @@ module Profligacy
         end
       end
     end
-
   end
 end

data/lib/profligacy/swing.rb

@@ -2,14 +2,43 @@ require 'java'
 
 import 'javax.swing.SwingUtilities'
 
-module Profligacy
+
+# Profligacy is a library that helps to build Swing GUIs without getting the
+# way of the huge number of components and options available.  The approach
+# taken by Profligacy is to be a purposefully leaky abstraction.  Rather than
+# try to cover all the possible configurable options available to Swing, it
+# simply attempts to solve three problems:
+#
+# First, building a swing interface involves mixing the layout construction with the
+# widget construction.  This is solved by a few simple builders named
+# Swing::Build and Swing::LEL that help organize your components inside a 
+# given layout in a way that looks like Ruby and reduces tons of complexity.
+#
+# Second, using any of the more complex layouts like GridBagLayout or GroupLayout is
+# nasty.  This is solved by the Layout Expression Language that uses a wiki syntax
+# that matches like a regex and builds any configurable GroupLayout you might need.
+# It removes an *insane* amount of code you'd need to write by hand or the need for
+# an external tool to configure the layout.
+#
+# Writing Java callback Listeners and Runnables is a pain in the ass.  This is 
+# solved by an ugly hack where Profligacy generates a bunch of Listener -> Proc
+# converters for each of the bazillion Listener implementations that SWing loves
+# even though they all do the same damn thing anyway.
+#
+# See http://ihate.rubyforge.org/profligacy/ for more information.
+#
+module Profligacy 
   module Swing
     include_class 'java.lang.Runnable'
     include_package 'java.awt.event'
     include_package 'javax.swing.event'
-    include_package 'javax.swing'
+    include_package 'javax.swing' 
     include_package 'java.awt'
 
+    # This is used by the added Proc.to_runnable to make a Runnable 
+    # interface that just calls a proc anyway.  With this you can
+    # do proc { puts "hi" }.to_runnable and pass the result to
+    # threads and such.
     class RunnableProc
       include Runnable
       def initialize(&block)
@@ -22,6 +51,8 @@ module Profligacy
     end
 
 
+    # NOTHING TO SEE HERE.  GO AWAY.  THIS CODE IS WRONG WRONG WRONG
+    # AND WILL GO AWAY IN THE NEAR FUTURE.
     module Listeners
       AWT_LISTENERS = ["Action","Adjustment","AWTEvent","Component","Container","Focus",
           "HierarchyBounds","Hierarchy","InputMethod","Item","Key","Mouse",
@@ -36,24 +67,28 @@ module Profligacy
           "UndoableEdit", ]
 
       horrid_java_sucks_ass_hack = (SWING_LISTENERS + AWT_LISTENERS).collect do |listener|
-        <<-END
-      class #{listener}ListenerProc
-        include Profligacy::Swing::#{listener}Listener
+        "class #{listener}ListenerProc
+          include Profligacy::Swing::#{listener}Listener
 
-        def initialize(&block)
-          @block = block
-        end
+          def initialize(&block)
+            @block = block
+          end
 
-        def method_missing(symb, *args)
-          @block.call(symb, *args)
-        end
-      end
-    END
+          def method_missing(symb, *args)
+            @block.call(symb, *args)
+          end
+        end" 
       end
 
       module_eval horrid_java_sucks_ass_hack.join("\n")
     end
 
+    # The Swing::Build class doesn't actually do any swing stuff, but instead
+    # it organizes the common pattern of constructing components, attaching
+    # interaction procs or methods.
+    #
+    # See the many examples and instructions at http://ihate.rubyforge.org/profligacy/
+    # for more information.
     class Build
       attr_accessor :children
       attr_accessor :contents
@@ -63,16 +98,40 @@ module Profligacy
 
       include_package 'javax.swing'
 
+      # When you construct a Swing::Build you pass in the container
+      # to use as the first argument, and then symbols for the names 
+      # of the contents as the rest of the arguments.
+      #
+      #   ui = Swing::Build.new JFrame, :left, :right, :top do |c,i|
+      #     ...
+      #   end
+      #
+      # The Build class doesn't actually do anything with this until
+      # you call the Swing::Build.build method.  It just collects up
+      # the contents and interactions you attach to the c and i parameters
+      # in the block.
+      #
+      # The c and i parameters stand for contents and interactions and are
+      # a Ruby Struct objects that have the names you gave as elements.
+      # This means if you try to set one that doesn't exist you'll get an
+      # error (which is pretty handy).
       def initialize(*children)
         @container_class = children.shift
         setup_children_and_interactions(children)
         yield @contents, @interactions
       end
 
-      def interactions
-        yield @contents, @interactions
-      end
-
+      # Build will finally build the container you configured, passing any
+      # arguments to that container.  When it's done it returns the resulting
+      # container for you to modify.
+      #
+      # You can also attach a block to the method call that will be called
+      # with the container right before it's completed.  This lets you modify
+      # it at the right moment.  For example, if you need to set some options
+      # to a JFrame right before it's made visible.
+      #
+      # Finally, it's so common to make containers visible and pack them that
+      # this method will do that if the container has those methods.
       def build(*args)
         # create the container they ask for with these args
         @container = @container_class.new *args
@@ -102,6 +161,11 @@ module Profligacy
         @container
       end
 
+      # It's kind of a pain to always access ui.contents.thename so
+      # the method_missing simply lets you do ui.thename.  Won't work
+      # of course if your component is named "build", "children", 
+      # "contents", "interactions", "layout", "container" since those
+      # exist in the Build object already.
       def method_missing(symb, *args)
         @contents[symb]
       end
@@ -135,16 +199,27 @@ module Profligacy
         } if actions
       end
     end
+
+
   end
 end
 
+# Modifications to Proc to make the Runnable and Listener conversion easy.
 class Proc
+  # Takes this proc and converts it to an ListenerProc based on the action name.
+  # The name should be one in Profligacy::Listeners and is based on the add_blah_listener
+  # method on that component.  So, if you need a ChangeListener you do:
+  #
+  #   proc {|t,e| puts t }.to_listener(:change)
+  #
+  # The two parameters are a symbol for the method that Java called on this, and then the
+  # event argument.
   def to_listener(action)
     Profligacy::Swing::Listeners.const_get("#{action.to_s.capitalize}ListenerProc").new &self
   end
 
+  # Converts this Proc to a RunnableProc which implements the Runnable interface.
   def to_runnable
     Profligacy::Swing::RunnableProc.new &self
   end
 end
-

metadata

@@ -53,11 +53,11 @@ requirements: []
 authors: 
 - Zed A. Shaw
 platform: jruby
-date: 2007-07-09 04:00:00 +00:00
+date: 2007-07-11 04:00:00 +00:00
 require_paths: 
 - lib
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: !str 1.0
 test_files: []
 bindir: bin
 dependencies: []