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
whenwidth
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 theellipsize
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.