class HexaPDF:: Layout:: Style
Parent | Object |
---|
A Style
is a container for properties that describe the appearance of text or graphics.
Each property except font
has a default value, so only the desired properties need to be changed.
Each property has three associated methods:
- property_name
-
Getter method.
- property_name(*args) and property_name=
-
Setter method.
- property_name?
-
Tester method to see if a value has been set or if the default value has already been used.
Public Class Methods
Public Instance Methods
The horizontal alignment of text, defaults to :left.
Possible values:
- :left
-
Left-align the text, i.e. the right side is rugged.
- :center
-
Center the text horizontally.
- :right
-
Right-align the text, i.e. the left side is rugged.
- :justify
-
Justify the text, except for those lines that end in a hard line break.
Examples:
text = "Lorem ipsum dolor sit amet. " * 2
composer.style(:base, border: {width: 1})
composer.text(text, align: :left)
composer.text(text, align: :center)
composer.text(text, align: :right)
composer.text(text, align: :justify)
The alpha value applied to the background when it is colored, defaults to 1 (i.e. 100% opaque).
See: HexaPDF::Content::Canvas#opacity
Examples:
composer.text("Some text here", background_color: "red", background_alpha: 0.5)
The border around the contents, defaults to no border for all four sides.
The value has to be a hash containing any of the keys :width, :color and :style. The width, color and style of the border can be set independently for each side (see Style::Quad#set
).
See Border
for more details.
Examples:
composer.text("Some text here", border: {
width: [6, 3],
color: ["green", "blue", "orange"],
style: [:solid, :dashed]
})
The calculated font size, taking superscript and subscript into account.
Returns the correct offset from the baseline for the strikeout line.
Returns the correct thickness for the strikeout line.
The calculated text rise, taking superscript and subscript into account.
Returns the correct offset from the baseline for the underline.
Returns the correct thickness for the underline.
The character spacing, defaults to 0 (i.e. no additional character spacing).
See: HexaPDF::Content::Canvas#character_spacing
Examples:
composer.text("More spacing between characters", character_spacing: 1)
Clears all cached values.
This method needs to be called if the following style properties are changed and values were already cached: font, font_size
, character_spacing
, word_spacing
, horizontal_scaling
, ascender, descender.
The alpha value applied to filling operations (e.g. text), defaults to 1 (i.e. 100% opaque).
See: HexaPDF::Content::Canvas#opacity
Examples:
composer.text("This is some semi-transparent text", fill_alpha: 0.5)
The color used for filling (e.g. text), defaults to black.
See: HexaPDF::Content::Canvas#fill_color
Examples:
composer.text("This is some red text", fill_color: "red")
The font to be used, must be set to a valid font wrapper object before it can be used.
HexaPDF::Composer
handles this property specially in that it resolves a set string or array to a font wrapper object before doing else with the style object.
This is the only style property without a default value!
See: HexaPDF::Content::Canvas#font
Examples:
composer.text("Helvetica", font: composer.document.fonts.add("Helvetica"))
composer.text("Courier", font: "Courier") # works only with composer
helvetica_bold = composer.document.fonts.add("Helvetica", variant: :bold)
composer.text("Helvetica Bold", font: helvetica_bold)
composer.text("Courier Bold", font: ["Courier", variant: :bold]) # only composer
The font features (e.g. kerning, ligatures, …) that should be applied by the shaping engine, defaults to {} (i.e. no font features are applied).
Each feature to be applied is indicated by a key with a truthy value.
See: HexaPDF::Layout::TextShaper#shape_text
for available features.
Examples:
composer.style(:base, font: ["Times", custom_encoding: true], font_size: 30)
composer.text("Test flight")
composer.text("Test flight", font_features: {kern: true, liga: true})
The font size, defaults to 10.
See: HexaPDF::Content::Canvas#font_size
Examples:
composer.text("Default size")
composer.text("Larger size", font_size: 20)
The horizontal scaling, defaults to 100 (in percent, i.e. normal scaling).
See: HexaPDF::Content::Canvas#horizontal_scaling
Examples:
composer.text("Horizontal scaling", horizontal_scaling: 150)
Duplicates the complex properties that can be modified, as well as the cache.
The font size used for line height calculations, default is nil
meaing it defaults to font_size
.
This value should never be smaller than the font size since this would lead to overlapping text.
Examples:
composer.text("Line 1")
composer.text("Larger line height", line_height: 30)
composer.text("Line 3")
The type of line spacing to be used for text lines, defaults to type :single.
This method can set the line spacing in two ways:
-
Using two positional arguments
type
andvalue
. -
Or a hash with the keys
type
andvalue
.
Note that the last line has no additional spacing after it by default. Set last_line_gap
for adding such a spacing.
See LineSpacing
for supported types of line spacing.
Examples:
composer.text("This is some longer text that wraps around in two lines.",
line_spacing: 1.5)
composer.text("This is some longer text that wraps around in two lines.",
line_spacing: :double)
composer.text("This is some longer text that wraps around in two lines.",
line_spacing: {type: :proportional, value: 1.2})
The margin around a box, defaults to 0 for all four sides.
See Style::Quad#set
for information on how to set the values.
Examples:
composer.text("Some text here", margin: [5, 10], position: :float,
border: {width: 1})
composer.text("Text starts after floating box and continues below it, " \
"respecting the margin.", position: :flow)
A Style::Layers
object containing all the layers that should be drawn over the box; defaults to no layers being drawn.
The layers
argument needs to be an array of layer objects. To define a layer either use a callable object taking the canvas and the box as arguments; or use a pre-defined layer using an array of the form [:layer_name, **options]. See Style::Layers
for details.
Examples:
composer.text("Some text here", overlays: [
lambda do |canvas, box|
canvas.stroke_color("red").opacity(stroke_alpha: 0.5).
line_width(5).line(0, 0, box.width, box.height).stroke
end,
[:link, uri: "https://hexapdf.gettalong.org"]
])
The padding between the border and the contents, defaults to 0 for all four sides.
See Style::Quad#set
for information on how to set the values.
Examples:
composer.text("Some text here", padding: 10, border: {width: 1})
Specifies how a box should be positioned in a frame. The property position_hint
provides additional, position specific data. Defaults to :default.
Possible values:
- :default
-
Position the box at the current position. The exact horizontal position is given via the position hint. Space to the left/right of the box can't be used for other boxes.
- :float
-
Position the box at the current position but let it “float” so that the space to the left/right can still be used. The position hint specifies where the box should float.
- :flow
-
Flows the content of the box inside the frame around objects.
A box needs to indicate whether it supports this value by implementing the supports_position_flow? method and returning
true
if it does orfalse
if it doesn't. - :absolute
-
Position the box at an absolute position relative to the frame. The coordinates are given via the position hint.
See position_hint
for examples
Specifies additional information on how a box should be positioned in a frame. The exact meaning depends on the value of the position
property.
Possible values depending on the position
property:
- :default
- :left
-
(default) Align the box to the left side of the available region.
- :center
-
Horizontally center the box in the available region.
- :right
-
Align the box to the right side of the available region.
Examples:
composer.text("Left", border: {width: 1}) draw_current_frame_shape("red") composer.text("Center", position_hint: :center, border: {width: 1}) draw_current_frame_shape("blue") composer.text("Right", position_hint: :right, border: {width: 1}) draw_current_frame_shape("green")
- :float
- :left
-
(default) Float the box to the left side of the available region.
- :center
-
Float the box to the center of the available region.
- :right
-
Float the box to the right side of the available region.
Examples:
composer.style(:base, position: :float, border: {width: 1}) composer.text("Left", position_hint: :left) draw_current_frame_shape("red") composer.text("Center", position_hint: :center) draw_current_frame_shape("blue") composer.text("Right", position_hint: :right) draw_current_frame_shape("green")
- :absolute
-
An array with the x- and y-coordinates of the bottom left corner of the absolutely positioned box. The coordinates are taken as being relative to the bottom left corner of the frame into which the box is drawn.
Examples:
composer.text("Absolute", position: :absolute, position_hint: [30, 40]) draw_current_frame_shape("red")
The character spacing scaled appropriately.
The ascender of the font scaled appropriately.
The descender of the font scaled appropriately.
The font size scaled appropriately.
The horizontal scaling scaled appropriately.
Returns the width of the item scaled appropriately (by taking font size, characters spacing, word spacing and horizontal scaling into account).
The item may be a (singleton) glyph object or an integer/float, i.e. items that can appear inside a TextFragment
.
The word spacing scaled appropriately.
The maximum y-coordinate, calculated using the scaled ascender of the font and the line height or font size.
The minimum y-coordinate, calculated using the scaled descender of the font and the line height or font size.
The alpha value applied to stroking operations (e.g. text outlines), defaults to 1 (i.e. 100% opaque).
See: HexaPDF::Content::Canvas#opacity
Examples:
composer.text("Stroked text", font_size: 40, stroke_alpha: 0.5,
text_rendering_mode: :stroke)
The line cap style used for stroking operations (e.g. text outlines), defaults to :butt. The returned values is always a normalized line cap style value.
See: HexaPDF::Content::Canvas#line_cap_style
Examples:
composer.text("Stroked text", font_size: 40, stroke_cap_style: :round,
text_rendering_mode: :stroke)
The color used for stroking (e.g. text outlines), defaults to black.
See: HexaPDF::Content::Canvas#stroke_color
Examples:
composer.text("Stroked text", font_size: 40, stroke_color: "red",
text_rendering_mode: :stroke)
The line dash pattern used for stroking operations (e.g. text outlines), defaults to a solid line.
See: HexaPDF::Content::Canvas#line_dash_pattern
Examples:
composer.text("Stroked text", font_size: 40, stroke_dash_pattern: [4, 2],
text_rendering_mode: :stroke)
The line join style used for stroking operations (e.g. text outlines), defaults to :miter. The returned values is always a normalized line joine style value.
See: HexaPDF::Content::Canvas#line_join_style
Examples:
composer.text("Stroked text", font_size: 40, stroke_join_style: :bevel,
text_rendering_mode: :stroke)
The miter limit used for stroking operations (e.g. text outlines) when stroke_join_style
is :miter, defaults to 10.0.
See: HexaPDF::Content::Canvas#miter_limit
Examples:
composer.text("Stroked text", font_size: 40, stroke_join_style: :bevel,
stroke_miter_limit: 1, text_rendering_mode: :stroke)
The line width used for stroking operations (e.g. text outlines), defaults to 1.
See: HexaPDF::Content::Canvas#line_width
Examples:
composer.text("Stroked text", font_size: 40, stroke_width: 2,
text_rendering_mode: :stroke)
The line wrapping algorithm that should be used, defaults to TextLayouter::SimpleLineWrapping
.
When setting the algorithm, either an object that responds to call or a block can be used. See TextLayouter::SimpleLineWrapping#call for the needed method signature.
The text rendering mode, i.e. whether text should be filled, stroked, clipped, invisible or a combination thereof, defaults to :fill. The returned value is always a normalized text rendering mode value.
See: HexaPDF::Content::Canvas#text_rendering_mode
Examples:
composer.text("Test flight", font_size: 40, text_rendering_mode: :stroke)
The text rise, i.e. the vertical offset from the baseline, defaults to 0.
See: HexaPDF::Content::Canvas#text_rise
Examples:
composer.formatted_text(["Normal", {text: "Up in the air", text_rise: 5}])
The algorithm to use for text segmentation purposes, defaults to TextLayouter::SimpleTextSegmentation
.
When setting the algorithm, either an object that responds to call(items) or a block can be used.
A Style::Layers
object containing all the layers that should be drawn under the box; defaults to no layers being drawn.
The layers
argument needs to be an array of layer objects. To define a layer either use a callable object taking the canvas and the box as arguments; or use a pre-defined layer using an array of the form [:layer_name, **options]. See Style::Layers
for details.
Examples:
composer.text("Some text here", underlays: [
lambda do |canvas, box|
canvas.stroke_color("red").opacity(stroke_alpha: 0.5).
line_width(5).line(0, 0, box.width, box.height).stroke
end,
[:link, uri: "https://hexapdf.gettalong.org"]
])
Updates the style's properties using the key-value pairs specified by the properties
hash.
The vertical alignment of items (normally text) inside a text box, defaults to :top.
For :center and :bottom alignment the box will fill the whole available height. If this is not wanted, an explicit height will need to be set for the box.
This property is ignored when using position :flow for a text box.
Possible values:
- :top
-
Vertically align the items to the top of the box.
- :center
-
Vertically align the items in the center of the box.
- :bottom
-
Vertically align the items to the bottom of the box.
Examples:
composer.style(:base, border: {width: 1})
composer.text("Top aligned", height: 20, valign: :top)
composer.text("Center aligned", height: 20, valign: :center)
composer.text("Bottom aligned", valign: :bottom)
The word spacing, defaults to 0 (i.e. no additional word spacing).
See: HexaPDF::Content::Canvas#word_spacing
Examples:
composer.text("More word spacing", word_spacing: 20)