write_xlsx 1.12.2 → 1.13.0

data/lib/write_xlsx/worksheet/drawing_methods.rb

@@ -0,0 +1,308 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  class Worksheet
+    module DrawingMethods
+      ###############################################################################
+      #
+      # DrawingMethods
+      #
+      # Provides high-level Worksheet APIs for inserting drawing-related objects
+      # such as charts, images, shapes, tables, and sparklines.
+      #
+      # Responsibilities:
+      # - Public insertion entry points used by Worksheet users
+      # - Argument normalization and option extraction
+      # - Shape insertion workflow and helper utilities
+      #
+      # This module handles *what gets added to the sheet*.
+      # It does not manage relationships or XML output.
+      #
+      ###############################################################################
+      #
+      # This method can be used to insert a Chart object into a worksheet.
+      # The Chart must be created by the add_chart() Workbook method and
+      # it must have the embedded option set.
+      #
+      def insert_chart(row, col, chart = nil, *options)
+        normalized_row, normalized_col, normalized_chart, normalized_options =
+          normalize_row_col_args(row, col, chart, options)
+        raise WriteXLSXInsufficientArgumentError if [normalized_row, normalized_col, normalized_chart].include?(nil)
+
+        x_offset, y_offset, x_scale, y_scale, anchor, description, decorative =
+          extract_chart_options(normalized_options)
+
+        raise "Not a Chart object in insert_chart()" unless normalized_chart.is_a?(Chart) || normalized_chart.is_a?(Chartsheet)
+        raise "Not a embedded style Chart object in insert_chart()" if normalized_chart.respond_to?(:embedded) && normalized_chart.embedded == 0
+
+        if normalized_chart.already_inserted? || (normalized_chart.combined && normalized_chart.combined.already_inserted?)
+          raise "Chart cannot be inserted in a worksheet more than once"
+        else
+          normalized_chart.already_inserted          = true
+          normalized_chart.combined.already_inserted = true if normalized_chart.combined
+        end
+
+        # Use the values set with chart.set_size, if any.
+        x_scale  = normalized_chart.x_scale  if normalized_chart.x_scale  != 1
+        y_scale  = normalized_chart.y_scale  if normalized_chart.y_scale  != 1
+        x_offset = normalized_chart.x_offset if ptrue?(normalized_chart.x_offset)
+        y_offset = normalized_chart.y_offset if ptrue?(normalized_chart.y_offset)
+
+        @assets.add_chart(
+          InsertedChart.new(
+            normalized_row,    normalized_col, normalized_chart,
+            x_offset, y_offset, x_scale, y_scale, anchor, description, decorative
+          )
+        )
+      end
+
+      def insert_image(row, col, image = nil, *options)
+        normalized_row, normalized_col, normalized_image, normalized_options =
+          normalize_row_col_args(row, col, image, options)
+        raise WriteXLSXInsufficientArgumentError if [normalized_row, normalized_col, normalized_image].include?(nil)
+
+        x_offset, y_offset, x_scale, y_scale,
+        anchor, url, tip, description, decorative = extract_image_options(normalized_options)
+
+        @assets.add_image(
+          Image.new(
+            normalized_row, normalized_col, normalized_image, x_offset, y_offset,
+            x_scale, y_scale, url, tip, anchor, description, decorative
+          )
+        )
+      end
+
+      def embed_image(row, col, filename, options = nil)
+        normalize_row, normalize_col, image, normalize_options = normalize_row_col_args(row, col, filename, options)
+
+        raise WriteXLSXInsufficientArgumentError if [normalize_row, normalize_col, image].include?(nil)
+        raise "Couldn't locate #{image}" unless File.exist?(image)
+
+        # Check that row and col are valid and store max and min values
+        check_dimensions(normalize_row, normalize_col)
+        store_row_col_max_min_values(normalize_row, normalize_col)
+
+        if options
+          xf          = options[:cell_format]
+          url         = options[:url]
+          tip         = options[:tip]
+          description = options[:description]
+          decorative  = options[:decorative]
+        else
+          xf, url, tip, description, decorative = []
+        end
+
+        # Write the url without writing a string.
+        if url
+          xf ||= @default_url_format
+
+          write_url(row, col, url, xf, nil, tip, true)
+        end
+
+        # Get the image properties, mainly for the type and checksum.
+        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[image_property.md5]
+
+        unless ptrue?(image_index)
+          @workbook.embedded_images << image_property
+
+          image_index = @workbook.embedded_images.size
+          @embedded_image_indexes[image_property.md5] = image_index
+        end
+
+        # Write the cell placeholder.
+        store_data_to_table(EmbedImageCellData.new(image_index, xf), normalize_row, normalize_col)
+        @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
+          )
+        row, col, normalized_shape, normalized_options =
+          normalize_shape_args(row_start, column_start, shape, x_offset, y_offset, x_scale, y_scale, anchor)
+        raise "Insufficient arguments in insert_shape()" if [row, col, normalized_shape].include?(nil)
+
+        set_shape_position(normalized_shape, row, col, normalized_options)
+        assign_shape_id(normalized_shape)
+
+        # Allow lookup of entry into shape array by shape ID.
+        @shape_hash[normalized_shape.id] = normalized_shape.element = shapes.size
+
+        inserted_shape = build_inserted_shape(normalized_shape)
+
+        # For connectors change x/y coords based on location of connected shapes.
+        auto_locate_shape_connectors(inserted_shape)
+
+        # Insert a link to the shape on the list of shapes. Connection to
+        # the parent shape is maintained.
+        @assets.add_shape(inserted_shape)
+        inserted_shape
+      end
+
+      #
+      # :call-seq:
+      #    add_table(row1, col1, row2, col2, properties)
+      #
+      # Add an Excel table to a worksheet.
+      #
+      def add_table(*args)
+        # Table count is a member of Workbook, global to all Worksheet.
+        table = Package::Table.new(self, *args)
+        @assets.add_table(table)
+        table
+      end
+
+      #
+      # :call-seq:
+      #    add_sparkline(properties)
+      #
+      # Add sparklines to the worksheet.
+      #
+      def add_sparkline(param)
+        @assets.add_sparkline(Sparkline.new(self, param, quote_sheetname(@name)))
+      end
+
+      private
+
+      def normalize_row_col_args(row, col, object, options)
+        if (row_col_array = row_col_notation(row))
+          normalized_row, normalized_col = row_col_array
+          normalized_object = col
+          normalized_options = [object] + options
+        else
+          normalized_row = row
+          normalized_col = col
+          normalized_object = object
+          normalized_options = options
+        end
+
+        [normalized_row, normalized_col, normalized_object, normalized_options]
+      end
+
+      def extract_chart_options(options)
+        if options.first.instance_of?(Hash)
+          params = options.first
+          [
+            params[:x_offset] || 0,
+            params[:y_offset] || 0,
+            params[:x_scale] || 1,
+            params[:y_scale] || 1,
+            params[:object_position] || 1,
+            params[:description],
+            params[:decorative]
+          ]
+        else
+          x_offset, y_offset, x_scale, y_scale, anchor = options
+          [x_offset || 0, y_offset || 0, x_scale || 1, y_scale || 1, anchor || 1, nil, nil]
+        end
+      end
+
+      def extract_image_options(options)
+        if options.first.instance_of?(Hash)
+          params = options.first
+          [
+            params[:x_offset] || 0,
+            params[:y_offset] || 0,
+            params[:x_scale] || 1,
+            params[:y_scale] || 1,
+            params[:object_position] || 2,
+            params[:url],
+            params[:tip],
+            params[:description],
+            params[:decorative]
+          ]
+        else
+          x_offset, y_offset, x_scale, y_scale, anchor = options
+          [x_offset || 0, y_offset || 0, x_scale || 1, y_scale || 1, anchor || 2, nil, nil, nil, nil]
+        end
+      end
+
+      def normalize_shape_args(row_start, column_start, shape,
+                               x_offset, y_offset, x_scale, y_scale, anchor)
+        if (row_col_array = row_col_notation(row_start))
+          normalized_row, normalized_col = row_col_array
+          normalized_shape    = column_start
+          normalized_x_offset = shape
+          normalized_y_offset = x_offset
+          normalized_x_scale  = y_offset
+          normalized_y_scale  = x_scale
+          normalized_anchor   = y_scale
+        else
+          normalized_row      = row_start
+          normalized_col      = column_start
+          normalized_shape    = shape
+          normalized_x_offset = x_offset
+          normalized_y_offset = y_offset
+          normalized_x_scale  = x_scale
+          normalized_y_scale  = y_scale
+          normalized_anchor   = anchor
+        end
+
+        [
+          normalized_row,
+          normalized_col,
+          normalized_shape,
+          {
+            x_offset: normalized_x_offset,
+            y_offset: normalized_y_offset,
+            x_scale:  normalized_x_scale,
+            y_scale:  normalized_y_scale,
+            anchor:   normalized_anchor
+          }
+        ]
+      end
+
+      def set_shape_position(shape, row, col, options)
+        shape.set_position(
+          row, col,
+          options[:x_offset],
+          options[:y_offset],
+          options[:x_scale],
+          options[:y_scale],
+          options[:anchor]
+        )
+      end
+
+      def assign_shape_id(shape)
+        loop do
+          id = shape.id || 0
+          used = @shape_hash[id]
+
+          if !used && id != 0
+            break
+          else
+            @last_shape_id += 1
+            shape.id = @last_shape_id
+          end
+        end
+
+        @shape_hash[shape.id] = shape.element = shapes.size
+      end
+
+      def build_inserted_shape(shape)
+        if ptrue?(shape.stencil)
+          shape.dup
+        else
+          shape
+        end
+      end
+
+      def auto_locate_shape_connectors(shape)
+        shape.auto_locate_connectors(shapes, @shape_hash)
+      end
+    end
+  end
+end

data/lib/write_xlsx/worksheet/drawing_preparation.rb

@@ -0,0 +1,290 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  class Worksheet
+    module DrawingPreparation
+      ###############################################################################
+      #
+      # DrawingPreparation
+      #
+      # Prepares drawing-related assets for XLSX output.
+      #
+      # Responsibilities:
+      # - Convert inserted charts, images, shapes, and media into Drawing objects
+      # - Register drawing assets with the Workbook and Drawings containers
+      # - Prepare background, header/footer images, and VML objects
+      # - Coordinate drawing setup before XML serialization
+      #
+      # This module handles *how drawing assets are assembled for output*.
+      # Relationship management and XML writing are handled elsewhere.
+      #
+      ###############################################################################
+
+      # Drawing preparation
+
+      def prepare_drawings(drawing_id, chart_ref_id, image_ref_id, image_ids, header_image_ids, background_ids)
+        has_drawings = false
+
+        # Check that some image or drawing needs to be processed.
+        unless some_image_or_drawing_to_be_processed?
+
+          # Don't increase the drawing_id header/footer images.
+          unless charts.empty? && images.empty? && shapes.empty?
+            drawing_id += 1
+            has_drawings = true
+          end
+
+          # Prepare the background images.
+          image_ref_id = prepare_background_image(background_ids, image_ref_id)
+
+          # 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 up chart/drawings.
+      #
+      def prepare_chart(index, chart_id, drawing_id) # :nodoc:
+        drawing_type = 1
+
+        inserted_chart = charts[index]
+        inserted_chart.chart.id = chart_id - 1
+
+        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, 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 = true
+
+          @external_drawing_links << ['/drawing', "../drawings/drawing#{drawing_id}.xml"]
+        end
+        @drawing_links << ['/chart', "../charts/chart#{chart_id}.xml"]
+      end
+
+      #
+      # Set up image/drawings.
+      #
+      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
+
+        @workbook.store_image_types(image_type)
+
+        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
+
+        dimensions = position_object_emus(image)
+
+        # Create a Drawing object to use with worksheet unless one already exists.
+        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)
+
+        if image.url
+          target_mode = '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')
+
+            # Prefix absolute paths (not relative) with file:///
+            target = if target =~ /^\w:/ || target =~ /^\\\\/
+                       "file:///#{target}"
+                     else
+                       target.gsub("\\", '/')
+                     end
+          end
+
+          if image.url =~ /^internal:/
+            target      = image.url.sub(/^internal:/, '#')
+            target_mode = nil
+          end
+
+          if target.length > 255
+            raise <<"EOS"
+Ignoring URL #{target} where link or anchor > 255 characters since it exceeds Excel's limit for URLS. See LIMITATIONS section of the WriteXLSX documentation.
+EOS
+          end
+
+          @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
+
+      #
+      # Set up drawing shapes
+      #
+      def prepare_shape(index, drawing_id)
+        shape = shapes[index]
+
+        # Create a Drawing object to use with worksheet unless one already exists.
+        unless drawings?
+          @drawings = Drawings.new
+          @drawings.embedded = true
+          @external_drawing_links << ['/drawing', "../drawings/drawing#{drawing_id}.xml"]
+          @has_shapes = true
+        end
+
+        # Validate the he shape against various rules.
+        shape.validate(index)
+        shape.calc_position_emus(self)
+
+        drawing_type = 3
+        drawing = Drawing.new(
+          drawing_type, shape.dimensions, shape.width_emu, shape.height_emu,
+          shape, shape.anchor, drawing_rel_index, 0, shape.name, nil, 0
+        )
+        drawings.add_drawing_object(drawing)
+      end
+
+      # Image preparation
+
+      #
+      # Set up an image without a drawing object for the background image.
+      #
+      def prepare_background(image_id, image_type)
+        @external_background_links <<
+          ['/image', "../media/image#{image_id}.#{image_type}"]
+      end
+
+      def prepare_background_image(background_ids, image_ref_id)
+        unless background_image.nil?
+          @workbook.store_image_types(background_image.type)
+
+          if background_ids[background_image.md5]
+            ref_id = background_ids[background_image.md5]
+          else
+            image_ref_id += 1
+            ref_id = image_ref_id
+            background_ids[background_image.md5] = ref_id
+            @workbook.images << background_image
+          end
+
+          prepare_background(ref_id, background_image.type)
+        end
+
+        image_ref_id
+      end
+
+      def prepare_header_image(image_id, image_property)
+        # Strip the extension from the filename.
+        body = image_property.name.dup
+        body[/\.[^.]+$/, 0] = ''
+        image_property.body = body
+
+        @vml_drawing_links << ['/image', "../media/image#{image_id}.#{image_property.type}"] unless @vml_drawing_rels[image_property.md5]
+
+        image_property.ref_id = get_vml_drawing_rel_index(image_property.md5)
+        @header_images_array << image_property
+      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
+
+      # VML preparation
+
+      #
+      # Turn the HoH that stores the comments into an array for easier handling
+      # and set the external links for comments and buttons.
+      #
+      def prepare_vml_objects(vml_data_id, vml_shape_id, vml_drawing_id, comment_id)
+        set_external_vml_links(vml_drawing_id)
+        set_external_comment_links(comment_id) if has_comments?
+
+        # The VML o:idmap data id contains a comma separated range when there is
+        # more than one 1024 block of comments, like this: data="1,2".
+        data = vml_data_id.to_s
+        (1..num_comments_block).each do |i|
+          data += ",#{vml_data_id + i}"
+        end
+        @vml_data_id = data
+        @vml_shape_id = vml_shape_id
+      end
+
+      #
+      # Setup external linkage for VML header/footer images.
+      #
+      def prepare_header_vml_objects(vml_header_id, vml_drawing_id)
+        @vml_header_id = vml_header_id
+        @external_vml_links << ['/vmlDrawing', "../drawings/vmlDrawing#{vml_drawing_id}.vml"]
+      end
+    end
+  end
+end

data/lib/write_xlsx/worksheet/drawing_relations.rb

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  class Worksheet
+    module DrawingRelations
+      ###############################################################################
+      #
+      # DrawingRelations
+      #
+      # Manages drawing relationships and external linkage information.
+      #
+      # Responsibilities:
+      # - Relationship ID allocation for drawings and VML objects
+      # - Tracking drawing and VML relationship mappings
+      # - Managing external links for drawings, comments, tables, and media
+      # - Providing relationship data for rels file generation
+      #
+      # This module handles *how drawing resources are linked together*.
+      # It does not prepare drawing objects or write XML output.
+      #
+      ###############################################################################
+      #
+      # 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
+          @drawing_rels_id += 1
+          @drawing_rels[target] = @drawing_rels_id
+        end
+      end
+
+      #
+      # Get the index used to address a vml_drawing rel link.
+      #
+      def get_vml_drawing_rel_index(target)
+        if @vml_drawing_rels[target]
+          @vml_drawing_rels[target]
+        else
+          @vml_drawing_rels_id += 1
+          @vml_drawing_rels[target] = @vml_drawing_rels_id
+        end
+      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
+
+      def external_links
+        [
+          @external_hyper_links,
+          @external_drawing_links,
+          @external_vml_links,
+          @external_background_links,
+          @external_table_links,
+          @external_comment_links
+        ].reject(&:empty?)
+      end
+
+      def drawing_links
+        [@drawing_links]
+      end
+    end
+  end
+end