XYWH Shorthands

For the arguments x, y, width, and height, a few convenient shorthands are available.

  • middle for x and width refer to the deck’s width / 2
  • middle for y and height refer to the deck’s height / 2
  • The word center behaves the same way
  • deck refers to the deck’s width for x and width
  • deck refers to the deck’s height for y and height
  • You can offset from the middle by using + or - operators, e.g. middle + 1in
  • You can offset from the deck width or height using the + or - operators, e.g. deck - 1in or deck - 2mm
  • You can offset from the deck width or height using, e.g. deck / 3
  • Works with all unit conversion too, e.g. middle + 1 cell. See Unit Conversion.

These are all passed as strings. So you will need to quote them in Ruby, or just plain in your layout YAML.

Note that the following are NOT supported:

  • The += operator when using extends in a layout file
  • Complicated formulas. We’re not evaluating this as code, we’re looking for these specific patterns and applying them. Anything more complicated you’ll have to handle with Ruby code.

Samples

_shorthands.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
require_relative '../../lib/squib'

# Lots of DSL methods have shorthands that are accepted for
# x, y, width, and height parameters.
Squib::Deck.new(width: '0.5in', height: '0.25in') do
  background color: :white

  # middle for x and y will resolve to half the height
  text str: 'xymiddle', font: 'Sans Bold 3', hint: :red,
       x: 'middle', y: :middle

  # 'center' also works
  rect width: 30, height: 30,
       x: :center, y: 'center'

  # Applies to shapes
  triangle x1: 20, y1: 20,
           x2: 60, y2: 20,
           x3: :middle, y3: :middle

  # We can also do width-, height-, width/, height/
  rect x: 20, y: 5, stroke_color: :green,
  width: 'deck - 0.1in', height: 10

  rect x: 10, y: 50, width: 10, height: 'deck / 3',
       stroke_color: :purple

  # And middle+/-
  rect x: 'middle + 0.1in', y: 'center - 0.1in',
       width: '0.1in', height: '0.1in', fill_color: :blue

  # Layouts apply this too.
  use_layout file: 'shorthands.yml'
  rect layout: :example

  # HOWEVER! Shorthands don't combine in an "extends" situation,
  # e.g. this won't work:
  # parent:
  #   x: middle
  # child:
  #   extends: parent
  #   x: += 0.5in

  # These shorthands are not intended for every xywh parameter or
  # length parameter, see docs for when they do or do not apply.

  save_png prefix: 'shorthand_'
end