Class: Squib::Deck

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/squib/deck.rb,
lib/squib/api/data.rb,
lib/squib/api/save.rb,
lib/squib/api/text.rb,
lib/squib/api/image.rb,
lib/squib/api/units.rb,
lib/squib/api/shapes.rb,
lib/squib/api/settings.rb,
lib/squib/api/background.rb,
lib/squib/graphics/save_doc.rb,
lib/squib/graphics/showcase.rb

Overview

The main interface to Squib. Provides a front-end porcelain whereas the Card class interacts with the graphics plumbing.

Instance Method Summary collapse

Constructor Details

#initialize(width: 825, height: 1125, cards: 1, dpi: 300, config: 'config.yml', layout: nil, &block) ⇒ Deck

Squib's constructor that sets the immutable properties.

This is the starting point for Squib. In providing a block to the constructor, you have access to all of Deck's instance methods. The documented methods in Deck are the ones intended for use by most users. If your game requires multiple different sizes or orientations, I recommend using multiple Squib::Decks in your deck.rb. You can modify the internals of Squib::Deck (e.g. @cards), but that's not recommended.

Examples:

require 'squib'
Squib::Deck.new do
  text str: 'Hello, World!"
end

Parameters:

  • width (Integer) (defaults to: 825) —

    the width of each card in pixels

  • height (Integer) (defaults to: 1125) —

    the height of each card in pixels

  • cards (Integer) (defaults to: 1) —

    the number of cards in the deck

  • dpi (Integer) (defaults to: 300) —

    the pixels per inch when rendering out to PDF or calculating using inches.

  • config (String) (defaults to: 'config.yml') —

    the file used for global settings of this deck

  • layout (String, Array) (defaults to: nil) —

    load a YML file of custom layouts. Multiple files are merged sequentially, redefining collisons. See README and sample for details.

  • block (Block) —

    the main body of the script.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/squib/deck.rb', line 57

def initialize(width: 825, height: 1125, cards: 1, dpi: 300, config: 'config.yml', layout: nil, &block)
  @width=width; @height=height
  @dpi = dpi
  @font = Squib::SYSTEM_DEFAULTS[:default_font]
  @cards = []
  @custom_colors = {}
  @img_dir = '.'
  @progress_bar = Squib::Progress.new(false)
  @text_hint = :off
  cards.times{ @cards << Squib::Card.new(self, width, height) }
  show_info(config, layout)
  load_config(config)
  @layout = LayoutParser.load_layout(layout)
  if block_given?
    instance_eval(&block)
  end
end

Instance Method Details

#background(opts = {}) ⇒ nil

Fills the background with the given color Options support Arrays, see Arrays and Singleon Expansion

Examples:

background color: :white

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • color (String) — default: :black —

    the color the font will render to. See Specifying Colors.

Returns:

  • (nil) —

    nothing



13
14
15
16
 
# File 'lib/squib/api/background.rb', line 13

def background(opts = {})
  opts = needs(opts,[:range, :color])
  opts[:range].each { |i| @cards[i].background(opts[:color][i]) }
end

#circle(opts = {}) ⇒ nil

Draw a circle centered at the given coordinates

Options support Arrays, see Arrays and Singleon Expansion

Examples:

circle x: 0, y: 0, radius: 100

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • x (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y (Integer) — default: 0 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • radius (Integer) — default: 100 —

    radius of the circle. Supports Unit Conversion, see Units.

  • fill_color (String) — default: '#0000' —

    the color with which to fill the rectangle

  • stroke_color (String) — default: :black —

    the color with which to stroke the outside of the rectangle

  • stroke_width (Decimal) — default: 2.0 —

    the width of the outside stroke. Supports Unit Conversion, see Units.

Returns:

  • (nil) —

    intended to be void



52
53
54
55
56
57
58
59
60
 
# File 'lib/squib/api/shapes.rb', line 52

def circle(opts = {})
  opts = {radius: 100}.merge(opts) # overriding the non-system default
  opts = needs(opts, [:range, :x, :y, :circle_radius, :layout,
                      :fill_color, :stroke_color, :stroke_width])
  opts[:range].each do |i|
    @cards[i].circle(opts[:x][i], opts[:y][i], opts[:radius][i],
      opts[:fill_color][i], opts[:stroke_color][i], opts[:stroke_width][i])
  end
end

#cm(n) ⇒ Decimal

Given cm, returns the number of pixels according to the deck's DPI.

Examples:

cm(1) # 750 (for default Deck::dpi of 300)

Parameters:

  • n (Decimal) —

    , the number of centimeters

Returns:

  • (Decimal) —

    the number of pixels, according to the deck's DPI



26
27
28
 
# File 'lib/squib/api/units.rb', line 26

def cm(n)
  @dpi * Squib::INCHES_IN_CM * n.to_f
end

#csv(opts = {}) ⇒ Object

Convenience call on deck goes to the module function



94
95
96
 
# File 'lib/squib/api/data.rb', line 94

def csv(opts = {})
  Squib.csv(opts)
end

#hint(text: :off) ⇒ nil

Toggle hints globally.

Text hints are rectangles around where the text will be laid out. They are intended to be temporary. Setting a hint to nil or to :off will disable hints. @see samples/text.rb

Examples:

hint text: :cyan
hint text: :cyan

Parameters:

  • text (String) (defaults to: :off) —

    the color of the text hint. To turn off use :off. @see README.md

Returns:

  • (nil) —

    Returns nothing



15
16
17
 
# File 'lib/squib/api/settings.rb', line 15

def hint(text: :off)
  @text_hint = text
end

#inches(n) ⇒ Decimal

Given inches, returns the number of pixels according to the deck's DPI.

Examples:

inches(2.5) # 750 (for default Deck::dpi of 300)

Parameters:

  • n (Decimal) —

    , the number of inches

Returns:

  • (Decimal) —

    the number of pixels, according to the deck's DPI



14
15
16
 
# File 'lib/squib/api/units.rb', line 14

def inches(n)
  @dpi * n.to_f
end

#line(opts = {}) ⇒ nil

Draw a line using the given coordinates

Examples:

triangle :x1 => 0, :y1 => 0, :x2 => 50, :y2 => 50

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • x1 (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y1 (Integer) — default: 0 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • x2 (Integer) — default: 50 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y2 (Integer) — default: 50 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • stroke_color (String) — default: :black —

    the color with which to stroke the line

  • stroke_width (Decimal) — default: 2.0 —

    the width of the outside stroke. Supports Unit Conversion, see Units.

Returns:

  • (nil) —

    intended to be void



107
108
109
110
111
112
113
114
 
# File 'lib/squib/api/shapes.rb', line 107

def line(opts = {})
  opts = needs(opts, [:range, :x1, :y1, :x2, :y2, :layout,
                      :stroke_color, :stroke_width])
  opts[:range].each do |i|
    @cards[i].line(opts[:x1][i], opts[:y1][i], opts[:x2][i], opts[:y2][i],
                   opts[:stroke_color][i], opts[:stroke_width][i])
  end
end

#perspective(src, scale, face_right) ⇒ Object 



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/squib/graphics/showcase.rb', line 63

def perspective(src, scale, face_right)
  dest_cxt = Cairo::Context.new(Cairo::ImageSurface.new(src.width * scale, src.height))
  in_thickness = 1 # Take strip 1 pixel-width at a time
  out_thickness = 3 # Scale it to 3 pixels wider to cover any gaps
  (0..src.width).step(in_thickness) do |i|
    percentage = i / src.width.to_f
    i = src.width - i if face_right
    factor = scale + (percentage * (1.0 - scale)) #linear interpolation
    dest_cxt.save
    dest_cxt.translate 0, src.height / 2.0 * (1.0 - factor)
    dest_cxt.scale factor * scale, factor
    dest_cxt.set_source src, 0, 0
    dest_cxt.rounded_rectangle i, 0, out_thickness, src.height, 0,0
    dest_cxt.fill
    dest_cxt.restore
  end
  return dest_cxt.target
end

#png(opts = {}) ⇒ nil

Renders a png file at the given location.

See samples/image.rb and samples/tgc-overlay.rb as examples.

Examples:

png file: 'img.png', x: 50, y: 50

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • file (String) — default: (empty) —

    file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See Specifying Files. Supports Arrays, see Arrays and Singleon Expansion

  • x (Integer) — default: 0 —

    the x-coordinate to place. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • y (Integer) — default: 0 —

    the y-coordinate to place. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • width (Integer) — default: :native —

    the pixel width that the image should scale to. Scaling PNGs is not recommended for professional-looking cards. When set to :native, uses the DPI and units of the loaded SVG document. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • height (Integer) — default: :native —

    the pixel width that the image should scale to. Scaling PNGs is not recommended for professional-looking cards. When set to :native, uses the DPI and units of the loaded SVG document. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • layout (String, Symbol) — default: nil —

    entry in the layout to use as defaults for this command. See Custom Layouts. Supports Arrays, see Arrays and Singleon Expansion

  • alpha (Decimal) — default: 1.0 —

    the alpha-transparency percentage used to blend this image. Supports Arrays, see Arrays and Singleon Expansion

  • blend (:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity) — default: :none —

    the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see Arrays and Singleon Expansion

  • angle (FixNum) — default: 0 —

    Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see Arrays and Singleon Expansion

Returns:

  • (nil) —

    Returns nil



22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/squib/api/image.rb', line 22

def png(opts = {})
  opts = needs(opts, [:range, :files, :x, :y, :width, :height, :alpha, :layout, :blend, :angle])
  Dir.chdir(@img_dir) do
    @progress_bar.start('Loading PNG(s)', opts[:range].size) do |bar|
      opts[:range].each do |i|
        @cards[i].png(opts[:file][i],
                      opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
                      opts[:alpha][i], opts[:blend][i], opts[:angle][i])
        bar.increment
      end
    end
  end
end

#rect(opts = {}) ⇒ nil

Draw a rounded rectangle

Options support Arrays, see Arrays and Singleon Expansion

Examples:

rect x: 0, y: 0, width: 825, height: 1125, radius: 25

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • x (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y (Integer) — default: 0 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • width (Integer) —

    the width of the rectangle. Supports Unit Conversion, see Units.

  • height (Integer) —

    the height of the rectangle. Supports Unit Conversion, see Units.

  • x_radius (Integer) — default: 0 —

    the radius of the rounded corner horiztonally. Zero is a non-rounded corner. Supports Unit Conversion, see Units.

  • y_radius (Integer) — default: 0 —

    the radius of the rounded corner vertically. Zero is a non-rounded corner. Supports Unit Conversion, see Units.

  • radius (Integer) — default: nil —

    when set, overrides both x_radius and y_radius. Supports Unit Conversion, see Units.

  • fill_color (String) — default: '#0000' —

    the color with which to fill the rectangle

  • stroke_color (String) — default: :black —

    the color with which to stroke the outside of the rectangle

  • stroke_width (Decimal) — default: 2.0 —

    the width of the outside stroke. Supports Unit Conversion, see Units.

  • layout (String, Symbol) — default: nil —

    entry in the layout to use as defaults for this command. See Custom Layouts

Returns:

  • (nil) —

    intended to be void



25
26
27
28
29
30
31
32
33
34
 
# File 'lib/squib/api/shapes.rb', line 25

def rect(opts = {})
  opts = needs(opts, [:range, :x, :y, :width, :height, :rect_radius, :x_radius, :y_radius,
                      :fill_color, :stroke_color, :stroke_width, :layout])
  opts[:range].each do |i|
    @cards[i].rect(opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
                   opts[:x_radius][i], opts[:y_radius][i],
                   opts[:fill_color][i], opts[:stroke_color][i],
                   opts[:stroke_width][i])
  end
end

#save(opts = {}) ⇒ Object

Saves the given range of cards to either PNG or PDF

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • dir (String) — default: _output —

    the directory for the output to be sent to. Will be created if it doesn't exist.

  • format (Symbol) — default: :png —

    the format that this will be rendered too. Options :pdf, :png. Array of both is allowed: [:pdf, :png]

  • prefix (String) — default: card_ —

    the prefix of the file name to be printed

  • rotate (Boolean) — default: false —

    PNG saving only. If true, the saved cards will be rotated 90 degrees clockwise. Intended to rendering landscape instead of portrait.

Returns:

  • self



13
14
15
16
17
18
 
# File 'lib/squib/api/save.rb', line 13

def save(opts = {})
  opts = needs(opts, [:range, :creatable_dir, :formats, :prefix, :rotate])
  save_png(opts) if opts[:format].include? :png
  save_pdf(opts) if opts[:format].include? :pdf
  self
end

#save_pdf(opts = {}) ⇒ nil

Lays out the cards in range and renders a PDF

Examples:

save_pdf file: 'deck.pdf', margin: 75, gap: 5, trim: 37

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • file (String) —

    the name of the PDF file to save. See Specifying Files

  • dir (String) — default: _output —

    the directory to save to. Created if it doesn't exist.

  • margin (Integer) — default: 75 —

    the margin around the outside of the page

  • gap (Integer) — default: 0 —

    the space in pixels between the cards

  • trim (Integer) — default: 0 —

    the space around the edge of each card to trim (e.g. to cut off the bleed margin for print-and-play)

Returns:

  • (nil) 


16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/squib/graphics/save_doc.rb', line 16

def save_pdf(opts = {})
  p = needs(opts, [:range, :file_to_save, :creatable_dir, :margin, :gap, :trim])
  width  = 11  * @dpi
  height = 8.5 * @dpi #TODO: allow this to be specified too
  cc = Cairo::Context.new(Cairo::PDFSurface.new("#{p[:dir]}/#{p[:file]}", width, height))
  x = p[:margin]
  y = p[:margin]
  @progress_bar.start("Saving PDF to #{p[:dir]}/#{p[:file]}", p[:range].size) do |bar|
    p[:range].each do |i|
      surface = trim(@cards[i].cairo_surface, p[:trim], @width, @height)
      cc.set_source(surface, x, y)
      cc.paint
      bar.increment
      x += surface.width + p[:gap]
      if x > (width - surface.width - p[:margin])
        x = p[:margin]
        y += surface.height + p[:gap]
        if y > (height - surface.height - p[:margin])
          x = p[:margin]
          y = p[:margin]
          cc.show_page #next page
        end
      end
    end
  end
end

#save_png(opts = {}) ⇒ nil

Saves the given range of cards to a PNG

Examples:

save range: 1..8, dir: '_pnp', prefix: 'bw_'

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • dir (String) — default: _output —

    the directory for the output to be sent to. Will be created if it doesn't exist.

  • prefix (String) — default: card_ —

    the prefix of the file name to be printed.

  • rotate (Boolean, :clockwise, :counterclockwise) — default: false —

    if true, the saved cards will be rotated 90 degrees clockwise. Or, rotate by the number of radians. Intended to rendering landscape instead of portrait.

Returns:

  • (nil) —

    Returns nothing



31
32
33
34
35
36
37
38
39
 
# File 'lib/squib/api/save.rb', line 31

def save_png(opts = {})
  opts = needs(opts,[:range, :creatable_dir, :prefix, :rotate])
  @progress_bar.start("Saving PNGs to #{opts[:dir]}/#{opts[:prefix]}*", @cards.size) do |bar|
    opts[:range].each do |i|
      @cards[i].save_png(i, opts[:dir], opts[:prefix], opts[:rotate], opts[:angle])
      bar.increment
    end
  end
end

#save_sheet(opts = {}) ⇒ nil

Lays out the cards in range and renders a stitched PNG sheet

Examples:

save_png_sheet prefix: 'sheet_', margin: 75, gap: 5, trim: 37

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • colulmns (Integer) — default: 1 —

    the number of columns in the grid

  • rows (Integer) — default: :infinite —

    the number of rows in the grid. When set to :infinite, the sheet scales to the rows needed. If there are more cards than rows*columns, new sheets are started.

  • prefix (String) — default: card_ —

    the prefix of the file name(s)

  • dir (String) — default: _output —

    the directory to save to. Created if it doesn't exist.

  • margin (Integer) — default: 0 —

    the margin around the outside of the page

  • gap (Integer) — default: 0 —

    the space in pixels between the cards

  • trim (Integer) — default: 0 —

    the space around the edge of each card to trim (e.g. to cut off the bleed margin for print-and-play)

Returns:

  • (nil) 


58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/squib/graphics/save_doc.rb', line 58

def save_sheet(opts = {})
  opts = {margin: 0}.merge(opts) # overriding the non-system default
  p = needs(opts, [:range, :prefix, :creatable_dir, :margin, :gap, :trim, :rows, :columns])
  # EXTRACT METHOD HERE
  sheet_width = (p[:columns] * (@width + 2 * p[:gap] - 2 * p[:trim])) + (2 * p[:margin])
  sheet_height = (p[:rows] * (@height + 2 * p[:gap] - 2 * p[:trim])) + (2 * p[:margin])
  cc = Cairo::Context.new(Cairo::ImageSurface.new(sheet_width, sheet_height))
  num_this_sheet = 0
  sheet_num = 0
  x, y = p[:margin], p[:margin]
  @progress_bar.start("Saving PNG sheet to #{p[:dir]}/#{p[:prefix]}_*", @cards.size + 1) do |bar|
    p[:range].each do |i|
      if num_this_sheet >= (p[:columns] * p[:rows]) # new sheet
        cc.target.write_to_png("#{p[:dir]}/#{p[:prefix]}#{sheet_num}.png")
        new_sheet = false
        num_this_sheet = 0
        sheet_num += 1
        x, y = p[:margin], p[:margin]
        cc = Cairo::Context.new(Cairo::ImageSurface.new(sheet_width, sheet_height))
      end
      surface = trim(@cards[i].cairo_surface, p[:trim], @width, @height)
      cc.set_source(surface, x, y)
      cc.paint
      bar.increment
      num_this_sheet += 1
      x += surface.width + p[:gap]
      if num_this_sheet % p[:columns] == 0 # new row
        x = p[:margin]
        y += surface.height + p[:gap]
      end
      bar.increment
    end
    cc.target.write_to_png("#{p[:dir]}/#{p[:prefix]}#{sheet_num}.png")
  end
end

#set(opts = {}) ⇒ nil

Sets various defaults for this deck. Defaults can be overriden by the commands themselves when that command supports it.

Examples:

set font: 'Arial 26'
text 'blah'                     # in Arial 26
text 'blah24', font: 'Arial 24' # in Arial 24
set font: :default              # Back to Squib-wide default

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • font: (Object) —

    the font string to set as default. Can also be set to :default to use the Squib-wide default.

  • img_dir: (Object) —

    the default directory to READ images from. Default is .. Useful for switching from bw to color images.

Returns:

  • (nil) —

    Returns nothing



30
31
32
33
34
 
# File 'lib/squib/api/settings.rb', line 30

def set(opts = {})
  opts = needs(opts, [:font, :img_dir])
  @font = opts[:font][0] #was expanded - just need the first
  @img_dir = opts[:img_dir]
end

#showcase(opts = {}) ⇒ nil

Renders a range of files in a showcase as if they are sitting on a reflective surface See showcase for full example

Examples:

showcase file: 'showcase_output.png', trim: 78, trim_radius: 32

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • trim (Fixnum) — default: 0 —

    the margin around the card to trim before putting into the showcase

  • trim_radius (Fixnum) — default: 38 —

    the rounded rectangle radius around the card to trim before putting into the showcase

  • margin (Fixnum) — default: 75 —

    the margin around the entire showcase

  • scale (Fixnum) — default: 0.8 —

    percentage of original width of each (trimmed) card to scale to. Must be between 0.0 and 1.0, but starts looking bad around 0.6.

  • offset (Fixnum) — default: 1.1 —

    percentage of the scaled width of each card to shift each offset. e.g. 1.1 is a 10% shift, and 0.95 is overlapping by 5%

  • fill_color (String, Color) — default: :white —

    backdrop color. Usually black or white.

  • reflect_offset (Fixnum) — default: 15 —

    the number of pixels between the bottom of the card and the reflection

  • reflect_strength (Fixnum) — default: 0.2 —

    the starting alpha transparency of the reflection (at the top of the card). Percentage between 0 and 1. Looks more realistic at low values since even shiny surfaces lose a lot of light.

  • reflect_percent (Fixnum) — default: 0.25 —

    the length of the reflection in percentage of the card. Larger values tend to make the reflection draw just as much attention as the card, which is not good.

  • face (:left, :right) — default: :left —

    which direction the cards face. Anything but :right will face left

  • dir (String) — default: _output —

    the directory for the output to be sent to. Will be created if it doesn't exist.

  • file (String) — default: 'showcase.png' —

    the file to save in dir. Will be overwritten.

Returns:

  • (nil) —

    Returns nothing.



62
63
64
65
66
67
68
69
70
 
# File 'lib/squib/api/save.rb', line 62

def showcase(opts = {})
  opts = {file: 'showcase.png', fill_color: :white}.merge(opts)
  opts = needs(opts,[:range, :trim, :trim_radius, :creatable_dir, :file_to_save, :face])
  render_showcase(opts[:range], opts[:trim], opts[:trim_radius],
                  opts[:scale], opts[:offset], opts[:fill_color],
                  opts[:reflect_offset], opts[:reflect_percent], opts[:reflect_strength],
                  opts[:margin], opts[:face],
                  opts[:dir], opts[:file])
end

#svg(opts = {}) ⇒ nil

Renders an entire svg file at the given location. Uses the SVG-specified units and DPI to determine the pixel width and height.

See samples/load-images.rb and samples/tgc-overlay.rb as examples.

Examples:

svg 1..2, 'icon.svg', '#stone', x: 50, y:50

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • file (String) — default: '') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See {file:README.md#Specifying_Files Specifying Files}. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion} —

    '') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done. See Specifying Files. Supports Arrays, see Arrays and Singleon Expansion

  • id (String) — default: nil —

    if set, then only render the SVG element with the given id. Prefix '#' is optional. Note: the x-y coordinates are still relative to the SVG document's page. Supports Arrays, see Arrays and Singleon Expansion

  • force_id (Boolean) — default: false —

    if set, then this svg will not be rendered at all if the id is empty or nil. If not set, the entire SVG is rendered. Supports Arrays, see Arrays and Singleon Expansion

  • x (Integer) — default: 0 —

    the x-coordinate to place. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • y (Integer) — default: 0 —

    the y-coordinate to place. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • width (Integer) — default: :native —

    the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to :native, uses the DPI and units of the loaded SVG document. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • height (Integer) — default: :native —

    the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to :native, uses the DPI and units of the loaded SVG document. Supports Arrays, see Arrays and Singleon Expansion. Supports Unit Conversion, see Units.

  • layout (String, Symbol) — default: nil —

    entry in the layout to use as defaults for this command. See Custom Layouts. Supports Arrays, see Arrays and Singleon Expansion

  • alpha (Decimal) — default: 1.0 —

    the alpha-transparency percentage used to blend this image. Supports Arrays, see Arrays and Singleon Expansion

  • blend (:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity) — default: :none —

    the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see Arrays and Singleon Expansion

  • angle (FixNum) — default: 0 —

    Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see Arrays and Singleon Expansion

Returns:

  • (nil) —

    Returns nil



56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/squib/api/image.rb', line 56

def svg(opts = {})
  p = needs(opts,[:range, :files, :svgid, :force_svgid, :x, :y, :width, :height, :layout, :alpha, :blend, :angle])
  Dir.chdir(@img_dir) do
    @progress_bar.start('Loading SVG(s)', p[:range].size) do |bar|
      p[:range].each do |i|
        unless p[:force_id][i] && p[:id][i].to_s.empty?
          @cards[i].svg(p[:file][i], p[:id][i], p[:x][i], p[:y][i],
                        p[:width][i], p[:height][i], p[:alpha][i], p[:blend][i], p[:angle][i])
        end
        bar.increment
      end
    end
  end
end

#text(opts = {}) ⇒ Array

Renders a string at a given location, width, alignment, font, etc.

Unix-like newlines are interpreted even on Windows. See the samples/text.rb for a lengthy example.

Options support Arrays, see Arrays and Singleon Expansion

Examples:

text str: 'hello'
text str: 'hello', x: 50, y:50, align: center

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • str (String, Array) — default: '') the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards. —

    '') the string to be rendered. Must support #to_s. If the card responds to #each, it's mapped out one at a time across the cards.

  • font (String) — default: Arial 36 or whatever was set with `set` —

    the Font description string, including family, styles, and size. (e.g. 'Arial bold italic 12') For the official documentation, see the Pango docs. This description is also quite good. See the samples/text.rb as well.

  • font_size (Integer) — default: nil —

    an override of font string description, for scaling the font according to the size of the string

  • x (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y (Integer) — default: 0 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • color (String) — default: :black —

    the color the font will render to. See Specifying Colors

  • markup: (Boolean) — default: false —

    Enable markup parsing of str using the HTML-like Pango Markup syntax, defined here and here.

  • width (Integer, :native) — default: :native —

    the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion, see Units.

  • height (Integer, :native) —

    the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion, see Units.

  • layout (String, Symbol) — default: nil —

    entry in the layout to use as defaults for this command. See Custom Layouts

  • wrap (:none, :word, :char, :word_char, true, false) — default: :word_char —

    When height is set, determines the behavior of how the string wraps. The :word_char option will break at words, but then fall back to characters when the word cannot fit. # Options are :none, :word, :char, :word_char. Also: true is the same as :word_char, false is the same as :none. Default :word_char

  • spacing (Integer) — default: 0 —

    Adjust the spacing when the text is multiple lines. No effect when the text does not wrap.

  • align (:left, right, :center) — default: :left —

    The alignment of the text

  • justify (Boolean) — default: false —

    toggles whether or not the text is justified or not.

  • valign (:top, :middle, :bottom) — default: :top —

    When width and height are set, align text vertically according to the ink extents of the text.

  • ellipsize (:none, :start, :middle, :end, true, false) — default: :end —

    When width and height are set, determines the behavior of overflowing text. Also: true maps to :end and false maps to :none. Default :end

  • angle (FixNum) — default: 0 —

    Rotation of the text in radians. Note that this rotates around the upper-left corner of the text box, making the placement of x-y coordinates slightly tricky.

  • hint (String) — default: :nil —

    draw a rectangle around the text with the given color. Overrides global hints (see #hint).

Returns:

  • (Array) —

    Returns an Array of hashes keyed by :width and :height that mark the ink extents of the text rendered.



41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/squib/api/text.rb', line 41

def text(opts = {})
  opts = needs(opts, [:range, :str, :font, :font_size, :x, :y, :width, :height, :color, :wrap,
                      :align, :justify, :spacing, :valign, :markup, :ellipsize, :hint, :layout, :angle])
  extents = Array.new(@cards.size)
  opts[:range].each do |i|
    extents[i] = @cards[i].text(opts[:str][i], opts[:font][i], opts[:font_size][i], opts[:color][i],
                   opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
                   opts[:markup][i], opts[:justify][i], opts[:wrap][i],
                   opts[:ellipsize][i], opts[:spacing][i], opts[:align][i],
                   opts[:valign][i], opts[:hint][i], opts[:angle][i])
  end
  return extents
end

#triangle(opts = {}) ⇒ nil

Draw a triangle using the given coordinates

Options support Arrays, see Arrays and Singleon Expansion

Examples:

triangle :x1 => 0, :y1 => 0, :x2 => 50, :y2 => 50, :x3 => 0, :y3 => 50

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • range (Enumerable, :all) — default: :all —

    the range of cards over which this will be rendered. See Specifying Ranges

  • x1 (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y1 (Integer) — default: 0 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • x2 (Integer) — default: 50 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y2 (Integer) — default: 50 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • x3 (Integer) — default: 0 —

    the x-coordinate to place. Supports Unit Conversion, see Units.

  • y3 (Integer) — default: 50 —

    the y-coordinate to place. Supports Unit Conversion, see Units.

  • fill_color (String) — default: '#0000' —

    the color with which to fill the triangle

  • stroke_color (String) — default: :black —

    the color with which to stroke the outside of the triangle

  • stroke_width (Decimal) — default: 2.0 —

    the width of the outside stroke. Supports Unit Conversion, see Units.

Returns:

  • (nil) —

    intended to be void



81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/squib/api/shapes.rb', line 81

def triangle(opts = {})
  opts = needs(opts, [:range, :x1, :y1, :x2, :y2, :x3, :y3, :layout,
                      :fill_color, :stroke_color, :stroke_width])
  opts[:range].each do |i|
    @cards[i].triangle(opts[:x1][i], opts[:y1][i],
                       opts[:x2][i], opts[:y2][i],
                       opts[:x3][i], opts[:y3][i],
                       opts[:fill_color][i], opts[:stroke_color][i],
                       opts[:stroke_width][i])
  end
end

#xlsx(opts = {}) ⇒ Object

Convenience call on deck goes to the module function



89
90
91
 
# File 'lib/squib/api/data.rb', line 89

def xlsx(opts = {})
  Squib.xlsx(opts)
end