Add dash option to drawing operations

Currently only impacts rect, but it will impact others with the new design shortly

CHANGELOG.md

@@ -3,11 +3,16 @@ Squib follows [semantic versioning](http://semver.org).
 
 ## v0.7.0 / Unreleased
 
+Features
+* Added `cap` option to `line` and `curve` to define how those ends are drawn
+* Added `join` option to all drawing operations (e.g. `rect`, `star`) to define how corners are drawn.
+* Added `dash` option to all drawing operations (e.g. `rect`, `star`) so you can specify your own dash pattern. Just specify a string with space-separated numbers to specify the on-and-off alternating pattern (e.g. `'2 2'` with a stroke width of 2 is evenly spaced dots). Supports unit conversion, too!
+
 Compatibility:
 * All drawn shapes (e.g. circle, triangle, star) will now draw their stroke on top of the fill. This was not consistent before, and now it is (because Squib is more DRY about it!). This might mean that your `stroke_width` will render wider than before.
 
 Chores:
-* Refactoring to make internal drawing code more DRY (#75)
+* Refactoring to make internal drawing code more DRY (#75, and much more). This is a big re-design that will help ease future features that involve manipulating arguments.
 
 ## v0.6.0 / 2015-05-26
 

lib/squib/api/shapes.rb

@@ -22,6 +22,8 @@ module Squib
     # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
     # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle. {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
+    # @option opts join [String] ('miter') how corners will be drawn on stroke. Options are 'miter', 'bevel', or 'round'. Note that this is separate from the x_radius and y_radius of the rounded rectangle. Becomes more obvious with wider strokes.
+    # @option opts dash [String] ('') define a dash pattern for the stroke. Provide a string with space-separated numbers that define the pattern of on-and-off alternating strokes, measured in pixels by defautl. Supports Unit Conversion, see {file:README.md#Units Units} (e.g. `'0.02in 0.02in'`).
     # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}
     # @return [nil] intended to be void
     # @api public
@@ -160,6 +162,7 @@ module Squib
     # @option opts stroke_color [String] (:black) the color with which to stroke the line. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts fill_color [String] ('#0000') the color with which to fill the triangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
+    # @option opts cap [String] ('butt') how the end of the line is drawn. Options are "square", "butt", and "round"
     # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}
     # @return [nil] intended to be void
     # @api public

lib/squib/args/arg_loader.rb

@@ -12,6 +12,7 @@ module Squib
 
       # Main class invoked by the client (i.e. api/ methods)
       def load!(args, expand_by: 1, layout: {}, dpi: 300)
+        @dpi = dpi
         set_attributes(args: args)
         expand(by: expand_by)
         layout_args = prep_layout_args(args[:layout], expand_by: expand_by)

lib/squib/args/draw.rb

@@ -13,7 +13,8 @@ module Squib
           stroke_color: :black,
           stroke_width: 2.0,
           join: :miter,
-          cap: 'butt'
+          cap: 'butt',
+          dash: ''
         }
       end
 
@@ -47,6 +48,12 @@ module Squib
         end
       end
 
+      def validate_dash(arg, _i)
+        arg.to_s.split.collect do |x|
+          convert_unit(x, @dpi).to_f
+        end
+      end
+
     end
 
   end

lib/squib/graphics/cairo_context_wrapper.rb

@@ -25,7 +25,7 @@ module Squib
         :operator=, :show_page, :clip, :transform, :mask, :create_pango_layout,
         :antialias=, :curve_to, :matrix, :matrix=, :identity_matrix, :pango_layout_path,
         :stroke_preserve, :target, :new_path, :fill_preserve, :close_path,
-        :set_line_join, :set_line_cap
+        :set_line_join, :set_line_cap, :set_dash
 
       # :nodoc:
       # @api private
@@ -52,13 +52,16 @@ module Squib
 
       # Convenience method for a common task
       # @api private
-      def fill_n_stroke(fill_color, stroke_color, stroke_width, line_join = 0, line_cap = Cairo::LINE_CAP_BUTT)
+      def fill_n_stroke(fill_color, stroke_color, stroke_width,
+                        line_join = 0, line_cap = Cairo::LINE_CAP_BUTT,
+                        dash = [])
         set_source_squibcolor(fill_color)
         fill_preserve
         set_source_squibcolor(stroke_color)
         set_line_width(stroke_width)
         set_line_join(line_join)
         set_line_cap(line_cap)
+        set_dash(dash)
         stroke
       end
 

lib/squib/graphics/shapes.rb

@@ -7,7 +7,7 @@ module Squib
     def rect(box, draw)
       use_cairo do |cc|
         cc.rounded_rectangle(box.x, box.y, box.width, box.height, box.x_radius, box.y_radius)
-        cc.fill_n_stroke(draw.fill_color, draw.stroke_color, draw.stroke_width, draw.join)
+        cc.fill_n_stroke(draw.fill_color, draw.stroke_color, draw.stroke_width, draw.join, draw.cap, draw.dash)
       end
     end
 

samples/draw_shapes.rb

@@ -3,7 +3,7 @@ require 'squib'
 Squib::Deck.new do
   background color: :white
 
-  rect x: 300, y: 100, width: 200, height: 50
+  rect x: 300, y: 100, width: 200, height: 50, dash: '4 2'
 
   rect x: 300, y: 300, width: 400, height: 400,
        fill_color: :blue, stroke_color: :red, stroke_width: 50.0,

spec/args/draw_spec.rb

@@ -19,7 +19,28 @@ describe Squib::Args::Draw do
     it 'converts to Cairo options' do
       args = {join: 'bevel', cap: 'round'}
       draw.load!(args)
-      expect(draw).to have_attributes(join: [Cairo::LINE_JOIN_BEVEL])
+      expect(draw).to have_attributes(
+        join: [Cairo::LINE_JOIN_BEVEL],
+        cap: [Cairo::LINE_CAP_ROUND]
+        )
+    end
+
+    it 'parses dash options' do
+      args = {dash: '3 4 5'}
+      draw.load!(args)
+      expect(draw).to have_attributes(dash: [[3, 4, 5]])
+    end
+
+    it 'parses more complex dash options' do
+      args = {dash: '30.5,  90,  5'}
+      draw.load!(args)
+      expect(draw).to have_attributes(dash: [[30.5, 90, 5]])
+    end
+
+    it 'does unit conversion on dash options' do
+      args = {dash: '3in  4in 5in'}
+      draw.load!(args)
+      expect(draw).to have_attributes(dash: [[900, 1200, 1500]])
     end
 
   end