text

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

Unix newlines are interpreted even on Windows (i.e. "\n").

Options

All of these options support arrays and singleton expansion (except for range). See Squib Thinks in Arrays for deeper explanation.

str

default: ''

the string to be rendered. Must support #to_s.

font

default: 'Arial 36'

the Font description string, including family, styles, and size. (e.g. 'Arial bold italic 12'). For the official documentation, see the Pango font string docs. This description is also quite good.

font_size

default: nil

an override of font string description (i.e. font).

x

default: 0

the x-coordinate to place, relative to the upper-left corner of the card and moving right as it increases. Supports Unit Conversion and XYWH Shorthands.

y

default: 0

the y-coordinate to place, relative to the upper-left corner of the card and moving downward as it increases. Supports Unit Conversion and XYWH Shorthands.

markup

default: false

When set to true, various extra styles are allowed. See Markup.

width

default: :auto

the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion and XYWH Shorthands.

height

default: :auto

the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion and XYWH Shorthands.

wrap

default: :word_char

when width 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 :word, :char, or :word_char.
spacing

default: 0

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

align

default: :left

The alignment of the text. [:left, right, :center]

justify

default: false

toggles whether or not the text is justified or not.

valign

default: :top

When width and height are set, align text vertically according to the ink extents of the text. [:top, :middle, :bottom]

ellipsize

default: :end

When width and height are set, determines the behavior of overflowing text. If set to :autoscale, text is automatically scaled down from the set font size to the largest size that does no longer ellipsize. Also: true maps to :end and false maps to :none. Also, as mentioned in Configuration Options, if text is ellipsized a warning is thrown. [:none, :start, :middle, :end, :autoscale, true, false]

angle

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.

stroke_width

default: 0.0

the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.

stroke_color

default: :black

the color with which to stroke the outside of the rectangle. {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}

stroke_strategy

default: :fill_first

specify whether the stroke is done before (thinner) or after (thicker) filling the shape. [:fill_first, :stroke_first]

dash

default: ''

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 (e.g. '0.02in 0.02in').

hint

default: :nil (i.e. no hint)

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

color
default: [String] (:black) the color the font will render to. Gradients supported. See {file:README.md#Specifying_Colors___Gradients Specifying Colors}
fill_color

default: '#0000' (fully transparent)

the color or gradient to fill with. See Specifying Colors & Gradients.

stroke_color

default: :black

the color with which to stroke the outside of the shape. See Specifying Colors & Gradients.

stroke_width

default: 2

the width of the outside stroke. Supports Unit Conversion.

stroke_strategy

default: :fill_first

Specify whether the stroke is done before (thinner) or after (thicker) filling the shape.

Must be either :fill_first or :stroke_first (or their string equivalents).

dash

default: '' (no dash pattern set)

Define a dash pattern for the stroke. This is a special string with space-separated numbers that define the pattern of on-and-off alternating strokes, measured in pixels or units. For example, '0.02in 0.02in' will be an equal on-and-off dash pattern. Supports Unit Conversion.

cap

default: :butt

Define how the end of the stroke is drawn. Options are :square, :butt, and :round (or string equivalents of those).

join

default: :mitre

Specifies how to render the junction of two lines when stroking. Options are :mitre, :round, and :bevel.

range

default: :all

the range of cards over which this will be rendered. See Using range to specify cards

layout

default: nil

entry in the layout to use as defaults for this command. See Layouts are Squib’s Best Feature.

Markup

If you want to do specialized formatting within a given string, Squib has lots of options. By setting markup: true, you enable tons of text processing. This includes:

  • Pango Markup. This is an HTML-like formatting language that specifies formatting inside your string. Pango Markup essentially supports any formatting option, but on a letter-by-letter basis. Such as: font options, letter spacing, gravity, color, etc. See the Pango markup docs for details.
  • Quotes are converted to their curly counterparts where appropriate.
  • Apostraphes are converted to curly as well.
  • LaTeX-style quotes are explicitly converted (``like this'')
  • Em-dash and en-dash are converted with triple and double-dashes respectively (-- is an en-dash, and --- becomes an em-dash.)
  • Ellipses can be specified with ... (three periods). Note that this is entirely different from the ellipsize option (which determines what to do with overflowing text).
A few notes:
  • Smart quoting assumes the UTF-8 character set by default. If you are in a different character set and want to change how it behaves
  • Pango markup uses an XML/HTML-ish processor. Some characters require HTML-entity escaping (e.g. & for &)

You can also disable the auto-quoting mechanism by setting smart_quotes: false in your config. Explicit replacements will still be performed. See Configuration Options

Embedded Icons

The text method will also respond to a block. The object that gets passed to this block allows for embedding images into the flow of your text. The following methods are supported:

text(str: 'Take 1 :tool: and gain 2 :health:') do |embed|
  embed.svg key: ':tool:', file: 'tool.svg'
  embed.png key: ':health:', file: 'health.png'
end

embed.svg

All of these options support arrays and singleton expansion (except for range). See Squib Thinks in Arrays for deeper explanation.

key

default: '*'

the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'

file

default: ''

file(s) to read in, relative to the root directory or img_dir if set in the config.

data

default: nil

render from an SVG XML string. Overrides file if both are specified (a warning is shown).

id

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.

force_id

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.

layout

default: nil

entry in the layout to use as defaults for this command. See Layouts are Squib’s Best Feature

width

default: :native

the width of the image rendered. Does not support :scale (yet)

height

default: :native

the height the height of the image rendered. Does not support :scale (yet)

dx

default: 0

“delta x”, or adjust the icon horizontally by x pixels

dy

default: 0

“delta y”, or adjust the icon vertically by y pixels

flip_horizontal

default: false

Flip this image about its center horizontally (i.e. left becomes right and vice versa).

flip_vertical

default: false

Flip this image about its center verticall (i.e. top becomes bottom and vice versa).

alpha

default: 1.0

the alpha-transparency percentage used to blend this image.

angle

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.

embed.png

All of these options support arrays and singleton expansion (except for range). See Squib Thinks in Arrays for deeper explanation.

key

default: '*'

the string to replace with the graphic. Can be multiple letters, e.g. ':tool:'

file

default: ''

file(s) to read in, relative to the root directory or img_dir if set in the config.

layout

default: nil

entry in the layout to use as defaults for this command. See Layouts are Squib’s Best Feature

width

default: :native

the width of the image rendered.

height

default: :native

the height the height of the image rendered.

dx

default: 0

“delta x”, or adjust the icon horizontally by x pixels

dy

default: 0

“delta y”, or adjust the icon vertically by y pixels

flip_horizontal

default: false

Flip this image about its center horizontally (i.e. left becomes right and vice versa).

flip_vertical

default: false

Flip this image about its center verticall (i.e. top becomes bottom and vice versa).

alpha

default: 1.0

the alpha-transparency percentage used to blend this image.

blend

default: :none

the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.

placeholder

default: nil

if file does not exist, but the file pointed to by this string does, then draw this image instead.

No warning is thrown when a placeholder is used.

If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.

mask

default: nil

Accepts a color (see Specifying Colors & Gradients). If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.

angle

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.

Examples

See The Mighty text Method.