RUIC 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f88b39bad10863d43c14c6cc303416a786229a8
-  data.tar.gz: 25e776627d2205f34de467708ced0998491000a7
+  metadata.gz: 3cd982f65f8cae25edc67f0619f9a5f11d36fd89
+  data.tar.gz: 5600614882179d970952c0d67bc428a8e7f8ee73
 SHA512:
-  metadata.gz: afc0a558732656717910d510eabd5cc2befca05e875177a797d04e51528a1b16636144a4308a1038a9ca4006161712a287d8eb6c8e343808a23649fa10347df8
-  data.tar.gz: b81d44122d54f693ef1044749e5cb84ddff25a6b3812b2885569ec5a222aa5c14d4e6c52d2b793c9cfade150f89693d36955234e327a874c3a84495f3c9e0326
+  metadata.gz: 4aa749d218b876a2a13261063989ca02ee57dace463b291f80328673d7207622b49bd5e93ceb21c010f7b443230d0f31079e6d85779f41e2d8ba0d2bcd5aaaf7
+  data.tar.gz: 97fdefc32b8356d2c8ca48d40c1cc19a3fc954564810677e64d331151077a1e3f66cce981d19ae26179a10ab578f4c4f53e3602793b1ed28564bf9642c6416d4

data/lib/ruic/assets.rb

@@ -47,76 +47,164 @@ class UIC::MetaData
 		end
 		alias_method :/, :at
 
-		attr_accessor :presentation, :el
+		# @return [Presentation] the presentation that this asset is part of.
+		attr_accessor :presentation
+
+		# @return [Nokogiri::XML::Element] the internal XML element in the scene graph of the presentation.
+		attr_accessor :el
+
+		# Create a new asset. This is called for you automatically; you likely should not be using it.
+		# @param presentation [Presentation] the presentation owning this asset.
+		# @param element [Nokogiri::XML::Element] the internal XML element in the scene graph of the presentation.
 		def initialize( presentation, element )
 			@presentation = presentation
 			@el = element
 		end
 
+		# @return [String] the type of this asset. For example: `"Model"`, `"Material"`, `"ReferencedMaterial"`, `"PathAnchorPoint"`, etc.
 		def type
 			self.class.name
-			# self.class.name.split('::').last
 		end
 
+		# @return [AssetBase] the parent of this asset in the scene graph.
+		# @see Presentation#parent_asset
 		def parent
 			presentation.parent_asset(self)
 		end
 
+		# @return [Array<AssetBase>] array of child assets in the scene graph. Children are in scene graph order.
+		# @see Presentation#child_assets
 		def children
 			presentation.child_assets(self)
 		end
 
+		# Find descendant assets matching criteria.
+		# This method is the same as (but more convenient than) {Presentation#find} using the `:_under` criteria.
+		# See that method for documentation of the `criteria`.
+		#
+		# @example
+		#  preso = app.main
+		#  group = preso/"Scene.Layer.Vehicle"
+		#  tires = group.find name:/^Tire/
+		#
+		#  # alternative
+		#  tires = preso.find name:/^Tire/, _under:group
+		#
+		# @return [Array<AssetBase>]
+		#
+		# @see Presentation#find
 		def find(criteria={},&block)
 			criteria[:_under] ||= self
 			presentation.find(criteria,&block)
 		end
 
-		# Find the owning component (even if you are a component)
+		# @return [AssetBase] the component or scene that owns this asset.
+		#         If this asset is a component, does not return itself.
+		# @see Presentation#owning_component
 		def component
 			presentation.owning_component(self)
 		end
 
+		# @return [Boolean] `true` if this asset is a component or Scene.
 		def component?
-			@el.name == 'Component'
+			@el.name=='Component' || @el.name=='Scene'
 		end
 
+		# @return [Boolean] `true` if this asset is on the master slide.
+		# @see Presentation#master?
 		def master?
 			presentation.master?(self)
 		end
 
+		# @return [Boolean] `true` if this asset is a Slide.
 		def slide?
 			false
 		end
 
+		# @param slide_name_or_index [Integer,String] the slide number of name to check for presence on.
+		# @return [Boolean] `true` if this asset is present on the specified slide.
+		# @see Presentation#has_slide?
 		def has_slide?(slide_name_or_index)
 			presentation.has_slide?(self,slide_name_or_index)
 		end
 
+		# @return [SlideCollection] an array-like collection of all slides that the asset is available on.
+		# @see Presentation#slides_for
 		def slides
 			presentation.slides_for(self)
 		end
 
+		# @example
+		#  logo = app/"main:Scene.UI.Logo"
+		#  assert logo.master?             # It's a master object
+		#
+		#  show logo['endtime'].values     #=> [10000,500,1000,750]
+		#  show logo['opacity'].values     #=> [100,0,0,100]
+		#  logo1 = logo.on_slide(1)
+		#  logo2 = logo.on_slide(2)
+		#  show logo1['endtime']           #=> 500
+		#  show logo2['endtime']           #=> 1000
+		#  show logo1['opacity']           #=> 0
+		#  show logo2['opacity']           #=> 0
+		#
+		#  logo2['opacity'] = 66
+		#  show logo['opacity'].values     #=> [100,0,66,100]
+		#
+		# @param slide_name_or_index [Integer,String] the slide number or name to create the proxy for.
+		# @return [SlideValues] a proxy that yields attribute values for a specific slide.
 		def on_slide(slide_name_or_index)
 			if has_slide?(slide_name_or_index)
 				UIC::SlideValues.new( self, slide_name_or_index )
 			end
 		end
 
+		# @return [String] the script path to this asset.
+		# @see #path_to
+		# @see Presentation#path_to
 		def path
 			@path ||= @presentation.path_to(self)
 		end
 
+		# @param other_asset [AssetBase] the asset to find the relative path to.
+		# @return [String] the script path to another asset, relative to this one.
+		# @see #path
+		# @see Presentation#path_to
+		def path_to(other_asset)
+			@presentation.path_to(other_asset,self)
+		end
+
+		# @return [String] the name of this asset in the scene graph.
 		def name
 			properties['name'].get( self, presentation.slide_index(self) )
 		end
 
+		# Change the name of the asset in the scene graph.
+		# @param new_name [String] the new name for this asset.
+		# @return [String] the new name.
 		def name=( new_name )
+			@path = nil # invalidate the memoization
 			properties['name'].set( self, new_name, presentation.slide_index(self) )
 		end
 
-		# Get the value(s) of an attribute
+		# Get the value(s) of an attribute.
+		# If `slide_name_or_index` is omitted, creates a ValuesPerSlide proxy for the specified attribute.
+		# @example
+		#  logo = app/"main:Scene.UI.Logo"
+		#  show logo.master?               #=> true  (it's a master object)
+		#  show logo['endtime'].linked?    #=> false (the endtime property is unlinked)
+		#  show logo['endtime'].values     #=> [10000,500,1000,750]
+		#  show logo['endtime',0]          #=> 10000 (the master slide value)
+		#  show logo['endtime',"Slide 1"]  #=> 500
+		#  show logo['endtime',2]          #=> 1000
+		#
+		# @param attribute_name [String,Symbol] the name of the attribute.
+		# @param slide_name_or_index [Integer,String] the slide number or name to find the value on.
+		# @return [Object] the value of the property on the given slide.
+		# @return [ValuesPerSlide] if no slide is specified.
+		# @see #on_slide
+		# @see Presentation#get_attribute
 		def [](attribute_name, slide_name_or_index=nil)
-			if property = properties[attribute_name]
+			if property = properties[attribute_name.to_s]
 				if slide_name_or_index
 					property.get( self, slide_name_or_index ) if has_slide?(slide_name_or_index)
 				else
@@ -125,26 +213,47 @@ class UIC::MetaData
 			end
 		end
 
-		# Set the value of an attribute, either across all slides, or on a particular slide
-		# el['foo']   = 42
-		# el['foo',0] = 42
+		# Set the value of an attribute, either across all slides, or on a particular slide.
+		#
+		# @example
+		#  logo = app/"main:Scene.UI.Logo"
+		#  show logo.master?               #=> true  (it's a master object)
+		#  show logo['endtime'].linked?    #=> false (the endtime property is unlinked)
+		#  show logo['endtime'].values     #=> [10000,500,1000,750]
+		#
+		#  logo['endtime',1] = 99
+		#  show logo['endtime'].values     #=> [10000,99,1000,750]
+		#
+		#  logo['endtime'] = 42
+		#  show logo['endtime'].values     #=> [42,42,42,42]
+		#  show logo['endtime'].linked?    #=> false (the endtime property is still unlinked)
+		#
+		# @param attribute_name [String,Symbol] the name of the attribute.
+		# @param slide_name_or_index [Integer,String] the slide number or name to set the value on.
+		# @param new_value [Numeric,String] the new value for the attribute.
+		# @see Presentation#set_attribute
 		def []=( attribute_name, slide_name_or_index=nil, new_value )
-			if property = properties[attribute_name] then
+			if property = properties[attribute_name.to_s] then
 				property.set(self,new_value,slide_name_or_index)
 			end
 		end
 
+		# @return [String] the XML representation of the scene graph element.
 		def to_xml
 			@el.to_xml
 		end
+
+		# @private no need to document this
 		def inspect
 			"<asset #{@el.name}##{@el['id']}>"
 		end
 
+		# @private no need to document this
 		def to_s
 			"<#{type} #{path}>"
 		end
 
+		# @private no need to document this
 		def ==(other)
 			(self.class==other.class) && (el==other.el)
 		end

data/lib/ruic/presentation.rb

@@ -103,6 +103,7 @@ class UIC::Presentation
 
 	# @param child_asset [MetaData::AssetBase] an asset in the presentation.
 	# @return [MetaData::AssetBase] the scene graph parent of the child asset, or `nil` for the Scene.
+	# @see MetaData::AssetBase#parent
 	def parent_asset( child_asset )
 		child_graph_el = child_asset.el
 		unless child_graph_el==@scene || child_graph_el.parent.nil?
@@ -112,6 +113,7 @@ class UIC::Presentation
 
 	# @param parent_asset [MetaData::AssetBase] an asset in the presentation.
 	# @return [Array<MetaData::AssetBase>] array of scene graph children of the specified asset.
+	# @see MetaData::AssetBase#children
 	def child_assets( parent_asset )
 		parent_asset.el.element_children.map{ |child| asset_for_el(child) }
 	end
@@ -181,9 +183,23 @@ class UIC::Presentation
 	# * If `from_asset` is supplied the path will be relative to that asset (e.g. `"parent.parent.Group.Model"`).
 	# * If `from_asset` is omitted the path will be absolute (e.g. `"Scene.Layer.Group.Model"`).
 	#
+	# This is used internally by {MetaData::AssetBase#path} and {MetaData::AssetBase#path_to};
+	# those methods are usually more convenient to use.
+	#
+	# @example
+	#  preso = app.main
+	#  preso.scene.children.each{ |child| show preso.path_to(child) }
+	#  #=> "main:Scene.MyAppBehavior"
+	#  #=> "main:Scene.UILayer"
+	#  #=> "main:Scene.ContentLayer"
+	#  #=> "main:Scene.BGLayer"
+	#
 	# @param asset [MetaData::AssetBase] the asset to find the path to.
 	# @param from_asset [MetaData::AssetBase] the asset to find the path relative to.
 	# @return [String] the script path to the element.
+	#
+	# @see MetaData::AssetBase#path
+	# @see MetaData::AssetBase#path_to
 	def path_to( asset, from_asset=nil )
 		el = asset.el
 
@@ -269,6 +285,8 @@ class UIC::Presentation
 	# @param asset [MetaData::AssetBase] the asset to fetch the attribute for.
 	# @param attr_name [String] the name of the attribute to get the value of.
 	# @param slide_name_or_index [String,Integer] the string name or integer index of the slide.
+	# @return [Object] the value of the asset on the slide
+	# @see MetaData::AssetBase#[]
 	def get_attribute( asset, attr_name, slide_name_or_index )
 		graph_element = asset.el
 		((addsets=@addsets_by_graph[graph_element]) && ( # State (slide) don't have any addsets
@@ -295,6 +313,7 @@ class UIC::Presentation
 	# @param asset [MetaData::AssetBase] the asset to fetch the attribute for.
 	# @param attr_name [String] the name of the attribute to get the value of.
 	# @param slide_name_or_index [String,Integer] the string name or integer index of the slide.
+	# @see MetaData::AssetBase#[]=
 	def set_attribute( asset, property_name, slide_name_or_index, str )
 		graph_element = asset.el
 		if attribute_linked?( asset, property_name )
@@ -325,13 +344,18 @@ class UIC::Presentation
 	end
 
 	# @return [MetaData::AssetBase] the component asset that owns the supplied asset.
-	# @see MetaData::AssetBase#component
+	#         If the graph_element **is** a component this will return its parent component or Scene.
+	# @see owning_or_self_component_element
+	# @api private
 	def owning_component_element( graph_element )
 		graph_element.at_xpath('(ancestor::Component[1] | ancestor::Scene[1])[last()]')
 	end
 	private :owning_component_element
 
 	# @return [Nokogiri::XML::Element] the "time context" scene graph element that owns the supplied element.
+	#         If the graph_element **is** a component this will return the element itself.
+	# @see owning_component_element
+	# @api private
 	def owning_or_self_component_element( graph_element )
 		graph_element.at_xpath('(ancestor-or-self::Component[1] | ancestor-or-self::Scene[1])[last()]')
 	end
@@ -425,6 +449,7 @@ class UIC::Presentation
 	end
 
 	# @return [Boolean] `true` if the asset is added on the master slide.
+	# @see MetaData::AssetBase#master?
 	def master?(asset)
 		graph_element = asset.el
 		(graph_element == @scene) || !!(@addsets_by_graph[graph_element] && @addsets_by_graph[graph_element][0])
@@ -517,16 +542,20 @@ class UIC::Presentation
 	end
 end
 
-def UIC.Presentation( uip_path )
+# @param uip_path [String] Path to the `.uip` presentation file on disk to load.
+# @return [Presentation] Shortcut for `UIC::Presentation.new`
+def UIC.Presentation( uip_path=nil )
 	UIC::Presentation.new( uip_path )
 end
 
+# An {Application::Presentation} is a {Presentation} that is associated with a specific `.uia` application.
+# In addition to normal {Presentation} methods it has additional methods related to its presense in the application.
 class UIC::Application::Presentation < UIC::Presentation
 	include UIC::ElementBacked
 	# @!parse extend UIC::ElementBacked::ClassMethods
 
 	# @!attribute [rw] id
-	#   @return [String] the id of the presentation asset
+	#   @return [String] the id of the presentation asset in the `.uia`
 	xmlattribute :id do |new_id|
 		main_preso = app.main_presentation
 		super(new_id)
@@ -538,11 +567,13 @@ class UIC::Application::Presentation < UIC::Presentation
 	xmlattribute :src
 
 	# @!attribute active
-	#   @return [Boolean] is the presentation initially active?
-	xmlattribute :active, ->(val){ val=="True" } do |new_val|
+	#   @return [Boolean] Is the presentation initially active in the application?
+	xmlattribute :active, ->(val){ val=="True" || val=="" } do |new_val|
 		new_val ? 'True' : 'False'
 	end
 
+	# @param application [Application] the {Application} object owning this presentation.
+	# @param el [Nokogiri::XML::Element] the XML element in the `.uia` representing this presentation.
 	def initialize(application,el)
 		self.owner = application
 		self.el    = el
@@ -550,8 +581,9 @@ class UIC::Application::Presentation < UIC::Presentation
 	end
 	alias_method :app, :owner
 
+	# Overrides {UIC::Presentation#path_to} to prefix all absolute paths with the {#id}
 	def path_to( el, from=nil )
-		"#{id}:#{super}"
+		from ? super : "#{id}:#{super}"
 	end
 end
 

data/lib/ruic/version.rb

@@ -1,3 +1,3 @@
 class RUIC
-	VERSION = '0.4.3'
+	VERSION = '0.4.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: RUIC
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - Gavin Kistner