axlsx 1.1.8 → 1.2.0

data/lib/axlsx/drawing/d_lbls.rb

@@ -0,0 +1,100 @@
+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
+
+    # 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_ATTRIBUTES = [:show_legend_key, :show_val, :show_cat_name, :show_ser_name, :show_percent, :show_bubble_size, :show_leader_lines]
+
+    # creates a new DLbls object
+    def initialize(chart_type, options={})
+      raise ArgumentError, 'chart_type must inherit from Chart' unless chart_type.superclass == Chart
+      @chart_type = chart_type
+      initialize_defaults
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # Initialize all the values to false as Excel requires them to
+    # explicitly be disabled or all will show.
+    def initialize_defaults
+      BOOLEAN_ATTRIBUTES.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
+
+    # Dynamically create accessors for boolean attriubtes
+    BOOLEAN_ATTRIBUTES.each do |attr|    
+      class_eval %{
+      # The #{attr} attribute reader
+      # @return [Boolean]
+      attr_reader :#{attr} 
+
+      # The #{attr} writer
+      # @param [Boolean] value The value to assign to #{attr}
+      # @return [Boolean]
+      def #{attr}=(value)
+        Axlsx::validate_boolean(value)
+        @#{attr} = value
+      end
+      }
+    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

@@ -1,5 +1,6 @@
 # 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'
@@ -69,6 +70,7 @@ module Axlsx
       @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

data/lib/axlsx/drawing/line_3D_chart.rb

@@ -71,6 +71,7 @@ module Axlsx
       super(frame, options)
       @series_type = LineSeries
       @view_3D = View3D.new({:perspective=>30}.merge(options))
+      @d_lbls = nil
     end
 
     # @see grouping
@@ -94,14 +95,7 @@ module Axlsx
         str_inner << '<c:grouping val="' << grouping.to_s << '"/>'
         str_inner << '<c:varyColors val="1"/>'
         @series.each { |ser| ser.to_xml_string(str_inner) }
-        str_inner << '<c:dLbls>'
-        str_inner << '<c:showLegendKey val="0"/>'
-        str_inner << '<c:showVal val="0"/>'
-        str_inner << '<c:showCatName val="0"/>'
-        str_inner << '<c:showSerName val="0"/>'
-        str_inner << '<c:showPercent val="0"/>'
-        str_inner << '<c:showBubbleSize val="0"/>'
-        str_inner << '</c:dLbls>'
+        @d_lbls.to_xml_string(str) if @d_lbls
         str_inner << '<c:gapDepth val="' << @gapDepth.to_s << '"/>' unless @gapDepth.nil?
         str_inner << '<c:axId val="' << @catAxId.to_s << '"/>'
         str_inner << '<c:axId val="' << @valAxId.to_s << '"/>'
@@ -112,6 +106,5 @@ module Axlsx
         @serAxis.to_xml_string str_inner
       end
     end
-
   end
 end

data/lib/axlsx/drawing/pie_3D_chart.rb

@@ -26,6 +26,7 @@ module Axlsx
       super(frame, options)
       @series_type = PieSeries
       @view_3D = View3D.new({:rot_x =>30, :perspective=>30}.merge(options))
+      @d_lbls = nil
     end
 
     # Serializes the object
@@ -33,9 +34,11 @@ module Axlsx
     # @return [String]
     def to_xml_string(str = '')
       super(str) do |str_inner|
+
         str_inner << '<c:pie3DChart>'
         str_inner << '<c:varyColors val="1"/>'
         @series.each { |ser| ser.to_xml_string(str_inner) }
+        d_lbls.to_xml_string(str) if @d_lbls
         str_inner << '</c:pie3DChart>'
       end
     end

data/lib/axlsx/drawing/scatter_chart.rb

@@ -29,6 +29,7 @@ module Axlsx
       @yValAxis = ValAxis.new(@yValAxId, @xValAxId)
       super(frame, options)
       @series_type = ScatterSeries
+      @d_lbls = nil
       options.each do |o|
         self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
       end
@@ -49,14 +50,7 @@ module Axlsx
         str_inner << '<c:scatterStyle val="' << scatterStyle.to_s << '"/>'
         str_inner << '<c:varyColors val="1"/>'
         @series.each { |ser| ser.to_xml_string(str_inner) }
-        str_inner << '<c:dLbls>'
-        str_inner << '<c:showLegendKey val="0"/>'
-        str_inner << '<c:showVal val="0"/>'
-        str_inner << '<c:showCatName val="0"/>'
-        str_inner << '<c:showSerName val="0"/>'
-        str_inner << '<c:showPercent val="0"/>'
-        str_inner << '<c:showBubbleSize val="0"/>'
-        str_inner << '</c:dLbls>'
+        d_lbls.to_xml_string(str) if @d_lbls
         str_inner << '<c:axId val="' << @xValAxId.to_s << '"/>'
         str_inner << '<c:axId val="' << @yValAxId.to_s << '"/>'
         str_inner << '</c:scatterChart>'

data/lib/axlsx/drawing/two_cell_anchor.rb

@@ -25,7 +25,6 @@ module Axlsx
     # @return [Drawing]
     attr_reader :drawing
 
-
     # Creates a new TwoCellAnchor object
     # c.start_at 5, 9
     # @param [Drawing] drawing
@@ -37,6 +36,22 @@ module Axlsx
       @from, @to =  Marker.new, Marker.new(:col => 5, :row=>10)
     end
 
+    # sets the col, row attributes for the from marker.
+    # @note The recommended way to set the start position for graphical
+    # objects is directly thru the object. 
+    # @see Chart#start_at
+    def start_at(x, y)
+      set_marker_coords(x, y, from)
+    end
+
+    # sets the col, row attributes for the to marker
+    # @note the recommended way to set the to position for graphical
+    # objects is directly thru the object
+    # @see Char#end_at
+    def end_at(x, y)
+      set_marker_coords(x, y, to) 
+    end
+
     # Creates a graphic frame and chart object associated with this anchor
     # @return [Chart]
     def add_chart(chart_type, options)
@@ -70,6 +85,28 @@ module Axlsx
       str << '<xdr:clientData/>'
       str << '</xdr:twoCellAnchor>'
     end
+    private 
+
+    # parses coordinates and sets up a marker's row/col propery
+    def set_marker_coords(x, y, marker)
+      marker.col, marker.row = *parse_coord_args(x, y)
+    end
+
+    # handles multiple inputs for setting the position of a marker
+    # @see Chart#start_at
+    def parse_coord_args(x, y=0)
+      if x.is_a?(String)
+        x, y = *Axlsx::name_to_indices(x)
+      end
+      if x.is_a?(Cell)
+        x, y = *x.pos
+      end
+      if x.is_a?(Array)
+        x, y = *x
+      end
+      [x, y]
+    end
+
 
   end
 end

data/lib/axlsx/util/simple_typed_list.rb

@@ -50,6 +50,18 @@ module Axlsx
       @locked_at = nil
       self
     end
+    
+    # join operator
+    # @param [Array] v the array to join
+    # @raise [ArgumentError] if any of the values being joined are not
+    # one of the allowed types
+    # @return [SimpleTypedList]
+    def +(v)
+      v.each do |item| 
+        DataTypeValidator.validate "SimpleTypedList.+", @allowed_types, item
+        @list << item 
+      end 
+    end
 
     # Concat operator
     # @param [Any] v the data to be added
@@ -60,12 +72,7 @@ module Axlsx
       @list << v
       @list.size - 1
     end
-
-    # alternate of << method
-    # @see <<
-    def push(v)
-      self.<< v
-    end
+    alias :push :<<
 
     # delete the item from the list
     # @param [Any] v The item to be deleted.

data/lib/axlsx/version.rb

@@ -1,10 +1,5 @@
 # encoding: UTF-8
 module Axlsx
-
-  # The version of the gem
-  # When using bunle exec rake and referencing the gem on github or locally
-  # it will use the gemspec, which preloads this constant for the gem's version.
-  # We check to make sure that it has not already been loaded
-  VERSION="1.1.8" unless defined? Axlsx::VERSION
-
+  # The current version
+  VERSION="1.2.0"
 end

data/lib/axlsx/workbook/defined_name.rb

@@ -0,0 +1,174 @@
+#  <definedNames>
+#    <definedName name="_xlnm.Print_Titles" localSheetId="0">Sheet1!$1:$1</definedName>
+#  </definedNames>
+
+#<xsd:complexType name="CT_DefinedName">
+# <xsd:simpleContent>
+# <xsd:extension base="ST_Formula">
+# <xsd:attribute name="name" type="s:ST_Xstring" use="required"/>
+# <xsd:attribute name="comment" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="customMenu" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="description" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="help" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="statusBar" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="localSheetId" type="xsd:unsignedInt" use="optional"/>
+# <xsd:attribute name="hidden" type="xsd:boolean" use="optional" default="false"/>
+# <xsd:attribute name="function" type="xsd:boolean" use="optional" default="false"/>
+# <xsd:attribute name="vbProcedure" type="xsd:boolean" use="optional" default="false"/>
+# <xsd:attribute name="xlm" type="xsd:boolean" use="optional" default="false"/>
+# <xsd:attribute name="functionGroupId" type="xsd:unsignedInt" use="optional"/>
+# <xsd:attribute name="shortcutKey" type="s:ST_Xstring" use="optional"/>
+# <xsd:attribute name="publishToServer" type="xsd:boolean" use="optional" default="false"/>
+# <xsd:attribute name="workbookParameter" type="xsd:boolean" use="optional" default="false"/>
+# </xsd:extenstion>
+# </xsd:simpleContent>
+
+module Axlsx
+  # This element defines the defined names that are defined within this workbook. 
+  # Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value.
+  # Use easy-to-understand names, such as Products, to refer to hard to understand ranges, such as Sales!C20:C30.
+  # A defined name in a formula can make it easier to understand the purpose of the formula. 
+  # @example
+  #     The formula =SUM(FirstQuarterSales) might be easier to identify than =SUM(C20:C30
+  #
+  # Names are available to any sheet.
+  # @example
+  #     If the name ProjectedSales refers to the range A20:A30 on the first worksheet in a workbook, 
+  #     you can use the name ProjectedSales on any other sheet in the same workbook to refer to range A20:A30 on the first worksheet.
+  # Names can also be used to represent formulas or values that do not change (constants).
+  #
+  # @example
+  #     The name SalesTax can be used to represent the sales tax amount (such as 6.2 percent) applied to sales transactions.
+  # You can also link to a defined name in another workbook, or define a name that refers to cells in another workbook.
+  #
+  # @example
+  #     The formula =SUM(Sales.xls!ProjectedSales) refers to the named range ProjectedSales in the workbook named Sales.
+  # A compliant producer or consumer considers a defined name in the range A1-XFD1048576 to be an error.
+  # All other names outside this range can be defined as names and overrides a cell reference if an ambiguity exists.
+  #
+  # @example
+  #     For clarification: LOG10 is always a cell reference, LOG10() is always formula, LOGO1000 can be a defined name that overrides a cell reference.
+  class DefinedName
+    # creates a new DefinedName.
+    # @param [String] formula - the formula the defined name references
+    # @param [Hash] options - A hash of key/value pairs that will be mapped to this instances attributes.
+    # 
+    # @option [String] name - Specifies the name that appears in the user interface for the defined name.
+    #                         This attribute is required. 
+    #                         The following built-in names are defined in this SpreadsheetML specification:
+    #                         Print
+    #                           _xlnm.Print_Area: this defined name specifies the workbook's print area.
+    #                           _xlnm.Print_Titles: this defined name specifies the row(s) or column(s) to repeat
+    #                                                the top of each printed page.
+    #                         Filter & Advanced Filter
+    #                           _xlnm.Criteria: this defined name refers to a range containing the criteria values
+    #                                  to be used in applying an advanced filter to a range of data.
+    #                           _xlnm._FilterDatabase: can be one of the following
+    #                                     a. this defined name refers to a range to which an advanced filter has been
+    #                                         applied. This represents the source data range, unfiltered.
+    #                                      b. This defined name refers to a range to which an AutoFilter has been
+    #                                         applied.
+    #                           _xlnm.Extract: this defined name refers to the range containing the filtered output 
+    #                                           values resulting from applying an advanced filter criteria to a source range.
+    #                         Miscellaneous
+    #                           _xlnm.Consolidate_Area: the defined name refers to a consolidation area.
+    #                           _xlnm.Database: the range specified in the defined name is from a database data source.
+    #                           _xlnm.Sheet_Title: the defined name refers to a sheet title.
+    # @option [String] comment - A comment to optionally associate with the name
+    # @option [String] custom_menu - The menu text for the defined name
+    # @option [String] description - An optional description for the defined name
+    # @option [String] help - The help topic to display for this defined name
+    # @option [String] status_bar - The text to display on the application status bar when this defined name has focus
+    # @option [String] local_sheet_id - Specifies the sheet index in this workbook where data from an external reference is displayed
+    # @option [Boolean] hidden - Specifies a boolean value that indicates whether the defined name is hidden in the user interface.
+    # @option [Boolean] function - Specifies a boolean value that indicates that the defined name refers to a user-defined function.
+    #                             This attribute is used when there is an add-in or other code project associated with the file.
+    # @option [Boolean] vb_proceedure - Specifies a boolean value that indicates whether the defined name is related to an external function, command, or other executable code.
+    # @option [Boolean] xlm - Specifies a boolean value that indicates whether the defined name is related to an external function, command, or other executable code.
+    # @option [Integer] function_group_id - Specifies the function group index if the defined name refers to a function. 
+    #                                       The function group defines the general category for the function.
+    #                                       This attribute is used when there is an add-in or other code project associated with the file.
+    #                                       See Open Office XML Part 1 for more info.
+    # @option [String] short_cut_key - Specifies the keyboard shortcut for the defined name.
+    # @option [Boolean] publish_to_server - Specifies a boolean value that indicates whether the defined name is included in the 
+    #                                       version of the workbook that is published to or rendered on a Web or application server.
+    # @option [Boolean] workbook_parameter - Specifies a boolean value that indicates that the name is used as a workbook parameter on a 
+    #                                        version of the workbook that is published to or rendered on a Web or application server.
+    def initialize(formula, options={})
+      @formula = formula
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+    attr_reader :local_sheet_id
+
+    # The local sheet index (0-based)
+    # @param [Integer] value the unsinged integer index of the sheet this defined_name applies to.
+    def local_sheet_id=(value)
+      Axlsx::validate_unsigned_int(value)
+      @local_sheet_id = value
+    end
+
+    # string attributes that will be added when this class is evaluated
+    STRING_ATTRIBUTES = [:short_cut_key, :status_bar, :help, :description, :custom_menu, :comment]
+
+    # boolean attributes that will be added when this class is evaluated
+    BOOLEAN_ATTRIBUTES = [:workbook_parameter, :publish_to_server, :xlm, :vb_proceedure, :function, :hidden] 
+
+    # Dynamically create string attribute accessors
+    STRING_ATTRIBUTES.each do |attr|
+      class_eval %{
+        # The #{attr} attribute reader
+        # @return [String]
+        attr_reader :#{attr}
+
+        # The #{attr} writer
+        # @param [String] value The value to assign to #{attr}
+        # @return [String]
+        def #{attr}=(value)
+          Axlsx::validate_string(value)
+          @#{attr}= value
+        end
+      }
+    end
+
+    # Dynamically create boolean attribute accessors
+    BOOLEAN_ATTRIBUTES.each do |attr|
+      class_eval %{
+      # The #{attr} attribute reader
+      # @return [Boolean]
+      attr_reader :#{attr}
+
+      # The #{attr} writer
+      # @param [Boolean] value The value to assign to #{attr}
+      # @return [Boolean]
+      def #{attr}=(value)
+        Axlsx::validate_boolean(value)
+        @#{attr} = value
+      end
+      }
+    end
+   
+    attr_reader :name
+    # The name of this defined name. Please refer to the class documentation for more information
+    def name=(value)
+      Axlsx::RestrictionValidator.validate 'DefinedName.name', %w(_xlnm.Print_Area _xlnm.Print_Titles _xlnm.Criteria _xlnm._FilterDatabase _xlnm.Extract _xlnm.Consolidate_Area _xlnm.Database _xlnm.Sheet_Title), value
+      @name = value
+    end
+
+    # The formula this defined name references
+    attr_reader :formula
+
+    def to_xml_string(str='')
+      raise ArgumentError, 'you must specify the name for this defined name. Please read the documentation for Axlsx::DefinedName for more details' unless name 
+      str << '<definedName'
+      instance_values.each do |name, value| 
+        unless name == 'formula'
+          str << ' ' << Axlsx::camel(name, false) << "='#{value}'"
+        end
+      end
+      str << '>' << @formula
+      str << '</definedName>'
+    end
+  end
+end