limelight 0.2.0-java → 0.2.1-java

data/lib/limelight/producer.rb

@@ -14,8 +14,15 @@ require 'limelight/production'
 
 module Limelight
 
+  # A Producer has the hefty responsibility of producing Productions.  Given a directory, it will load the neccessary
+  # files and create all the neccessary objects to bring a Production to life.
+  #
+  # For directory structures, see Limelight::Main
+  #
   class Producer
 
+    # Creates a new Producer and has it open a Production by specified name.
+    #
     def self.open(production_name)
       producer = new(production_name)
       producer.open
@@ -23,7 +30,10 @@ module Limelight
     
     attr_reader :loader, :theater, :production
     attr_writer :builtin_styles
-    
+
+    # A Production name, or root directory, must be provided. If not Theater is provided, one will be created.
+    # You may also provide an existing Production for which this Producer will interact.
+    #
     def initialize(root_path, theater=nil, production=nil)
       if(root_path[-4..-1] == ".llp")
         root_path = unpack_production(root_path)
@@ -32,12 +42,17 @@ module Limelight
       @theater = theater.nil? ? Theater.new : theater
       @production = production
     end
-    
+
+    # Returns the CastingDirector for this Production.
+    #
     def casting_director
       @casting_director = CastingDirector.new(loader) if not @casting_director
       return @casting_director
     end
-    
+
+    # Opens the Production specified during construction. If the file 'init.rb' exists in the root directory of the
+    # Production, it will be loaded before anything else.
+    #
     def open()
       establish_production
       Kernel.load(@loader.path_to("init.rb")) if @loader.exists?("init.rb")
@@ -49,6 +64,8 @@ module Limelight
       @casting_director = nil
     end
 
+    # Opens the specified Scene onto the Spcified Stage.
+    #
     def open_scene(path, stage)
       styles = load_styles(path)
       merge_with_root_styles(styles)
@@ -57,7 +74,9 @@ module Limelight
 
       stage.open(scene)
     end
-    
+
+    # Loads the 'stages.rb' file and configures all the Stages in the Production.
+    #
     def load_stages
       content = @loader.load("stages.rb")
       stages = Limelight.build_stages(@theater) do
@@ -69,7 +88,9 @@ module Limelight
       end
       return stages
     end
-    
+
+    # Loads of the 'props.rb' file for a particular Scene and creates all the Prop objects and Scene.
+    #
     def load_props(path, options = {})
       return Scene.new(options) if path.nil?
       filename = File.join(path, "props.rb")
@@ -83,7 +104,9 @@ module Limelight
         end
       end
     end
-    
+
+    # Loads the specified 'styles.rb' file and created a Hash of Styles.
+    #
     def load_styles(path)
       styles = builtin_styles
       return styles if path.nil?
@@ -98,7 +121,9 @@ module Limelight
         end
       end
     end
-    
+
+    # Loads the 'production.rb' file if it exists and configures the Production.
+    #
     def establish_production
       return if @production
       if @loader.exists?("production.rb")
@@ -115,6 +140,9 @@ module Limelight
       end      
     end
 
+    # A production with multiple Scenes may have a 'styles.rb' file in the root directory.  This is called the
+    # root_style.  This method loads the root_styles, if they haven't already been loaded, and returns them.
+    #
     def root_styles
       return @root_syles if @root_syles
       if @loader.exists?('styles.rb')

data/lib/limelight/production.rb

@@ -4,12 +4,17 @@
 require 'limelight/limelight_exception'
 
 module Limelight
-  
+
+  # The root object of Limelight Production.  Every Prop in a production has access to its Production object.
+  # Therefore it is typical to store reasources in the Production.
+  #
+  # Productions are configured, and attributes are added, by the ProductionBuilder.
+  #
   class Production
     
     class << self
       
-      def index(production)
+      def index(production) #:nodoc:
         @index = [] if @index.nil?
         if production.name.nil?
           assign_name_to(production) 
@@ -19,12 +24,12 @@ module Limelight
         @index << production
       end
       
-      def [](name)
+      def [](name) #:nodoc:
         return nil if @index.nil?
         return @index.find { |production| production.name == name }
       end
       
-      def assign_name_to(production)
+      def assign_name_to(production) #:nodoc:
         count = @index.length + 1
         while name_taken?(count.to_s)
           count += 1
@@ -32,28 +37,32 @@ module Limelight
         production.name = count.to_s
       end
       
-      def name_taken?(name)
+      def name_taken?(name) #:nodoc:
         return self[name] != nil
       end
 
-      def clear_index
+      def clear_index #:nodoc:
         @index = []
       end
       
-      def error_if_duplicate_name(name)
+      def error_if_duplicate_name(name) #:nodoc:
         raise Limelight::LimelightException.new("Production name '#{name}' is already taken") if name_taken?(name)
       end
       
     end
     
     attr_reader :producer, :theater, :name
-    
+
+    # Users typically need not create Production objects.
+    #
     def initialize(producer, theater)
       @producer = producer
       @theater = theater
       self.class.index(self)
     end
-    
+
+    # Sets the name of the Production.  The name must be unique amongst all Productions in memory.
+    #
     def name=(value)
       self.class.error_if_duplicate_name(value)
       @name = value

data/lib/limelight/production_builder.rb

@@ -5,13 +5,26 @@ require 'limelight/production'
 require 'limelight/limelight_exception'
 
 module Limelight
-  
+
+  # A trigger to configure Production objects using the ProductionBuilder DSL.
+  #
+  # See Limelight::ProductionBuilder
+  #
   def self.build_production(producer, theater, &block)
     builder = ProductionBuilder.new(producer, theater)
     builder.instance_eval(&block) if block
     return builder.__production__
   end
-  
+
+  # The basis of the DSL for building Style objects.
+  #
+  #  name "Stage Composer"
+  #  attribute :controller
+  #  attribute :inspector
+  #
+  # The above example names the Production 'Stage Composer' and creates two attributes on the Production: 'controller'
+  # and 'inspector'
+  #
   class ProductionBuilder
     
     class << self
@@ -26,12 +39,14 @@ module Limelight
       @__production__ = Production.new(producer, theater)
     end
     
-    def method_missing(sym, value)
+    def method_missing(sym, value) #:nodoc:
       setter_sym = "#{sym}=".to_s
       raise ProductionBuilderException.new(sym) if !@__production__.respond_to?(setter_sym)
       @__production__.send(setter_sym, value)
     end
-    
+
+    # Creates an attribute on the Production
+    #
     def attribute(sym)
       ProductionBuilder.current_attribute = sym
       class << @__production__
@@ -39,7 +54,9 @@ module Limelight
       end
     end
   end
-  
+
+  # Thrown if there is an error in the ProductionBuilder DSL
+  #
   class ProductionBuilderException < LimelightException
     def initialize(name)
       super("'#{name}' is not a valid production property")

data/lib/limelight/prop.rb

@@ -7,16 +7,22 @@ require 'limelight/paint_action'
 require 'limelight/animation'
 
 module Limelight
+
+  # Prop is the fundamental building block of a scene.  A prop represents a rectangular area in the scene, of almost any dimension.
+  # It may have borders, backgrounds, margin, padding, and it may contain other props or text.  However it is the props'
+  # Styles that determine their size and appearance.
+  #
+  # A Prop may have one parent and many children.  Hense, when put together, they form a tree structure.  The Scene is
+  # the root Prop of a tree.
+  #
   class Prop
     
     class << self
 
-      def event(*syms)       
+      def event(event_symbol)
         @events ||= []
-        syms.each do |sym|
-          @events << sym unless @events.include?(sym)
-          define_method(sym) { |event|  } # do nothing by default
-        end
+        @events << event_symbol unless @events.include?(event_symbol)
+        define_method(event_symbol) { |event|  } # do nothing by default
       end
 
       def events
@@ -27,72 +33,100 @@ module Limelight
     
     include UI::Api::Prop
   
-    attr_reader :panel, :style, :hover_style, :children, :scene, :parent
-    attr_reader :name, :id, :players
-    getters :panel, :style, :hover_style, :scene, :name, :text
-    setters :text
-    
+    attr_reader :panel #:nodoc:
+    attr_reader :style, :hover_style, :children, :scene, :parent, :name, :id, :players
+    getters :panel, :style, :hover_style, :scene, :name, :text  #:nodoc:
+    setters :text #:nodoc:
+
+    # When creating a Prop, an optional Hash is accepted. These are called initialization options.
+    # The key/value pairs in the initialiaztion options will be used to
+    # set properties on the Prop, it Style, or included Player properties. These properties are not set
+    # until the prop is added to a Prop tree with a Scene.
+    #
     def initialize(hash = {})
       @options = hash
       @children = []
       @style = Styles::ScreenableStyle.new
       @panel = UI::Model::Panel.new(self)
     end
-    
+
+    # Add a Prop as a child of this Prop.
+    #
     def add(child)
       child.set_parent(self)
       @children << child
       @panel.add(child.panel)
     end
-     
+
+    # Same as add.  Returns self so adding may be chained.
+    #
+    #   prop << child1 << child2 << child3
+    #
     def <<(child)
       add(child)
       return self
     end
-    
+
+    # Allows the adding of child Props using the PropBuilder DSL.
+    #
+    #    prop.build do
+    #      child1 do
+    #        grand_child
+    #      end
+    #      child2
+    #    end
+    #
     def build(&block)
       require 'limelight/prop_builder'
       builder = Limelight::PropBuilder.new(self)
       builder.instance_eval(&block)
     end
-    
+
+    # Removes a child Prop.  The child Prop will be parentless after removal.
+    #
     def remove(child)
       if children.delete(child)
         @panel.remove(child.panel)
       end
     end
-    
+
+    # Removes all child Props.
+    #
     def remove_all
       @panel.remove_all
       @children = []
     end
-    
-    def add_controller(controller_module)
-      extend controller_module unless self.is_a?(controller_module)
+
+    # Injects the behavior of the specified Player into the Prop.  The Player must be a Module.
+    #
+    def include_player(player_module)
+      extend player_module unless self.is_a?(player_module)
     end
     
-    alias :include_player :add_controller
-    
-    def update
+    def update #:nodoc:
       return if(@scene.nil? || !@scene.visible)
       @panel.doLayout
       @panel.repaint
     end
     
-    def update_now
+    def update_now #:nodoc:
       return if(@scene.nil? || !@scene.visible)
       @panel.doLayout()
       @panel.paintImmediately(0, 0, @panel.width, @panel.height)
     end    
-    
+
+    # A hook to invoke behavior after a Prop is painted.
+    #
     def after_painting(flag = true, &block)
       if flag
         @panel.after_paint_action = PaintAction.new(&block)
       else
         @panel.after_paint_action = nil
       end
-    end 
-    
+    end
+
+    # Searches all children for a Prop with the given id.  Returns the desired Prop if found, nil otherwise.
+    #
     def find(id)
       return self if @id == id
       @children.each do |child|
@@ -101,73 +135,111 @@ module Limelight
       end
       return nil
     end   
-    
+
+    # Searches all children for Props with the specified name.  Returns an Array of matching Props. Returns an
+    # empty Array is none are found.
+    #
     def find_by_name(name, results = [])
       results << self if @name == name
       @children.each { |child| child.find_by_name(name, results) }
       return results
     end
-    
+
+    # Sets the text of this Prop.  If a prop is given text, it will become sterilized (it may not have any more children).
+    # Some Players such as text_box, will cause the text to appear in the text_box.
+    #
     def text=(value)
-      @panel.text = value
+      @panel.text = value.to_s
     end
-    
+
+    # Returns the text of the Prop.
+    #
     def text
       return panel.text
     end
     
     #TODO - MDM - DELETE ME
-    def stage
+    def stage #:nodoc:
       return scene.stage
     end
-    
+
+    # Returns the current Production this Prop lives in.
+    #
     def production
       return scene.production
     end
     
-    def to_s
+    def to_s #:nodoc:
       return "#{self.class.name}[id: #{@id}, name: #{@name}]"
     end
     
-    def inspect
+    def inspect #:nodoc:
       return self.to_s
     end
     
     # unusual name because it's not part of public api
-    def set_parent(parent)
+    def set_parent(parent) #:nodoc:
       @parent = parent
       set_scene parent.scene
     end
     
     # unusual name because it's not part of public api
-    def set_scene(scene)
+    def set_scene(scene) #:nodoc:
       return if scene == @scene || scene.nil?
       @scene = scene
       illuminate
       children.each { |child| child.set_scene(scene) }
     end
-    
+
+    # Allows the addition of extra initialization options.  Will raise an exception if the Prop has already been
+    # illuminated (added to a scene).
+    #
     def add_options(more_options)
       raise "Too late to add options" if @options.nil?
       @options.merge!(more_options)
     end
-    
+
+    # Returns a Box representing the relative bounds of the Prop. Is useful with usign the Pen.
+    #
+    #   box = prop.area
+    #   box.x, box.y # represents the Prop's location within its parent Prop
+    #   box.width, box.height # represents the Prop's dimensions
+    #
     def area
       return panel.get_box.clone
     end
-    
+
+    # Returns a Box representing the bounds inside the borders of the prop.  If the Prop's style has no margin or
+    # border_width, then this will be equivalant to area.
+    #
     def bordered_area
       return panel.get_box_inside_borders.clone
     end
-    
+
+    # Returns a Pen object. Pen objects allow to you to draw directly on the screen, withing to bounds of this Prop.
+    #
     def pen
       return Pen.new(panel.getGraphics)
     end
-    
+
+    # Plays a sound on the computers audio output.  The parameter is the filename of a .au sound file.
+    # This filename should relative to the root directory of the current Production, or an absolute path.
+    #
     def play_sound(filename)
       @panel.play_sound(@scene.loader.path_to(filename))
     end
 
+    # Initiate an animation loop.  Options may include :name (string), :updates_per_second (int: defaults to 60)
+    # An Animation object is returned.
+    # The provided block will be invoked :updates_per_second times per second until the Animation is stopped.
+    #
+    #    @animation = prop.animate(:updates_per_second => 20) do
+    #      prop.style.border_width = (prop.style.top_border_width.to_i + 1).to_s
+    #      @animation.stop if prop.style.top_border_width.to_i > 60
+    #    end
+    #
+    # This above example will cause the Prop's border to grow until it is 60 pixels wide.
+    #
     def animate(options={}, &block)
       animation = Animation.new(self, block, options)
       animation.start
@@ -175,11 +247,21 @@ module Limelight
     end
     
     # GUI Events ##########################################
-    
-    EVENTS = [:mouse_clicked, :mouse_entered, :mouse_exited, :mouse_pressed, :mouse_released, :mouse_dragged, :mouse_moved,
-         :key_typed, :key_pressed, :key_released, :focus_gained, :focus_lost, :button_pressed, :value_changed]
-         
-    event *EVENTS
+
+    event :mouse_clicked
+    event :mouse_entered
+    event :mouse_exited
+    event :mouse_pressed
+    event :mouse_released
+    event :mouse_dragged
+    event :mouse_moved
+    event :key_typed
+    event :key_pressed
+    event :key_released
+    event :focus_gained
+    event :focus_lost
+    event :button_pressed
+    event :value_changed
    
     private ###############################################