dg-axlsx 2.1.0

data/lib/axlsx/drawing/bubble_series.rb

@@ -0,0 +1,63 @@
+# encoding: UTF-8
+module Axlsx
+
+  # A BubbleSeries defines the x/y position and bubble size of data in the chart
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  # @see examples/example.rb
+  class BubbleSeries < Series
+
+    # The x data for this series.
+    # @return [AxDataSource]
+    attr_reader :xData
+
+    # The y data for this series.
+    # @return [NumDataSource]
+    attr_reader :yData
+
+    # The bubble size for this series.
+    # @return [NumDataSource]
+    attr_reader :bubbleSize
+
+    # The fill color for this series.
+    # Red, green, and blue is expressed as sequence of hex digits, RRGGBB. A perceptual gamma of 2.2 is used.
+    # @return [String]
+    attr_reader :color
+
+    # Creates a new BubbleSeries
+    def initialize(chart, options={})
+      @xData, @yData, @bubbleSize = nil
+      super(chart, options)
+      @xData = AxDataSource.new(:tag_name => :xVal, :data => options[:xData]) unless options[:xData].nil?
+      @yData = NumDataSource.new({:tag_name => :yVal, :data => options[:yData]}) unless options[:yData].nil?
+      @bubbleSize = NumDataSource.new({:tag_name => :bubbleSize, :data => options[:bubbleSize]}) unless options[:bubbleSize].nil?
+    end
+
+    # @see color
+    def color=(v)
+      @color = v
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      super(str) do
+        # needs to override the super color here to push in ln/and something else!
+        if color
+          str << '<c:spPr><a:solidFill>'
+          str << ('<a:srgbClr val="' << color << '"/>')
+          str << '</a:solidFill>'
+          str << '<a:ln><a:solidFill>'
+          str << ('<a:srgbClr val="' << color << '"/></a:solidFill></a:ln>')
+          str << '</c:spPr>'
+        end
+        @xData.to_xml_string(str) unless @xData.nil?
+        @yData.to_xml_string(str) unless @yData.nil?
+        @bubbleSize.to_xml_string(str) unless @bubbleSize.nil?
+      end
+      str
+    end
+  end
+end

data/lib/axlsx/drawing/cat_axis.rb

@@ -0,0 +1,85 @@
+# encoding: UTF-8
+module Axlsx
+  #A CatAxis object defines a chart category axis
+  class CatAxis < Axis
+
+    # Creates a new CatAxis object
+    # @option options [Integer] tick_lbl_skip
+    # @option options [Integer] tick_mark_skip
+    def initialize(options={})
+      @tick_lbl_skip = 1
+      @tick_mark_skip = 1
+      self.auto = 1
+      self.lbl_algn = :ctr
+      self.lbl_offset = "100"
+      super(options)
+    end
+
+    # From the docs: This element specifies that this axis is a date or text axis based on the data that is used for the axis labels, not a specific choice.
+    # @return [Boolean]
+    attr_reader :auto
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:ctr, :l, :r]
+    # @return [Symbol]
+    attr_reader :lbl_algn
+    alias :lblAlgn :lbl_algn
+
+    # The offset of the labels
+    # must be between a string between 0 and 1000
+    # @return [Integer]
+    attr_reader :lbl_offset
+    alias :lblOffset :lbl_offset
+
+    # The number of tick lables to skip between labels
+    # @return [Integer]
+    attr_reader :tick_lbl_skip
+    alias :tickLblSkip :tick_lbl_skip
+
+    # The number of tickmarks to be skipped before the next one is rendered.
+    # @return [Boolean]
+    attr_reader :tick_mark_skip
+    alias :tickMarkSkip :tick_mark_skip
+
+    # regex for validating label offset
+    LBL_OFFSET_REGEX = /0*(([0-9])|([1-9][0-9])|([1-9][0-9][0-9])|1000)/
+
+    # @see tick_lbl_skip
+    def tick_lbl_skip=(v) Axlsx::validate_unsigned_int(v); @tick_lbl_skip = v; end
+    alias :tickLblSkip= :tick_lbl_skip=
+
+    # @see tick_mark_skip
+    def tick_mark_skip=(v) Axlsx::validate_unsigned_int(v); @tick_mark_skip = v; end
+    alias :tickMarkSkip= :tick_mark_skip=
+
+    # From the docs: This element specifies that this axis is a date or text axis based on the data that is used for the axis labels, not a specific choice.
+    def auto=(v) Axlsx::validate_boolean(v); @auto = v; end
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:ctr, :l, :r]
+    def lbl_algn=(v) RestrictionValidator.validate "#{self.class}.lbl_algn", [:ctr, :l, :r], v; @lbl_algn = v; end
+    alias :lblAlgn= :lbl_algn=
+
+    # The offset of the labels
+    # must be between a string between 0 and 1000
+    def lbl_offset=(v) RegexValidator.validate "#{self.class}.lbl_offset", LBL_OFFSET_REGEX, v; @lbl_offset = v; end
+    alias :lblOffset= :lbl_offset=
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<c:catAx>'
+      super(str)
+      str << ('<c:auto val="' << @auto.to_s << '"/>')
+      str << ('<c:lblAlgn val="' << @lbl_algn.to_s << '"/>')
+      str << ('<c:lblOffset val="' << @lbl_offset.to_i.to_s << '"/>')
+      str << ('<c:tickLblSkip val="' << @tick_lbl_skip.to_s << '"/>')
+      str << ('<c:tickMarkSkip val="' << @tick_mark_skip.to_s << '"/>')
+      str << '</c:catAx>'
+    end
+
+  end
+
+
+end

data/lib/axlsx/drawing/chart.rb

@@ -0,0 +1,269 @@
+# 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 [Symbol] legend_position
+    # @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
+      @legend_position = :r
+      @display_blanks_as = :gap
+      @series_type = Series
+      @title = Title.new
+      @bg_color = nil
+      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
+
+    # Set the location of the chart's legend
+    # @return [Symbol] The position of this legend
+    # @note
+    #  The following are allowed
+    #    :b
+    #    :l
+    #    :r
+    #    :t
+    #    :tr
+    attr_reader :legend_position
+
+    # 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
+
+    # Background color for the chart
+    # @return [String]
+    attr_reader :bg_color
+
+    # 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
+
+    # @see legend_position
+    def legend_position=(v) RestrictionValidator.validate "Chart.legend_position", [:b, :l, :r, :t, :tr], v; @legend_position = 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
+
+    # Assigns a background color to chart area
+    def bg_color=(v)
+      DataTypeValidator.validate(:color, Color, Color.new(:rgb => v))
+      @bg_color = v
+    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 if block_given?
+      str << '</c:plotArea>'
+      if @show_legend
+        str << '<c:legend>'
+        str << ('<c:legendPos val="' << @legend_position.to_s << '"/>')
+        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>'
+      if bg_color
+        str << '<c:spPr>'
+        str << '<a:solidFill>'
+        str << '<a:srgbClr val="' << bg_color << '"/>'
+        str << '</a:solidFill>'
+        str << '<a:ln>'
+        str << '<a:noFill/>'
+        str << '</a:ln>'
+        str << '</c:spPr>'
+      end
+      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