whirled_peas 0.6.0 → 0.9.1

data/lib/whirled_peas/graphics/canvas.rb

@@ -4,28 +4,29 @@ module WhirledPeas
   module Graphics
     # Canvas represent the area of the screen a painter can paint on.
     class Canvas
-      attr_reader :left, :top, :width, :height, :start_left, :start_top
+      attr_reader :left, :top, :width, :height
 
       def self.unwritable
-        new(-1, -1, 0, 0, -1, -1)
+        new(-1, -1, 0, 0)
       end
 
-      def initialize(left, top, width, height, start_left, start_top)
+      def initialize(left, top, width, height)
         @left = left
         @top = top
         @width = width
         @height = height
-        @start_left = start_left
-        @start_top = start_top
       end
 
       def writable?
         width > 0 || height > 0
       end
 
-      def child(start_left, start_top, child_width, child_height)
-        child_left = start_left
-        child_top = start_top
+      def child(child_left, child_top, child_width, child_height)
+        Graphics.debugger(
+          proc do
+            "Create child: #{self.inspect}.child(left=#{child_left}, top=#{child_top}, width=#{child_width}, height=#{child_height})"
+          end
+        )
         if child_left >= left + width
           self.class.unwritable
         elsif child_left + child_width <= left
@@ -45,20 +46,25 @@ module WhirledPeas
             child_top = top
           end
           child_height = [height - (child_top - top), child_height].min
-          self.class.new(
+          child_canvas = self.class.new(
             child_left,
             child_top,
             child_width,
             child_height,
-            start_left,
-            start_top
           )
+          Graphics.debugger(proc { "  -> #{child_canvas.inspect}" })
+          child_canvas
         end
       end
 
       # Yields a single line of formatted characters positioned on the canvas,
       # verifying only characters within the canvas are included.
       def stroke(stroke_left, stroke_top, raw, formatting=[], &block)
+        Graphics.debugger(
+          proc do
+            "Stroke: #{self.inspect}.stroke(left=#{stroke_left}, top=#{stroke_top}, length=#{raw.length})"
+          end
+        )
         if stroke_left >= left + width
           # The stroke starts to the right of the canvas
           fstring = Utils::FormattedString.blank
@@ -88,6 +94,11 @@ module WhirledPeas
           end_index = start_index + visible_length - 1
           fstring = Utils::FormattedString.new(raw[start_index..end_index], formatting)
         end
+        Graphics.debugger(
+          proc do
+            "  -> Stroke(left=#{stroke_left}, top=#{stroke_top}, length=#{fstring.length})"
+          end
+        )
         yield stroke_left, stroke_top, fstring
       end
 

data/lib/whirled_peas/graphics/composer.rb

@@ -1,8 +1,10 @@
 require 'whirled_peas/settings/box_settings'
+require 'whirled_peas/settings/graph_settings'
 require 'whirled_peas/settings/grid_settings'
 require 'whirled_peas/settings/text_settings'
 
 require_relative 'box_painter'
+require_relative 'graph_painter'
 require_relative 'grid_painter'
 require_relative 'text_painter'
 
@@ -45,6 +47,7 @@ module WhirledPeas
         child = TextPainter.new(name, child_settings)
         # TextPainters are not composable, so yield nil
         content = yield nil, child_settings
+        child_settings.validate!
         unless self.class.stringable?(content)
           raise ArgumentError, "Unsupported type for text: #{content.class}"
         end
@@ -52,11 +55,25 @@ module WhirledPeas
         painter.add_child(child)
       end
 
+      def add_graph(name=self.class.next_name, &block)
+        child_settings = Settings::GraphSettings.inherit(painter.settings)
+        child = GraphPainter.new(name, child_settings)
+        # GraphPainters are not composable, so yield nil
+        content = yield nil, child_settings
+        child_settings.validate!
+        unless content.is_a?(Array) && content.length > 0
+          raise ArgumentError, 'Graphs require a non-empty array as the content'
+        end
+        child.content = content
+        painter.add_child(child)
+      end
+
       def add_box(name=self.class.next_name, &block)
         child_settings = Settings::BoxSettings.inherit(painter.settings)
         child = BoxPainter.new(name, child_settings)
         composer = self.class.new(child)
         value = yield composer, child.settings
+        child_settings.validate!
         painter.add_child(child)
         if !child.children? && self.class.stringable?(value)
           composer.add_text("#{name}-Text") { value.to_s }
@@ -68,6 +85,7 @@ module WhirledPeas
         child = GridPainter.new(name, child_settings)
         composer = self.class.new(child)
         values = yield composer, child.settings
+        child_settings.validate!
         painter.add_child(child)
         if !child.children? && values.is_a?(Array)
           values.each.with_index do |value, index|

data/lib/whirled_peas/graphics/container_coords.rb

@@ -1,18 +1,19 @@
 module WhirledPeas
   module Graphics
     class ContainerCoords
-      def initialize(canvas, dimensions, settings)
-        @canvas = canvas
+      def initialize(dimensions, settings, start_left, start_top)
         @dimensions = dimensions
         @settings = settings
+        @start_left = start_left
+        @start_top = start_top
       end
 
       def left
-        canvas.start_left + settings.position.left
+        start_left + settings.position.left
       end
 
       def top
-        canvas.start_top + settings.position.top
+        start_top + settings.position.top
       end
 
       def border_left
@@ -65,7 +66,7 @@ module WhirledPeas
 
       private
 
-      attr_reader :canvas, :settings, :dimensions
+      attr_reader :settings, :dimensions, :start_left, :start_top
     end
   end
 end

data/lib/whirled_peas/graphics/container_dimensions.rb

@@ -1,11 +1,11 @@
 module WhirledPeas
   module Graphics
     class ContainerDimensions
-      attr_reader :content_width, :content_height, :children_width, :children_height, :num_cols, :num_rows
+      attr_reader :children_width, :children_height, :num_cols, :num_rows
 
       def initialize(settings, content_width, content_height, num_cols=1, num_rows=1)
-        @content_width = settings.width || content_width
-        @content_height = settings.height || content_height
+        @orig_content_width = content_width
+        @orig_content_height = content_height
         @children_width = content_width
         @children_height = content_height
         @num_cols = num_cols
@@ -13,17 +13,35 @@ module WhirledPeas
         @settings = settings
       end
 
+      def content_width
+        return orig_content_width unless settings.width
+        if settings.border_sizing?
+          settings.width - outer_border_width - scrollbar_width - padding_width
+        else
+          settings.width
+        end
+      end
+
+      def content_height
+        return orig_content_height unless settings.height
+        if settings.border_sizing?
+          settings.height - outer_border_height - scrollbar_height - padding_height
+        else
+          settings.height
+        end
+      end
+
       def outer_width
         @outer_width ||= margin_width +
           outer_border_width +
-          num_cols * (padding_width + content_width + vert_scroll_width) +
+          num_cols * (padding_width + content_width + scrollbar_width) +
           (num_cols - 1) * inner_border_width
       end
 
       def outer_height
         @outer_height ||= margin_height +
           outer_border_height +
-          num_rows * (padding_height + content_height + horiz_scroll_height) +
+          num_rows * (padding_height + content_height + scrollbar_height) +
           (num_rows - 1) * inner_border_height
       end
 
@@ -59,17 +77,17 @@ module WhirledPeas
         settings.padding.top + settings.padding.bottom
       end
 
-      def vert_scroll_width
+      def scrollbar_width
         settings.scrollbar.vert? ? 1 : 0
       end
 
-      def horiz_scroll_height
+      def scrollbar_height
         settings.scrollbar.horiz? ? 1 : 0
       end
 
       private
 
-      attr_reader :settings
+      attr_reader :settings, :orig_content_width, :orig_content_height
     end
   end
 end

data/lib/whirled_peas/graphics/container_painter.rb

@@ -5,6 +5,8 @@ require_relative 'painter'
 
 module WhirledPeas
   module Graphics
+    # Abstract Painter for containers. Containers (as the name implies) contain other child
+    # elements and must delegate painting of the children to the children themselves.
     class ContainerPainter < Painter
       PADDING = ' '
 
@@ -13,38 +15,65 @@ module WhirledPeas
         @children = []
       end
 
-      def paint(canvas, &block)
+      # Paint the common attributes of containers (e.g. border and background color). Any
+      # class that inherits from this one should call `super` at the start of its #paint
+      # method, before painting its children.
+      def paint(canvas, left, top, &block)
         return unless canvas.writable?
         return unless needs_printing?
-        canvas_coords = coords(canvas)
+        canvas_coords = coords(left, top)
+
+        # Paint the border, background color, and scrollbar starting from the top left
+        # border position, moving down row by row until we reach the bottom border
+        # position
         stroke_left = canvas_coords.border_left
         stroke_top = canvas_coords.border_top
+
+        # All strokes will have the same formatting options
         formatting = [*settings.border.color, *settings.bg_color]
+
+        # Paint the top border if the settings call for it
         if settings.border.top?
           canvas.stroke(stroke_left, stroke_top, top_border_stroke(canvas_coords), formatting, &block)
           stroke_top += 1
         end
+        # Precalculate the middle border container grids with more than 1 row
         middle_border = dimensions.num_rows > 1 ? middle_border_stroke(canvas_coords) : ''
+
+        # Paint each grid row by row
         dimensions.num_rows.times do |row_num|
+          # In a grid with N rows, we will need to paint N - 1 inner horizontal borders.
+          # This code treats the inner horizontal border as the top of each row except for
+          # the first one.
           if row_num > 0 && settings.border.inner_horiz?
             canvas.stroke(stroke_left, stroke_top, middle_border, formatting, &block)
             stroke_top += 1
           end
+
+          # Paint the interior of each row (horizontal borders, veritical scroll bar and
+          # background color for the padding and content area)
           canvas_coords.inner_grid_height.times do |row_within_cell|
             canvas.stroke(stroke_left, stroke_top, content_line_stroke(canvas_coords, row_within_cell), formatting, &block)
             stroke_top += 1
           end
+
+          # Paint the horizontal scroll bar is the settings call for it
           if settings.scrollbar.horiz?
             canvas.stroke(stroke_left, stroke_top, bottom_scroll_stroke(canvas_coords), formatting, &block)
             stroke_top += 1
           end
         end
+
+        # Paint the bottom border if the settings call for it
         if settings.border.bottom?
           canvas.stroke(stroke_left, stroke_top, bottom_border_stroke(canvas_coords), formatting, &block)
           stroke_top += 1
         end
       end
 
+      # Tightly manage access to the children (rather than simply exposing the underlying
+      # array). This allows subclasses to easily modify behavior based on that element's
+      # specific settings.
       def add_child(child)
         children << child
       end
@@ -65,6 +94,8 @@ module WhirledPeas
 
       attr_reader :children
 
+      # Determine if there is anything to print for the container (this does not accont for
+      # children, just the border, scrollbar, and background color)
       def needs_printing?
         return true if settings.bg_color
         return true if settings.border.outer?
@@ -73,10 +104,66 @@ module WhirledPeas
         settings.scrollbar.horiz? || settings.scrollbar.vert?
       end
 
-      def coords(canvas)
-        ContainerCoords.new(canvas, dimensions, settings)
+      # Return an object that allows easy access to important coordinates within the container,
+      # e.g. the left position where the left border is printed
+      def coords(left, top)
+        ContainerCoords.new(dimensions, settings, left, top)
+      end
+
+      # @return [Array<Integer>] a two-item array, the first being the amount of horizontal
+      #   spacing to paint *before the first* child and the second being the amount of spacing
+      #   to paint *between each* child
+      def horiz_justify_offset(containing_width)
+        if settings.align_center?
+          [(dimensions.content_width - containing_width) / 2, 0]
+        elsif settings.align_right?
+          [dimensions.content_width - containing_width, 0]
+        elsif settings.align_between?
+          return [0, 0] if num_children == 1
+          [0, (dimensions.content_width - containing_width) / (num_children - 1)]
+        elsif settings.align_around?
+          full_spacing = (dimensions.content_width - containing_width) / num_children
+          [full_spacing / 2, full_spacing]
+        elsif settings.align_evenly?
+          spacing = (dimensions.content_width - containing_width) / (num_children + 1)
+          [spacing, spacing]
+        else
+          [0, 0]
+        end
+      end
+
+      # @return [Array<Integer>] a two-item array, the first being the amount of vertical
+      #   spacing to paint *above the first* child and the second being the amount of spacing
+      #   to paint *between each* child
+      def vert_justify_offset(containing_height)
+        if settings.valign_middle?
+          [(dimensions.content_height - containing_height) / 2, 0]
+        elsif settings.valign_bottom?
+          [dimensions.content_height - containing_height, 0]
+        elsif settings.valign_between?
+          return [0, 0] if num_children == 1
+          [0, (dimensions.content_height - containing_height) / (num_children - 1)]
+        elsif settings.valign_around?
+          full_spacing = (dimensions.content_height - containing_height) / num_children
+          [full_spacing / 2, full_spacing]
+        elsif settings.valign_evenly?
+          spacing = (dimensions.content_height - containing_height) / (num_children + 1)
+          [spacing, spacing]
+        else
+          [0, 0]
+        end
       end
 
+      # Return a stroke for one line of the container
+      #
+      # @param left_border [String] the character to print as the first character if there
+      #   is a left border
+      # @param junc_border [String] the character to print as the junction between two grid
+      #   columns if there is an inner vertical border
+      # @param right_border [String] the character to print as the last character if there
+      #   is a right border
+      # @block [String] the block should yield a string that represents the interior
+      #   (including padding) of a grid cell
       def line_stroke(left_border, junc_border, right_border, &block)
         stroke = ''
         stroke += left_border if settings.border.left?
@@ -88,6 +175,7 @@ module WhirledPeas
         stroke
       end
 
+      # Return the stroke for the top border
       def top_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.top_left,
@@ -98,6 +186,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for an inner horizontal border
       def middle_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.left_junc,
@@ -108,6 +197,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for the bottom border
       def bottom_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.bottom_left,
@@ -118,6 +208,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for a grid row between any borders
       def content_line_stroke(canvas_coords, row_within_cell)
         line_stroke(
           settings.border.style.left_vert,
@@ -142,6 +233,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for the horizontal scroll bar
       def bottom_scroll_stroke(canvas_coords)
         line_stroke(
           settings.border.style.left_vert,
@@ -159,6 +251,7 @@ module WhirledPeas
         end
       end
 
+      # Contants to paint scrollbars
       GUTTER = ' '
       HORIZONTAL = %w[▗ ▄ ▖]
       VERTICAL = %w[
@@ -167,16 +260,33 @@ module WhirledPeas
         ▝
       ]
 
+      # Determine the character to paint the horizontal scroll bar with for the given column
+      #
+      # @see #scroll_char for more details
       def horiz_scroll_char(col_count, viewable_col_count, first_visible_col, curr_col)
         scroll_char(col_count, viewable_col_count, first_visible_col, curr_col, HORIZONTAL)
       end
 
+      # Determine the character to paint the vertical scroll bar with for the given row
+      #
+      # @see #scroll_char for more details
       def vert_scroll_char(row_count, viewable_row_count, first_visible_row, curr_row)
         scroll_char(row_count, viewable_row_count, first_visible_row, curr_row, VERTICAL)
       end
 
       private
 
+      # Determine which character to paint a for a scrollbar
+      #
+      # @param total_count [Integer] total number of rows/columns in the content
+      # @param viewable_count [Integer] number of rows/columns visible in the viewport
+      # @param first_visible [Integer] zero-based index of the first row/column that is visible
+      #   in the viewport
+      # @param curr [Integer] zero-based index of the row/column (relative to the first visible
+      #   row/column) that the painted character is being requested for
+      # @param chars [Array<String>] an array with three 1-character strings, the frist is the
+      #   "second half" scrollbar character, the second is the "full" scrollbar character, and
+      #   the third is the "first half" scrollbar character.
       def scroll_char(total_count, viewable_count, first_visible, curr, chars)
         return GUTTER unless total_count > 0 && viewable_count > 0
         # The scroll handle has the exact same relative size and position in the scroll gutter
@@ -201,6 +311,25 @@ module WhirledPeas
         #    |                             *                   *
         #    +---------1---------2---------3*********4*********+
         #                                  |...........********|
+        #
+        # Returning to the first example, we can match up the arguments to this method to the
+        # diagram
+        #
+        #                       total_count = 50
+        #    |<----------------------------------------------->|
+        #    |                                                 |
+        #    |                veiwable_count = 20              |
+        #    |               |<----------------->|             |
+        #    ↓               ↓                   ↓             ↓
+        #    +---------1-----****2*********3******---4---------+
+        #    |               *                   *             |
+        #    |   hidden      *     viewable      *   hidden    |
+        #    |               *                   *             |
+        #    +---------1-----****2*********3******---4---------+
+        #                    |......****?***.....|
+        #                    ↑          ↑
+        #      first_visible = 16       |
+        #                             curr = 11
 
         # The first task of determining how much of the handle is visible in a row/column is to
         # calculate the range (as a precentage of the total) of viewable items