Class Limelight::Prop
In: lib/limelight/prop.rb
Parent: Object

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.


<<   add   add_options   after_painting   animate   area   bordered_area   build   child_area   event   event2   events   find_by_name   include_player   launch   loader   new   pen   play_sound   production   remove   remove_all   scene   text   text=  

Included Modules



children  [R] 
hover_style  [RW] 
id  [R] 
name  [R] 
parent  [R] 
players  [R] 
style  [RW] 

Public Class methods


    # File lib/limelight/prop.rb, line 22
22:       def event(event_symbol)
23:         @events ||= []
24:         @events << event_symbol unless @events.include?(event_symbol)
25:         define_method(event_symbol) { |event|  } # do nothing by default
26:       end


    # File lib/limelight/prop.rb, line 32
32:       def event2(event_symbol)
33:         @events ||= []
34:         @events << event_symbol unless @events.include?(event_symbol)
35:         define_method("accepts_#{event_symbol}".to_sym) { return self.respond_to?(event_symbol) }
36:       end


    # File lib/limelight/prop.rb, line 28
28:       def events
29:         return @events
30:       end

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.


    # File lib/limelight/prop.rb, line 52
52:     def initialize(hash = {})
53:       @options = hash || {}
54:       @children = []
55:       @style =
56:       @panel =
57:     end

Public Instance methods

Same as add. Returns self so adding may be chained.

  prop << child1 << child2 << child3


    # File lib/limelight/prop.rb, line 71
71:     def <<(child)
72:       add(child)
73:       return self
74:     end

Add a Prop as a child of this Prop.


    # File lib/limelight/prop.rb, line 61
61:     def add(child)
62:       child.set_parent(self)
63:       @children << child
64:       @panel.add(child.panel)
65:     end

Allows the addition of extra initialization options. Will raise an exception if the Prop has already been illuminated (added to a scene).


     # File lib/limelight/prop.rb, line 201
201:     def add_options(more_options)
202:       raise "Too late to add options" if illuminated?
203:       @options.merge!(more_options)
204:     end

A hook to invoke behavior after a Prop is painted.


     # File lib/limelight/prop.rb, line 133
133:     def after_painting(flag = true, &block)
134:       if flag
135:         @panel.after_paint_action =
136:       else
137:         @panel.after_paint_action = nil
138:       end
139:     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 = ( + 1).to_s
     @animation.stop if > 60

This above example will cause the Prop‘s border to grow until it is 60 pixels wide.


     # File lib/limelight/prop.rb, line 247
247:     def animate(options={}, &block)
248:       animation =, block, options)
249:       animation.start
250:       return animation
251:     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


     # File lib/limelight/prop.rb, line 212
212:     def area
213:       return panel.get_bounding_box.clone
214:     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.


     # File lib/limelight/prop.rb, line 219
219:     def bordered_area
220:       return panel.get_box_inside_borders.clone
221:     end

Allows the adding of child Props using the PropBuilder DSL. do
     child1 do


    # File lib/limelight/prop.rb, line 85
85:     def build(options = {}, &block)
86:       require 'limelight/dsl/prop_builder'
87:       builder =
88:       builder.__install_instance_variables(options)
89:       builder.__loader__ = scene.loader
90:       builder.instance_eval(&block)
91:     end

Returns a Box representing the bounds inside the padding of the prop. This is the area where child props may be located


     # File lib/limelight/prop.rb, line 226
226:     def child_area
227:       return panel.getChildConsumableArea().clone
228:     end

Searches all descendant of the Prop (including itself) for Props with the specified name. Returns an Array of matching Props. Returns an empty Array if none are found.


     # File lib/limelight/prop.rb, line 144
144:     def find_by_name(name, results = [])
145:       results << self if @name == name
146:       @children.each { |child| child.find_by_name(name, results) }
147:       return results
148:     end

Injects the behavior of the specified Player into the Prop. The Player must be a Module.


     # File lib/limelight/prop.rb, line 112
112:     def include_player(player_module)
113:       unless self.is_a?(player_module)
114:         extend player_module
115:         self.casted if player_module.instance_methods.include?("casted")
116:       end 
117:     end

Luanches the spcified URL using the OS‘s default handlers. For example, opening a URL in a browser:


To create a link prop add an accessor on the player (say url) and use that in the prop definition Ex:

  link :text => "I am a link", :url => ""


     # File lib/limelight/prop.rb, line 268
268:     def launch(url)
269:       Context.instance.os.launch(url)
270:     end

TODO get rid of me.… The Java Prop interface declares this method.


     # File lib/limelight/prop.rb, line 172
172:     def loader
173:       return scene.production.root;
174:     end

Returns a Pen object. Pen objects allow to you to draw directly on the screen, withing to bounds of this Prop.


     # File lib/limelight/prop.rb, line 232
232:     def pen
233:       return
234:     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.


     # File lib/limelight/prop.rb, line 256
256:     def play_sound(filename)
257:       @panel.play_sound(scene.loader.path_to(filename))
258:     end

Returns the current Production this Prop lives in.


     # File lib/limelight/prop.rb, line 178
178:     def production
179:       return scene.production
180:     end

Removes a child Prop. The child Prop will be parentless after removal.


     # File lib/limelight/prop.rb, line 95
 95:     def remove(child)
 96:       if children.delete(child)
 97:         scene.unindex_prop(child) if scene
 98:         @panel.remove(child.panel)
 99:       end
100:     end

Removes all child Props.


     # File lib/limelight/prop.rb, line 104
104:     def remove_all
105:       @panel.remove_all
106:       @children.each { |child| scene.unindex_prop(child) } if scene
107:       @children = []
108:     end

Returns the scene to which this prop belongs to.


     # File lib/limelight/prop.rb, line 165
165:     def scene 
166:       return nil if @parent.nil?
167:       @scene = @parent.scene if @scene.nil?
168:       return @scene
169:     end

Returns the text of the Prop.


     # File lib/limelight/prop.rb, line 159
159:     def text
160:       return panel.text
161:     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.


     # File lib/limelight/prop.rb, line 153
153:     def text=(value)    
154:       @panel.text = value.to_s
155:     end