gruff 0.30.0 → 0.32.0

data/lib/gruff/base.rb

@@ -23,7 +23,7 @@ module Gruff
   # A common base class inherited from class of drawing a graph.
   class Base
     # Space around text elements. Mostly used for vertical spacing.
-    LEGEND_MARGIN = 20.0
+    LEGEND_MARGIN = 10.0
     TITLE_MARGIN = 20.0
     LABEL_MARGIN = 15.0
     DEFAULT_MARGIN = 20.0
@@ -48,9 +48,6 @@ module Gruff
     # Blank space below the title. Default is +20+.
     attr_writer :title_margin #: Float | Integer
 
-    # Blank space below the legend. Default is +20+.
-    attr_writer :legend_margin #: Float | Integer
-
     # Truncates labels if longer than max specified.
     attr_writer :label_max_size #: Float | Integer
 
@@ -115,13 +112,16 @@ module Gruff
     # first. This does not affect the legend. Default is +false+.
     attr_writer :sorted_drawing #: bool
 
-    # Display the legend under the graph. Default is +false+.
-    attr_writer :legend_at_bottom #: bool
+    # Blank space below the legend. Default is +20+.
+    attr_writer :legend_margin #: Float | Integer
 
-    # Optionally set the size of the colored box by each item in the legend.
-    # Default is +20.0+.
-    #
-    # Will be scaled down if graph is smaller than 800px wide.
+    # Set the vertical spacing between individual legend items. Default is +5.0+.
+    attr_writer :legend_spacing #: Float | Integer
+
+    # Set the inner padding between the legend frame and its contents. Default is +7.0+.
+    attr_writer :legend_padding #: Float | Integer
+
+    # Optionally set the size of the colored box by each item in the legend. Default is +20.0+.
     attr_writer :legend_box_size #: Float | Integer
 
     # If one numerical argument is given, the graph is drawn at 4/3 ratio
@@ -154,6 +154,7 @@ module Gruff
       self.theme = Themes::KEYNOTE
     end
 
+    # @rbs return: void
     def initialize_graph_scale
       @raw_columns = DEFAULT_TARGET_WIDTH
       @raw_rows = DEFAULT_TARGET_WIDTH * (@rows / @columns)
@@ -165,6 +166,7 @@ module Gruff
     end
     protected :initialize_graph_scale
 
+    # @rbs return: void
     def initialize_store
       @store = Gruff::Store.new(Gruff::Store::BasicData)
     end
@@ -176,6 +178,8 @@ module Gruff
     #
     # This makes it possible to set defaults in a subclass but still allow
     # developers to change this values in their program.
+    #
+    # @rbs return: void
     def initialize_attributes
       @marker_count = nil
       @maximum_value = @minimum_value = nil
@@ -186,19 +190,22 @@ module Gruff
 
       @title_font = Gruff::Font.new(size: 36.0, bold: true)
       @marker_font = Gruff::Font.new(size: 21.0)
-      @legend_font = Gruff::Font.new(size: 20.0)
+      @legend_font = Gruff::Font.new(size: 12.0)
       @no_data_font = Gruff::Font.new(size: 80.0)
 
       @label_margin = LABEL_MARGIN
       @top_margin = @bottom_margin = @left_margin = @right_margin = DEFAULT_MARGIN
-      @legend_margin = LEGEND_MARGIN
       @title_margin = TITLE_MARGIN
 
-      @legend_box_size = 20.0
+      @legend_margin = LEGEND_MARGIN
+      @legend_spacing = 5.0
+      @legend_padding = 7.0
+      @legend_box_size = 10.0
+      @legend_position = :top_right
 
       @no_data_message = 'No Data'
 
-      @hide_line_markers = @hide_legend = @hide_title = @hide_line_numbers = @legend_at_bottom = false
+      @hide_line_markers = @hide_legend = @hide_title = @hide_line_numbers = false
       @label_max_size = 0
       @label_truncation_style = :absolute
       @label_rotation = 0
@@ -228,6 +235,7 @@ module Gruff
     #   g = Gruff::Bar.new
     #   g.labels = ['2005', nil, nil, '2006', nil, nil, '2007', nil, nil, '2008'] # same labels for columns
     #
+    # @rbs return: void
     def labels=(labels)
       if labels.is_a?(Array)
         labels = labels.each_with_index.with_object({}) do |(label, index), hash|
@@ -243,18 +251,41 @@ module Gruff
     #
     # @param rotation [Numeric] the rotation.
     # @rbs rotation: Float | Integer
+    # @rbs return: void
     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
 
+    # Set the corner position of the floating legend. Accepts +:top_right+ (default),
+    # +:top_left+, +:bottom_right+, or +:bottom_left+.
+    #
+    # @param position [Symbol] the position.
+    # @rbs position: Symbol
+    # @rbs return: void
+    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
+
     # Height of staggering between labels.
     # @deprecated
+    # @rbs return: void
     def label_stagger_height=(_value)
       warn '#label_stagger_height= is deprecated. It is no longer effective.'
     end
 
+    # Set the legend position to the bottom of the graph.
+    # @deprecated
+    # @rbs return: void
+    def legend_at_bottom=(_value)
+      warn '#legend_at_bottom= is deprecated. It is no longer effective.'
+    end
+
     # 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.
@@ -269,6 +300,7 @@ module Gruff
     #   g = Gruff::Bar.new
     #   g.title = ['The first line of title', 'The second line of title']
     #
+    # @rbs return: void
     def title=(title)
       if title.is_a?(Array)
         title = title.join("\n")
@@ -281,6 +313,7 @@ module Gruff
     #
     # @param margin [Numeric] The margin size.
     # @rbs margin: Float | Integer
+    # @rbs return: void
     def margins=(margin)
       @top_margin = @left_margin = @right_margin = @bottom_margin = margin
     end
@@ -289,6 +322,7 @@ module Gruff
     #
     # @param font_path [String] The path to font.
     # @rbs font_path: String
+    # @rbs return: void
     def font=(font_path)
       @title_font.path = font_path unless @title_font.path
       @marker_font.path = font_path
@@ -300,6 +334,7 @@ module Gruff
     #
     # @param font_path [String] The path to font.
     # @rbs font_path: String
+    # @rbs return: void
     def title_font=(font_path)
       @title_font.path = font_path
     end
@@ -308,6 +343,7 @@ module Gruff
     #
     # @param value [Numeric] title font size
     # @rbs value: Float | Integer
+    # @rbs return: void
     def title_font_size=(value)
       @title_font.size = value
     end
@@ -316,6 +352,7 @@ module Gruff
     #
     # @param value [Numeric] marker font size
     # @rbs value: Float | Integer
+    # @rbs return: void
     def marker_font_size=(value)
       @marker_font.size = value
     end
@@ -327,6 +364,7 @@ module Gruff
     #
     # @param value [Numeric] legend font size
     # @rbs value: Float | Integer
+    # @rbs return: void
     def legend_font_size=(value)
       @legend_font.size = value
     end
@@ -335,6 +373,7 @@ module Gruff
     #
     # @param value [Numeric] no data font size
     # @rbs value: Float | Integer
+    # @rbs return: void
     def no_data_font_size=(value)
       @no_data_font.size = value
     end
@@ -343,6 +382,7 @@ module Gruff
     #
     # @param value [Boolean] specifies whether to draw the title bolded or not.
     # @rbs value: bool
+    # @rbs return: void
     def bold_title=(value)
       @title_font.bold = value
     end
@@ -351,6 +391,7 @@ module Gruff
     #
     # @param value [String] color
     # @rbs value: String
+    # @rbs return: void
     def font_color=(value)
       @title_font.color = value
       @marker_font.color = value
@@ -365,6 +406,7 @@ module Gruff
     #
     # @example
     #   add_color('#c0e9d3')
+    # @rbs return: void
     def add_color(colorname)
       @colors << colorname
     end
@@ -385,6 +427,7 @@ module Gruff
     #
     # @example
     #   replace_colors ['#cc99cc', '#d9e043', '#34d8a2']
+    # @rbs return: void
     def replace_colors(color_list = [])
       @colors = color_list
     end
@@ -393,6 +436,7 @@ module Gruff
     #
     # @param value [Boolean] Specify whether to make background transparent.
     # @rbs value: bool
+    # @rbs return: void
     def transparent_background=(value)
       @renderer.transparent_background(@columns, @rows) if value
     end
@@ -428,6 +472,7 @@ module Gruff
     #
     # @param options [Hash] The optional setting for theme
     # @rbs options: Hash[Symbol, untyped]
+    # @rbs return: void
     def theme=(options)
       reset_themes
 
@@ -451,31 +496,37 @@ module Gruff
     end
 
     # Apply Apple's keynote theme.
+    # @rbs return: void
     def theme_keynote
       self.theme = Themes::KEYNOTE
     end
 
     # Apply 37signals theme.
+    # @rbs return: void
     def theme_37signals
       self.theme = Themes::THIRTYSEVEN_SIGNALS
     end
 
     # Apply Rails theme.
+    # @rbs return: void
     def theme_rails_keynote
       self.theme = Themes::RAILS_KEYNOTE
     end
 
     # Apply Odeo theme.
+    # @rbs return: void
     def theme_odeo
       self.theme = Themes::ODEO
     end
 
     # Apply pastel theme.
+    # @rbs return: void
     def theme_pastel
       self.theme = Themes::PASTEL
     end
 
     # Apply greyscale theme.
+    # @rbs return: void
     def theme_greyscale
       self.theme = Themes::GREYSCALE
     end
@@ -503,6 +554,7 @@ module Gruff
     #
     # @example
     #   data("Bart S.", [95, 45, 78, 89, 88, 76], '#ffcc00')
+    # @rbs return: void
     def data(name, data_points = [], color = nil)
       store.add(name, data_points, color)
     end
@@ -540,6 +592,7 @@ module Gruff
     #
     # @example
     #   write('graphs/my_pretty_graph.png')
+    # @rbs return: void
     def write(file_name = 'graph.png')
       to_image.write(file_name)
     end
@@ -561,6 +614,7 @@ module Gruff
     #   image = image.resize(400, 300).quantize(128, Magick::RGBColorspace)
     #   image.write('test.png')
     #
+    # @rbs return: untyped
     def to_image(format = 'PNG')
       @to_image ||= begin
         draw
@@ -587,6 +641,7 @@ module Gruff
     end
 
     # Draw a graph.
+    # @rbs return: void
     def draw
       setup_data
 
@@ -598,11 +653,11 @@ module Gruff
 
       setup_drawing
 
-      draw_legend
       draw_line_markers
       draw_axis_labels
       draw_title
       draw_graph
+      draw_legend
     end
 
   protected
@@ -610,6 +665,7 @@ module Gruff
     attr_reader :renderer #: Gruff::Renderer
 
     # Perform data manipulation before calculating chart measurements
+    # @rbs return: void
     def setup_data
       if @y_axis_increment && !@hide_line_markers
         self.maximum_value = [@y_axis_increment, maximum_value, (maximum_value / @y_axis_increment).round * @y_axis_increment].max
@@ -624,6 +680,7 @@ module Gruff
     # * line markers
     # * legend
     # * title
+    # @rbs return: void
     def setup_drawing
       calculate_spread
       calculate_increment
@@ -666,10 +723,12 @@ module Gruff
 
     # Make copy of data with values scaled between 0-100
     # @rbs return: Array[Gruff::Store::BasicData | Gruff::Store::XYData | Gruff::Store::XYPointsizeData]
+    # @rbs return: void
     def normalize
       store.normalize(minimum: minimum_value, spread: @spread)
     end
 
+    # @rbs return: Float
     def calculate_spread
       @spread = maximum_value.to_f - minimum_value.to_f
       @spread = @spread > 0 ? @spread : 1.0
@@ -698,6 +757,7 @@ module Gruff
     ##
     # Calculates size of drawable area, general font dimensions, etc.
 
+    # @rbs return: void
     def setup_graph_measurements
       @graph_right = setup_right_margin
       @graph_left = setup_left_margin
@@ -709,6 +769,7 @@ module Gruff
     end
 
     # Draw the optional labels for the x axis and y axis.
+    # @rbs return: void
     def draw_axis_labels
       if @x_axis_label
         # X Axis
@@ -728,6 +789,7 @@ module Gruff
     end
 
     # Draws horizontal background lines and labels
+    # @rbs return: void
     def draw_line_markers
       return if @hide_line_markers
 
@@ -747,11 +809,16 @@ module Gruff
       end
     end
 
+    # @rbs y: Float | Integer
+    # @rbs return: void
     def draw_marker_horizontal_line(y)
       Gruff::Renderer::Line.new(renderer, color: @marker_color).render(@graph_left, y, @graph_right, y)
       Gruff::Renderer::Line.new(renderer, color: @marker_shadow_color).render(@graph_left, y + 1, @graph_right, y + 1) if @marker_shadow_color
     end
 
+    # @rbs x: Float | Integer
+    # @rbs tick_mark_mode: bool
+    # @rbs return: void
     def draw_marker_vertical_line(x, tick_mark_mode: false)
       if tick_mark_mode
         Gruff::Renderer::Line.new(renderer, color: @marker_color).render(x, @graph_bottom, x, @graph_bottom + 5)
@@ -775,55 +842,68 @@ module Gruff
 
     # Draws a legend with the names of the datasets matched
     # to the colors used to draw them.
+    # @rbs return: void
     def draw_legend
       return if @hide_legend
 
-      legend_labels = store.data.map(&:label)
-      legend_square_width = @legend_box_size # small square with color of this item
-      legend_label_lines = calculate_legend_label_widths_for_each_line(legend_labels, legend_square_width)
-      line_height = [legend_caps_height, legend_square_width].max + @legend_margin
-
-      current_y_offset = begin
-        if @legend_at_bottom
-          @graph_bottom + @legend_margin + labels_caps_height + @label_margin + (@x_axis_label ? (@label_margin * 2) + marker_caps_height : 0)
-        else
-          hide_title? ? @top_margin + @title_margin : @top_margin + @title_margin + title_caps_height
-        end
+      legend_labels = store.data.map(&:label).reject(&:empty?)
+      return if legend_labels.empty?
+
+      line_height = [legend_caps_height, @legend_box_size].max + @legend_spacing
+      max_legend_label_width = legend_labels.map { |l| calculate_width(@legend_font, l) }.max || 0.0
+
+      legend_content_width  = (@legend_box_size * 1.5) + max_legend_label_width
+      legend_content_height = (line_height * (legend_labels.size - 1)) + @legend_box_size
+
+      case @legend_position
+      when :top_left
+        current_x_offset = @graph_left + @legend_margin
+        current_y_offset = @graph_top  + @legend_margin + @legend_spacing
+      when :bottom_right
+        current_x_offset = @graph_right  - @legend_margin - legend_content_width
+        current_y_offset = @graph_bottom - @legend_margin - legend_content_height
+      when :bottom_left
+        current_x_offset = @graph_left + @legend_margin
+        current_y_offset = @graph_bottom - @legend_margin - legend_content_height
+      else # :top_right (default)
+        current_x_offset = @graph_right - @legend_margin - legend_content_width
+        current_y_offset = @graph_top + @legend_margin + @legend_spacing
       end
 
-      index = 0
-      legend_label_lines.each do |(legend_labels_width, legend_labels_line)|
-        current_x_offset = center(legend_labels_width)
-
-        legend_labels_line.each do |legend_label|
-          unless legend_label.empty?
-            legend_label_width = calculate_width(@legend_font, legend_label)
-
-            # Draw label
-            text_renderer = Gruff::Renderer::Text.new(renderer, legend_label, font: @legend_font)
-            text_renderer.add_to_render_queue(legend_label_width,
-                                              legend_square_width,
-                                              current_x_offset + (legend_square_width * 1.7),
-                                              current_y_offset,
-                                              Magick::CenterGravity)
-
-            # Now draw box with color of this dataset
-            rect_renderer = Gruff::Renderer::Rectangle.new(renderer, color: store.data[index].color)
-            rect_renderer.render(current_x_offset,
-                                 current_y_offset,
-                                 current_x_offset + legend_square_width,
-                                 current_y_offset + legend_square_width)
-
-            current_x_offset += legend_label_width + (legend_square_width * 2.7)
-          end
-          index += 1
-        end
+      legend_items_end_x = current_x_offset + legend_content_width
+      legend_items_end_y = current_y_offset + legend_content_height
+
+      frame_renderer = Gruff::Renderer::Rectangle.new(renderer, color: @marker_color, width: 1.1, opacity: 0.2, round: true)
+      frame_renderer.render(current_x_offset - @legend_padding,
+                            current_y_offset - @legend_padding,
+                            legend_items_end_x + @legend_padding,
+                            legend_items_end_y + @legend_padding)
+
+      store.data.each do |data_row|
+        legend_label = data_row.label
+        next if legend_label.empty?
+
+        legend_label_width = calculate_width(@legend_font, legend_label)
+
+        text_renderer = Gruff::Renderer::Text.new(renderer, legend_label, font: @legend_font)
+        text_renderer.add_to_render_queue(legend_label_width,
+                                          @legend_box_size,
+                                          current_x_offset + (@legend_box_size * 1.5),
+                                          current_y_offset,
+                                          Magick::CenterGravity)
+
+        rect_renderer = Gruff::Renderer::Rectangle.new(renderer, color: data_row.color)
+        rect_renderer.render(current_x_offset,
+                             current_y_offset,
+                             current_x_offset + @legend_box_size,
+                             current_y_offset + @legend_box_size)
 
         current_y_offset += line_height
       end
     end
 
     # Draws a title on the graph.
+    # @rbs return: void
     def draw_title
       return if hide_title?
 
@@ -842,6 +922,7 @@ module Gruff
     # @rbs index: Integer
     # @rbs gravity: untyped
     # @rbs &: () -> void
+    # @rbs return: void
     def draw_label(x, index, gravity = Magick::NorthGravity, &block)
       draw_unique_label(index) do
         if x.between?(@graph_left, @graph_right)
@@ -856,6 +937,7 @@ module Gruff
 
     # @rbs index: Integer
     # @rbs yields: () -> void
+    # @rbs return: void
     def draw_unique_label(index)
       return if hide_labels?
 
@@ -873,6 +955,7 @@ module Gruff
     # @rbs text: String | _ToS
     # @rbs gravity: untyped
     # @rbs rotation: Float | Integer
+    # @rbs return: void
     def draw_label_at(width, height, x, y, text, gravity: Magick::NorthGravity, rotation: 0)
       label_text = truncate_label_text(text)
       text_renderer = Gruff::Renderer::Text.new(renderer, label_text, font: @marker_font, rotation: rotation)
@@ -887,6 +970,7 @@ module Gruff
     # @rbs y_offset: Float | Integer
     # @rbs data_point: String | _ToS
     # @rbs gravity: untyped
+    # @rbs return: void
     def draw_value_label(width, height, x_offset, y_offset, data_point, gravity: Magick::CenterGravity)
       return if @hide_line_markers
 
@@ -894,17 +978,20 @@ module Gruff
     end
 
     # Shows an error message because you have no data.
+    # @rbs return: void
     def draw_no_data
       font = @no_data_font
       text_renderer = Gruff::Renderer::Text.new(renderer, @no_data_message, font: font)
       text_renderer.render(@raw_columns, @raw_rows, 0, 0, Magick::CenterGravity)
     end
 
+    # @rbs return: void
     def draw_graph
       raise 'Should implement this method at inherited class.'
     end
 
     # Resets everything to defaults (except data).
+    # @rbs return: void
     def reset_themes
       @theme_options = {}
     end
@@ -945,17 +1032,20 @@ module Gruff
     end
 
     # Sort with largest overall summed value at front of array.
+    # @rbs return: void
     def sort_data
       store.sort_data!
     end
 
     # Set the color for each data set unless it was given in the data(...) call.
+    # @rbs return: void
     def set_colors
       store.change_colors(@colors)
     end
 
     # Sort with largest overall summed value at front of array so it shows up
     # correctly in the drawn graph.
+    # @rbs return: void
     def sort_norm_data
       store.sort_norm_data!
     end
@@ -1068,14 +1158,12 @@ module Gruff
       # When @hide title, leave a title_margin space for aesthetics.
       # Same with @hide_legend
       @top_margin +
-        (hide_title? ? @title_margin : title_caps_height + @title_margin) +
-        (@hide_legend || @legend_at_bottom ? @legend_margin : calculate_legend_height + @legend_margin)
+        (hide_title? ? @title_margin : title_caps_height + @title_margin)
     end
 
     # @rbs return: Float
     def setup_bottom_margin
       graph_bottom_margin = hide_bottom_label_area? ? @bottom_margin : @bottom_margin + labels_caps_height + @label_margin
-      graph_bottom_margin += (calculate_legend_height + @legend_margin) if @legend_at_bottom
 
       x_axis_label_height = @x_axis_label.nil? ? 0.0 : marker_caps_height + (@label_margin * 2)
       @raw_rows - graph_bottom_margin - x_axis_label_height
@@ -1156,40 +1244,6 @@ module Gruff
       end
     end
 
-    # TODO: RBS signature
-    def calculate_legend_label_widths_for_each_line(legend_labels, legend_square_width)
-      label_widths = [[]]
-      label_lines = [[]]
-      legend_labels.each do |label|
-        if label.empty?
-          label_width = 0.0
-        else
-          width = calculate_width(@legend_font, label)
-          label_width = width + (legend_square_width * 2.7)
-        end
-        label_widths.last.push label_width
-        label_lines.last.push label
-
-        if label_widths.last.sum > (@raw_columns * 0.9)
-          label_widths.push [label_widths.last.pop]
-          label_lines.push [label_lines.last.pop]
-        end
-      end
-
-      label_widths.map(&:sum).zip(label_lines)
-    end
-
-    # TODO: RBS signature
-    def calculate_legend_height
-      return 0.0 if @hide_legend
-
-      legend_labels = store.data.map(&:label)
-      legend_label_lines = calculate_legend_label_widths_for_each_line(legend_labels, @legend_box_size)
-      line_height = [legend_caps_height, @legend_box_size].max
-
-      (line_height * legend_label_lines.count) + (@legend_margin * (legend_label_lines.count - 1))
-    end
-
     # Returns the height of the capital letter 'X' for the current font and
     # size.
     #

data/lib/gruff/bezier.rb

@@ -23,6 +23,7 @@
 class Gruff::Bezier < Gruff::Base
 private
 
+  # @rbs return: void
   def draw_graph
     x_increment = (@graph_width / (column_count - 1)).to_f
 

data/lib/gruff/box.rb

@@ -26,6 +26,7 @@ class Gruff::Box < Gruff::Base
   # Default value is +0.8+.
   #
   # @rbs space_percent: Float | Integer
+  # @rbs return: void
   def spacing_factor=(space_percent)
     raise ArgumentError, 'spacing_factor must be between 0.00 and 1.00' if (space_percent < 0) || (space_percent > 1)
 
@@ -34,6 +35,7 @@ class Gruff::Box < Gruff::Base
 
 private
 
+  # @rbs return: void
   def initialize_attributes
     super
     @fill_opacity = 0.2
@@ -41,6 +43,7 @@ private
     @spacing_factor = 0.8
   end
 
+  # @rbs return: void
   def draw_graph
     # Setup the BarConversion Object
     conversion = Gruff::BarConversion.new(
@@ -93,6 +96,7 @@ private
     end
   end
 
+  # @rbs return: Array[Gruff::Box::BoxData]
   def normalized_boxes
     @normalized_boxes ||= store.norm_data.map { |data| Gruff::Box::BoxData.new(data.label, data.points, data.color) }
   end
@@ -113,6 +117,10 @@ private
     attr_accessor :points #: Array[Float | Integer]
     attr_accessor :color #: String
 
+    # @rbs label: String
+    # @rbs points: Array[Float | Integer]
+    # @rbs color: String
+    # @rbs return: void
     def initialize(label, points, color)
       @label = label
       @points = points.compact.sort