limelight 0.2.0-java → 0.2.1-java

data/lib/limelight/prop_builder.rb

@@ -4,21 +4,63 @@
 require 'limelight/prop'
 require 'limelight/scene'
 require 'limelight/build_exception'
+require 'limelight/util'
 
 module Limelight
-  
+
+  # A trigger to build a Limelight::Scene using the PropBuilder DSL.
+  #
+  # See Limelight::PropBuilder
+  #
   def self.build_scene(options={}, &block)
     loader = options.delete(:build_loader)
     builder = SceneBuilder.new(options)
     builder.__loader__ = loader
-    builder.instance_eval(&block) if block
+    builder.instance_eval(&block) if block 
     return builder.__prop__
   end
-  
-  class PropBuilder
+
+  # The basis of the DSL for building Limelight::Prop objects.
+  #
+  # Sample usage:
+  #
+  #   builder = Limelight::PropBuilder.new(a_prop)
+  #   builder.instance_eval(&block)
+  #
+  # The prop passed into the constructor will be the root of the contructed Prop tree.
+  # The block passed into instance_eval contains the DSL for building props.
+  #
+  # Example block/DSL:
+  #
+  #   parent :id => "the_parent" do
+  #     child_one do
+  #       grand_child_one :id => "gc_1", :styles => "grand_child"
+  #       grand_child_two :id => "gc_2", :styles => "grand_child"
+  #     end
+  #     child_two
+  #   end
+  #
+  # The above example will create a Limelight::Prop named 'parent' and add it to the root prop passed into the builder.
+  # The 'parent' prop will contain two props named 'child_one' and 'child_two'.  'child_one' will contain two props named
+  # 'grand_child_one' and 'grand_child_two'.  'child_two' has no child props nor do 'grand_child_one' or 'grand_child_two'.
+  #
+  # An options Hash may be passed into each prop.  The key, value pairs in the hash will be used to set properties on the prop
+  # when it is added to a Limelight::Scene.
+  #
+  # See Limelight::Prop
+  #
+  class PropBuilder   
+
+    Limelight::Util.lobotomize(self)
+
+    # Returns the root prop either passed in or created by this builder.
+    #
     attr_reader :__prop__
     attr_accessor :__loader__
-    
+
+    # Creates a new builder.  If a prop is passed it, it will be the root on which props are created.
+    # If the paramter is a Hash, the Hash will be used to construct a prop that will be used as the root.
+    #
     def initialize(options)    
       if options.is_a?(Prop)
         @__prop__ = options
@@ -26,11 +68,27 @@ module Limelight
         @__prop__ = Prop.new(options)  
       end
     end
-    
+
+    # Add extra initialization options to the prop currently under construction.
+    #
+    #   tree :id => "stump" do
+    #     __ :height => "100%", :width => "30", :background_color => :brown
+    #     branch :height => "100", :width => "20"
+    #     branch do
+    #       __ :height => "100", :width => "20"
+    #     end
+    #   end
+    #
+    # In the above example, the 'tree' prop has the following initialization options: id, height, width, background_color.
+    # The two 'branch' child props are identical.
+    # 
     def __(options)
       @__prop__.add_options(options)
     end
-    
+
+    # Installs props from another file using the prop DSL.  The path will be relative to the
+    # root directory of the current production.
+    #
     def __install(file)
       raise "Cannot install external props because no loader was provided" if @__loader__.nil?
       raise "External prop file: '#{file}' doesn't exist" if !@__loader__.exists?(file)
@@ -41,8 +99,9 @@ module Limelight
         raise BuildException.new(file, content, e)
       end
     end
-    
-    def method_missing(sym, options={}, &prop)
+
+
+    def method_missing(sym, options={}, &prop) # :nodoc:
       options[:name] ||= sym.to_s
       builder = PropBuilder.new(options)
       builder.__loader__ = @__loader__
@@ -50,8 +109,8 @@ module Limelight
       @__prop__.add(builder.__prop__)
     end
   end
-  
-  class SceneBuilder < PropBuilder
+
+  class SceneBuilder < PropBuilder # :nodoc:
     def initialize(options)
       @__prop__ = Scene.new(options)
     end

data/lib/limelight/scene.rb

@@ -6,6 +6,10 @@ require 'limelight/prop'
 require 'limelight/button_group_cache'
 
 module Limelight
+
+  # A Scene is a root Prop.  Scenes may be loaded onto a Stage.  In addition to being a Prop object, Scenes have a
+  # few extra attributes and behaviors.
+  #
   class Scene < Prop
     
     include UI::Api::Scene
@@ -23,32 +27,26 @@ module Limelight
       illuminate
     end
   
-    def add_options(options)
+    def add_options(options) #:nodoc:
       @options = options
       illuminate
     end
-    
-    def illuminate
-      @styles = @options.has_key?(:styles) ? @options.delete(:styles) : (@styles || {})
-      @casting_director = @options.delete(:casting_director) if @options.has_key?(:casting_director)
-      super
-    end
-    
-    def has_static_size?
-      return is_static?(style.get_width) && is_static?(style.get_height)
-    end
-    
+
+    # Creates the menu bar for the Scene 
+    #
     def menu_bar
       return MenuBar.build(self) do
         menu("File") do
-          item("Open", :open_chosen_scene)
+          item("Open", :open_chosen_production)
           item("Refresh", :reload)
         end
       end
     end
-    
-    def open_chosen_scene
-      options = { :title => "Open New Limelight Scene", :description => "Limelight Production or Scene", :directory => @directory }
+
+    # Opens a FileChooser for a new Production.  Loads the chosen Production.
+    #
+    def open_chosen_production
+      options = { :title => "Open New Limelight Production", :description => "Limelight Production", :directory => @directory }
       chosen_file = stage.choose_file(options) { |file| Util.is_limelight_scene?(file) || Util.is_limelight_production?(file) }
       if chosen_file
         @directory = File.dirname(chosen_file)
@@ -56,19 +54,25 @@ module Limelight
       end
     end
 
+    # Creates a new Producer to open the specified Production.
+    #
     def open_production(production_path)
       producer = Producer.new(production_path, @production.theater)
       producer.open
     end
-    
-    def load(path)
-      @production.producer.open_scene(path, @stage)
+
+    # Opens the specified Scene on the Stage currently occupied by this Scene.s
+    #
+    def load(scene_name)
+      @production.producer.open_scene(scene_name, @stage)
     end
     
     private ###############################################
     
-    def is_static?(value)
-      return !(value.to_s.include?("%")) && !(value.to_s == "auto")
+    def illuminate
+      @styles = @options.has_key?(:styles) ? @options.delete(:styles) : (@styles || {})
+      @casting_director = @options.delete(:casting_director) if @options.has_key?(:casting_director)
+      super
     end
     
     def reload

data/lib/limelight/stage.rb

@@ -8,76 +8,118 @@ require 'limelight/file_chooser'
 require 'limelight/util'
 
 module Limelight
-  
+
+  # In the metephorical sense, a Stage is a platform which may hold a scene.  In a more, to-the-point sence, a Stage
+  # represents a window on the computer screen.  The Stage objects within a Production are configured by the StagesBuilder.
+  # By default a Production will have one Stage.  A Stage may open any number of Scenes but it may only have one current
+  # scene loaded at a time.
+  #
   class Stage
     attr_accessor :default_scene
     attr_reader :frame, :current_scene, :name, :theater
     
     include UI::Api::Stage
-    
-    def public_choose_file
-      choose_file
-    end
-    
+
+    # To create a new Stage, it be given a Theater to which it belongs, and the name is optional.  If no name is provided
+    # it will default to 'default'.  A stage name must be unique, so it is recommended you provide a name.
+    #
     def initialize(theater, name="default")
       @theater = theater
       @name = name
       build_frame
       self.title = @name
     end
-    
+
+    # Returns the title that is displayed at the top of the window that this stage represents.
+    #
     def title
       return @frame.title
     end
-    
+
+    # Sets the title that is displayed at the top of the window that this stage represents. 
+    #
     def title=(value)
       @frame.title = value
     end
-    
+
+    # Returns the width and height of the Stage.
+    #
+    #   width, height = stage.size
+    #
     def size
       return @frame.width, @frame.height
     end
-    
+
+    # Sets the width and height of the Stage. The dimensions are passed in as an array.
+    #
+    #   state.size = [100, 200]
+    #
     def size=(values)
       @frame.set_size(values[0], values[1])
     end
-    
+
+    # The location of the Stage on the screen.
+    #
+    #   x, y = stage.location
+    #
     def location
       return @frame.location.x, @frame.location.y
     end
-    
+
+    # Sets the location of the Stage on the screen.
+    #
+    #   stage.location = [500, 200]
+    #
     def location= values
       @frame.set_location(values[0], values[1])
     end
-    
+
+    # Opens the Stage and loads the provided Scene.
+    #
+    # See load_scene
+    #
     def open(scene)
       load_scene(scene)
       @frame.open
       scene.visible = true
       scene.scene_opened(self)
     end
-  
+
+    # Closes the Stage. It's window will no longer be displayed on the screen.
+    #
     def close
       @frame.close
     end
-    
+
+    # Loads a scene on the Stage.  If the Stage is currently hosting a Scene, the original Scene will be removed and
+    # the new Scene will replace it.
+    #
     def load_scene(scene)
       @frame.setJMenuBar(scene.menu_bar)
       @frame.load(scene.panel)
       scene.stage = self
       scene.panel.snap_to_size
-      if(scene.has_static_size?)
-        @frame.set_size(scene.panel.width, scene.panel.height)
+      if(has_static_size?(scene.style))
+        @frame.set_size(scene.panel.width + @frame.getHorizontalInsetWidth, scene.panel.height + @frame.getVerticalInsetWidth)
       end
       @current_scene = scene
     end
-    
+
+    # Opens a file chooser window to select a file on the file system. Options may include:
+    # * :description => a string describing the desired file
+    # * :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 choose_file(options={}, &block)
       options[:parent] = @frame
       chooser = FileChooser.new(options, &block)
       return chooser.choose_file
     end
 
+    # Pops up a simple modal dialog with the provided message.
+    #
     def alert(message)
       frame.alert(message)
     end
@@ -90,6 +132,14 @@ module Limelight
       @frame.set_location(200, 25)
       @frame.title = title
     end
+
+    def has_static_size?(style)
+      return is_static?(style.get_width) && is_static?(style.get_height)
+    end
+
+    def is_static?(value)
+      return !(value.to_s.include?("%")) && !(value.to_s == "auto")
+    end
     
   end
     

data/lib/limelight/stage_builder.rb

@@ -5,58 +5,99 @@ require 'limelight/stage'
 require 'limelight/limelight_exception'
 
 module Limelight
-  
+
+  # A trigger to build/configure Stage objects using the StageBuilder DSL.
+  #
+  # See Limelight::Stagesbuilder, Limelight::Stagebuilder
+  #
   def self.build_stages(theater, &block)
     builder = StagesBuilder.new(theater)
     builder.instance_eval(&block) if block
-    return builder.stages
+    return builder.__stages__
   end
-  
+
+  # The basis of the DSL for building Stage objects.
+  #
+  #  stage "inspector" do
+  #    default_scene "inspector"
+  #    title "Limelight Composer Inspector"
+  #    location [0, 0]
+  #    size [300, 800]
+  #  end
+  #
+  #  stage "viewer" do
+  #    title "Limelight Composer Viewer"
+  #    location [350, 0]
+  #    size [800, 800]
+  #  end
+  #
+  # In this example above, two stages are created for the production.  One is named 'inspector' and the other is named
+  # 'viewer'.  'inspector' has a default scene that will be loaded on startup.  'viewer' will not contain any scene
+  # on startup.  Using the DSL, each stage can be configured to set the title, location, size, or any other attribute
+  # of a stage.
+  #
+  # See Limelight::Stage
+  #
   class StagesBuilder
-    
-    attr_reader :stages
-    
+
+    Limelight::Util.lobotomize(self)
+
+    attr_reader :__stages__
+
+    # Constructs a new StagesBuilder.  A Theater object is required as a parameter.  Each stages created will belong
+    # to the Theater passed in.
+    #
     def initialize(theater)
-      @theater = theater
-      @stages = []
+      @__theater__ = theater
+      @__stages__ = []
     end
-    
+
+    # Creates a new stage with the provided name.  The block will contain StageBuilder DSL to configure the stage.
+    #
     def stage(name, &block)
-      stage_builder = StageBuilder.new(@theater, name)
+      stage_builder = StageBuilder.new(@__theater__, name)
       stage_builder.instance_eval(&block) if block
-      @stages << stage_builder.stage
+      @__stages__ << stage_builder.__stage__
     end
-    
+
   end
-  
+
+  # The basis of the DSL for configuring a Stage object.
+  #
   class StageBuilder
-    
-    attr_reader :stage
-    
-    def initialize(theater, name)
+
+    Limelight::Util.lobotomize(self)
+
+    attr_reader :__stage__
+
+    def initialize(theater, name) #:nodoc:
       if theater[name]
-        @stage = theater[name]
+        @__stage__ = theater[name]
       else
-        @stage = Stage.new(theater, name)
-        theater.add_stage(@stage)
+        @__stage__ = Stage.new(theater, name)
+        theater.add_stage(@__stage__)
       end
     end
-    
+
+    # Specifies the scene that will be displayed on the stage upon opening of the production.
+    #
     def default_scene(scene_name)
-      @stage.default_scene = scene_name
+      @__stage__.default_scene = scene_name
     end
-    
-    def method_missing(sym, value)
+
+    def method_missing(sym, value)  #:nodoc:
       setter_sym = "#{sym}=".to_s
-      raise StageBuilderException.new(sym) if !@stage.respond_to?(setter_sym)
-      @stage.send(setter_sym, value)
+      raise StageBuilderException.new(sym) if !@__stage__.respond_to?(setter_sym)
+      @__stage__.send(setter_sym, value)
     end
   end
 
+  # Exception thrown by StageBuilder in the event of an invalid configuration.
+  #
   class StageBuilderException < LimelightException
     def initialize(name)
       super("'#{name}' is not a valid stage property")
     end
   end
-  
+
 end