axlsx-alt 3.0.0

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 [Pie3DChart, LineChart].include? @chart_type
+      @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 [Pie3DChart, LineChart].include? @chart_type
+      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 [Pie3DChart, LineChart].include? @chart_type
+      @d_lbl_pos = nil
+      @show_leader_lines = nil
+    end
+
+
+  end
+end

data/lib/axlsx/drawing/drawing.rb

@@ -0,0 +1,167 @@
+# 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/bubble_series.rb'
+  require 'axlsx/drawing/area_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/bar_chart.rb'
+  require 'axlsx/drawing/line_chart.rb'
+  require 'axlsx/drawing/line_3D_chart.rb'
+  require 'axlsx/drawing/scatter_chart.rb'
+  require 'axlsx/drawing/bubble_chart.rb'
+  require 'axlsx/drawing/area_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

data/lib/axlsx/drawing/graphic_frame.rb

@@ -0,0 +1,54 @@
+# encoding: UTF-8
+module Axlsx
+  # A graphic frame defines a container for a chart object
+  # @note The recommended way to manage charts is Worksheet#add_chart
+  # @see Worksheet#add_chart
+  class GraphicFrame
+
+    # A reference to the chart object associated with this frame
+    # @return [Chart]
+    attr_reader :chart
+
+    # A anchor that holds this frame
+    # @return [TwoCellAnchor]
+    attr_reader :anchor
+
+    # Creates a new GraphicFrame object
+    # @param [TwoCellAnchor] anchor
+    # @param [Class] chart_type
+    def initialize(anchor, chart_type, options)
+      DataTypeValidator.validate "Drawing.chart_type", Chart, chart_type
+      @anchor = anchor
+      @chart = chart_type.new(self, options)
+    end
+
+    # The relationship id for this graphic frame.
+    # @return [String]
+    def rId
+      @anchor.drawing.relationships.for(chart).Id
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      # macro attribute should be optional!
+      str << '<xdr:graphicFrame>'
+      str << '<xdr:nvGraphicFramePr>'
+      str << ('<xdr:cNvPr id="' << @anchor.drawing.index.to_s << '" name="' << 'item_' << @anchor.drawing.index.to_s << '"/>')
+      str << '<xdr:cNvGraphicFramePr/>'
+      str << '</xdr:nvGraphicFramePr>'
+      str << '<xdr:xfrm>'
+      str << '<a:off x="0" y="0"/>'
+      str << '<a:ext cx="0" cy="0"/>'
+      str << '</xdr:xfrm>'
+      str << '<a:graphic>'
+      str << ('<a:graphicData uri="' << XML_NS_C << '">')
+      str << ('<c:chart xmlns:c="' << XML_NS_C << '" xmlns:r="' << XML_NS_R << '" r:id="' << rId << '"/>')
+      str << '</a:graphicData>'
+      str << '</a:graphic>'
+      str << '</xdr:graphicFrame>'
+    end
+
+  end
+end

data/lib/axlsx/drawing/hyperlink.rb

@@ -0,0 +1,100 @@
+# encoding: UTF-8
+module Axlsx
+  # a hyperlink object adds an action to an image when clicked so that when the image is clicked the link is fecthed.
+  # @note using the hyperlink option when calling add_image on a drawing object is the recommended way to manage hyperlinks
+  # @see {file:README} README
+  class Hyperlink
+
+    include Axlsx::SerializedAttributes
+    include Axlsx::OptionsParser
+
+    #Creates a hyperlink object
+    # parent must be a Pic for now, although I expect that other object support this tag and its cNvPr parent
+    # @param [Pic] parent
+    # @option options [String] tooltip message shown when hyperlinked object is hovered over with mouse.
+    # @option options [String] tgtFrame Target frame for opening hyperlink
+    # @option options [String] invalidUrl supposedly use to store the href when we know it is an invalid resource.
+    # @option options [String] href the target resource this hyperlink links to. This is actually stored on the relationship.
+    # @option options [String] action A string that can be used to perform specific actions. For excel please see this reference: http://msdn.microsoft.com/en-us/library/ff532419%28v=office.12%29.aspx
+    # @option options [Boolean] endSnd terminate any sound events when processing this link
+    # @option options [Boolean] history include this link in the list of visited links for the applications history.
+    # @option options [Boolean] highlightClick indicate that the link has already been visited.
+    def initialize(parent, options={})
+      DataTypeValidator.validate "Hyperlink.parent", [Pic], parent
+      @parent = parent
+      parse_options options
+      yield self if block_given?
+    end
+
+    serializable_attributes :invalid_url, :action, :end_snd, :highlight_click, :history, :tgt_frame, :tooltip
+
+    # The destination of the hyperlink stored in the drawing's relationships document.
+    # @return [String]
+    attr_accessor :href
+
+    # The spec says: Specifies the URL when it has been determined by the generating application that the URL is invalid. That is the generating application can still store the URL but it is known that this URL is not correct.
+    #
+    # What exactly that means is beyond me so if you ever use this, let me know!
+    # @return [String]
+    attr_accessor :invalid_url
+    alias :invalidUrl :invalid_url
+    alias :invalidUrl= :invalid_url=
+
+    #An action to take when the link is clicked. The specification says "This can be used to specify a slide to be navigated to or a script of code to be run." but in most cases you will not need to do anything with this. MS does reserve a few interesting strings. @see http://msdn.microsoft.com/en-us/library/ff532419%28v=office.12%29.aspx
+    # @return [String]
+    attr_accessor :action
+
+    # Specifies if all sound events should be terminated when this link is clicked.
+    # @return [Boolean]
+    attr_reader :end_snd
+    alias :endSnd :end_snd
+
+    # @see endSnd
+    # @param [Boolean] v The boolean value indicating the termination of playing sounds on click
+    # @return [Boolean]
+    def end_snd=(v) Axlsx::validate_boolean(v); @end_snd = v end
+    alias :endSnd= :end_snd=
+
+    # indicates that the link has already been clicked.
+    # @return [Boolean]
+    attr_reader :highlight_click
+    alias :highlightClick :highlight_click
+
+    # @see highlightClick
+    # @param [Boolean] v The value to assign
+    def highlight_click=(v) Axlsx::validate_boolean(v); @highlight_click = v end
+    alias :highlightClick= :highlight_click=
+
+    # From the specs: Specifies whether to add this URI to the history when navigating to it. This allows for the viewing of this presentation without the storing of history information on the viewing machine. If this attribute is omitted, then a value of 1 or true is assumed.
+    # @return [Boolean]
+    attr_reader :history
+
+    # @see history
+    # param [Boolean] v The value to assing
+    def history=(v) Axlsx::validate_boolean(v); @history = v end
+
+    # From the specs: Specifies the target frame that is to be used when opening this hyperlink. When the hyperlink is activated this attribute is used to determine if a new window is launched for viewing or if an existing one can be used. If this attribute is omitted, than a new window is opened.
+    # @return [String]
+    attr_accessor :tgt_frame
+    alias :tgtFrame :tgt_frame
+    alias :tgtFrame= :tgt_frame=
+
+    # Text to show when you mouse over the hyperlink. If you do not set this, the href property will be shown.
+    # @return [String]
+    attr_accessor :tooltip
+
+    # The relationship object for this hyperlink.
+    # @return [Relationship]
+    def relationship
+      Relationship.new(self, HYPERLINK_R, href, :target_mode => :External)
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      serialized_tag 'a:hlinkClick', str, {:'r:id' => relationship.Id, :'xmlns:r' => XML_NS_R }
+    end
+
+  end
+end

data/lib/axlsx/drawing/line_3D_chart.rb

@@ -0,0 +1,68 @@
+# encoding: UTF-8
+module Axlsx
+
+  # The Line3DChart is a three dimentional line chart (who would have guessed?) that you can add to your worksheet.
+  # @example Creating a chart
+  #   # This example creates a line in a single sheet.
+  #   require "rubygems" # if that is your preferred way to manage gems!
+  #   require "axlsx"
+  #
+  #   p = Axlsx::Package.new
+  #   ws = p.workbook.add_worksheet
+  #   ws.add_row ["This is a chart with no data in the sheet"]
+  #
+  #   chart = ws.add_chart(Axlsx::Line3DChart, :start_at=> [0,1], :end_at=>[0,6], :t#itle=>"Most Popular Pets")
+  #   chart.add_series :data => [1, 9, 10], :labels => ["Slimy Reptiles", "Fuzzy Bunnies", "Rottweiler"]
+  #
+  # @see Worksheet#add_chart
+  # @see Worksheet#add_row
+  # @see Chart#add_series
+  # @see Series
+  # @see Package#serialize
+  class Line3DChart < Axlsx::LineChart
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    attr_reader :gap_depth
+    alias :gapDepth :gap_depth
+
+    # validation regex for gap amount percent
+    GAP_AMOUNT_PERCENT = /0*(([0-9])|([1-9][0-9])|([1-4][0-9][0-9])|500)%/
+
+    # the category axis
+    # @return [Axis]
+    def ser_axis
+      axes[:ser_axis]
+    end
+    alias :serAxis :ser_axis
+
+    # Creates a new line chart object
+    # @option options [String] gap_depth
+    # @see Chart
+    # @see lineChart
+    # @see View3D
+    def initialize(frame, options={})
+      @gap_depth = nil
+      @view_3D = View3D.new({:r_ang_ax=>1}.merge(options))
+      super(frame, options)
+      axes.add_axis :ser_axis, SerAxis
+    end
+
+
+    # @see gapDepth
+    def gap_depth=(v)
+      RegexValidator.validate "Line3DChart.gapWidth", GAP_AMOUNT_PERCENT, v
+      @gap_depth=(v)
+    end
+    alias :gapDepth= :gap_depth=
+
+      # Serializes the object
+      # @param [String] str
+      # @return [String]
+      def to_xml_string(str = '')
+        super(str) do
+          str << ('<c:gapDepth val="' << @gap_depth.to_s << '"/>') unless @gap_depth.nil?
+        end
+      end
+  end
+end