write_xlsx 1.12.1 → 1.12.3

data/lib/write_xlsx/worksheet.rb

@@ -1,15 +1,18 @@
 # -*- coding: utf-8 -*-
 # frozen_string_literal: true
 
-require 'write_xlsx/package/xml_writer_simple'
-require 'write_xlsx/package/button'
 require 'write_xlsx/colors'
-require 'write_xlsx/format'
+require 'write_xlsx/compatibility'
 require 'write_xlsx/drawing'
+require 'write_xlsx/format'
+require 'write_xlsx/image'
+require 'write_xlsx/image_property'
+require 'write_xlsx/inserted_chart'
+require 'write_xlsx/package/button'
+require 'write_xlsx/package/conditional_format'
+require 'write_xlsx/package/xml_writer_simple'
 require 'write_xlsx/sparkline'
-require 'write_xlsx/compatibility'
 require 'write_xlsx/utility'
-require 'write_xlsx/package/conditional_format'
 require 'write_xlsx/worksheet/cell_data'
 require 'write_xlsx/worksheet/data_validation'
 require 'write_xlsx/worksheet/hyperlink'
@@ -21,24 +24,23 @@ module Writexlsx
   class Worksheet
     include Writexlsx::Utility
 
-    MAX_DIGIT_WIDTH = 7    # For Calabri 11.  # :nodoc:
-    PADDING         = 5                       # :nodoc:
-    COLINFO         = Struct.new('ColInfo', :width, :format, :hidden, :level, :collapsed, :autofit)
+    COLINFO = Struct.new('ColInfo', :width, :format, :hidden, :level, :collapsed, :autofit)
 
-    attr_reader :index                                            # :nodoc:
+    attr_reader :index, :name                                     # :nodoc:
     attr_reader :charts, :images, :tables, :shapes, :drawings     # :nodoc:
     attr_reader :header_images, :footer_images, :background_image # :nodoc:
     attr_reader :vml_drawing_links                                # :nodoc:
     attr_reader :vml_data_id                                      # :nodoc:
     attr_reader :vml_header_id                                    # :nodoc:
     attr_reader :autofilter_area                                  # :nodoc:
-    attr_reader :writer, :set_rows, :col_info                     # :nodoc:
+    attr_reader :writer, :set_rows, :col_info, :row_sizes         # :nodoc:
     attr_reader :vml_shape_id                                     # :nodoc:
     attr_reader :comments, :comments_author                       # :nodoc:
     attr_accessor :data_bars_2010, :dxf_priority                  # :nodoc:
     attr_reader :vba_codename                                     # :nodoc:
     attr_writer :excel_version                                    # :nodoc:
     attr_reader :filter_cells                                     # :nodoc:
+    attr_accessor :default_row_height                             # :nodoc:
 
     def initialize(workbook, index, name) # :nodoc:
       rowmax   = 1_048_576
@@ -78,6 +80,7 @@ module Writexlsx
 
       @set_cols = {}
       @set_rows = {}
+      @col_size_changed = false
       @zoom = 100
       @zoom_scale_normal = true
       @right_to_left = false
@@ -94,7 +97,6 @@ module Writexlsx
 
       @last_shape_id          = 1
       @rel_count              = 0
-      @hlink_count            = 0
       @external_hyper_links   = []
       @external_drawing_links = []
       @external_comment_links = []
@@ -116,27 +118,25 @@ module Writexlsx
       @has_dynamic_functions  = false
       @has_embedded_images    = false
 
-      @use_future_functions  = false
+      @use_future_functions   = false
 
       @header_images          = []
       @footer_images          = []
-      @background_image       = ''
+      @background_image       = nil
 
-      @outline_row_level = 0
-      @outline_col_level = 0
+      @outline_row_level      = 0
+      @outline_col_level      = 0
 
       @original_row_height    = 15
       @default_row_height     = 15
       @default_row_pixels     = 20
       @default_col_width      = 8.43
-      @default_col_pixels     = 64
       @default_row_rezoed     = 0
       @default_date_pixels    = 68
 
       @merge = []
 
-      @has_vml        = false
-      @has_header_vml = false
+      @has_vml  = false
       @comments = Package::Comments.new(self)
       @buttons_array          = []
       @header_images_array    = []
@@ -155,8 +155,8 @@ module Writexlsx
         @original_row_height      = 12.75
         @default_row_height       = 12.75
         @default_row_pixels       = 17
-        self.margins_left_right  = 0.75
-        self.margins_top_bottom  = 1
+        self.margins_left_right   = 0.75
+        self.margins_top_bottom   = 1
         @page_setup.margin_header = 0.5
         @page_setup.margin_footer = 0.5
         @page_setup.header_footer_aligns = false
@@ -204,11 +204,6 @@ module Writexlsx
       end
     end
 
-    #
-    # The name method is used to retrieve the name of a worksheet.
-    #
-    attr_reader :name
-
     #
     # Set this worksheet as a selected worksheet, i.e. the worksheet has its tab
     # highlighted.
@@ -296,29 +291,6 @@ module Writexlsx
       @protected_ranges << [range, range_name, password]
     end
 
-    def protect_default_settings  # :nodoc:
-      {
-        sheet:                 true,
-        content:               false,
-        objects:               false,
-        scenarios:             false,
-        format_cells:          false,
-        format_columns:        false,
-        format_rows:           false,
-        insert_columns:        false,
-        insert_rows:           false,
-        insert_hyperlinks:     false,
-        delete_columns:        false,
-        delete_rows:           false,
-        select_locked_cells:   true,
-        sort:                  false,
-        autofilter:            false,
-        pivot_tables:          false,
-        select_unlocked_cells: true
-      }
-    end
-    private :protect_default_settings
-
     #
     # :call-seq:
     #   set_column(firstcol, lastcol, width, format, hidden, level, collapsed)
@@ -376,7 +348,7 @@ module Writexlsx
       end
 
       # Store the column change to allow optimisations.
-      @col_size_changed = 1
+      @col_size_changed = true
     end
 
     #
@@ -398,12 +370,8 @@ module Writexlsx
       # Ensure at least $first_col, $last_col and $width
       return if data.size < 3
 
-      first_col = data[0]
-      last_col  = data[1]
-      pixels    = data[2]
-      format    = data[3]
-      hidden    = data[4] || 0
-      level     = data[5]
+      first_col, last_col, pixels, format, hidden, level = data
+      hidden ||= 0
 
       width = pixels_to_width(pixels) if ptrue?(pixels)
 
@@ -671,7 +639,10 @@ module Writexlsx
       raise 'Header string must be less than 255 characters' if string.length > 255
 
       # Replace the Excel placeholder &[Picture] with the internal &G.
-      @page_setup.header = string.gsub("&[Picture]", '&G')
+      header_footer_string = string.gsub("&[Picture]", '&G')
+      # placeholeder /&G/ の数
+      placeholder_count = header_footer_string.scan("&G").count
+      @page_setup.header = header_footer_string
 
       @page_setup.header_footer_aligns = options[:align_with_margins] if options[:align_with_margins]
 
@@ -683,17 +654,13 @@ module Writexlsx
       [
         [:image_left, 'LH'], [:image_center, 'CH'], [:image_right, 'RH']
       ].each do |p|
-        @header_images << [options[p.first], p.last] if options[p.first]
+        @header_images << ImageProperty.new(options[p.first], position: p.last) if options[p.first]
       end
 
-      # placeholeder /&G/ の数
-      placeholder_count = @page_setup.header.scan("&G").count
-
-      image_count = @header_images.count
+      # # placeholeder /&G/ の数
+      # placeholder_count = @page_setup.header.scan("&G").count
 
-      raise "Number of header image (#{image_count}) doesn't match placeholder count (#{placeholder_count}) in string: #{@page_setup.header}" if image_count != placeholder_count
-
-      @has_header_vml = true if image_count > 0
+      raise "Number of header image (#{@header_images.size}) doesn't match placeholder count (#{placeholder_count}) in string: #{@page_setup.header}" if @header_images.size != placeholder_count
 
       @page_setup.margin_header         = margin || 0.3
       @page_setup.header_footer_changed = true
@@ -705,8 +672,6 @@ module Writexlsx
     def set_footer(string = '', margin = 0.3, options = {})
       raise 'Footer string must be less than 255 characters' if string.length > 255
 
-      @page_setup.footer = string.dup
-
       # Replace the Excel placeholder &[Picture] with the internal &G.
       @page_setup.footer = string.gsub("&[Picture]", '&G')
 
@@ -720,17 +685,13 @@ module Writexlsx
       [
         [:image_left, 'LF'], [:image_center, 'CF'], [:image_right, 'RF']
       ].each do |p|
-        @footer_images << [options[p.first], p.last] if options[p.first]
+        @footer_images << ImageProperty.new(options[p.first], position: p.last) if options[p.first]
       end
 
       # placeholeder /&G/ の数
       placeholder_count = @page_setup.footer.scan("&G").count
 
-      image_count = @footer_images.count
-
-      raise "Number of footer image (#{image_count}) doesn't match placeholder count (#{placeholder_count}) in string: #{@page_setup.footer}" if image_count != placeholder_count
-
-      @has_header_vml = true if image_count > 0
+      raise "Number of footer image (#{@footer_images.size}) doesn't match placeholder count (#{placeholder_count}) in string: #{@page_setup.footer}" if @footer_images.size != placeholder_count
 
       @page_setup.margin_footer         = margin
       @page_setup.header_footer_changed = true
@@ -1327,18 +1288,6 @@ module Writexlsx
       store_data_to_table(BlankCellData.new(_format), _row, _col)
     end
 
-    def expand_formula(formula, function, addition = '')
-      if formula =~ /\b(#{function})/
-        formula.gsub(
-          ::Regexp.last_match(1),
-          "_xlfn#{addition}.#{::Regexp.last_match(1)}"
-        )
-      else
-        formula
-      end
-    end
-    private :expand_formula
-
     #
     # Utility method to strip equal sign and array braces from a formula
     # and also expand out future and dynamic array formulas.
@@ -1758,7 +1707,7 @@ module Writexlsx
     # The outline_settings() method is used to control the appearance of
     # outlines in Excel.
     #
-    def outline_settings(visible = 1, symbols_below = 1, symbols_right = 1, auto_style = 0)
+    def outline_settings(visible = 1, symbols_below = 1, symbols_right = 1, auto_style = false)
       @outline_on    = visible
       @outline_below = symbols_below
       @outline_right = symbols_right
@@ -1804,14 +1753,15 @@ module Writexlsx
         _tip                 = tip
         _ignore_write_string = ignore_write_string
       end
-      _format, _str = _str, _format if _str.respond_to?(:xf_index) || !_format.respond_to?(:xf_index)
+
+      _format, _str = _str, _format if _str.respond_to?(:xf_index) || (_format && !_format.respond_to?(:xf_index))
       raise WriteXLSXInsufficientArgumentError if [_row, _col, _url].include?(nil)
 
       # Check that row and col are valid and store max and min values
       check_dimensions(_row, _col)
       store_row_col_max_min_values(_row, _col)
 
-      hyperlink = Hyperlink.factory(_url, _str, _tip)
+      hyperlink = Hyperlink.factory(_url, _str, _tip, @max_url_length)
       store_hyperlink(_row, _col, hyperlink)
 
       raise "URL '#{url}' added but URL exceeds Excel's limit of 65,530 URLs per worksheet." if hyperlinks_count > 65_530
@@ -1914,10 +1864,10 @@ module Writexlsx
       x_offset = _chart.x_offset if ptrue?(_chart.x_offset)
       y_offset = _chart.y_offset if ptrue?(_chart.y_offset)
 
-      @charts << [
+      @charts << InsertedChart.new(
         _row,    _col,    _chart, x_offset,    y_offset,
         x_scale, y_scale, anchor, description, decorative
-      ]
+      )
     end
 
     #
@@ -1959,10 +1909,10 @@ module Writexlsx
       y_scale  ||= 1
       anchor   ||= 2
 
-      @images << [
+      @images << Image.new(
         _row, _col, _image, x_offset, y_offset,
         x_scale, y_scale, url, tip, anchor, description, decorative
-      ]
+      )
     end
 
     #
@@ -2005,18 +1955,19 @@ module Writexlsx
       end
 
       # Get the image properties, mainly for the type and checksum.
-      image_properties = get_image_properties(image)
-      type = image_properties[0]
-      md5  = image_properties[6]
+      image_property = ImageProperty.new(
+        image, description: description, decorative: decorative
+      )
+      @workbook.store_image_types(image_property.type)
 
       # Check for duplicate images.
-      image_index = @embedded_image_indexes[md5]
+      image_index = @embedded_image_indexes[image_property.md5]
 
       unless ptrue?(image_index)
-        @workbook.embedded_images << [image, type, description, decorative]
+        @workbook.embedded_images << image_property
 
         image_index = @workbook.embedded_images.size
-        @embedded_image_indexes[md5] = image_index
+        @embedded_image_indexes[image_property.md5] = image_index
       end
 
       # Write the cell placeholder.
@@ -2024,6 +1975,76 @@ module Writexlsx
       @has_embedded_images = true
     end
 
+    #
+    # :call-seq:
+    #   insert_shape(row, col, shape [ , x, y, x_scale, y_scale ])
+    #
+    # Insert a shape into the worksheet.
+    #
+    def insert_shape(
+          row_start, column_start, shape = nil, x_offset = nil, y_offset = nil,
+          x_scale = nil, y_scale = nil, anchor = nil
+        )
+      # Check for a cell reference in A1 notation and substitute row and column.
+      if (row_col_array = row_col_notation(row_start))
+        _row_start, _column_start = row_col_array
+        _shape    = column_start
+        _x_offset = shape
+        _y_offset = x_offset
+        _x_scale  = y_offset
+        _y_scale  = x_scale
+        _anchor   = y_scale
+      else
+        _row_start = row_start
+        _column_start = column_start
+        _shape = shape
+        _x_offset = x_offset
+        _y_offset = y_offset
+        _x_scale = x_scale
+        _y_scale = y_scale
+        _anchor = anchor
+      end
+      raise "Insufficient arguments in insert_shape()" if [_row_start, _column_start, _shape].include?(nil)
+
+      _shape.set_position(
+        _row_start, _column_start, _x_offset, _y_offset,
+        _x_scale, _y_scale, _anchor
+      )
+      # Assign a shape ID.
+      while true
+        id = _shape.id || 0
+        used = @shape_hash[id]
+
+        # Test if shape ID is already used. Otherwise assign a new one.
+        if !used && id != 0
+          break
+        else
+          @last_shape_id += 1
+          _shape.id = @last_shape_id
+        end
+      end
+
+      # Allow lookup of entry into shape array by shape ID.
+      @shape_hash[_shape.id] = _shape.element = @shapes.size
+
+      insert = if ptrue?(_shape.stencil)
+                 # Insert a copy of the shape, not a reference so that the shape is
+                 # used as a stencil. Previously stamped copies don't get modified
+                 # if the stencil is modified.
+                 _shape.dup
+               else
+                 _shape
+               end
+
+      # For connectors change x/y coords based on location of connected shapes.
+      insert.auto_locate_connectors(@shapes, @shape_hash)
+
+      # Insert a link to the shape on the list of shapes. Connection to
+      # the parent shape is maintained.
+      @shapes << insert
+      insert
+    end
+
     #
     # :call-seq:
     #   repeat_formula(row, column, formula [ , format ])
@@ -2087,9 +2108,6 @@ module Writexlsx
       level  = args[4] || 0
       collapsed = args[5] || 0
 
-      # Get the default row height.
-      default_height = @default_row_height
-
       # Use min col in check_dimensions. Default to 0 if undefined.
       min_col = @dim_colmin || 0
 
@@ -2097,12 +2115,12 @@ module Writexlsx
       check_dimensions(row, min_col)
       store_row_col_max_min_values(row, min_col)
 
-      height ||= default_height
+      height ||= @default_row_height
 
       # If the height is 0 the row is hidden and the height is the default.
       if height == 0
         hidden = 1
-        height = default_height
+        height = @default_row_height
       end
 
       # Set the limits for the outline levels (0 <= x <= 7).
@@ -2311,8 +2329,11 @@ module Writexlsx
         _col = col
         _properties = properties
       end
-      @buttons_array << button_params(_row, _col, _properties)
-      @has_vml = 1
+
+      @buttons_array << Writexlsx::Package::Button.new(
+        self, _row, _col, _properties, @default_row_pixels, @buttons_array.size + 1
+      )
+      @has_vml = true
     end
 
     #
@@ -2415,7 +2436,7 @@ module Writexlsx
 
       tokens = extract_filter_tokens(expression)
 
-      raise "Incorrect number of tokens in expression '#{expression}'" unless tokens.size == 3 || tokens.size == 7
+      raise "Incorrect number of tokens in expression '#{expression}'" unless [3, 7].include?(tokens.size)
 
       tokens = parse_filter_expression(expression, tokens)
 
@@ -2494,7 +2515,7 @@ module Writexlsx
     end
 
     def has_header_vml?  # :nodoc:
-      @has_header_vml
+      !(@header_images.empty? && @footer_images.empty?)
     end
 
     def has_comments? # :nodoc:
@@ -2509,49 +2530,29 @@ module Writexlsx
       !!@is_chartsheet
     end
 
-    def set_external_vml_links(vml_drawing_id) # :nodoc:
-      @external_vml_links <<
-        ['/vmlDrawing', "../drawings/vmlDrawing#{vml_drawing_id}.vml"]
-    end
-
-    def set_external_comment_links(comment_id) # :nodoc:
-      @external_comment_links <<
-        ['/comments',   "../comments#{comment_id}.xml"]
-    end
-
     #
     # Set up chart/drawings.
     #
     def prepare_chart(index, chart_id, drawing_id) # :nodoc:
       drawing_type = 1
 
-      row,     col,     chart,  x_offset,    y_offset,
-      x_scale, y_scale, anchor, description, decorative = @charts[index]
-
-      chart.id = chart_id - 1
-      x_scale ||= 0
-      y_scale ||= 0
+      inserted_chart = @charts[index]
+      inserted_chart.chart.id = chart_id - 1
 
-      # Use user specified dimensions, if any.
-      width  = chart.width  if ptrue?(chart.width)
-      height = chart.height if ptrue?(chart.height)
-
-      width  = (0.5 + (width  * x_scale)).to_i
-      height = (0.5 + (height * y_scale)).to_i
-
-      dimensions = position_object_emus(col, row, x_offset, y_offset, width, height, anchor)
-
-      # Set the chart name for the embedded object if it has been specified.
-      name = chart.name
+      dimensions = position_object_emus(inserted_chart)
 
       # Create a Drawing object to use with worksheet unless one already exists.
-      drawing = Drawing.new(drawing_type, dimensions, 0, 0, nil, anchor, drawing_rel_index, 0, nil, name, description, decorative)
+      drawing = Drawing.new(
+        drawing_type, dimensions, 0, 0, nil, inserted_chart.anchor,
+        drawing_rel_index, 0, nil, inserted_chart.name,
+        inserted_chart.description, inserted_chart.decorative
+      )
       if drawings?
         @drawings.add_drawing_object(drawing)
       else
         @drawings = Drawings.new
         @drawings.add_drawing_object(drawing)
-        @drawings.embedded = 1
+        @drawings.embedded = true
 
         @external_drawing_links << ['/drawing', "../drawings/drawing#{drawing_id}.xml"]
       end
@@ -2589,85 +2590,6 @@ module Writexlsx
       data
     end
 
-    #
-    # Calculate the vertices that define the position of a graphical object within
-    # the worksheet in pixels.
-    #
-    def position_object_pixels(col_start, row_start, x1, y1, width, height, anchor = nil) # :nodoc:
-      # Adjust start column for negative offsets.
-      while x1 < 0 && col_start > 0
-        x1 += size_col(col_start - 1)
-        col_start -= 1
-      end
-
-      # Adjust start row for negative offsets.
-      while y1 < 0 && row_start > 0
-        y1 += size_row(row_start - 1)
-        row_start -= 1
-      end
-
-      # Ensure that the image isn't shifted off the page at top left.
-      x1 = 0 if x1 < 0
-      y1 = 0 if y1 < 0
-
-      # Calculate the absolute x offset of the top-left vertex.
-      x_abs = if @col_size_changed
-                (0..col_start - 1).inject(0) { |sum, col| sum += size_col(col, anchor) }
-              else
-                # Optimisation for when the column widths haven't changed.
-                @default_col_pixels * col_start
-              end
-      x_abs += x1
-
-      # Calculate the absolute y offset of the top-left vertex.
-      # Store the column change to allow optimisations.
-      y_abs = if @row_size_changed
-                (0..row_start - 1).inject(0) { |sum, row| sum += size_row(row, anchor) }
-              else
-                # Optimisation for when the row heights haven't changed.
-                @default_row_pixels * row_start
-              end
-      y_abs += y1
-
-      # Adjust start column for offsets that are greater than the col width.
-      while x1 >= size_col(col_start, anchor)
-        x1 -= size_col(col_start)
-        col_start += 1
-      end
-
-      # Adjust start row for offsets that are greater than the row height.
-      while y1 >= size_row(row_start, anchor)
-        y1 -= size_row(row_start)
-        row_start += 1
-      end
-
-      # Initialise end cell to the same as the start cell.
-      col_end = col_start
-      row_end = row_start
-
-      # Only offset the image in the cell if the row/col isn't hidden.
-      width  += x1 if size_col(col_start, anchor) > 0
-      height += y1 if size_row(row_start, anchor) > 0
-
-      # Subtract the underlying cell widths to find the end cell of the object.
-      while width >= size_col(col_end, anchor)
-        width -= size_col(col_end, anchor)
-        col_end += 1
-      end
-
-      # Subtract the underlying cell heights to find the end cell of the object.
-      while height >= size_row(row_end, anchor)
-        height -= size_row(row_end, anchor)
-        row_end += 1
-      end
-
-      # The end vertices are whatever is left from the width and height.
-      x2 = width
-      y2 = height
-
-      [col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs]
-    end
-
     def comments_visible? # :nodoc:
       !!@comments_visible
     end
@@ -2725,7 +2647,7 @@ module Writexlsx
       if index.to_s =~ /^#([0-9A-F]{6})$/i
         "FF#{::Regexp.last_match(1).upcase}"
       else
-        "FF#{super(index)}"
+        "FF#{palette_color_from_index(index)}"
       end
     end
 
@@ -2872,42 +2794,242 @@ module Writexlsx
       @has_embedded_images
     end
 
-    private
+    # Check that some image or drawing needs to be processed.
+    def some_image_or_drawing_to_be_processed?
+      charts.size + images.size + shapes.size + header_images.size + footer_images.size + (background_image ? 1 : 0) == 0
+    end
 
-    #
-    # Compare adjacent column information structures.
-    #
-    def compare_col_info(col_options, previous_options)
-      if !col_options.width.nil? != !previous_options.width.nil?
-        return nil
-      end
-      if col_options.width && previous_options.width &&
-         col_options.width != previous_options.width
-        return nil
-      end
+    def prepare_drawings(drawing_id, chart_ref_id, image_ref_id, image_ids, header_image_ids, background_ids)
+      has_drawings = false
 
-      if !col_options.format.nil? != !previous_options.format.nil?
-        return nil
-      end
-      if col_options.format && previous_options.format &&
-         col_options.format != previous_options.format
-        return nil
-      end
+      # Check that some image or drawing needs to be processed.
+      unless some_image_or_drawing_to_be_processed?
 
-      return nil if col_options.hidden    != previous_options.hidden
-      return nil if col_options.level     != previous_options.level
-      return nil if col_options.collapsed != previous_options.collapsed
+        # Don't increase the drawing_id header/footer images.
+        unless charts.empty? && images.empty? && shapes.empty?
+          drawing_id += 1
+          has_drawings = true
+        end
 
-      true
-    end
+        # Prepare the background images.
+        image_ref_id = prepare_background_image(background_ids, image_ref_id)
 
-    #
-    # Get the index used to address a drawing rel link.
-    #
-    def drawing_rel_index(target = nil)
-      if !target
-        # Undefined values for drawings like charts will always be unique.
-        @drawing_rels_id += 1
+        # Prepare the worksheet images.
+        images.each do |image|
+          image_ref_id = prepare_image(image, drawing_id, image_ids, image_ref_id)
+        end
+
+        # Prepare the worksheet charts.
+        charts.each_with_index do |_chart, index|
+          chart_ref_id += 1
+          prepare_chart(index, chart_ref_id, drawing_id)
+        end
+
+        # Prepare the worksheet shapes.
+        shapes.each_with_index do |_shape, index|
+          prepare_shape(index, drawing_id)
+        end
+
+        # Prepare the header and footer images.
+        [header_images, footer_images].each do |images|
+          images.each do |image|
+            image_ref_id = prepare_header_footer_image(
+              image, header_image_ids, image_ref_id
+            )
+          end
+        end
+
+        if has_drawings
+          @workbook.drawings << drawings
+        end
+      end
+
+      [drawing_id, chart_ref_id, image_ref_id]
+    end
+
+    #
+    # Set the background image for the worksheet.
+    #
+    def set_background(image)
+      raise "Couldn't locate #{image}: $!" unless File.exist?(image)
+
+      @background_image = ImageProperty.new(image)
+    end
+
+    #
+    # Calculate the vertices that define the position of a graphical object
+    # within the worksheet in pixels.
+    #
+    def position_object_pixels(col_start, row_start, x1, y1, width, height, anchor = nil) # :nodoc:
+      # Adjust start column for negative offsets.
+      while x1 < 0 && col_start > 0
+        x1 += size_col(col_start - 1)
+        col_start -= 1
+      end
+
+      # Adjust start row for negative offsets.
+      while y1 < 0 && row_start > 0
+        y1 += size_row(row_start - 1)
+        row_start -= 1
+      end
+
+      # Ensure that the image isn't shifted off the page at top left.
+      x1 = 0 if x1 < 0
+      y1 = 0 if y1 < 0
+
+      # Calculate the absolute x offset of the top-left vertex.
+      x_abs = if @col_size_changed
+                (0..(col_start - 1)).inject(0) { |sum, col| sum += size_col(col, anchor) }
+              else
+                # Optimisation for when the column widths haven't changed.
+                DEFAULT_COL_PIXELS * col_start
+              end
+      x_abs += x1
+
+      # Calculate the absolute y offset of the top-left vertex.
+      # Store the column change to allow optimisations.
+      y_abs = if @row_size_changed
+                (0..(row_start - 1)).inject(0) { |sum, row| sum += size_row(row, anchor) }
+              else
+                # Optimisation for when the row heights haven't changed.
+                @default_row_pixels * row_start
+              end
+      y_abs += y1
+
+      # Adjust start column for offsets that are greater than the col width.
+      while x1 >= size_col(col_start, anchor)
+        x1 -= size_col(col_start)
+        col_start += 1
+      end
+
+      # Adjust start row for offsets that are greater than the row height.
+      while y1 >= size_row(row_start, anchor)
+        y1 -= size_row(row_start)
+        row_start += 1
+      end
+
+      # Initialise end cell to the same as the start cell.
+      col_end = col_start
+      row_end = row_start
+
+      # Only offset the image in the cell if the row/col isn't hidden.
+      width  += x1 if size_col(col_start, anchor) > 0
+      height += y1 if size_row(row_start, anchor) > 0
+
+      # Subtract the underlying cell widths to find the end cell of the object.
+      while width >= size_col(col_end, anchor)
+        width -= size_col(col_end, anchor)
+        col_end += 1
+      end
+
+      # Subtract the underlying cell heights to find the end cell of the object.
+      while height >= size_row(row_end, anchor)
+        height -= size_row(row_end, anchor)
+        row_end += 1
+      end
+
+      # The end vertices are whatever is left from the width and height.
+      x2 = width
+      y2 = height
+
+      [col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs]
+    end
+
+    private
+
+    #
+    # Convert the width of a cell from user's units to pixels. Excel rounds
+    # the column width to the nearest pixel. If the width hasn't been set
+    # by the user we use the default value. A hidden column is treated as
+    # having a width of zero unless it has the special "object_position" of
+    # 4 (size with cells).
+    #
+    def size_col(col, anchor = 0) # :nodoc:
+      # Look up the cell value to see if it has been changed.
+      if col_info[col]
+        width  = col_info[col].width || @default_col_width
+        hidden = col_info[col].hidden
+
+        # Convert to pixels.
+        pixels = if hidden == 1 && anchor != 4
+                   0
+                 elsif width < 1
+                   ((width * (MAX_DIGIT_WIDTH + PADDING)) + 0.5).to_i
+                 else
+                   ((width * MAX_DIGIT_WIDTH) + 0.5).to_i + PADDING
+                 end
+      else
+        pixels = DEFAULT_COL_PIXELS
+      end
+      pixels
+    end
+
+    #
+    # Convert the height of a cell from user's units to pixels. If the height
+    # hasn't been set by the user we use the default value. A hidden row is
+    # treated as having a height of zero unless it has the special
+    # "object_position" of 4 (size with cells).
+    #
+    def size_row(row, anchor = 0) # :nodoc:
+      # Look up the cell value to see if it has been changed
+      if row_sizes[row]
+        height, hidden = row_sizes[row]
+
+        pixels = if hidden == 1 && anchor != 4
+                   0
+                 else
+                   (4 / 3.0 * height).to_i
+                 end
+      else
+        pixels = (4 / 3.0 * default_row_height).to_i
+      end
+      pixels
+    end
+
+    #
+    # Compare adjacent column information structures.
+    #
+    def compare_col_info(col_options, previous_options)
+      if !col_options.width.nil? != !previous_options.width.nil?
+        return nil
+      end
+      if col_options.width && previous_options.width &&
+         col_options.width != previous_options.width
+        return nil
+      end
+
+      if !col_options.format.nil? != !previous_options.format.nil?
+        return nil
+      end
+      if col_options.format && previous_options.format &&
+         col_options.format != previous_options.format
+        return nil
+      end
+
+      return nil if col_options.hidden    != previous_options.hidden
+      return nil if col_options.level     != previous_options.level
+      return nil if col_options.collapsed != previous_options.collapsed
+
+      true
+    end
+
+    def set_external_vml_links(vml_drawing_id) # :nodoc:
+      @external_vml_links <<
+        ['/vmlDrawing', "../drawings/vmlDrawing#{vml_drawing_id}.vml"]
+    end
+
+    def set_external_comment_links(comment_id) # :nodoc:
+      @external_comment_links <<
+        ['/comments',   "../comments#{comment_id}.xml"]
+    end
+
+    #
+    # Get the index used to address a drawing rel link.
+    #
+    def drawing_rel_index(target = nil)
+      if !target
+        # Undefined values for drawings like charts will always be unique.
+        @drawing_rels_id += 1
       elsif ptrue?(@drawing_rels[target])
         @drawing_rels[target]
       else
@@ -3185,12 +3307,13 @@ module Writexlsx
     end
 
     #
-    # Calculate the vertices that define the position of a graphical object within
-    # the worksheet in EMUs.
+    # Calculate the vertices that define the position of a graphical object
+    # within the worksheet in EMUs.
     #
-    def position_object_emus(col_start, row_start, x1, y1, width, height, anchor = nil) # :nodoc:
+    def position_object_emus(graphical_object) # :nodoc:
+      go = graphical_object
       col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs =
-        position_object_pixels(col_start, row_start, x1, y1, width, height, anchor)
+        position_object_pixels(go.col, go.row, go.x_offset, go.y_offset, go.scaled_width, go.scaled_height, go.anchor)
 
       # Convert the pixel values to EMUs. See above.
       x1    = (0.5 + (9_525 * x1)).to_i
@@ -3203,54 +3326,6 @@ module Writexlsx
       [col_start, row_start, x1, y1, col_end, row_end, x2, y2, x_abs, y_abs]
     end
 
-    #
-    # Convert the width of a cell from user's units to pixels. Excel rounds the
-    # column width to the nearest pixel. If the width hasn't been set by the user
-    # we use the default value. A hidden column is treated as having a width of
-    # zero unless it has the special "object_position" of 4 (size with cells).
-    #
-    def size_col(col, anchor = 0) # :nodoc:
-      # Look up the cell value to see if it has been changed.
-      if @col_info[col]
-        width  = @col_info[col].width || @default_col_width
-        hidden = @col_info[col].hidden
-
-        # Convert to pixels.
-        pixels = if hidden == 1 && anchor != 4
-                   0
-                 elsif width < 1
-                   ((width * (MAX_DIGIT_WIDTH + PADDING)) + 0.5).to_i
-                 else
-                   ((width * MAX_DIGIT_WIDTH) + 0.5).to_i + PADDING
-                 end
-      else
-        pixels = @default_col_pixels
-      end
-      pixels
-    end
-
-    #
-    # Convert the height of a cell from user's units to pixels. If the height
-    # hasn't been set by the user we use the default value. A hidden row is
-    # treated as having a height of zero unless it has the special
-    # "object_position" of 4 (size with cells).
-    #
-    def size_row(row, anchor = 0) # :nodoc:
-      # Look up the cell value to see if it has been changed
-      if @row_sizes[row]
-        height, hidden = @row_sizes[row]
-
-        pixels = if hidden == 1 && anchor != 4
-                   0
-                 else
-                   (4 / 3.0 * height).to_i
-                 end
-      else
-        pixels = (4 / 3.0 * @default_row_height).to_i
-      end
-      pixels
-    end
-
     #
     # Convert the width of a cell from pixels to character units.
     #
@@ -3277,48 +3352,44 @@ module Writexlsx
     #
     # Set up image/drawings.
     #
-    def prepare_image(index, image_id, drawing_id, width, height, name, image_type, x_dpi = 96, y_dpi = 96, md5 = nil) # :nodoc:
-      x_dpi ||= 96
-      y_dpi ||= 96
+    def prepare_image(image, drawing_id, image_ids, image_ref_id) # :nodoc:
+      image_type = image.type
+      x_dpi  = image.x_dpi || 96
+      y_dpi  = image.y_dpi || 96
+      md5    = image.md5
       drawing_type = 2
 
-      row, col, _image, x_offset, y_offset,
-      x_scale, y_scale, url, tip, anchor, description, decorative = @images[index]
+      @workbook.store_image_types(image_type)
 
-      width  *= x_scale
-      height *= y_scale
-
-      width  *= 96.0 / x_dpi
-      height *= 96.0 / y_dpi
-
-      dimensions = position_object_emus(col, row, x_offset, y_offset, width, height, anchor)
+      if image_ids[md5]
+        image_id = image_ids[md5]
+      else
+        image_ref_id += 1
+        image_ids[md5] = image_id = image_ref_id
+        @workbook.images << image
+      end
 
-      # Convert from pixels to emus.
-      width  = (0.5 + (width  * 9_525)).to_i
-      height = (0.5 + (height * 9_525)).to_i
+      dimensions = position_object_emus(image)
 
       # Create a Drawing object to use with worksheet unless one already exists.
-      drawing = Drawing.new(drawing_type, dimensions, width, height, nil, anchor, 0, 0, tip, name, description, decorative)
-      if drawings?
-        drawings = @drawings
-      else
-        drawings = Drawings.new
-        drawings.embedded = 1
-
-        @drawings = drawings
+      drawing = Drawing.new(
+        drawing_type, dimensions, image.width_emus, image.height_emus,
+        nil, image.anchor, 0, 0, image.tip, image.name,
+        image.description || image.name, image.decorative
+      )
+      unless drawings?
+        @drawings = Drawings.new
+        @drawings.embedded = true
 
         @external_drawing_links << ['/drawing', "../drawings/drawing#{drawing_id}.xml"]
       end
-      drawings.add_drawing_object(drawing)
-
-      drawing.description = name unless description
+      @drawings.add_drawing_object(drawing)
 
-      if url
-        rel_type = '/hyperlink'
+      if image.url
         target_mode = 'External'
-        target = escape_url(url) if url =~ %r{^[fh]tt?ps?://} || url =~ /^mailto:/
-        if url =~ /^external:/
-          target = escape_url(url.sub(/^external:/, ''))
+        target = escape_url(image.url) if image.url =~ %r{^[fh]tt?ps?://} || image.url =~ /^mailto:/
+        if image.url =~ /^external:/
+          target = escape_url(image.url.sub(/^external:/, ''))
 
           # Additional escape not required in worksheet hyperlinks
           target = target.gsub("#", '%23')
@@ -3331,8 +3402,8 @@ module Writexlsx
                    end
         end
 
-        if url =~ /^internal:/
-          target      = url.sub(/^internal:/, '#')
+        if image.url =~ /^internal:/
+          target      = image.url.sub(/^internal:/, '#')
           target_mode = nil
         end
 
@@ -3342,37 +3413,28 @@ Ignoring URL #{target} where link or anchor > 255 characters since it exceeds Ex
 EOS
         end
 
-        @drawing_links << [rel_type, target, target_mode] if target && !@drawing_rels[url]
-        drawing.url_rel_index = drawing_rel_index(url)
+        @drawing_links << ['/hyperlink', target, target_mode] if target && !@drawing_rels[image.url]
+        drawing.url_rel_index = drawing_rel_index(image.url)
       end
 
       @drawing_links << ['/image', "../media/image#{image_id}.#{image_type}"] unless @drawing_rels[md5]
 
       drawing.rel_index = drawing_rel_index(md5)
+
+      image_ref_id
     end
-    public :prepare_image
 
-    def prepare_header_image(image_id, width, height, name, image_type, position, x_dpi, y_dpi, md5)
+    def prepare_header_image(image_id, image_property)
       # Strip the extension from the filename.
-      body = name.dup
+      body = image_property.name.dup
       body[/\.[^.]+$/, 0] = ''
+      image_property.body = body
 
-      @vml_drawing_links << ['/image', "../media/image#{image_id}.#{image_type}"] unless @vml_drawing_rels[md5]
+      @vml_drawing_links << ['/image', "../media/image#{image_id}.#{image_property.type}"] unless @vml_drawing_rels[image_property.md5]
 
-      ref_id = get_vml_drawing_rel_index(md5)
-      @header_images_array << [width, height, body, position, x_dpi, y_dpi, ref_id]
+      image_property.ref_id = get_vml_drawing_rel_index(image_property.md5)
+      @header_images_array << image_property
     end
-    public :prepare_header_image
-
-    #
-    # Set the background image for the worksheet.
-    #
-    def set_background(image)
-      raise "Couldn't locate #{image}: $!" unless File.exist?(image)
-
-      @background_image = image
-    end
-    public :set_background
 
     #
     # Set up an image without a drawing object for the background image.
@@ -3381,78 +3443,25 @@ EOS
       @external_background_links <<
         ['/image', "../media/image#{image_id}.#{image_type}"]
     end
-    public :prepare_background
 
-    #
-    # :call-seq:
-    #   insert_shape(row, col, shape [ , x, y, x_scale, y_scale ])
-    #
-    # Insert a shape into the worksheet.
-    #
-    def insert_shape(
-          row_start, column_start, shape = nil, x_offset = nil, y_offset = nil,
-          x_scale = nil, y_scale = nil, anchor = nil
-        )
-      # Check for a cell reference in A1 notation and substitute row and column.
-      if (row_col_array = row_col_notation(row_start))
-        _row_start, _column_start = row_col_array
-        _shape    = column_start
-        _x_offset = shape
-        _y_offset = x_offset
-        _x_scale  = y_offset
-        _y_scale  = x_scale
-        _anchor   = y_scale
-      else
-        _row_start = row_start
-        _column_start = column_start
-        _shape = shape
-        _x_offset = x_offset
-        _y_offset = y_offset
-        _x_scale = x_scale
-        _y_scale = y_scale
-        _anchor = anchor
-      end
-      raise "Insufficient arguments in insert_shape()" if [_row_start, _column_start, _shape].include?(nil)
+    def prepare_background_image(background_ids, image_ref_id)
+      unless background_image.nil?
+        @workbook.store_image_types(background_image.type)
 
-      _shape.set_position(
-        _row_start, _column_start, _x_offset, _y_offset,
-        _x_scale, _y_scale, _anchor
-      )
-      # Assign a shape ID.
-      while true
-        id = _shape.id || 0
-        used = @shape_hash[id]
-
-        # Test if shape ID is already used. Otherwise assign a new one.
-        if !used && id != 0
-          break
+        if background_ids[background_image.md5]
+          ref_id = background_ids[background_image.md5]
         else
-          @last_shape_id += 1
-          _shape.id = @last_shape_id
+          image_ref_id += 1
+          ref_id = image_ref_id
+          background_ids[background_image.md5] = ref_id
+          @workbook.images << background_image
         end
-      end
-
-      # Allow lookup of entry into shape array by shape ID.
-      @shape_hash[_shape.id] = _shape.element = @shapes.size
 
-      insert = if ptrue?(_shape.stencil)
-                 # Insert a copy of the shape, not a reference so that the shape is
-                 # used as a stencil. Previously stamped copies don't get modified
-                 # if the stencil is modified.
-                 _shape.dup
-               else
-                 _shape
-               end
-
-      # For connectors change x/y coords based on location of connected shapes.
-      insert.auto_locate_connectors(@shapes, @shape_hash)
+        prepare_background(ref_id, background_image.type)
+      end
 
-      # Insert a link to the shape on the list of shapes. Connection to
-      # the parent shape is maintained.
-      @shapes << insert
-      insert
+      image_ref_id
     end
-    public :insert_shape
 
     #
     # Set up drawing shapes
@@ -3463,7 +3472,7 @@ EOS
       # Create a Drawing object to use with worksheet unless one already exists.
       unless drawings?
         @drawings = Drawings.new
-        @drawings.embedded = 1
+        @drawings.embedded = true
         @external_drawing_links << ['/drawing', "../drawings/drawing#{drawing_id}.xml"]
         @has_shapes = true
       end
@@ -3479,70 +3488,6 @@ EOS
       )
       drawings.add_drawing_object(drawing)
     end
-    public :prepare_shape
-
-    #
-    # This method handles the parameters passed to insert_button as well as
-    # calculating the button object position and vertices.
-    #
-    def button_params(row, col, params)
-      button = Writexlsx::Package::Button.new
-
-      button_number = 1 + @buttons_array.size
-
-      # Set the button caption.
-      caption = params[:caption] || "Button #{button_number}"
-
-      button.font = { _caption: caption }
-
-      # Set the macro name.
-      button.macro = if params[:macro]
-                       "[0]!#{params[:macro]}"
-                     else
-                       "[0]!Button#{button_number}_Click"
-                     end
-
-      # Set the alt text for the button.
-      button.description = params[:description]
-
-      # Ensure that a width and height have been set.
-      default_width  = @default_col_pixels
-      default_height = @default_row_pixels
-      params[:width]  = default_width  unless params[:width]
-      params[:height] = default_height unless params[:height]
-
-      # Set the x/y offsets.
-      params[:x_offset] = 0 unless params[:x_offset]
-      params[:y_offset] = 0 unless params[:y_offset]
-
-      # Scale the size of the button box if required.
-      params[:width] = params[:width] * params[:x_scale] if params[:x_scale]
-      params[:height] = params[:height] * params[:y_scale] if params[:y_scale]
-
-      # Round the dimensions to the nearest pixel.
-      params[:width]  = (0.5 + params[:width]).to_i
-      params[:height] = (0.5 + params[:height]).to_i
-
-      params[:start_row] = row
-      params[:start_col] = col
-
-      # Calculate the positions of button object.
-      vertices = position_object_pixels(
-        params[:start_col],
-        params[:start_row],
-        params[:x_offset],
-        params[:y_offset],
-        params[:width],
-        params[:height]
-      )
-
-      # Add the width and height for VML.
-      vertices << [params[:width], params[:height]]
-
-      button.vertices = vertices
-
-      button
-    end
 
     #
     # Hash a worksheet password. Based on the algorithm in ECMA-376-4:2016,
@@ -3868,7 +3813,7 @@ EOS
           end
         else
           # Row attributes only.
-          write_empty_row(row_num, span, *(@set_rows[row_num]))
+          write_empty_row(row_num, span, *@set_rows[row_num])
         end
       end
     end
@@ -4374,7 +4319,7 @@ EOS
       return unless outline_changed?
 
       attributes = []
-      attributes << ["applyStyles",  1] if @outline_style != 0
+      attributes << ["applyStyles",  1] if @outline_style
       attributes << ["summaryBelow", 0] if @outline_below == 0
       attributes << ["summaryRight", 0] if @outline_right == 0
       attributes << ["showOutlineSymbols", 0] if @outline_on == 0
@@ -4471,7 +4416,7 @@ EOS
     # Write the <picture> element.
     #
     def write_picture
-      return unless ptrue?(@background_image)
+      return unless @background_image
 
       # Increment the relationship id.
       @rel_count += 1
@@ -4704,7 +4649,7 @@ EOS
     def write_sparklines(sparkline)
       # Write the sparkline elements.
       @writer.tag_elements('x14:sparklines') do
-        (0..sparkline[:count] - 1).each do |i|
+        (0..(sparkline[:count] - 1)).each do |i|
           range    = sparkline[:ranges][i]
           location = sparkline[:locations][i]
 
@@ -4984,5 +4929,54 @@ EOS
 
       @writer.empty_tag('ignoredError', attributes)
     end
+
+    def prepare_header_footer_image(image, header_image_ids, image_ref_id)
+      @workbook.store_image_types(image.type)
+
+      if header_image_ids[image.md5]
+        ref_id = header_image_ids[image.md5]
+      else
+        image_ref_id += 1
+        header_image_ids[image.md5] = ref_id = image_ref_id
+        @workbook.images << image
+      end
+
+      prepare_header_image(ref_id, image)
+
+      image_ref_id
+    end
+
+    def protect_default_settings  # :nodoc:
+      {
+        sheet:                 true,
+        content:               false,
+        objects:               false,
+        scenarios:             false,
+        format_cells:          false,
+        format_columns:        false,
+        format_rows:           false,
+        insert_columns:        false,
+        insert_rows:           false,
+        insert_hyperlinks:     false,
+        delete_columns:        false,
+        delete_rows:           false,
+        select_locked_cells:   true,
+        sort:                  false,
+        autofilter:            false,
+        pivot_tables:          false,
+        select_unlocked_cells: true
+      }
+    end
+
+    def expand_formula(formula, function, addition = '')
+      if formula =~ /\b(#{function})/
+        formula.gsub(
+          ::Regexp.last_match(1),
+          "_xlfn#{addition}.#{::Regexp.last_match(1)}"
+        )
+      else
+        formula
+      end
+    end
   end
 end