limelight 0.2.0-java → 0.2.1-java

data/lib/limelight/file_chooser.rb

@@ -4,18 +4,31 @@
 require 'limelight/file_filter'
 
 module Limelight
-  
+
+  # An object that manages the selection of a file on the file system.  When invoked, a file chooser window
+  # will pop up and allow the user to select a file.
+  #
   class FileChooser
     
     attr_reader :chooser, :chosen_file
-    
+
+    # Creates a new FileChooser. Options may include:
+    # * :description => a string describing the desired file
+    # * :parent => (required) the parent window
+    # * :directory => starting directory
+    # * :title => title of the window
+    # * :directories_only => boolean, true if the user must select a directory
+    # * :files_only => boolean, true if the user must select a file
+    #
     def initialize(options = {}, &filter)
       @options = options
       @parent = options[:parent]
       create_chooser
       @chooser.setFileFilter(FileFilter.new(@options[:description], &filter)) if filter
     end
-    
+
+    # Opens the windows and returns the chosen file.
+    #
     def choose_file
       returnVal = @chooser.showOpenDialog(@parent);
       

data/lib/limelight/file_filter.rb

@@ -2,17 +2,24 @@
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
 
 module Limelight
-  
+
+  # A FileFiler is used in conjunction with FileChooser.  It is used to help the user select only files of the
+  # desired type.
+  #
   class FileFilter < javax.swing.filechooser::FileFilter
     
     attr_reader :description, :filter
-    
+
+    # The filter parameter is a block that contains the logic to decide whether a given file is selectable or not.
+    #
     def initialize(description, &filter)
       super()
       @description = description
       @filter = filter
     end
-    
+
+    # Called to determine if a file is selectable.  Invokes the filter block.
+    #
     def accept(file)
       return @filter.call(file)
     end

data/lib/limelight/java_couplings.rb

@@ -1,32 +1,33 @@
 #- Copyright 2008 8th Light, Inc. All Rights Reserved.
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
-
-module Limelight
+    
+module Limelight #:nodoc:
 
   Main = Java::limelight.Main
   SceneLoader = Java::limelight.SceneLoader
   Context = Java::limelight.Context
   AnimationTask = Java::limelight.AnimationTask
 
-  module Styles
+  module Styles #:nodoc:
     Style = Java::limelight.styles.Style
     FlatStyle = Java::limelight.styles.FlatStyle
     RichStyle = Java::limelight.styles.RichStyle
     ScreenableStyle = Java::limelight.styles.ScreenableStyle
   end
 
-  module Util
+  module Util #:nodoc:
     Colors = Java::limelight.util.Colors
   end
 
-  module UI
+  module UI #:nodoc:
 
     ButtonGroupCache = Java::limelight.ui.ButtonGroupCache
 
-    module Model
+    module Model #:nodoc:
       Frame = Java::limelight.ui.model.Frame
       Panel = Java::limelight.ui.model.PropPanel
-      module Inputs
+
+      module Inputs #:nodoc:
        ButtonPanel = Java::limelight.ui.model.inputs.ButtonPanel
        CheckBoxPanel = Java::limelight.ui.model.inputs.CheckBoxPanel
        ComboBoxPanel = Java::limelight.ui.model.inputs.ComboBoxPanel
@@ -36,20 +37,20 @@ module Limelight
       end
     end
 
-    module Api
+    module Api #:nodoc:
       Scene = Java::limelight.ui.api.Scene
       Prop = Java::limelight.ui.api.Prop
       Stage = Java::limelight.ui.api.Stage
       Theater = Java::limelight.ui.api.Theater
     end
 
-    module Painting
+    module Painting #:nodoc:
       PaintAction = Java::limelight.ui.painting.PaintAction
     end
 
   end
 
-  module Util
+  module Util #:nodoc:
 
     Packer = Java::limelight.io.Packer
 

data/lib/limelight/java_util.rb

@@ -2,13 +2,41 @@
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
 
 class Class
-  
+
+  # Class level method to creates Java style getters.
+  #
+  #   getters :foo, :bar
+  #
+  # Creates the following methods:
+  #
+  #   def getFoo
+  #     return @foo
+  #   end
+  #
+  #   def getBar
+  #     return @bar
+  #   end
+  #
   def getters(*symbols)
     symbols.each do |symbol|
       self.class_eval "def get#{symbol.to_s.camalized}; return #{symbol}; end"
     end
   end
-  
+
+  # Class level method to creates Java style setters.
+  #
+  #   setters :foo, :bar
+  #
+  # Creates the following methods:
+  #
+  #   def setFoo(value)
+  #     @foo = value
+  #   end
+  #
+  #   def setBar(value)
+  #     @bar = value
+  #   end
+  #
   def setters(*symbols)
     symbols.each do |symbol|
       self.class_eval "def set#{symbol.to_s.camalized}(value); self.#{symbol} = value; end"
@@ -18,7 +46,12 @@ class Class
 end
 
 class String
-  
+
+  # Converts Ruby style names to Java style camal case.
+  #
+  #   "four_score".camalized # => "FourScore"
+  #   "and_seven_years".camalized(:lower) # => "andSevenYears"
+  #
   def camalized(starting_case = :upper)
     value = self.downcase.gsub(/[_| ]([a-z])/) { |match| match[-1..-1].upcase } 
     value = value[0..0].upcase + value[1..-1] if starting_case == :upper

data/lib/limelight/limelight_exception.rb

@@ -2,7 +2,9 @@
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
 
 module Limelight
-  
+
+  # Most exeception thrown by Limelight Ruby code will be of this type.
+  #
   class LimelightException < Exception
   end
   

data/lib/limelight/loaders/file_scene_loader.rb

@@ -4,7 +4,7 @@
 module Limelight
   module Loaders
     
-    class FileSceneLoader
+    class FileSceneLoader #:nodoc:
       
       include SceneLoader
     

data/lib/limelight/main.rb

@@ -0,0 +1,108 @@
+#- Copyright 2008 8th Light, Inc. All Rights Reserved.
+#- Limelight and all included source files are distributed under terms of the GNU LGPL.
+
+require 'limelight/commands'
+
+module Limelight
+
+  # Used to open and manage Limelight Productions.
+  #
+  # Productions may have a single scene or multiple scenes.
+  #
+  # Single-Scene Production Directory Structure:
+  #
+  #   - calculator
+  #   | - props.rb
+  #   | - styles.rb
+  #   | - players
+  #     | - <player_name>.rb
+  #     | - *
+  #   | - stages.rb
+  #   | - production.rb
+  #
+  # In a Single-Scene production, the scene name and production name are the same.  As seen above, both names are 'calculator'.
+  # Inside the scene there are three files and one directory, all of which are options.
+  #
+  # == props.rb
+  # This file defines the props contained in the scene
+  # See Limelight::PropBuilder
+  #
+  # == styles.rb
+  # This file defines the styles used in the scene
+  # See Limelight::StylesBuilder
+  #
+  # == players
+  # A directory containing all the players used in the scene.  Players are modules that are included by Prop objects.
+  # If you have a Prop named 'wall', then you may optionaly have a file named 'wall.rb' in the players directory.
+  # Inside 'wall.rb' you would define a module named 'Wall'.  All behavior defined in the Wall modules will automatically be included
+  # in every prop named 'wall'.
+  #
+  # == stages.rb
+  # This file uses a DSL to configure the stages that will be used in the production.
+  # See Limelight::StagesBuilder
+  #
+  # == production.rb
+  # This file uses a DSL to configure the current Production.
+  # See Limelight::ProductionBuilder
+  #
+  # Multiple-Scene Production Directory Structure:
+  #
+  #   - sandbox
+  #   | - stages.rb
+  #   | - production.rb
+  #   | - styles.rb
+  #   | - players
+  #     | - <player_name>.rb
+  #   | - fader
+  #     | - props.rb
+  #     | - styles.rb
+  #     | - players
+  #       | - <player_name>.rb
+  #   | - floater
+  #     | - props.rb
+  #     | - styles.rb
+  #     | - players
+  #       | - <player_name>.rb
+  #
+  # In a Multiple-Scene production, the production acquires that name of the root directory.  In this case the production is named 'sandbox'.
+  # Each directory inside the root directory is a scene.  This production has two scenes named 'fader' and 'floater'.  Each scene is structured
+  # the same as in a Single-Scene production with the exception of the 'stages.rb' file.  This file is specific to the production.  The production
+  # may contain a 'styles.rb' which contains styles used by multiple scenes.  If some players are used in multiple Scenes, then it is useful to
+  # to create a players directory in the Production root to hold the common players. Other files may exist in the directory structure and they will not
+  # conflict with Limelight.
+  #
+  # See Limelight::Commands
+  #
+  class Main
+
+    class << self
+
+      # Executes behavior of limelight command.
+      #
+      def run(args)
+        command_name = args.shift
+        command = Commands::COMMANDS[command_name]
+        if command
+          command.new.run(args)
+        else
+          usage
+        end
+      end
+
+      # Prints the usage of the limelight command.
+      #
+      def usage
+        puts "Usage: limelight <command> [options] [params]"
+        puts "commands:"
+        Commands::COMMANDS.keys.sort.each do |key|
+          command = Commands::COMMANDS[key]
+          puts "\t#{key}\t\t#{command.description}"
+        end
+      end
+    end
+
+
+  end
+
+
+end

data/lib/limelight/menu_bar.rb

@@ -2,48 +2,67 @@
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
 
 module Limelight
-  
-  class AnonymousActionListener
+
+  class AnonymousActionListener #:nodoc:
     include java.awt.event.ActionListener
-    
+
     def initialize(context, symbol)
       @context = context
       @symbol = symbol
     end
-    
+
     def actionPerformed(e)
       method = @context.method(@symbol)
       method.call
     end
   end
-  
+
+  # A class used to build menu bars using a DSL.
+  #
+  #  MenuBar.build(self) do
+  #    menu("File") do
+  #      item("Open", :open_chosen_scene)
+  #      item("Refresh", :reload)
+  #    end
+  #  end
+  #
+  # This example created one menu named 'File' with two menu items: 'Open' and 'Refresh'. The seconds parameter of the
+  # menu items is the symbol of a method on the context that will be invoked when the menu item is selected.
+  #
   class MenuBar
-    
+
     def self.build(context, &prop)
       builder = self.new(context)
       builder.instance_eval(&prop)
       return builder.menu_bar
     end
-    
+
     attr_reader :menu_bar
-    
+
+    # This builder must be provided with a context.  All menu item actions will be invoked on the context.
+    #
     def initialize(context)
       @context = context
       @menu_bar = javax.swing.JMenuBar.new
     end
-    
+
+    # Creates a new menu with the provided name
+    #
     def menu(name)
       @menu = javax.swing.JMenu.new(name)
       @menu_bar.add(@menu)
       yield
     end
-    
+
+    # Created a new menu item with the provided name.  The symbols paramter is the name of a method on the context
+    # that will be invoked when the item is selected.
+    #
     def item(name, symbol)
       menu_item = javax.swing.JMenuItem.new(name)
       @menu.add(menu_item)
       menu_item.addActionListener(AnonymousActionListener.new(@context, symbol))
     end
-    
+
   end
-  
+
 end

data/lib/limelight/paint_action.rb

@@ -4,8 +4,10 @@
 require 'limelight/pen'
 
 module Limelight
-  
-  class PaintAction 
+
+  # A PaintAction is created by Prop.after_painting.
+  #
+  class PaintAction #:nodoc:
     
     include UI::Painting::PaintAction
     

data/lib/limelight/pen.rb

@@ -2,48 +2,78 @@
 #- Limelight and all included source files are distributed under terms of the GNU LGPL.
 
 module Limelight
-  
+
+  # The Pen is acquired from Prop.pen.  It is used to draw directly on the screen withing the bounds of the prop
+  # from which the Pen was acquired.
+  #
+  # All points used by the Pen are relative to the bounds of the Prop.  The top left corner of the Prop is represented
+  # by the point (0, 0).  If a Prop has margin, border, or padding, the point (0, 0) may appear to be outside the Prop.  
+  #
   class Pen
     
     attr_accessor :context
-    
+
+    # It is constructed with a context which is essentially a java.awt.Graphic2D object.  Defaults are set:
+    # * color = "black"
+    # * width = 1
+    # * smooth = false
+    #
     def initialize(context)
       @context = context
       self.color = "black"
       self.width = 1
       self.smooth = false
     end
-    
+
+    # Sets the color of the Pen.  The passed value should be a string that either names a known color or specifies
+    # a hex color value.
+    #
     def color=(value)
       resolve_color = Util::Colors.resolve(value)
       @context.setColor(resolve_color)
     end
-    
+
+    # Sets the width, in pixels, of the pen.
+    #
     def width=(value)
       @context.setStroke(java.awt.BasicStroke.new(value))
     end
-    
+
+    # Specifies whether the pen will use anti-aliasing to draw smooth shapes or not.  Shapes will appear pixilated when
+    # smooth is set to false.
+    #
     def smooth=(value)
       hint = value ? java.awt.RenderingHints::VALUE_ANTIALIAS_ON : java.awt.RenderingHints::VALUE_ANTIALIAS_OFF
       @context.setRenderingHint(java.awt.RenderingHints::KEY_ANTIALIASING, hint)
     end
-    
+
+    # Draws a line from the point (x1, y1) to the point (x2, y2)
+    #
     def draw_line(x1, y1, x2, y2)
       @context.drawLine(x1, y1, x2, y2)
     end
-    
+
+    # Draws a rectangle with the top left corner at (x, y).
+    #
     def draw_rectangle(x, y, width, height)
       @context.drawRect(x, y, width, height)
     end
-    
+
+    # Fills a rectangle with the current color of the Pen.  The top left corner of the rectangle is (x, y).
+    #
     def fill_rectangle(x, y, width, height)
       @context.fillRect(x, y, width, height)
     end
-    
+
+    # Draws the largest oval that will fit in the specified rectangle.  The top left corner of the bounding
+    # rectangle is at (x, y).  The center of the oval will be at (x + width/2, y + height/2).
+    #
     def draw_oval(x, y, width, height)
       @context.drawOval(x, y, width, height)
     end
 
+    # Fills an oval specified by the bounding rectangle.  See draw_oval.  
+    #
     def fill_oval(x, y, width, height)
       @context.fillOval(x, y, width, height)
     end