Class: Gruff::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/gruff/base.rb

Overview

A common base class inherited from class of drawing a graph.

Constant Summary collapse

LEGEND_MARGIN =

Space around text elements. Mostly used for vertical spacing.

10.0
TITLE_MARGIN = 
20.0
LABEL_MARGIN = 
15.0
DEFAULT_MARGIN = 
20.0
DEFAULT_TARGET_WIDTH = 
800.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target_width = DEFAULT_TARGET_WIDTH) ⇒ Base

If one numerical argument is given, the graph is drawn at 4/3 ratio according to the given width (800 results in 800x600, 400 gives 400x300, etc.).

Or, send a geometry string for other ratios ( ‘800x400’, ‘400x225’).

Parameters:

  • target_width (Numeric, String) (defaults to: DEFAULT_TARGET_WIDTH) —

    The graph image width.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/gruff/base.rb', line 137

def initialize(target_width = DEFAULT_TARGET_WIDTH)
  if target_width.is_a?(String)
    @columns, @rows = target_width.split('x').map(&:to_f)
  else
    @columns = target_width.to_f
    @rows = target_width.to_f * 0.75
  end
  @columns.freeze
  @rows.freeze

  @has_left_labels = false
  @center_labels_over_point = true

  initialize_graph_scale
  initialize_attributes
  initialize_store

  self.theme = Themes::KEYNOTE
end

Instance Attribute Details

#bottom_margin=(value) ⇒ Object (writeonly)

Blank space below the graph. Default is 20.



40
41
42
 
# File 'lib/gruff/base.rb', line 40

def bottom_margin=(value)
  @bottom_margin = value
end

#colors ⇒ Object

Get or set the list of colors that will be used to draw the bars or lines.



80
81
82
 
# File 'lib/gruff/base.rb', line 80

def colors
  @colors
end

#hide_legend=(value) ⇒ Object (writeonly)

Prevent drawing of the legend. Default is false.



86
87
88
 
# File 'lib/gruff/base.rb', line 86

def hide_legend=(value)
  @hide_legend = value
end

#hide_line_markers=(value) ⇒ Object (writeonly)

Prevent drawing of line markers. Default is false.



83
84
85
 
# File 'lib/gruff/base.rb', line 83

def hide_line_markers=(value)
  @hide_line_markers = value
end

#hide_line_numbers=(value) ⇒ Object (writeonly)

Prevent drawing of line numbers. Default is false.



92
93
94
 
# File 'lib/gruff/base.rb', line 92

def hide_line_numbers=(value)
  @hide_line_numbers = value
end

#hide_title=(value) ⇒ Object (writeonly)

Prevent drawing of the title. Default is false.



89
90
91
 
# File 'lib/gruff/base.rb', line 89

def hide_title=(value)
  @hide_title = value
end

#label_margin=(value) ⇒ Object (writeonly)

Blank space between graph and labels. Default is 15.



34
35
36
 
# File 'lib/gruff/base.rb', line 34

def label_margin=(value)
  @label_margin = value
end

#label_max_size=(value) ⇒ Object (writeonly)

Truncates labels if longer than max specified.



52
53
54
 
# File 'lib/gruff/base.rb', line 52

def label_max_size=(value)
  @label_max_size = value
end

#label_truncation_style=(value) ⇒ Object (writeonly)

How truncated labels visually appear if they exceed #label_max_size=.

  • :absolute - does not show trailing dots to indicate truncation. This is the default.

  • :trailing_dots - shows trailing dots to indicate truncation (note that #label_max_size= must be greater than 3).



59
60
61
 
# File 'lib/gruff/base.rb', line 59

def label_truncation_style=(value)
  @label_truncation_style = value
end

#left_margin=(value) ⇒ Object (writeonly)

Blank space to the left of the graph. Default is 20.



46
47
48
 
# File 'lib/gruff/base.rb', line 46

def left_margin=(value)
  @left_margin = value
end

#legend_box_size=(value) ⇒ Object (writeonly)

Optionally set the size of the colored box by each item in the legend. Default is 20.0.



125
126
127
 
# File 'lib/gruff/base.rb', line 125

def legend_box_size=(value)
  @legend_box_size = value
end

#legend_margin=(value) ⇒ Object (writeonly)

Blank space below the legend. Default is 20.



116
117
118
 
# File 'lib/gruff/base.rb', line 116

def legend_margin=(value)
  @legend_margin = value
end

#legend_padding=(value) ⇒ Object (writeonly)

Set the inner padding between the legend frame and its contents. Default is 7.0.



122
123
124
 
# File 'lib/gruff/base.rb', line 122

def legend_padding=(value)
  @legend_padding = value
end

#legend_spacing=(value) ⇒ Object (writeonly)

Set the vertical spacing between individual legend items. Default is 5.0.



119
120
121
 
# File 'lib/gruff/base.rb', line 119

def legend_spacing=(value)
  @legend_spacing = value
end

#marker_color=(value) ⇒ Object (writeonly)

Set the color of the auxiliary lines.



99
100
101
 
# File 'lib/gruff/base.rb', line 99

def marker_color=(value)
  @marker_color = value
end

#marker_count=(value) ⇒ Object

Set the number of horizontal lines shown for reference.



105
106
107
 
# File 'lib/gruff/base.rb', line 105

def marker_count=(value)
  @marker_count = value
end

#marker_shadow_color=(value) ⇒ Object (writeonly)

Set the shadow color of the auxiliary lines.



102
103
104
 
# File 'lib/gruff/base.rb', line 102

def marker_shadow_color=(value)
  @marker_shadow_color = value
end

#maximum_value ⇒ Float

You can manually set a maximum value, such as a percentage-based graph that always goes to 100.

If you use this, you must set it after you have given all your data to the graph object.

Returns:

  • (Float) —

    The maximum value.



583
584
585
 
# File 'lib/gruff/base.rb', line 583

def maximum_value
  (@maximum_value || store.max).to_f
end

#minimum_value ⇒ Float

You can manually set a minimum value instead of having the values guessed for you.

Set it after you have given all your data to the graph object.

Returns:

  • (Float) —

    The minimum value.



569
570
571
572
 
# File 'lib/gruff/base.rb', line 569

def minimum_value
  min = [0.0, store.min.to_f].min
  (@minimum_value || min).to_f
end

#no_data_message=(value) ⇒ Object (writeonly)

Set a message shown when there is no data. Fits up to 20 characters. Defaults to “No Data.”.



96
97
98
 
# File 'lib/gruff/base.rb', line 96

def no_data_message=(value)
  @no_data_message = value
end

#right_margin=(value) ⇒ Object (writeonly)

Blank space to the right of the graph. Default is 20.



43
44
45
 
# File 'lib/gruff/base.rb', line 43

def right_margin=(value)
  @right_margin = value
end

#sort=(value) ⇒ Object (writeonly)

Set to true if you want the data sets sorted with largest avg values drawn first. Default is false.



109
110
111
 
# File 'lib/gruff/base.rb', line 109

def sort=(value)
  @sort = value
end

#sorted_drawing=(value) ⇒ Object (writeonly)

Set to true if you want the data sets drawn with largest avg values drawn first. This does not affect the legend. Default is false.



113
114
115
 
# File 'lib/gruff/base.rb', line 113

def sorted_drawing=(value)
  @sorted_drawing = value
end

#title_margin=(value) ⇒ Object (writeonly)

Blank space below the title. Default is 20.



49
50
51
 
# File 'lib/gruff/base.rb', line 49

def title_margin=(value)
  @title_margin = value
end

#top_margin=(value) ⇒ Object (writeonly)

Blank space above the graph. Default is 20.



37
38
39
 
# File 'lib/gruff/base.rb', line 37

def top_margin=(value)
  @top_margin = value
end

#x_axis_increment=(value) ⇒ Object (writeonly)

Set increment of the vertical marking lines.



74
75
76
 
# File 'lib/gruff/base.rb', line 74

def x_axis_increment=(value)
  @x_axis_increment = value
end

#x_axis_label=(value) ⇒ Object

Set a label for the bottom of the graph.



62
63
64
 
# File 'lib/gruff/base.rb', line 62

def x_axis_label=(value)
  @x_axis_label = value
end

#x_axis_label_format=(value) ⇒ Object (writeonly)

Allow passing lambda to format labels for x axis.



68
69
70
 
# File 'lib/gruff/base.rb', line 68

def x_axis_label_format=(value)
  @x_axis_label_format = value
end

#y_axis_increment=(value) ⇒ Object (writeonly)

Set increment of the horizontal marking lines.



77
78
79
 
# File 'lib/gruff/base.rb', line 77

def y_axis_increment=(value)
  @y_axis_increment = value
end

#y_axis_label=(value) ⇒ Object

Set a label for the left side of the graph.



65
66
67
 
# File 'lib/gruff/base.rb', line 65

def y_axis_label=(value)
  @y_axis_label = value
end

#y_axis_label_format=(value) ⇒ Object (writeonly)

Allow passing lambda to format labels for y axis.



71
72
73
 
# File 'lib/gruff/base.rb', line 71

def y_axis_label_format=(value)
  @y_axis_label_format = value
end

Instance Method Details

#add_color(colorname) ⇒ Object

Add a color to the list of available colors for lines.

Examples:

add_color('#c0e9d3')

Parameters:

  • colorname (String) —

    The color.



410
411
412
 
# File 'lib/gruff/base.rb', line 410

def add_color(colorname)
  @colors << colorname
end

#bold_title=(value) ⇒ Object

Specifies whether to draw the title bolded or not. Default is true.

Parameters:

  • value (Boolean) —

    specifies whether to draw the title bolded or not.



386
387
388
 
# File 'lib/gruff/base.rb', line 386

def bold_title=(value)
  @title_font.bold = value
end

#data(name, data_points = [], color = nil) ⇒ Object

Note:

If you want to use a preset theme, you must set it before calling #data.

Input the data in the graph.

Parameters are an array where the first element is the name of the dataset and the value is an array of values to plot.

Can be called multiple times with different datasets for a multi-valued graph.

If the color argument is nil, the next color from the default theme will be used.

Examples:

data("Bart S.", [95, 45, 78, 89, 88, 76], '#ffcc00')

Parameters:

  • name (String, Symbol) —

    The name of the dataset.

  • data_points (Array) (defaults to: []) —

    The array of dataset.

  • color (String) (defaults to: nil) —

    The color for drawing graph of dataset.



558
559
560
 
# File 'lib/gruff/base.rb', line 558

def data(name, data_points = [], color = nil)
  store.add(name, data_points, color)
end

#draw ⇒ Object

Draw a graph.



645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/gruff/base.rb', line 645

def draw
  setup_data

  # Maybe should be done in one of the following functions for more granularity.
  unless data_given?
    draw_no_data
    return
  end

  setup_drawing

  draw_line_markers
  draw_axis_labels
  draw_title
  draw_graph
  draw_legend
end

#font=(font_path) ⇒ Object

Sets the font for graph text to the font at font_path.

Parameters:

  • font_path (String) —

    The path to font.



326
327
328
329
330
331
 
# File 'lib/gruff/base.rb', line 326

def font=(font_path)
  @title_font.path = font_path unless @title_font.path
  @marker_font.path = font_path
  @legend_font.path = font_path
  @no_data_font.path = font_path
end

#font_color=(value) ⇒ Object

Specifies the text color.

Parameters:

  • value (String) —

    color



395
396
397
398
399
400
 
# File 'lib/gruff/base.rb', line 395

def font_color=(value)
  @title_font.color = value
  @marker_font.color = value
  @legend_font.color = value
  @no_data_font.color = value
end

#label_rotation=(rotation) ⇒ Object

Set a rotation for labels. You can use Default is 0. You can use a rotation between 0.0 and 45.0, or between 0.0 and -45.0.

Parameters:

  • rotation (Numeric) —

    the rotation.

Raises:

  • (ArgumentError) 


255
256
257
258
259
 
# File 'lib/gruff/base.rb', line 255

def label_rotation=(rotation)
  raise ArgumentError, 'rotation must be between 0.0 and 45.0 or between 0.0 and -45.0' if rotation > 45.0 || rotation < -45.0

  @label_rotation = rotation.to_f
end

#label_stagger_height=(_value) ⇒ Object

Deprecated.

Height of staggering between labels.



278
279
280
 
# File 'lib/gruff/base.rb', line 278

def label_stagger_height=(_value)
  warn '#label_stagger_height= is deprecated. It is no longer effective.'
end

#labels=(labels) ⇒ Object

A hash of names for the individual columns, where the key is the array index for the column this label represents. Not all columns need to be named with hash.

Or, an array corresponding to the data values.

Examples:

g = Gruff::Bar.new
g.labels = { 0 => '2005', 3 => '2006', 5 => '2007', 7 => '2008' }

g = Gruff::Bar.new
g.labels = ['2005', nil, nil, '2006', nil, nil, '2007', nil, nil, '2008'] # same labels for columns

Parameters:

  • labels (Hash, Array) —

    the labels.



239
240
241
242
243
244
245
246
247
 
# File 'lib/gruff/base.rb', line 239

def labels=(labels)
  if labels.is_a?(Array)
    labels = labels.each_with_index.with_object({}) do |(label, index), hash|
      hash[index] = label
    end
  end

  @labels = labels
end

#legend_at_bottom=(_value) ⇒ Object

Deprecated.

Set the legend position to the bottom of the graph.



285
286
287
 
# File 'lib/gruff/base.rb', line 285

def legend_at_bottom=(_value)
  warn '#legend_at_bottom= is deprecated. It is no longer effective.'
end

#legend_font_size=(value) ⇒ Object

Optionally set the size of the font. Based on an 800x600px graph. Default is 20.

Will be scaled down if the graph is smaller than 800px wide.

Parameters:

  • value (Numeric) —

    legend font size



368
369
370
 
# File 'lib/gruff/base.rb', line 368

def legend_font_size=(value)
  @legend_font.size = value
end

#legend_position=(position) ⇒ Object

Set the corner position of the floating legend. Accepts :top_right (default), :top_left, :bottom_right, or :bottom_left.

Parameters:

  • position (Symbol) —

    the position.



267
268
269
270
271
272
273
 
# File 'lib/gruff/base.rb', line 267

def legend_position=(position)
  unless %i[top_right top_left bottom_right bottom_left].include?(position)
    raise ArgumentError, 'Invalid legend position. Must be :top_right, :top_left, :bottom_right, or :bottom_left.'
  end

  @legend_position = position
end

#margins=(margin) ⇒ Object

Sets the top, bottom, left and right margins to margin.

Parameters:

  • margin (Numeric) —

    The margin size.



317
318
319
 
# File 'lib/gruff/base.rb', line 317

def margins=(margin)
  @top_margin = @left_margin = @right_margin = @bottom_margin = margin
end

#marker_font_size=(value) ⇒ Object

The font size of the labels around the graph. Default is 21.

Parameters:

  • value (Numeric) —

    marker font size



356
357
358
 
# File 'lib/gruff/base.rb', line 356

def marker_font_size=(value)
  @marker_font.size = value
end

#no_data_font_size=(value) ⇒ Object

Set the font size of the no data message. Default is 80.

Parameters:

  • value (Numeric) —

    no data font size



377
378
379
 
# File 'lib/gruff/base.rb', line 377

def no_data_font_size=(value)
  @no_data_font.size = value
end

#replace_colors(color_list = []) ⇒ Object

Replace the entire color list with a new array of colors. Also aliased as the #colors= setter method.

If you specify fewer colors than the number of datasets you intend to draw, it will cycle through the array, reusing colors as needed.

Note that (as with the #theme= method), you should set up your color list before you send your data (via the #data method). Calls to the #data method made prior to this call will use whatever color scheme was in place at the time data was called.

Examples:

replace_colors ['#cc99cc', '#d9e043', '#34d8a2']

Parameters:

  • color_list (Array) (defaults to: []) —

    The array of colors.



431
432
433
 
# File 'lib/gruff/base.rb', line 431

def replace_colors(color_list = [])
  @colors = color_list
end

#theme=(options) ⇒ Object

You can set a theme manually. Assign a hash to this method before you send your data.

g = Gruff::Bar.new
g.theme = {
  colors: %w(orange purple green white red),
  marker_color: 'blue',
  background_colors: ['black', 'grey'],
  background_direction: :top_bottom
}

background_colors

  • Array<String> format value - background has gradation. (ex. background_colors: [‘black’, ‘grey’])

  • String value - background has solid color. (ex. background_colors: ‘orange’)

  • nil - background has transparent. (ex. background_colors: nil)

background_image:

  • Specify the path to image file when it draw the image as background.

background_direction accepts one of following parameters.

  • :top_bottom

  • :bottom_top

  • :left_right

  • :right_left

  • :topleft_bottomright

  • :topright_bottomleft

(Or hopefully something better looking than that.)

Parameters:

  • options (Hash) —

    The optional setting for theme



476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
 
# File 'lib/gruff/base.rb', line 476

def theme=(options)
  reset_themes

  defaults = {
    colors: %w[black white],
    marker_color: 'white',
    marker_shadow_color: nil,
    font_color: 'black',
    background_colors: 'gray',
    background_image: nil
  }
  @theme_options = defaults.merge options

  self.marker_color = @theme_options[:marker_color]
  self.font_color = @theme_options[:font_color] || @marker_color

  @colors = @theme_options[:colors].dup
  @marker_shadow_color = @theme_options[:marker_shadow_color]

  @renderer = Gruff::Renderer.new(@columns, @rows, @scale, @theme_options)
end

#theme_37signals ⇒ Object

Apply 37signals theme.



506
507
508
 
# File 'lib/gruff/base.rb', line 506

def theme_37signals
  self.theme = Themes::THIRTYSEVEN_SIGNALS
end

#theme_greyscale ⇒ Object

Apply greyscale theme.



530
531
532
 
# File 'lib/gruff/base.rb', line 530

def theme_greyscale
  self.theme = Themes::GREYSCALE
end

#theme_keynote ⇒ Object

Apply Apple’s keynote theme.



500
501
502
 
# File 'lib/gruff/base.rb', line 500

def theme_keynote
  self.theme = Themes::KEYNOTE
end

#theme_odeo ⇒ Object

Apply Odeo theme.



518
519
520
 
# File 'lib/gruff/base.rb', line 518

def theme_odeo
  self.theme = Themes::ODEO
end

#theme_pastel ⇒ Object

Apply pastel theme.



524
525
526
 
# File 'lib/gruff/base.rb', line 524

def theme_pastel
  self.theme = Themes::PASTEL
end

#theme_rails_keynote ⇒ Object

Apply Rails theme.



512
513
514
 
# File 'lib/gruff/base.rb', line 512

def theme_rails_keynote
  self.theme = Themes::RAILS_KEYNOTE
end

#title=(title) ⇒ Object

Set the large title of the graph displayed at the top. You can draw a multi-line title by putting a line break in the string or by setting an array as argument.

Examples:

g = Gruff::Bar.new
g.title = "The graph title"

g = Gruff::Bar.new
g.title = ['The first line of title', 'The second line of title']

Parameters:

  • title (String, Array) —

    the title.



304
305
306
307
308
309
310
 
# File 'lib/gruff/base.rb', line 304

def title=(title)
  if title.is_a?(Array)
    title = title.join("\n")
  end

  @title = title
end

#title_font=(font_path) ⇒ Object

Same as #font= but for the title.

Parameters:

  • font_path (String) —

    The path to font.



338
339
340
 
# File 'lib/gruff/base.rb', line 338

def title_font=(font_path)
  @title_font.path = font_path
end

#title_font_size=(value) ⇒ Object

Set the font size of the large title at the top of the graph. Default is 36.

Parameters:

  • value (Numeric) —

    title font size



347
348
349
 
# File 'lib/gruff/base.rb', line 347

def title_font_size=(value)
  @title_font.size = value
end

#to_blob(format = 'PNG') ⇒ String

Deprecated.

Please use to_image.to_blob instead.

Return the graph as a rendered binary blob.

Parameters:

  • format (String) (defaults to: 'PNG') —

    The image format of binary blob.

Returns:

  • (String) —

    The binary string.



637
638
639
640
641
 
# File 'lib/gruff/base.rb', line 637

def to_blob(format = 'PNG')
  warn '#to_blob is deprecated. Please use `to_image.to_blob` instead'
  to_image.format = format
  to_image.to_blob
end

#to_image(format = 'PNG') ⇒ Magick::Image

Return a rendered graph image. This can use RMagick’s methods to adjust the image before saving.

TODO: RBS signature

Examples:

g = Gruff::Line.new
g.data :Jimmy, [25, 36, 86, 39, 25, 31, 79, 88]
g.data :Charles, [80, 54, 67, 54, 68, 70, 90, 95]
image = g.to_image
image = image.resize(400, 300).quantize(128, Magick::RGBColorspace)
image.write('test.png')

Parameters:

  • format (String) (defaults to: 'PNG') —

    The output image format.

Returns:

  • (Magick::Image) —

    The rendered image.



618
619
620
621
622
623
624
625
626
 
# File 'lib/gruff/base.rb', line 618

def to_image(format = 'PNG')
  @to_image ||= begin
    draw
    renderer.finish
    image = renderer.image
    image.format = format
    image
  end
end

#transparent_background=(value) ⇒ Object

Set whether to make background transparent.

Parameters:

  • value (Boolean) —

    Specify whether to make background transparent.



440
441
442
 
# File 'lib/gruff/base.rb', line 440

def transparent_background=(value)
  @renderer.transparent_background(@columns, @rows) if value
end

#write(file_name = 'graph.png') ⇒ Object

Writes the graph to a file. Defaults to ‘graph.png’

Examples:

write('graphs/my_pretty_graph.png')

Parameters:

  • file_name (String) (defaults to: 'graph.png') —

    The file name of output image.



596
597
598
 
# File 'lib/gruff/base.rb', line 596

def write(file_name = 'graph.png')
  to_image.write(file_name)
end