Class: Writexlsx::Chart

Inherits:
Object
  • Object
show all
Includes:
Gradient, Utility
Defined in:
lib/write_xlsx/chart.rb,
lib/write_xlsx/chart/bar.rb,
lib/write_xlsx/chart/pie.rb,
lib/write_xlsx/chart/area.rb,
lib/write_xlsx/chart/axis.rb,
lib/write_xlsx/chart/line.rb,
lib/write_xlsx/chart/radar.rb,
lib/write_xlsx/chart/stock.rb,
lib/write_xlsx/chart/column.rb,
lib/write_xlsx/chart/legend.rb,
lib/write_xlsx/chart/series.rb,
lib/write_xlsx/chart/caption.rb,
lib/write_xlsx/chart/scatter.rb,
lib/write_xlsx/chart/doughnut.rb

Direct Known Subclasses

Area, Bar, Column, Line, Pie, Radar, Scatter, Stock

Defined Under Namespace

Classes: Area, Axis, Bar, Caption, Chartline, Column, Doughnut, Errorbars, Gridline, Legend, Line, Marker, Pie, Point, Radar, Scatter, Series, Stock, Trendline

Constant Summary

Constants included from Utility

Utility::CHAR_WIDTHS, Utility::COL_MAX, Utility::PERL_TRUE_VALUES, Utility::ROW_MAX, Utility::SHEETNAME_MAX, Utility::STR_MAX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Gradient

#gradient_properties

Methods included from Utility

#absolute_char, #check_dimensions, #check_dimensions_and_update_max_min_values, #check_parameter, #color, #convert_date_time, #convert_font_args, #dash_types, delete_files, #escape_url, #fill_properties, #float_to_str, #get_font_latin_attributes, #get_font_style_attributes, #get_image_properties, #layout_properties, #legend_properties, #line_fill_properties, #line_properties, #palette_color, #params_to_font, #pattern_properties, #pixels_to_points, #process_bmp, #process_gif, #process_jpg, #process_png, #process_workbook_options, #ptrue?, #put_deprecate_message, #quote_sheetname, #r_id_attributes, #row_col_notation, #shape_style_base, #store_col_max_min_values, #store_row_max_min_values, #substitute_cellref, #underline_attributes, #v_shape_attributes_base, #v_shape_style_base, #value_or_raise, #write_a_body_pr, #write_a_def_rpr, #write_a_end_para_rpr, #write_a_lst_style, #write_a_p_formula, #write_a_p_pr_formula, #write_a_solid_fill, #write_a_srgb_clr, #write_anchor, #write_auto_fill, #write_color, #write_comment_path, #write_def_rpr_r_pr_common, #write_div, #write_fill, #write_font, #write_stroke, #write_tx_pr, #write_xml_declaration, #xl_cell_to_rowcol, #xl_col_to_name, #xl_range, #xl_range_formula, #xl_rowcol_to_cell, #xl_string_pixel_width, #xml_str

Constructor Details

#initialize(subtype) ⇒ Chart

:nodoc:



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/write_xlsx/chart.rb', line 215

def initialize(subtype)   # :nodoc:
  @writer = Package::XMLWriterSimple.new

  @subtype           = subtype
  @sheet_type        = 0x0200
  @series            = []
  @embedded          = 0
  @id                = -1
  @series_index      = 0
  @style_id          = 2
  @formula_ids       = {}
  @formula_data      = []
  @protection        = 0
  @chartarea         = ChartArea.new
  @plotarea          = ChartArea.new
  @title             = Caption.new(self)
  @name              = ''
  @table             = nil
  set_default_properties
  @combined          = nil
  @is_secondary      = false
end

Instance Attribute Details

#already_inserted=(value) ⇒ Object (writeonly)

:nodoc:



175
176
177
 
# File 'lib/write_xlsx/chart.rb', line 175

def already_inserted=(value)
  @already_inserted = value
end

#axis2_ids ⇒ Object (readonly)

:nodoc:



178
179
180
 
# File 'lib/write_xlsx/chart.rb', line 178

def axis2_ids
  @axis2_ids
end

#combined ⇒ Object (readonly)

:nodoc:



174
175
176
 
# File 'lib/write_xlsx/chart.rb', line 174

def combined
  @combined
end

#date_category=(value) ⇒ Object (writeonly)

:nodoc:



175
176
177
 
# File 'lib/write_xlsx/chart.rb', line 175

def date_category=(value)
  @date_category = value
end

#embedded ⇒ Object (readonly)

:nodoc:



171
172
173
 
# File 'lib/write_xlsx/chart.rb', line 171

def embedded
  @embedded
end

#formula_data ⇒ Object (readonly)

:nodoc:



171
172
173
 
# File 'lib/write_xlsx/chart.rb', line 171

def formula_data
  @formula_data
end

#formula_ids ⇒ Object (readonly)

:nodoc:



171
172
173
 
# File 'lib/write_xlsx/chart.rb', line 171

def formula_ids
  @formula_ids
end

#height ⇒ Object (readonly)

:nodoc:



173
174
175
 
# File 'lib/write_xlsx/chart.rb', line 173

def height
  @height
end

#id ⇒ Object

:nodoc:



169
170
171
 
# File 'lib/write_xlsx/chart.rb', line 169

def id
  @id
end

#index=(value) ⇒ Object (writeonly)

:nodoc:



170
171
172
 
# File 'lib/write_xlsx/chart.rb', line 170

def index=(value)
  @index = value
end

#label_position_default ⇒ Object (readonly)

:nodoc:



174
175
176
 
# File 'lib/write_xlsx/chart.rb', line 174

def label_position_default
  @label_position_default
end

#label_positions ⇒ Object (readonly)

:nodoc:



174
175
176
 
# File 'lib/write_xlsx/chart.rb', line 174

def label_positions
  @label_positions
end

#name ⇒ Object

:nodoc:



169
170
171
 
# File 'lib/write_xlsx/chart.rb', line 169

def name
  @name
end

#palette=(value) ⇒ Object (writeonly)

:nodoc:



170
171
172
 
# File 'lib/write_xlsx/chart.rb', line 170

def palette=(value)
  @palette = value
end

#protection=(value) ⇒ Object (writeonly)

:nodoc:



170
171
172
 
# File 'lib/write_xlsx/chart.rb', line 170

def protection=(value)
  @protection = value
end

#series_index=(value) ⇒ Object (writeonly)

:nodoc:



176
177
178
 
# File 'lib/write_xlsx/chart.rb', line 176

def series_index=(value)
  @series_index = value
end

#width ⇒ Object (readonly)

:nodoc:



173
174
175
 
# File 'lib/write_xlsx/chart.rb', line 173

def width
  @width
end

#writer=(value) ⇒ Object (writeonly)

:nodoc:



177
178
179
 
# File 'lib/write_xlsx/chart.rb', line 177

def writer=(value)
  @writer = value
end

#x2_axis ⇒ Object (readonly)

:nodoc:



178
179
180
 
# File 'lib/write_xlsx/chart.rb', line 178

def x2_axis
  @x2_axis
end

#x_offset ⇒ Object (readonly)

:nodoc:



172
173
174
 
# File 'lib/write_xlsx/chart.rb', line 172

def x_offset
  @x_offset
end

#x_scale ⇒ Object (readonly)

:nodoc:



172
173
174
 
# File 'lib/write_xlsx/chart.rb', line 172

def x_scale
  @x_scale
end

#y2_axis ⇒ Object (readonly)

:nodoc:



178
179
180
 
# File 'lib/write_xlsx/chart.rb', line 178

def y2_axis
  @y2_axis
end

#y_offset ⇒ Object (readonly)

:nodoc:



172
173
174
 
# File 'lib/write_xlsx/chart.rb', line 172

def y_offset
  @y_offset
end

#y_scale ⇒ Object (readonly)

:nodoc:



172
173
174
 
# File 'lib/write_xlsx/chart.rb', line 172

def y_scale
  @y_scale
end

Class Method Details

.factory(current_subclass, subtype = nil) ⇒ Object

Factory method for returning chart objects based on their class type.



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/write_xlsx/chart.rb', line 183

def self.factory(current_subclass, subtype = nil) # :nodoc:
  case current_subclass.downcase.capitalize
  when 'Area'
    require 'write_xlsx/chart/area'
    Chart::Area.new(subtype)
  when 'Bar'
    require 'write_xlsx/chart/bar'
    Chart::Bar.new(subtype)
  when 'Column'
    require 'write_xlsx/chart/column'
    Chart::Column.new(subtype)
  when 'Doughnut'
    require 'write_xlsx/chart/doughnut'
    Chart::Doughnut.new(subtype)
  when 'Line'
    require 'write_xlsx/chart/line'
    Chart::Line.new(subtype)
  when 'Pie'
    require 'write_xlsx/chart/pie'
    Chart::Pie.new(subtype)
  when 'Radar'
    require 'write_xlsx/chart/radar'
    Chart::Radar.new(subtype)
  when 'Scatter'
    require 'write_xlsx/chart/scatter'
    Chart::Scatter.new(subtype)
  when 'Stock'
    require 'write_xlsx/chart/stock'
    Chart::Stock.new(subtype)
  end
end

Instance Method Details

#add_series(params) ⇒ Object

Add a series and it’s properties to a chart.



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/write_xlsx/chart.rb', line 268

def add_series(params)
  # Check that the required input has been specified.
  raise "Must specify ':values' in add_series" unless params.has_key?(:values)

  raise "Must specify ':categories' in add_series for this chart type" if @requires_category != 0 && !params.has_key?(:categories)

  raise "The maximum number of series that can be added to an Excel Chart is 255." if @series.size == 255

  @series << Series.new(self, params)

  # Set the secondary axis properties.
  x2_axis = params[:x2_axis]
  y2_axis = params[:y2_axis]

  # Store secondary status for combined charts.
  @is_secondary = true if ptrue?(x2_axis) || ptrue?(y2_axis)

  # Set the gap and overlap for Bar/Column charts.
  if params[:gap]
    if ptrue?(y2_axis)
      @series_gap_2 = params[:gap]
    else
      @series_gap_1 = params[:gap]
    end
  end

  # Set the overlap for Bar/Column charts.
  if params[:overlap]
    if ptrue?(y2_axis)
      @series_overlap_2 = params[:overlap]
    else
      @series_overlap_1 = params[:overlap]
    end
  end
end

#already_inserted? ⇒ Boolean

Returns:

  • (Boolean) 


563
564
565
 
# File 'lib/write_xlsx/chart.rb', line 563

def already_inserted?
  @already_inserted
end

#assemble_xml_file ⇒ Object

Assemble and write the XML file.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/write_xlsx/chart.rb', line 245

def assemble_xml_file   # :nodoc:
  write_xml_declaration do
    # Write the c:chartSpace element.
    write_chart_space do
      # Write the c:lang element.
      write_lang
      # Write the c:style element.
      write_style
      # Write the c:protection element.
      write_protection
      # Write the c:chart element.
      write_chart
      # Write the c:spPr element for the chartarea formatting.
      write_sp_pr(@chartarea)
      # Write the c:printSettings element.
      write_print_settings if @embedded && @embedded != 0
    end
  end
end

#combine(chart) ⇒ Object

Add another chart to create a combined chart.



457
458
459
 
# File 'lib/write_xlsx/chart.rb', line 457

def combine(chart)
  @combined = chart
end

#data_id(full_formula, data) ⇒ Object

Assign an id to a each unique series formula or title/axis formula. Repeated formulas such as for categories get the same id. If the series or title has user specified data associated with it then that is also stored. This data is used to populate cached Excel data when creating a chart. If there is no user defined data then it will be populated by the parent workbook in Workbook::_add_chart_data



541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/write_xlsx/chart.rb', line 541

def data_id(full_formula, data) # :nodoc:
  return unless full_formula

  # Strip the leading '=' from the formula.
  formula = full_formula.sub(/^=/, '')

  # Store the data id in a hash keyed by the formula and store the data
  # in a separate array with the same id.
  if @formula_ids.has_key?(formula)
    # Formula already seen. Return existing id.
    id = @formula_ids[formula]
    # Store user defined data if it isn't already there.
    @formula_data[id] ||= data
  else
    # Haven't seen this formula before.
    id = @formula_ids[formula] = @formula_data.size
    @formula_data << data
  end

  id
end

#is_secondary? ⇒ Boolean

Returns:

  • (Boolean) 


567
568
569
 
# File 'lib/write_xlsx/chart.rb', line 567

def is_secondary?
  @is_secondary
end

#process_names(name = nil, name_formula = nil) ⇒ Object

Switch name and name_formula parameters if required.



519
520
521
522
523
524
525
526
527
528
529
530
531
 
# File 'lib/write_xlsx/chart.rb', line 519

def process_names(name = nil, name_formula = nil) # :nodoc:
  # Name looks like a formula, use it to set name_formula.
  if name.respond_to?(:to_ary)
    cell = xl_rowcol_to_cell(name[1], name[2], 1, 1)
    name_formula = "#{quote_sheetname(name[0])}!#{cell}"
    name = ''
  elsif name && name =~ /^=[^!]+!\$/
    name_formula = name
    name         = ''
  end

  [name, name_formula]
end

#set_chartarea(params) ⇒ Object

Set the properties of the chart chartarea.



365
366
367
368
 
# File 'lib/write_xlsx/chart.rb', line 365

def set_chartarea(params)
  # Convert the user defined properties to internal properties.
  @chartarea = ChartArea.new(params)
end

#set_drop_lines(params = {}) ⇒ Object

Set properties for the chart drop lines.



443
444
445
 
# File 'lib/write_xlsx/chart.rb', line 443

def set_drop_lines(params = {})
  @drop_lines = Chartline.new(params)
end

#set_embedded_config_data ⇒ Object

Setup the default configuration data for an embedded chart.



464
465
466
 
# File 'lib/write_xlsx/chart.rb', line 464

def set_embedded_config_data
  @embedded = 1
end

#set_high_low_lines(params = {}) ⇒ Object

Set properties for the chart high-low lines.



450
451
452
 
# File 'lib/write_xlsx/chart.rb', line 450

def set_high_low_lines(params = {})
  @hi_low_lines = Chartline.new(params)
end

#set_legend(params) ⇒ Object

Set the properties of the chart legend.



349
350
351
352
 
# File 'lib/write_xlsx/chart.rb', line 349

def set_legend(params)
  # Convert the user default properties to internal properties.
  legend_properties(params)
end

#set_plotarea(params) ⇒ Object

Set the properties of the chart plotarea.



357
358
359
360
 
# File 'lib/write_xlsx/chart.rb', line 357

def set_plotarea(params)
  # Convert the user defined properties to internal properties.
  @plotarea = ChartArea.new(params)
end

#set_size(params = {}) ⇒ Object Also known as: size

Set dimensions for scale for the chart.



399
400
401
402
403
404
405
406
 
# File 'lib/write_xlsx/chart.rb', line 399

def set_size(params = {})
  @width    = params[:width]    if params[:width]
  @height   = params[:height]   if params[:height]
  @x_scale  = params[:x_scale]  if params[:x_scale]
  @y_scale  = params[:y_scale]  if params[:y_scale]
  @x_offset = params[:x_offset] if params[:x_offset]
  @y_offset = params[:y_offset] if params[:y_offset]
end

#set_style(style_id = 2) ⇒ Object

Set on of the 42 built-in Excel chart styles. The default style is 2.



373
374
375
376
 
# File 'lib/write_xlsx/chart.rb', line 373

def set_style(style_id = 2)
  style_id = 2 if style_id < 1 || style_id > 48
  @style_id = style_id
end

#set_table(params = {}) ⇒ Object

The set_table method adds a data table below the horizontal axis with the data used to plot the chart.



415
416
417
418
 
# File 'lib/write_xlsx/chart.rb', line 415

def set_table(params = {})
  @table = Table.new(params)
  @table.palette = @palette
end

#set_title(params) ⇒ Object

Set the properties of the chart title.



342
343
344
 
# File 'lib/write_xlsx/chart.rb', line 342

def set_title(params)
  @title.merge_with_hash(params)
end

#set_up_down_bars(params = {}) ⇒ Object

Set properties for the chart up-down bars.



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/write_xlsx/chart.rb', line 423

def set_up_down_bars(params = {})
  # Map border to line.
  %i[up down].each do |up_down|
    if params[up_down]
      params[up_down][:line] = params[up_down][:border] if params[up_down][:border]
    else
      params[up_down] = {}
    end
  end

  # Set the up and down bar properties.
  @up_down_bars = {
    _up:   Chartline.new(params[:up]),
    _down: Chartline.new(params[:down])
  }
end

#set_x2_axis(params = {}) ⇒ Object

Set the properties of the secondary X-axis.



326
327
328
329
 
# File 'lib/write_xlsx/chart.rb', line 326

def set_x2_axis(params = {})
  @date_category = true if ptrue?(params[:date_axis])
  @x2_axis.merge_with_hash(params)
end

#set_x_axis(params = {}) ⇒ Object

Set the properties of the x-axis.



307
308
309
310
 
# File 'lib/write_xlsx/chart.rb', line 307

def set_x_axis(params = {})
  @date_category = true if ptrue?(params[:date_axis])
  @x_axis.merge_with_hash(params)
end

#set_xml_writer(filename) ⇒ Object

:nodoc:



238
239
240
 
# File 'lib/write_xlsx/chart.rb', line 238

def set_xml_writer(filename)   # :nodoc:
  @writer.set_xml_writer(filename)
end

#set_y2_axis(params = {}) ⇒ Object

Set the properties of the secondary Y-axis.



334
335
336
337
 
# File 'lib/write_xlsx/chart.rb', line 334

def set_y2_axis(params = {})
  @date_category = true if ptrue?(params[:date_axis])
  @y2_axis.merge_with_hash(params)
end

#set_y_axis(params = {}) ⇒ Object

Set the properties of the Y-axis.

The set_y_axis() method is used to set properties of the Y axis. The properties that can be set are the same as for set_x_axis,



318
319
320
321
 
# File 'lib/write_xlsx/chart.rb', line 318

def set_y_axis(params = {})
  @date_category = true if ptrue?(params[:date_axis])
  @y_axis.merge_with_hash(params)
end

#show_blanks_as(option) ⇒ Object

Set the option for displaying blank data in a chart. The default is ‘gap’.



381
382
383
384
385
386
387
 
# File 'lib/write_xlsx/chart.rb', line 381

def show_blanks_as(option)
  return unless option

  raise "Unknown show_blanks_as() option '#{option}'\n" unless %i[gap zero span].include?(option.to_sym)

  @show_blanks = option
end

#show_hidden_data ⇒ Object

Display data in hidden rows or columns on the chart.



392
393
394
 
# File 'lib/write_xlsx/chart.rb', line 392

def show_hidden_data
  @show_hidden_data = true
end

#show_na_as_empty_cell ⇒ Object

Set the option for displaying #N/A as an empty cell in a chart.



574
575
576
 
# File 'lib/write_xlsx/chart.rb', line 574

def show_na_as_empty_cell
  @show_na_as_empty = true
end

#write_bar_chart(params) ⇒ Object

Write the <c:barChart> element.



471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/write_xlsx/chart.rb', line 471

def write_bar_chart(params)   # :nodoc:
  series = if ptrue?(params[:primary_axes])
             get_primary_axes_series
           else
             get_secondary_axes_series
           end
  return if series.empty?

  subtype = @subtype
  subtype = 'percentStacked' if subtype == 'percent_stacked'

  # Set a default overlap for stacked charts.
  @series_overlap_1 = 100 if @subtype =~ (/stacked/) && !@series_overlap_1

  @writer.tag_elements('c:barChart') do
    # Write the c:barDir element.
    write_bar_dir
    # Write the c:grouping element.
    write_grouping(subtype)
    # Write the c:ser elements.
    series.each { |s| write_ser(s) }

    # write the c:marker element.
    write_marker_value

    if ptrue?(params[:primary_axes])
      # Write the c:gapWidth element.
      write_gap_width(@series_gap_1)
      # Write the c:overlap element.
      write_overlap(@series_overlap_1)
    else
      # Write the c:gapWidth element.
      write_gap_width(@series_gap_2)
      # Write the c:overlap element.
      write_overlap(@series_overlap_2)
    end

    # write the c:overlap element.
    write_overlap(@series_overlap)

    # Write the c:axId elements
    write_axis_ids(params)
  end
end

#write_val_axis(x_axis, y_axis, axis_ids, position = nil) ⇒ Object

Write the <c:valAx> element. Usually the Y axis.



1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
 
# File 'lib/write_xlsx/chart.rb', line 1295

def write_val_axis(x_axis, y_axis, axis_ids, position = nil)
  return unless axis_ids && !axis_ids.empty?

  write_val_axis_base(
    x_axis, y_axis,
    axis_ids[0],
    axis_ids[1],
    y_axis.position || position || @val_axis_position
  )
end