Unit Conversion

By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in “in”, “cm”, or “mm” and computing based on the current DPI. The dpi is set on Squib::Deck.new (not config.yml).

Cells

A “cell” is a custom unit in Squib that, by default, refers to 37.5 pixels. In a 300 DPI situation (i.e. the default), that refers to a 1/8 inch or 3.175mm. This tends to be a standard unit of measure in a lot of templates. By specifying your units in cells, you can increase your rapid prototyping without having to multiply 37.5.

The cell_px measure is configurable. See Configuration Options.

To use the cell unit, you need to give Squib a string ending in cell, cells, or just c. For example:

  • 2 cells
  • 1cell
  • 0.5c

See more examples below.

Samples

_units.rb

Here are some examples, which lives here

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
require 'squib'

Squib::Deck.new(width: '1.5in', height: '1.5in') do
  background color: :white

  # We can use our DSL-method to use inches
  # Computed using @dpi (set to 300 by default)
  bleed = inches(0.125)
  cut   = inches(1.25)
  rect x: bleed, y: bleed,
       width: cut, height: cut,
       dash: '0.5mm 0.5mm' # yes, units are in dashes too

  # other units too
  cm(2)             # We can also use cm this way
  cm(2) + inches(2) # We can mix units too

  # Or we can use a string ending with cm or in
  safe_margin = '0.25 in' #you can have a space too
  safe_width  = '1 in'
  safe_height = '1.0 in  ' # trailing space is ok too
  rect x: safe_margin, y: safe_margin,
  	   width: safe_width, height: safe_height,
       radius: '2 mm '

  # Angles are also automatically converted to radians if you use deg
  svg file: '../spanner.svg',
      x: 100, y: 100, width: 40, height: 40, angle: '30deg'

  # We can also do stuff in layout. Check out the yml file...
  #  (even cleaner in Yaml since we don't need quotes!)
  use_layout file: 'using_units.yml'
  text str: 'Hello.', layout: :example
  svg file: '../spanner.svg', layout: :angled

  save prefix: 'units_', format: :png

  # But wait... there's more! See _shorthands.rb for more fanciness with units
end

_cells.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
42
43
44
45
46
47
48
49
50
51
require 'squib'

Squib::Deck.new(width: '1.5in', height: '1.5in') do
  background color: :white

  # Squib has a custom unit, called "cell"
  # A "cell" unit defaults to 37.5px, which at 300dpi is 1/8in or 3.175mm
  # This is a very common multiple for layouts.
  # This helps us lay things out in grids without doing much math in our heads
  # Here's an example... with grid!
  grid width: '1 cell', height: '1 cell'

  # Plurals are fine or just 'c' as a unit is fine
  # Whitespace is pretty lenient too.
  rect fill_color: :blue,
       x: '1 cell', y: '2 cells',
       width: '1c', height: '1cell  '

  # Technically, the "cell" is actually a "unit", so you can even combine
  # with xywh shorhands!!
  rect fill_color: :red,
       x: 'middle + 0.5c', y: 'deck - 1.5c',
       width: '1c', height: '1c'

  # And, unlike xywh shorthands, this applies basically everywhere we support
  # unit conversion.
  circle fill_color: :green,
         x: '3c', y: '2c', radius: '1c'
  # Decimals are fine too
  circle fill_color: :green,
         x: '5c', y: '2c', radius: '0.5c'
  # Even dashes!
  circle fill_color: '#0000', stroke_color: :purple,
         x: '1c', y: '4c', radius: '0.5c', dash: '0.25c 0.25c'

  # We can also do stuff in layout. Check out the yml file...
  #  (even cleaner in Yaml since we don't need quotes!)
  use_layout file: 'cells.yml'
  rect layout: :example
  rect layout: :extends_example

  save_png prefix: 'cells_'
end


# You can customize this with the cell_px configuration option
Squib::Deck.new(width: 100, height: 100, config: 'cell_config.yml') do
  background color: :white
  rect x: '1c', y: '1c', width: '1c', height: '1c', fill_color: :purple
  save_png prefix: 'custom_cell_'
end