caxlsx 2.0.2

data/lib/axlsx/drawing/chart.rb

@@ -0,0 +1,232 @@
+# encoding: UTF-8
+module Axlsx
+
+  # A Chart is the superclass for specific charts
+  # @note Worksheet#add_chart is the recommended way to create charts for your worksheets.
+  # @see README for examples
+  class Chart
+
+    include Axlsx::OptionsParser
+    # Creates a new chart object
+    # @param [GraphicalFrame] frame The frame that holds this chart.
+    # @option options [Cell, String] title
+    # @option options [Boolean] show_legend
+    # @option options [Array|String|Cell] start_at The X, Y coordinates defining the top left corner of the chart.
+    # @option options [Array|String|Cell] end_at The X, Y coordinates defining the bottom right corner of the chart.
+    def initialize(frame, options={})
+      @style = 18
+      @view_3D = nil
+      @graphic_frame=frame
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts << self
+      @series = SimpleTypedList.new Series
+      @show_legend = true
+      @display_blanks_as = :gap
+      @series_type = Series
+      @title = Title.new
+      parse_options options
+      start_at(*options[:start_at]) if options[:start_at]
+      end_at(*options[:end_at]) if options[:end_at]
+      yield self if block_given?
+    end
+
+    # The 3D view properties for the chart
+    attr_reader :view_3D
+    alias :view3D :view_3D
+
+    # A reference to the graphic frame that owns this chart
+    # @return [GraphicFrame]
+    attr_reader :graphic_frame
+
+    # A collection of series objects that are applied to the chart
+    # @return [SimpleTypedList]
+    attr_reader :series
+
+    # The type of series to use for this chart.
+    # @return [Series]
+    attr_reader :series_type
+
+    #TODO data labels!
+    def d_lbls
+      @d_lbls ||= DLbls.new(self.class)
+    end
+
+    # Indicates that colors should be varied by datum
+    # @return [Boolean]
+    attr_reader :vary_colors
+ 
+    # Configures the vary_colors options for this chart
+    # @param [Boolean] v The value to set
+    def vary_colors=(v) Axlsx::validate_boolean(v); @vary_colors = v; end
+
+    # The title object for the chart.
+    # @return [Title]
+    attr_reader :title
+
+    # The style for the chart.
+    # see ECMA Part 1 §21.2.2.196
+    # @return [Integer]
+    attr_reader :style
+
+    # Show the legend in the chart
+    # @return [Boolean]
+    attr_reader :show_legend
+
+    # How to display blank values
+    # Options are
+    # * gap:  Display nothing
+    # * span: Not sure what this does
+    # * zero: Display as if the value were zero, not blank
+    # @return [Symbol]
+    # Default :gap (although this really should vary by chart type and grouping)
+    attr_reader :display_blanks_as
+
+    # The relationship object for this chart.
+    # @return [Relationship]
+    def relationship
+      Relationship.new(self, CHART_R, "../#{pn}")
+    end
+
+    # The index of this chart in the workbooks charts collection
+    # @return [Integer]
+    def index
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts.index(self)
+    end
+
+    # The part name for this chart
+    # @return [String]
+    def pn
+      "#{CHART_PN % (index+1)}"
+    end
+
+    # The title object for the chart.
+    # @param [String, Cell] v
+    # @return [Title]
+    def title=(v)
+      DataTypeValidator.validate "#{self.class}.title", [String, Cell], v
+      if v.is_a?(String)
+        @title.text = v
+      elsif v.is_a?(Cell)
+        @title.cell = v
+      end
+    end
+
+    # Show the legend in the chart
+    # @param [Boolean] v
+    # @return [Boolean]
+    def show_legend=(v) Axlsx::validate_boolean(v); @show_legend = v; end
+
+    # How to display blank values
+    # @see display_blanks_as
+    # @param [Symbol] v
+    # @return [Symbol]
+    def display_blanks_as=(v) Axlsx::validate_display_blanks_as(v); @display_blanks_as = v; end
+
+    # The style for the chart.
+    # see ECMA Part 1 §21.2.2.196
+    # @param [Integer] v must be between 1 and 48
+    def style=(v) DataTypeValidator.validate "Chart.style", Integer, v, lambda { |arg| arg >= 1 && arg <= 48 }; @style = v; end
+
+    # backwards compatibility to allow chart.to and chart.from access to anchor markers
+    # @note This will be disconinued in version 2.0.0. Please use the end_at method
+    def to
+      @graphic_frame.anchor.to
+    end
+
+    # backwards compatibility to allow chart.to and chart.from access to anchor markers
+    # @note This will be disconinued in version 2.0.0. please use the start_at method
+    def from
+      @graphic_frame.anchor.from
+    end
+
+    # Adds a new series to the chart's series collection.
+    # @return [Series]
+    # @see Series
+    def add_series(options={})
+      @series_type.new(self, options)
+      @series.last
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<?xml version="1.0" encoding="UTF-8"?>'
+      str << '<c:chartSpace xmlns:c="' << XML_NS_C << '" xmlns:a="' << XML_NS_A << '" xmlns:r="' << XML_NS_R << '">'
+      str << '<c:date1904 val="' << Axlsx::Workbook.date1904.to_s << '"/>'
+      str << '<c:style val="' << style.to_s << '"/>'
+      str << '<c:chart>'
+      @title.to_xml_string str
+      str << '<c:autoTitleDeleted val="' << (@title == nil).to_s << '"/>'
+      @view_3D.to_xml_string(str) if @view_3D
+      str << '<c:floor><c:thickness val="0"/></c:floor>'
+      str << '<c:sideWall><c:thickness val="0"/></c:sideWall>'
+      str << '<c:backWall><c:thickness val="0"/></c:backWall>'
+      str << '<c:plotArea>'
+      str << '<c:layout/>'
+      yield str if block_given?
+      str << '</c:plotArea>'
+      if @show_legend
+        str << '<c:legend>'
+        str << '<c:legendPos val="r"/>'
+        str << '<c:layout/>'
+        str << '<c:overlay val="0"/>'
+        str << '</c:legend>'
+      end
+      str << '<c:plotVisOnly val="1"/>'
+      str << '<c:dispBlanksAs val="' << display_blanks_as.to_s << '"/>'
+      str << '<c:showDLblsOverMax val="1"/>'
+      str << '</c:chart>'
+      str << '<c:printSettings>'
+      str << '<c:headerFooter/>'
+      str << '<c:pageMargins b="1.0" l="0.75" r="0.75" t="1.0" header="0.5" footer="0.5"/>'
+      str << '<c:pageSetup/>'
+      str << '</c:printSettings>'
+      str << '</c:chartSpace>'
+    end
+
+    # This is a short cut method to set the anchor start marker position
+    # If you need finer granularity in positioning use
+    #
+    # This helper method acceps a fairly wide range of inputs exampled
+    # below
+    #
+    # @example
+    #
+    #      start_at 0, 5 # The anchor start marker is set to 6th row of
+    #      the first column
+    #
+    #      start_at [0, 5] # The anchor start marker is set to start on the 6th row
+    #      of the first column
+    #
+    #      start_at "C1" # The anchor start marker is set to start on the first row
+    #      of the third column
+    #
+    #      start_at sheet.rows.first.cells.last # The anchor start
+    #      marker is set to the location of a specific cell.
+    #
+    # @param [Array|String|Cell] x the column, coordinates, string
+    # reference or cell to use in setting the start marker position.
+    # @param [Integer] y The row
+    # @return [Marker]
+    def start_at(x=0, y=0)
+      @graphic_frame.anchor.start_at(x, y)
+    end
+
+    # This is a short cut method to set the end anchor position
+    # If you need finer granularity in positioning use
+    # graphic_frame.anchor.to.colOff / rowOff
+    # @param [Integer] x The column - default 10
+    # @param [Integer] y The row - default 10
+    # @return [Marker]
+    # @see start_at
+    def end_at(x=10, y=10)
+      @graphic_frame.anchor.end_at(x, y)
+    end
+
+    # sets the view_3D object for the chart
+    def view_3D=(v) DataTypeValidator.validate "#{self.class}.view_3D", View3D, v; @view_3D = v; end
+    alias :view3D= :view_3D=
+
+  end
+
+end

data/lib/axlsx/drawing/d_lbls.rb

@@ -0,0 +1,90 @@
+module Axlsx
+  # There are more elements in the dLbls spec that allow for
+  # customizations and formatting. For now, I am just implementing the
+  # basics.
+  #The DLbls class manages serialization of data labels
+  # showLeaderLines and leaderLines are not currently implemented
+  class DLbls
+
+    include Axlsx::Accessors
+    include Axlsx::OptionsParser 
+    # creates a new DLbls object
+    def initialize(chart_type, options={})
+      raise ArgumentError, 'chart_type must inherit from Chart' unless [Chart, LineChart].include?(chart_type.superclass)
+      @chart_type = chart_type
+      initialize_defaults
+      parse_options options
+    end
+
+    # These attributes are all boolean so I'm doing a bit of a hand
+    # waving magic show to set up the attriubte accessors
+    # @note 
+    #   not all charts support all methods! 
+    #   Bar3DChart and Line3DChart and ScatterChart do not support d_lbl_pos or show_leader_lines
+    #    
+    boolean_attr_accessor :show_legend_key, 
+                          :show_val, 
+                          :show_cat_name, 
+                          :show_ser_name, 
+                          :show_percent, 
+                          :show_bubble_size, 
+                          :show_leader_lines
+
+    # Initialize all the values to false as Excel requires them to
+    # explicitly be disabled or all will show.
+    def initialize_defaults
+      [:show_legend_key, :show_val, :show_cat_name, 
+       :show_ser_name, :show_percent, :show_bubble_size, 
+       :show_leader_lines].each do |attr|
+        self.send("#{attr}=", false)
+      end
+    end
+
+    # The chart type that is using this data lables instance. 
+    # This affects the xml output as not all chart types support the
+    # same data label attributes. 
+    attr_reader :chart_type
+
+    # The position of the data labels in the chart
+    # @see d_lbl_pos= for a list of allowed values
+    # @return [Symbol]
+    def d_lbl_pos
+      return unless @chart_type == Pie3DChart
+      @d_lbl_pos ||= :bestFit
+    end
+
+    # @see DLbls#d_lbl_pos
+    # Assigns the label postion for this data labels on this chart.
+    # Allowed positions are :bestFilt, :b, :ctr, :inBase, :inEnd, :l,
+    # :outEnd, :r and :t
+    # The default is :bestFit
+    # @param [Symbol] label_position the postion you want to use.
+    def d_lbl_pos=(label_position)
+      return unless @chart_type == Pie3DChart
+      Axlsx::RestrictionValidator.validate 'DLbls#d_lbl_pos',  [:bestFit, :b, :ctr, :inBase, :inEnd, :l, :outEnd, :r, :t], label_position
+      @d_lbl_pos = label_position
+    end
+
+   
+    # serializes the data labels
+    # @return [String]
+    def to_xml_string(str = '')
+      validate_attributes_for_chart_type
+      str << '<c:dLbls>'
+      %w(d_lbl_pos show_legend_key show_val show_cat_name show_ser_name show_percent show_bubble_size show_leader_lines).each do |key|
+        next unless instance_values.keys.include?(key) && instance_values[key] != nil
+        str <<  "<c:#{Axlsx::camel(key, false)} val='#{instance_values[key]}' />" 
+      end
+      str << '</c:dLbls>'
+    end
+
+    # nills out d_lbl_pos and show_leader_lines as these attributes, while valid in the spec actually chrash excel for any chart type other than pie charts.
+    def validate_attributes_for_chart_type
+      return if @chart_type == Pie3DChart
+      @d_lbl_pos = nil
+      @show_leader_lines = nil
+    end
+
+
+  end
+end

data/lib/axlsx/drawing/drawing.rb

@@ -0,0 +1,162 @@
+# encoding: UTF-8
+module Axlsx
+  require 'axlsx/drawing/d_lbls.rb'
+  require 'axlsx/drawing/title.rb'
+  require 'axlsx/drawing/series_title.rb'
+  require 'axlsx/drawing/series.rb'
+  require 'axlsx/drawing/pie_series.rb'
+  require 'axlsx/drawing/bar_series.rb'
+  require 'axlsx/drawing/line_series.rb'
+  require 'axlsx/drawing/scatter_series.rb'
+
+  require 'axlsx/drawing/scaling.rb'
+  require 'axlsx/drawing/axis.rb'
+
+  require 'axlsx/drawing/str_val.rb'
+  require 'axlsx/drawing/num_val.rb'
+  require 'axlsx/drawing/str_data.rb'
+  require 'axlsx/drawing/num_data.rb'
+  require 'axlsx/drawing/num_data_source.rb'
+  require 'axlsx/drawing/ax_data_source.rb'
+
+  require 'axlsx/drawing/ser_axis.rb'
+  require 'axlsx/drawing/cat_axis.rb'
+  require 'axlsx/drawing/val_axis.rb'
+  require 'axlsx/drawing/axes.rb'
+
+  require 'axlsx/drawing/marker.rb'
+
+  require 'axlsx/drawing/one_cell_anchor.rb'
+  require 'axlsx/drawing/two_cell_anchor.rb'
+  require 'axlsx/drawing/graphic_frame.rb'
+
+  require 'axlsx/drawing/view_3D.rb'
+  require 'axlsx/drawing/chart.rb'
+  require 'axlsx/drawing/pie_3D_chart.rb'
+  require 'axlsx/drawing/bar_3D_chart.rb'
+  require 'axlsx/drawing/line_chart.rb'
+  require 'axlsx/drawing/line_3D_chart.rb'
+  require 'axlsx/drawing/scatter_chart.rb'
+
+  require 'axlsx/drawing/picture_locking.rb'
+  require 'axlsx/drawing/pic.rb'
+  require 'axlsx/drawing/hyperlink.rb'
+
+  require 'axlsx/drawing/vml_drawing.rb'
+  require 'axlsx/drawing/vml_shape.rb'
+
+  # A Drawing is a canvas for charts and images. Each worksheet has a single drawing that manages anchors.
+  # The anchors reference the charts or images via graphical frames. This is not a trivial relationship so please do follow the advice in the note.
+  # @note The recommended way to manage drawings is to use the Worksheet.add_chart and Worksheet.add_image methods.
+  # @see Worksheet#add_chart
+  # @see Worksheet#add_image
+  # @see Chart
+  # see examples/example.rb for an example of how to create a chart.
+  class Drawing
+
+    # The worksheet that owns the drawing
+    # @return [Worksheet]
+    attr_reader :worksheet
+
+    # A collection of anchors for this drawing
+    # only TwoCellAnchors are supported in this version
+    # @return [SimpleTypedList]
+    attr_reader :anchors
+
+    # Creates a new Drawing object
+    # @param [Worksheet] worksheet The worksheet that owns this drawing
+    def initialize(worksheet)
+      DataTypeValidator.validate "Drawing.worksheet", Worksheet, worksheet
+      @worksheet = worksheet
+      @worksheet.workbook.drawings << self
+      @anchors = SimpleTypedList.new [TwoCellAnchor, OneCellAnchor]
+    end
+
+
+    # Adds an image to the chart If th end_at option is specified we create a two cell anchor. By default we use a one cell anchor.
+    # @note The recommended way to manage images is to use Worksheet.add_image. Please refer to that method for documentation.
+    # @see Worksheet#add_image
+    # @return [Pic]
+    def add_image(options={})
+      if options[:end_at]
+        TwoCellAnchor.new(self, options).add_pic(options)
+      else
+        OneCellAnchor.new(self, options)
+      end
+      @anchors.last.object
+    end
+
+    # Adds a chart to the drawing.
+    # @note The recommended way to manage charts is to use Worksheet.add_chart. Please refer to that method for documentation.
+    # @see Worksheet#add_chart
+    def add_chart(chart_type, options={})
+      TwoCellAnchor.new(self, options)
+      @anchors.last.add_chart(chart_type, options)
+    end
+
+    # An array of charts that are associated with this drawing's anchors
+    # @return [Array]
+    def charts
+      charts = @anchors.select { |a| a.object.is_a?(GraphicFrame) }
+      charts.map { |a| a.object.chart }
+    end
+
+    # An array of hyperlink objects associated with this drawings images
+    # @return [Array]
+    def hyperlinks
+      links = self.images.select { |a| a.hyperlink.is_a?(Hyperlink) }
+      links.map { |a| a.hyperlink }
+    end
+
+    # An array of image objects that are associated with this drawing's anchors
+    # @return [Array]
+    def images
+      images = @anchors.select { |a| a.object.is_a?(Pic) }
+      images.map { |a| a.object }
+    end
+
+    # The index of this drawing in the owning workbooks's drawings collection.
+    # @return [Integer]
+    def index
+      @worksheet.workbook.drawings.index(self)
+    end
+
+    # The part name for this drawing
+    # @return [String]
+    def pn
+      "#{DRAWING_PN % (index+1)}"
+    end
+
+    # The relational part name for this drawing
+    # #NOTE This should be rewritten to return an Axlsx::Relationship object.
+    # @return [String]
+    def rels_pn
+      "#{DRAWING_RELS_PN % (index+1)}"
+    end
+
+    # A list of objects this drawing holds.
+    # @return [Array]
+    def child_objects
+      charts + images + hyperlinks
+    end
+
+    # The drawing's relationships.
+    # @return [Relationships]
+    def relationships
+      r = Relationships.new
+      child_objects.each { |child| r << child.relationship }
+      r
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+      str << '<xdr:wsDr xmlns:xdr="' << XML_NS_XDR << '" xmlns:a="' << XML_NS_A << '">'
+      anchors.each { |anchor| anchor.to_xml_string(str) }
+      str << '</xdr:wsDr>'
+    end
+
+  end
+end