rubyvis 0.1.7 → 0.2.0

data/lib/rubyvis/mark.rb

@@ -1,3 +1,4 @@
+
 module Rubyvis
  # Constructs a new mark with default properties. Marks, with the exception of
  # the root panel, are not typically constructed directly; instead, they are
@@ -69,7 +70,7 @@ module Rubyvis
     # @attr [Panel]
     attr_accessor :root
     
-    # The child index. -1 if the enclosing parent panel is null; otherwise, the
+    # The child index. -1 if the enclosing parent panel is nil; otherwise, the
     # zero-based index of this mark into the parent panel's <tt>children</tt>
     # array.
     # @attr [Number]
@@ -118,7 +119,7 @@ module Rubyvis
     # If a cast function has been assigned to the specified property name, the
     # property function is wrapped by the cast function, or, if a constant is
     # specified, the constant is immediately cast. Note, however, that if the
-    # property value is null, the cast function is not invoked.
+    # property value is nil, the cast function is not invoked.
     # 
     # Parameters:
     # * @param [String] name the property name.
@@ -128,8 +129,12 @@ module Rubyvis
     
     def self.property_method(name, _def, func=nil, klass=nil)
       return if klass.method_defined? name
-      klass.send(:define_method, name) do |*arguments|
+      klass.send(:define_method, name) do |*arguments,&block|
+        
         v,dummy = arguments
+        if block
+          v=block
+        end
         if _def and self.scene
           if arguments.size>0
             defs[name]=OpenStruct.new({:id=>(v.nil?) ? 0 : Rubyvis.id, :value=> v})
@@ -137,7 +142,8 @@ module Rubyvis
           end
           return defs[name]
         end
-        if arguments.size>0
+        
+        if arguments.size>0 or block
           v=v.to_proc if v.respond_to? :to_proc
           type=(!_def).to_i<<1 | (v.is_a? Proc).to_i          
           
@@ -379,7 +385,7 @@ module Rubyvis
     end
 
     # Create a new Mark
-    def initialize(opts=Hash.new)
+    def initialize(opts=Hash.new, &block)
       @_properties=[]
       opts.each {|k,v|
         self.send("#{k}=",v) if self.respond_to? k
@@ -390,9 +396,18 @@ module Rubyvis
       @index_defined = true
       @scale=1
       @scene=nil
+      if block
+        block.arity<1 ? self.instance_eval(&block) : block.call(self)
+      end
     end
     
     
+    
+    
+
+      
+    
+    
     # The mark type; a lower name. The type name controls rendering
     # behavior, and unless the rendering engine is extended, must be one of the
     # built-in concrete mark types: area, bar, dot, image, label, line, panel,
@@ -454,9 +469,9 @@ module Rubyvis
     
     
     #Returns the previous instance of this mark in the scene graph, or
-    # null if this is the first instance.
+    # nil if this is the first instance.
     #
-    # @return a node in the scene graph, or null.
+    # @return a node in the scene graph, or nil.
     def sibling
       (self.index==0) ? nil: self.scene[self.index-1]
     end
@@ -464,9 +479,9 @@ module Rubyvis
     
     # Returns the current instance in the scene graph of this mark,
     # in the previous instance of the enclosing parent panel. 
-    # May return null if this instance could not be found.
+    # May return nil if this instance could not be found.
     #
-    # @return a node in the scene graph, or null.
+    # @return a node in the scene graph, or nil.
     def cousin
       par=self.parent
       s= par ? par.sibling : nil
@@ -969,3 +984,5 @@ require 'rubyvis/mark/rule'
 require 'rubyvis/mark/label'
 require 'rubyvis/mark/dot'
 require 'rubyvis/mark/wedge'
+require 'rubyvis/mark/shorcut_methods'
+

data/lib/rubyvis/mark/anchor.rb

@@ -56,9 +56,10 @@ module Rubyvis
     # Create a new Anchor. Use Mark.add instead.
     
     def initialize(target)
-      super()
+      
       self.target=target
       self.parent=target.parent
+      super()
     end
     
     # Sets the prototype of this anchor to the specified mark. Any properties not

data/lib/rubyvis/mark/area.rb

@@ -4,7 +4,7 @@ module Rubyvis
     Rubyvis::Area
   end
   # Provides methods pertinents to area like-marks.
-  module AreaPrototype 
+  module AreaPrototype  # :nodoc:
     def fixed
       {
         :line_width=> true,
@@ -99,9 +99,107 @@ module Rubyvis
       return anchor
     end
   end
+  
+  # Represents an area mark: the solid area between two series of
+  # connected line segments. Unsurprisingly, areas are used most frequently for
+  # area charts.
+  #
+  # <p>Just as a line represents a polyline, the <tt>Area</tt> mark type
+  # represents a <i>polygon</i>. However, an area is not an arbitrary polygon;
+  # vertices are paired either horizontally or vertically into parallel
+  # <i>spans</i>, and each span corresponds to an associated datum. Either the
+  # width or the height must be specified, but not both; this determines whether
+  # the area is horizontally-oriented or vertically-oriented.  Like lines, areas
+  # can be stroked and filled with arbitrary colors.
+
   class Area < Mark
     include AreaPrototype
     @properties=Mark.properties.dup
+    
+    
+  ##
+  # :attr: width
+  # The width of a given span, in pixels; used for horizontal spans. If the width
+  # is specified, the height property should be 0 (the default). Either the top
+  # or bottom property should be used to space the spans vertically, typically as
+  # a multiple of the index.
+  
+  
+  ##
+  # :attr: height  
+  # The height of a given span, in pixels; used for vertical spans. If the height
+  # is specified, the width property should be 0 (the default). Either the left
+  # or right property should be used to space the spans horizontally, typically
+  # as a multiple of the index.
+  
+  
+  ##
+  # :attr: line_width  
+  # The width of stroked lines, in pixels; used in conjunction with
+  # <tt>strokeStyle</tt> to stroke the perimeter of the area. Unlike the
+  # {@link Line} mark type, the entire perimeter is stroked, rather than just one
+  # edge. The default value of this property is 1.5, but since the default stroke
+  # style is null, area marks are not stroked by default.
+  #
+  # <p>This property is <i>fixed</i> for non-segmented areas. See
+  # {@link pv.Mark}.
+  
+  
+  ##
+  # :attr: stroke_style
+  # The style of stroked lines; used in conjunction with <tt>lineWidth</tt> to
+  # stroke the perimeter of the area. Unlike the {@link Line} mark type, the
+  # entire perimeter is stroked, rather than just one edge. The default value of
+  # this property is null, meaning areas are not stroked by default.
+  #
+  # <p>This property is <i>fixed</i> for non-segmented areas. See
+  # {@link pv.Mark}.
+  #
+  
+  
+  ##
+  # :attr: fill_style  
+  # The area fill style; if non-null, the interior of the polygon forming the
+  # area is filled with the specified color. The default value of this property
+  # is a categorical color.
+  #
+  # <p>This property is <i>fixed</i> for non-segmented areas. See
+  # {@link pv.Mark}.
+  
+  
+  ##
+  # :attr: segmented  
+  # Whether the area is segmented; whether variations in fill style, stroke
+  # style, and the other properties are treated as fixed. Rendering segmented
+  # areas is noticeably slower than non-segmented areas.
+  #
+  # <p>This property is <i>fixed</i>. See {@link pv.Mark}.
+  
+  
+  ##
+  # :attr: interpolate  
+  # How to interpolate between values. Linear interpolation ("linear") is the
+  # default, producing a straight line between points. For piecewise constant
+  # functions (i.e., step functions), either "step-before" or "step-after" can
+  # be specified. To draw open uniform b-splines, specify "basis".
+  # To draw cardinal splines, specify "cardinal"; see also Line.tension()
+  #
+  # <p>This property is <i>fixed</i>. See {@link pv.Mark}.
+  
+  
+  ##
+  # :attr: tension  
+  # The tension of cardinal splines; used in conjunction with
+  # interpolate("cardinal"). A value between 0 and 1 draws cardinal splines with
+  # the given tension. In some sense, the tension can be interpreted as the
+  # "length" of the tangent; a tension of 1 will yield all zero tangents (i.e.,
+  # linear interpolation), and a tension of 0 yields a Catmull-Rom spline. The
+  # default value is 0.7.
+  #
+  # <p>This property is <i>fixed</i>. See {@link pv.Mark}.
+    
+    
+    
     attr_accessor_dsl :width, :height, :line_width, [:stroke_style, lambda {|d| Rubyvis.color(d)}], [:fill_style, lambda {|d| Rubyvis.color(d)}], :segmented, :interpolate, :tension
     def type
       'area'

data/lib/rubyvis/mark/bar.rb

@@ -48,11 +48,11 @@ module Rubyvis
     ##
     # :attr: stroke_style
     # The style of stroked lines; used in conjunction with line_width to
-    # stroke the bar's border. The default value of this property is null, meaning bars are not stroked by default.
+    # stroke the bar's border. The default value of this property is nil, meaning bars are not stroked by default.
     
     ##
     # :attr: fill_style
-    # The bar fill style; if non-null, the interior of the bar is filled with the
+    # The bar fill style; if non-nil, the interior of the bar is filled with the
     # specified color. The default value of this property is a categorical color.
     
     attr_accessor_dsl :width, :height, :line_width, [:stroke_style, lambda {|d| Rubyvis.color(d)}], [:fill_style, lambda {|d| Rubyvis.color(d)}]

data/lib/rubyvis/mark/dot.rb

@@ -70,8 +70,8 @@ module Rubyvis
     
     ##
     # :attr: fill_style
-    # The fill style; if non-null, the interior of the dot is filled with the
-    # specified color. The default value of this property is null, meaning dots are
+    # The fill style; if non-nil, the interior of the dot is filled with the
+    # specified color. The default value of this property is nil, meaning dots are
     # not filled by default. See Rubyvis.color()
     
     attr_accessor_dsl :shape, :shape_angle, :shape_radius, :shape_size, :line_width, [:stroke_style, lambda {|d| Rubyvis.color(d)}], [:fill_style, lambda {|d| Rubyvis.color(d)}]

data/lib/rubyvis/mark/line.rb

@@ -3,7 +3,8 @@ module Rubyvis
   def self.Line
     Rubyvis::Line
   end
-  module LinePrototype 
+  # Provides methods pertinents to line like marks.  
+  module LinePrototype  # :nodoc:
     include AreaPrototype
     def line_anchor(name)
       anchor=area_anchor(name).text_align(lambda {|d|
@@ -14,26 +15,137 @@ module Rubyvis
       return anchor
     end
   end
+  
+  # Represents a series of connected line segments, or <i>polyline</i>,
+  # that can be stroked with a configurable color and thickness. Each
+  # articulation point in the line corresponds to a datum; for <i>n</i> points,
+  # <i>n</i>-1 connected line segments are drawn. The point is positioned using
+  # the box model. Arbitrary paths are also possible, allowing radar plots and
+  # other custom visualizations.
+  #
+  # <p>Like areas, lines can be stroked and filled with arbitrary colors. In most
+  # cases, lines are only stroked, but the fill style can be used to construct
+  # arbitrary polygons.
   class Line < Mark
     include AreaPrototype
     include LinePrototype
     @properties=Mark.properties.dup
+    
+      
+    ##
+    # :attr: line_width
+    # The width of stroked lines, in pixels; used in conjunction with
+    # +stroke_style+ to stroke the line.
+    
+    
+    ##
+    # :attr: stroke_style
+    # The style of stroked lines; used in conjunction with <tt>lineWidth</tt> to
+    # stroke the line. The default value of this property is a categorical color.
+    
+    
+    ##
+    # :attr: line_join
+    # The type of corners where two lines meet. Accepted values are "bevel",
+    # "round" and "miter". The default value is "miter".
+    #
+    # <p>For segmented lines, only "miter" joins and "linear" interpolation are
+    # currently supported. Any other value, including nil, will disable joins,
+    # producing disjoint line segments. Note that the miter joins must be computed
+    # manually (at least in the current SVG renderer); since this calculation may
+    # be expensive and unnecessary for small lines, specifying nil can improve
+    # performance significantly.
+    #
+    # <p>This property is <i>fixed</i>. See Rubyvis.Mark    
+    
+    ##
+    # :attr: fill_style
+    # The line fill style; if non-nil, the interior of the line is closed and
+    # filled with the specified color. The default value of this property is a
+    # nil, meaning that lines are not filled by default.
+    #
+    # <p>This property is <i>fixed</i>. See Rubyvis.Mark    
+    
+    
+    ##
+    # :attr: segmented
+    # Whether the line is segmented; whether variations in stroke style, line width and the other properties are treated as fixed. Rendering segmented lines is noticeably slower than non-segmented lines.
+    # <p>This property is <i>fixed</i>. See Rubyvis.Mark    
+    
+    
+    ##
+    # :attr: interpolate
+    # How to interpolate between values. Linear interpolation ("linear") is the
+    # default, producing a straight line between points. For piecewise constant
+    # functions (i.e., step functions), either "step-before" or "step-after" 
+    # can be specified. To draw a clockwise circular arc between points, 
+    # specify "polar"; to draw a counterclockwise circular arc between points,
+    # specify "polar-reverse". To draw open uniform b-splines, specify "basis". # To draw cardinal splines, specify "cardinal"; see also Line.tension()
+    #
+    # <p>This property is <i>fixed</i>. See Rubyvis.Mark    
+    
+    
+    ## 
+    # :attr: eccentricity
+    # The eccentricity of polar line segments; used in conjunction with
+    # interpolate("polar"). The default value of 0 means that line segments are
+    # drawn as circular arcs. A value of 1 draws a straight line. A value between 0
+    # and 1 draws an elliptical arc with the given eccentricity.
+    
+    
+    ##
+    # :attr: tension
+    # The tension of cardinal splines; used in conjunction with
+    # interpolate("cardinal"). A value between 0 and 1 draws cardinal splines with
+    # the given tension. In some sense, the tension can be interpreted as the
+    # "length" of the tangent; a tension of 1 will yield all zero tangents (i.e.,
+    # linear interpolation), and a tension of 0 yields a Catmull-Rom spline. The
+    # default value is 0.7.
+    #
+    # <p>This property is <i>fixed</i>. See Rubyvis.Mark    
+    
     attr_accessor_dsl :line_width, :line_join, [:stroke_style, lambda {|d| Rubyvis.color(d)}], [:fill_style, lambda {|d| Rubyvis.color(d)}], :segmented, :interpolate, :eccentricity, :tension
+    # Type of line
     def type
       "line"
     end
+    
+    # Constructs a new line anchor with default properties. Lines support five
+    # different anchors:<ul>
+    #
+    # <li>top
+    # <li>left
+    # <li>center
+    # <li>bottom
+    # <li>right
+    #
+    # </ul>In addition to positioning properties (left, right, top bottom), the
+    # anchors support text rendering properties (text-align, text-baseline). Text is
+    # rendered to appear outside the line. Note that this behavior is different
+    # from other mark anchors, which default to rendering text <i>inside</i> the
+    # mark.
+    #
+    # <p>For consistency with the other mark types, the anchor positions are
+    # defined in terms of their opposite edge. For example, the top anchor defines
+    # the bottom property, such that a bar added to the top anchor grows upward.
     def anchor(name)
       line_anchor(name)
     end
-    def bind(*args)
+    # Reuse Area's implementation for segmented bind & build.
+    def bind(*args) # :nodoc:
       area_bind(*args)
     end
-    def build_instance(*args)
+    # Reuse Area's implementation for segmented bind & build.
+    
+    def build_instance(*args) # :nodoc:
       area_build_instance(*args)
     end
+    # Default properties for lines. By default, there is no fill and the stroke
+    # style is a categorical color. The default interpolation is linear.
+
     def self.defaults
       a=Rubyvis::Colors.category10()
-      Line.new.extend(Mark.defaults).line_join('miter').line_width(1.5).stroke_style( lambda {return a.scale(self.parent.index)}).interpolate('linear').eccentricity(0).tension(7)
+      Line.new.extend(Mark.defaults).line_join('miter').line_width(1.5).stroke_style( lambda {return a.scale(self.parent.index)}).interpolate('linear').eccentricity(0).tension(0.7)
     end
   end
 end

data/lib/rubyvis/mark/panel.rb

@@ -12,9 +12,10 @@ module Rubyvis
     attr_accessor_dsl :transform, :overflow, :canvas
     attr_accessor :children, :root
     def initialize
-      super
       @children=[]
       @root=self
+      super
+      
     end
     def children_inspect(level=0)
       out=[]

data/lib/rubyvis/mark/shorcut_methods.rb

@@ -0,0 +1,58 @@
+class Rubyvis::Mark
+  ##
+  # :section: Ruby API
+  ##
+  
+  # Create 
+  def self.mark_method(name,mark) #:nodoc:
+    define_method(name) do |*args,&block|
+      opts=args[0]
+      opts||=Hash.new
+      if opts[:anchor]
+        base=anchor(opts[:anchor])
+      else
+        base=self
+      end
+      a=base.add(mark)
+      if block
+        block.arity<1 ? a.instance_eval(&block) : block.call(a)
+      end
+    end
+  end
+  ##
+  # :method: area(opts,&block)
+  #
+  mark_method :area, Rubyvis::Area
+  ##
+  # :method: bar(opts,&block)
+  #
+  mark_method :bar, Rubyvis::Bar
+  ##
+  # :method: dot(opts,&block)
+  #
+  mark_method :dot, Rubyvis::Dot
+  ##
+  # :method: _image(opts,&block)
+  #
+  mark_method :_image, Rubyvis::Image
+  ##
+  # :method: label(opts,&block)
+  #
+  mark_method :label, Rubyvis::Label
+  ##
+  # :method: line(opts,&block)
+  #
+  mark_method :line, Rubyvis::Line
+  ##
+  # :method: panel(opts,&block)
+  #
+  mark_method :panel, Rubyvis::Panel
+  ##
+  # :method: rule(opts,&block)
+  #    
+  mark_method :rule, Rubyvis::Rule
+  ##
+  # :method: wedge(opts,&block)
+  #    
+  mark_method :wedge, Rubyvis::Rule
+end