Class: Writexlsx::Chart

Inherits:
Object
  • Object
show all
Includes:
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/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, Line, Marker, Pie, Point, Radar, Scatter, Series, Stock, Trendline

Constant Summary

Constants included from Utility

Utility::COL_MAX, Utility::ROW_MAX, Utility::SHEETNAME_MAX, Utility::STR_MAX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utility

#absolute_char, #check_dimensions, #check_dimensions_and_update_max_min_values, #check_parameter, #convert_date_time, #dash_types, delete_files, #fill_properties, #float_to_str, #layout_properties, #line_fill_properties, #line_properties, #palette_color, #pixels_to_points, #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_anchor, #write_auto_fill, #write_color, #write_comment_path, #write_div, #write_fill, #write_font, #write_stroke, #write_xml_declaration, #xl_cell_to_rowcol, #xl_col_to_name, #xl_range, #xl_range_formula, #xl_rowcol_to_cell, #xml_str

Constructor Details

#initialize(subtype) ⇒ Chart

:nodoc:


194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
# File 'lib/write_xlsx/chart.rb', line 194

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)

Sets the attribute already_inserted


154
155
156
# File 'lib/write_xlsx/chart.rb', line 154

def already_inserted=(value)
  @already_inserted = value
end

#axis2_idsObject (readonly)

Returns the value of attribute axis2_ids


157
158
159
# File 'lib/write_xlsx/chart.rb', line 157

def axis2_ids
  @axis2_ids
end

#combinedObject (readonly)

:nodoc:


153
154
155
# File 'lib/write_xlsx/chart.rb', line 153

def combined
  @combined
end

#date_category=(value) ⇒ Object (writeonly)

Sets the attribute date_category


154
155
156
# File 'lib/write_xlsx/chart.rb', line 154

def date_category=(value)
  @date_category = value
end

#embeddedObject (readonly)

:nodoc:


150
151
152
# File 'lib/write_xlsx/chart.rb', line 150

def embedded
  @embedded
end

#formula_dataObject (readonly)

:nodoc:


150
151
152
# File 'lib/write_xlsx/chart.rb', line 150

def formula_data
  @formula_data
end

#formula_idsObject (readonly)

:nodoc:


150
151
152
# File 'lib/write_xlsx/chart.rb', line 150

def formula_ids
  @formula_ids
end

#heightObject (readonly)

:nodoc:


152
153
154
# File 'lib/write_xlsx/chart.rb', line 152

def height
  @height
end

#idObject

:nodoc:


148
149
150
# File 'lib/write_xlsx/chart.rb', line 148

def id
  @id
end

#index=(value) ⇒ Object (writeonly)

:nodoc:


149
150
151
# File 'lib/write_xlsx/chart.rb', line 149

def index=(value)
  @index = value
end

#label_position_defaultObject (readonly)

:nodoc:


153
154
155
# File 'lib/write_xlsx/chart.rb', line 153

def label_position_default
  @label_position_default
end

#label_positionsObject (readonly)

:nodoc:


153
154
155
# File 'lib/write_xlsx/chart.rb', line 153

def label_positions
  @label_positions
end

#nameObject

:nodoc:


148
149
150
# File 'lib/write_xlsx/chart.rb', line 148

def name
  @name
end

#palette=(value) ⇒ Object (writeonly)

:nodoc:


149
150
151
# File 'lib/write_xlsx/chart.rb', line 149

def palette=(value)
  @palette = value
end

#protection=(value) ⇒ Object (writeonly)

:nodoc:


149
150
151
# File 'lib/write_xlsx/chart.rb', line 149

def protection=(value)
  @protection = value
end

#series_index=(value) ⇒ Object (writeonly)

Sets the attribute series_index


155
156
157
# File 'lib/write_xlsx/chart.rb', line 155

def series_index=(value)
  @series_index = value
end

#widthObject (readonly)

:nodoc:


152
153
154
# File 'lib/write_xlsx/chart.rb', line 152

def width
  @width
end

#writer=(value) ⇒ Object (writeonly)

Sets the attribute writer


156
157
158
# File 'lib/write_xlsx/chart.rb', line 156

def writer=(value)
  @writer = value
end

#x2_axisObject (readonly)

Returns the value of attribute x2_axis


157
158
159
# File 'lib/write_xlsx/chart.rb', line 157

def x2_axis
  @x2_axis
end

#x_offsetObject (readonly)

:nodoc:


151
152
153
# File 'lib/write_xlsx/chart.rb', line 151

def x_offset
  @x_offset
end

#x_scaleObject (readonly)

:nodoc:


151
152
153
# File 'lib/write_xlsx/chart.rb', line 151

def x_scale
  @x_scale
end

#y2_axisObject (readonly)

Returns the value of attribute y2_axis


157
158
159
# File 'lib/write_xlsx/chart.rb', line 157

def y2_axis
  @y2_axis
end

#y_offsetObject (readonly)

:nodoc:


151
152
153
# File 'lib/write_xlsx/chart.rb', line 151

def y_offset
  @y_offset
end

#y_scaleObject (readonly)

:nodoc:


151
152
153
# File 'lib/write_xlsx/chart.rb', line 151

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.


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
# File 'lib/write_xlsx/chart.rb', line 162

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.


247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
# File 'lib/write_xlsx/chart.rb', line 247

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

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

  @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.
  if ptrue?(x2_axis) || ptrue?(y2_axis)
    @is_secondary = true
  end

  # 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


591
592
593
# File 'lib/write_xlsx/chart.rb', line 591

def already_inserted?
  @already_inserted
end

#assemble_xml_fileObject

Assemble and write the XML file.


224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
# File 'lib/write_xlsx/chart.rb', line 224

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.


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

def combine(chart)
  @combined = chart
end

#convert_font_args(params) ⇒ Object

Convert user defined font values into private hash values.


513
514
515
516
517
518
519
520
521
522
523
524
525
526
# File 'lib/write_xlsx/chart.rb', line 513

def convert_font_args(params)
  return unless params
  font = params_to_font(params)

  # Convert font size units.
  font[:_size] *= 100 if font[:_size] && font[:_size] != 0

  # Convert rotation into 60,000ths of a degree.
  if ptrue?(font[:_rotation])
    font[:_rotation] = 60_000 * font[:_rotation].to_i
  end

  font
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


569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
# File 'lib/write_xlsx/chart.rb', line 569

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


595
596
597
# File 'lib/write_xlsx/chart.rb', line 595

def is_secondary?
  @is_secondary
end

#params_to_font(params) ⇒ Object


528
529
530
531
532
533
534
535
536
537
538
539
540
541
# File 'lib/write_xlsx/chart.rb', line 528

def params_to_font(params)
  {
    :_name         => params[:name],
    :_color        => params[:color],
    :_size         => params[:size],
    :_bold         => params[:bold],
    :_italic       => params[:italic],
    :_underline    => params[:underline],
    :_pitch_family => params[:pitch_family],
    :_charset      => params[:charset],
    :_baseline     => params[:baseline] || 0,
    :_rotation     => params[:rotation]
  }
end

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

Switch name and name_formula parameters if required.


546
547
548
549
550
551
552
553
554
555
556
557
558
559
# File 'lib/write_xlsx/chart.rb', line 546

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.


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

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.


435
436
437
# File 'lib/write_xlsx/chart.rb', line 435

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

#set_embedded_config_dataObject

Setup the default configuration data for an embedded chart.


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

def set_embedded_config_data
  @embedded = 1
end

#set_high_low_lines(params = {}) ⇒ Object

Set properties for the chart high-low lines.


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

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

#set_legend(params) ⇒ Object

Set the properties of the chart legend.


332
333
334
335
336
337
338
339
340
341
342
343
# File 'lib/write_xlsx/chart.rb', line 332

def set_legend(params)
  if params[:none]
    @legend_position = 'none'
  else
    @legend_position = params[:position] || 'right'
  end
  @legend_delete_series = params[:delete_series]
  @legend_font          = convert_font_args(params[:font])

  # Set the legend layout.
  @legend_layout = layout_properties(params[:layout])
end

#set_plotarea(params) ⇒ Object

Set the properties of the chart plotarea.


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

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.


392
393
394
395
396
397
398
399
# File 'lib/write_xlsx/chart.rb', line 392

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.


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

def set_style(style_id = 2)
  style_id = 2 if style_id < 0 || 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.


408
409
410
# File 'lib/write_xlsx/chart.rb', line 408

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

#set_title(params) ⇒ Object

Set the properties of the chart title.


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

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

#set_up_down_bars(params = {}) ⇒ Object

Set properties for the chart up-down bars.


415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
# File 'lib/write_xlsx/chart.rb', line 415

def set_up_down_bars(params = {})
  # Map border to line.
  [: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.


309
310
311
312
# File 'lib/write_xlsx/chart.rb', line 309

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.


290
291
292
293
# File 'lib/write_xlsx/chart.rb', line 290

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:


217
218
219
# File 'lib/write_xlsx/chart.rb', line 217

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.


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

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,


301
302
303
304
# File 'lib/write_xlsx/chart.rb', line 301

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'.


372
373
374
375
376
377
378
379
380
# File 'lib/write_xlsx/chart.rb', line 372

def show_blanks_as(option)
  return unless option

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

  @show_blanks = option
end

#show_hidden_dataObject

Display data in hidden rows or columns on the chart.


385
386
387
# File 'lib/write_xlsx/chart.rb', line 385

def show_hidden_data
  @show_hidden_data = true
end

#write_bar_chart(params) ⇒ Object

Write the <c:barChart> element.


463
464
465
466
467
468
469
470
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
# File 'lib/write_xlsx/chart.rb', line 463

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

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

  # Set a default overlap for stacked charts.
  if @subtype =~ /stacked/
    @series_overlap_1 = 100 unless @series_overlap_1
  end

  @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.


1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
# File 'lib/write_xlsx/chart.rb', line 1307

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