kamelopard 0.0.7 → 0.0.8

data/lib/kamelopard/classes.rb

@@ -11,12 +11,13 @@ module Kamelopard
     require 'xml'
     require 'yaml'
     require 'erb'
+    require 'cgi'
 
     @@sequence = 0
     @@id_prefix = ''
 
     def Kamelopard.get_document
-        Document.instance
+        DocumentHolder.instance.current_document
     end
 
     def Kamelopard.get_next_id   # :nodoc
@@ -127,6 +128,11 @@ module Kamelopard
         attr_accessor :kml_id
         attr_reader :comment
 
+        # This constructor looks for values in the options hash that match
+        # class attributes, and sets those attributes to the values in the
+        # hash. So a class with an attribute called :when can be set via the
+        # constructor by including ":when => some-value" in the options
+        # argument to the constructor.
         def initialize(options = {})
             @kml_id = "#{Kamelopard.id_prefix}#{self.class.name.gsub('Kamelopard::', '')}_#{ Kamelopard.get_next_id }"
 
@@ -140,15 +146,15 @@ module Kamelopard
             end
         end
 
-        def comment=(a)
-            if a.respond_to? :gsub then
-                @comment = a.gsub(/</, '&lt;')
-            else
-                @comment = a
-            end
+        # Adds an XML comment to this node. Handles HTML escaping the comment
+        # if needed
+        def comment=(cmnt)
+            require 'cgi'
+            @comment = CGI.escapeHTML(cmnt)
         end
 
-        # Returns KML string for this object. Objects should override this method
+        # Returns XML::Node containing this object's KML. Objects should
+        # override this method
         def to_kml(elem)
             elem.attributes['id'] = @kml_id.to_s
             if not @comment.nil? and @comment != '' then
@@ -260,9 +266,9 @@ module Kamelopard
         # Note that this will not accept a one-dimensional array of numbers to add
         # a single point. Instead, create a Point with those numbers, and pass
         # it to add_element
-        #-
+        #--
         # XXX The above stipulation is a weakness that needs fixing
-        #+
+        #++
         def add_element(a)
             if a.kind_of? Enumerable then
                 # We've got some sort of array or list. It could be a list of
@@ -517,7 +523,9 @@ module Kamelopard
     class TimePrimitive < Object
     end
 
-    # Corresponds to KML's TimeStamp object. The @when attribute must be in a format KML understands.
+    # Corresponds to KML's TimeStamp object. The @when attribute must be in a
+    # format KML understands. Refer to the KML documentation to see which
+    # formats are available.
     class TimeStamp < TimePrimitive
         attr_accessor :when
         def initialize(ts_when = nil, options = {})
@@ -605,7 +613,7 @@ module Kamelopard
         end
     end
 
-    # ExtendedData SchemaData objects
+    # Corresponds to KML's ExtendedData SchemaData objects
     class SchemaData
         attr_accessor :schemaUrl, :simpleData
         def initialize(schemaUrl, simpleData = {})
@@ -632,13 +640,14 @@ module Kamelopard
     end
 
     # Abstract class corresponding to KML's Feature object.
+    #--
     # XXX Make this support alternate namespaces
+    #++
     class Feature < Object
-        # Abstract class
         attr_accessor :visibility, :open, :atom_author, :atom_link, :name,
-            :phoneNumber, :description, :abstractView, :styles,
-            :timeprimitive, :styleUrl, :styleSelector, :region, :metadata
-        attr_reader :addressDetails, :snippet, :extendedData
+            :phoneNumber, :abstractView, :styles, :timeprimitive, :styleUrl,
+            :styleSelector, :region, :metadata
+        attr_reader :addressDetails, :snippet, :extendedData, :description
 
         include Snippet
 
@@ -650,6 +659,15 @@ module Kamelopard
             @name = name unless name.nil?
         end
 
+        def description=(a)
+            b = CGI.escapeHTML(a)
+            if b != a then
+                @description = XML::Node.new_cdata a
+            else
+                @description = a
+            end
+        end
+
         def extendedData=(a)
             raise "extendedData attribute must respond to the 'each' method" unless a.respond_to? :each
             @extendedData = a
@@ -695,9 +713,9 @@ module Kamelopard
 
         def addressDetails=(a)
             if a.nil? or a == '' then
-                Document.instance.uses_xal = false
+                DocumentHolder.instance.current_document.uses_xal = false
             else
-                Document.instance.uses_xal = true
+                DocumentHolder.instance.current_document.uses_xal = true
             end
             @addressDetails = a
         end
@@ -794,7 +812,7 @@ module Kamelopard
             @styles = []
             @folders = []
             super
-            Document.instance.folders << self
+            DocumentHolder.instance.current_document.folders << self
         end
 
         def styles=(a)
@@ -844,18 +862,29 @@ module Kamelopard
         k
     end
 
-    # Represents KML's Document class. This is a Singleton object; Kamelopard
-    # scripts can (for now) manage only one Document at a time.
+    # Represents KML's Document class.
     class Document < Container
-        include Singleton
-        attr_accessor :flyto_mode, :folders, :tours, :uses_xal
+        attr_accessor :flyto_mode, :folders, :tours, :uses_xal, :vsr_actions
 
         def initialize(options = {})
             @tours = []
             @folders = []
+            @vsr_actions = []
+            DocumentHolder.instance << self
             super
         end
 
+        # Returns viewsyncrelay actions as a hash
+        def get_actions
+            {
+                'actions' => @vsr_actions.collect { |a| a.to_hash }
+            }
+        end
+
+        def get_actions_yaml
+            get_actions.to_yaml
+        end
+
         # Returns the current Tour object
         def tour
             Tour.new if @tours.length == 0
@@ -955,6 +984,61 @@ module Kamelopard
         end
     end
 
+    # Holds a set of Document objects, so we can work with multiple KML files
+    # at once and keep track of them. It's important for Kamelopard's usability
+    # to have the concept of a "current" document, so we don't have to specify
+    # the document we're talking about each time we do something interesting.
+    # This class supports that idea.
+    class DocumentHolder
+        include Singleton
+        attr_accessor :document_index, :initialized
+        attr_reader :documents
+
+        def initialize(doc = nil)
+            @documents = []
+            @document_index = -1
+            if ! doc.nil?
+                self.documents << doc
+            end
+        end
+
+        def document_index
+            return @document_index
+        end
+
+        def document_index=(a)
+            @document_index = a
+        end
+
+        def current_document
+            # Automatically create a Document if we don't already have one
+            if @documents.size <= 0
+                Document.new
+                @document_index = 0
+            end
+            return @documents[@document_index]
+        end
+
+        def <<(a)
+            raise "Cannot add a non-Document object to a DocumentHolder" unless a.kind_of? Document
+            @documents << a
+            @document_index += 1
+        end
+
+        def [](a)
+            return @documents[a]
+        end
+
+        def []=(i, v)
+            raise "Cannot include a non-Document object in a DocumentHolder" unless v.kind_of? Document
+            @documents[i] = v
+        end
+
+        def size
+            return @documents.size
+        end
+    end
+
     # Corresponds to KML's ColorStyle object. Color is stored as an 8-character hex
     # string, with two characters each of alpha, blue, green, and red values, in
     # that order, matching the ordering the KML spec demands.
@@ -1273,7 +1357,7 @@ module Kamelopard
         def initialize(options = {})
             super
             @attached = false
-            Document.instance.styles << self
+            DocumentHolder.instance.current_document.styles << self
         end
 
         def attached?
@@ -1411,7 +1495,7 @@ module Kamelopard
         attr_accessor :standalone
 
         def initialize(options = {})
-            Document.instance.tour << self unless options[:standalone]
+            DocumentHolder.instance.current_document.tour << self unless options[:standalone]
             super
         end
     end
@@ -1585,12 +1669,13 @@ module Kamelopard
     class Tour < Object
         attr_accessor :name, :description, :last_abs_view, :playlist, :icon
 
-        def initialize(name = nil, description = nil)
+        def initialize(name = nil, description = nil, no_wait = false)
             super()
             @name = name
             @description = description
             @playlist = []
-            Document.instance.tours << self
+            DocumentHolder.instance.current_document.tours << self
+            Wait.new(0.1, :comment => "This wait is automatic, and helps prevent animation glitches") unless no_wait
         end
 
         # Add another element to this Tour
@@ -1622,7 +1707,7 @@ module Kamelopard
 
         def initialize(options = {})
             super nil, options
-            Document.instance.folder << self
+            DocumentHolder.instance.current_document.folder << self
         end
 
         def to_kml(elem)
@@ -1799,7 +1884,7 @@ module Kamelopard
                 Kamelopard.add_altitudeMode(@altitudeMode, k)
             end
             m = XML::Node.new 'rotation'
-            m = @rotation.to_s
+            m << @rotation.to_s
             k << m
             elem << k unless elem.nil?
             k
@@ -2113,6 +2198,7 @@ module Kamelopard
         end
     end
 
+    # Abstract class corresponding to KML's MultiGeometry object
     class MultiGeometry < Geometry
         attr_accessor :geometries
 
@@ -2136,6 +2222,7 @@ module Kamelopard
         end
     end
 
+    # Analogue of KML's NetworkLink class
     class NetworkLink < Feature
         attr_accessor :refreshVisibility, :flyToView, :link
 
@@ -2185,6 +2272,7 @@ module Kamelopard
         end
     end
 
+    # Corresponds to Google Earth's gx:Track extension to KML
     class Track < Geometry
         attr_accessor :altitudeMode, :when, :coord, :angles, :model
         def initialize(options = {})
@@ -2210,5 +2298,43 @@ module Kamelopard
             e
         end
     end
+
+    # Viewsyncrelay action
+    class VSRAction < Object
+        attr_accessor :name, :tour_name, :verbose, :fail_count, :input,
+            :action, :exit_action, :repeat, :constraints, :reset_constraints,
+            :initially_disabled
+        # XXX Consider adding some constraints, so that things like @name and @action don't go nil
+        # XXX Also ensure constraints and reset_constraints are hashes,
+        #   containing reasonable values, and reasonable keys ('latitude' vs.
+        #   :latitude, for instance)
+
+        def initialize(name, options = {})
+            @name = name
+            @constraints = {}
+            @repeat = 'DEFAULT'
+            @input = 'ALL'
+            super(options)
+
+            DocumentHolder.instance.current_document.vsr_actions << self
+        end
+
+        def to_hash
+            a = {}
+            a['name']               = @name               unless @name.nil?
+            a['id']                 = @id                 unless @id.nil?
+            a['input']              = @input              unless @input.nil?
+            a['tour_name']          = @tour_name          unless @tour_name.nil?
+            a['verbose']            = @verbose            unless @verbose.nil?
+            a['fail_count']         = @fail_count         unless @fail_count.nil?
+            a['action']             = @action             unless @action.nil?
+            a['exit_action']        = @exit_action        unless @exit_action.nil?
+            a['repeat']             = @repeat             unless @repeat.nil?
+            a['initially_disabled'] = @initially_disabled unless @initially_disabled.nil?
+            a['constraints']        = @constraints        unless @constraints.nil?
+            a['reset_constraints']  = @reset_constraints  unless @reset_constraints.nil?
+            a
+        end
+    end
 end
 # End of Kamelopard module