class HexaPDF::Layout::Style
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
Creates a new Style
object.
The properties
hash may be used to set the initial values of properties by using keys equivalent to the property names.
Example:
Style.new(font_size: 15, align: :center, valign: center)
# File lib/hexapdf/layout/style.rb, line 524 def initialize(**properties) update(**properties) @scaled_item_widths = {}.compare_by_identity end
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.
# File lib/hexapdf/layout/style.rb, line 727
The color used for backgrounds, defaults to nil
(i.e. no background).
# File lib/hexapdf/layout/style.rb, line 783
The border around the contents, defaults to no border.
# File lib/hexapdf/layout/style.rb, line 804
The calculated font size, taking superscript and subscript into account.
# File lib/hexapdf/layout/style.rb, line 1003 def calculated_font_size (superscript || subscript ? 0.583 : 1) * font_size end
Returns the correct offset from the baseline for the strikeout line.
# File lib/hexapdf/layout/style.rb, line 1020 def calculated_strikeout_position calculated_text_rise + calculated_font_size / 1000.0 * font.wrapped_font.strikeout_position * font.scaling_factor - calculated_strikeout_thickness / 2.0 end
Returns the correct thickness for the strikeout line.
# File lib/hexapdf/layout/style.rb, line 1027 def calculated_strikeout_thickness calculated_font_size / 1000.0 * font.wrapped_font.strikeout_thickness * font.scaling_factor end
The calculated text rise, taking superscript and subscript into account.
# File lib/hexapdf/layout/style.rb, line 992 def calculated_text_rise if superscript text_rise + font_size * 0.33 elsif subscript text_rise - font_size * 0.20 else text_rise end end
Returns the correct offset from the baseline for the underline.
# File lib/hexapdf/layout/style.rb, line 1008 def calculated_underline_position calculated_text_rise + calculated_font_size / 1000.0 * font.wrapped_font.underline_position * font.scaling_factor - calculated_underline_thickness / 2.0 end
Returns the correct thickness for the underline.
# File lib/hexapdf/layout/style.rb, line 1015 def calculated_underline_thickness calculated_font_size / 1000.0 * font.wrapped_font.underline_thickness * font.scaling_factor end
The character spacing, defaults to 0 (i.e. no additional character spacing).
See: HexaPDF::Content::Canvas#character_spacing
# File lib/hexapdf/layout/style.rb, line 573
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.
# File lib/hexapdf/layout/style.rb, line 1093 def clear_cache @scaled_font_size = @scaled_character_spacing = @scaled_word_spacing = nil @scaled_horizontal_scaling = @scaled_font_ascender = @scaled_font_descender = nil @scaled_y_min = @scaled_y_max = nil @scaled_item_widths.clear end
The alpha value applied to filling operations (e.g. text), defaults to 1 (i.e. 100% opaque).
See: HexaPDF::Content::Canvas#opacity
# File lib/hexapdf/layout/style.rb, line 659
The color used for filling (e.g. text), defaults to black.
See: HexaPDF::Content::Canvas#fill_color
# File lib/hexapdf/layout/style.rb, line 650
The font to be used, must be set to a valid font wrapper object before it can be used.
This is the only style property without a default value!
See: HexaPDF::Content::Canvas#font
# File lib/hexapdf/layout/style.rb, line 553
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.
# File lib/hexapdf/layout/style.rb, line 609
The font size, defaults to 10.
See: HexaPDF::Content::Canvas#font_size
# File lib/hexapdf/layout/style.rb, line 564
The horizontal scaling, defaults to 100 (in percent, i.e. normal scaling).
See: HexaPDF::Content::Canvas#horizontal_scaling
# File lib/hexapdf/layout/style.rb, line 591
Duplicates the complex properties that can be modified, as well as the cache.
# File lib/hexapdf/layout/style.rb, line 530 def initialize_copy(other) super @scaled_item_widths = {} clear_cache @font_features = @font_features.dup if defined?(@font_features) @padding = @padding.dup if defined?(@padding) @margin = @margin.dup if defined?(@margin) @border = @border.dup if defined?(@border) @overlays = @overlays.dup if defined?(@overlays) @underlays = @underlays.dup if defined?(@underlays) end
Add an appropriately sized gap after the last line of text if enabled, defaults to false.
# File lib/hexapdf/layout/style.rb, line 776
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
.
See LineSpacing
for supported types of line spacing.
# File lib/hexapdf/layout/style.rb, line 761
The margin around a box, defaults to 0 for all four sides.
# File lib/hexapdf/layout/style.rb, line 797
A Layers
object containing all the layers that should be drawn over the box; defaults to no layers being drawn.
# File lib/hexapdf/layout/style.rb, line 811
The padding between the border and the contents, defaults to 0 for all four sides.
# File lib/hexapdf/layout/style.rb, line 790
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.
- :absolute
-
Position the box at an absolute position relative to the frame. The coordinates are given via the position hint.
# File lib/hexapdf/layout/style.rb, line 827
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.
- :right
-
Align the box to the right side of the available region.
- :center
-
Horizontally center the box in the available region.
- :float
- :left
-
(default) Float the box to the left side of the available region.
- :right
-
Float the box to the right side of the available region.
- :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.
# File lib/hexapdf/layout/style.rb, line 850
The character spacing scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1037 def scaled_character_spacing @scaled_character_spacing ||= character_spacing * scaled_horizontal_scaling end
The ascender of the font scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1052 def scaled_font_ascender @scaled_font_ascender ||= font.wrapped_font.ascender * font.scaling_factor * font_size / 1000 end
The descender of the font scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1057 def scaled_font_descender @scaled_font_descender ||= font.wrapped_font.descender * font.scaling_factor * font_size / 1000 end
The font size scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1032 def scaled_font_size @scaled_font_size ||= calculated_font_size / 1000.0 * scaled_horizontal_scaling end
The horizontal scaling scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1047 def scaled_horizontal_scaling @scaled_horizontal_scaling ||= horizontal_scaling / 100.0 end
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
.
# File lib/hexapdf/layout/style.rb, line 1076 def scaled_item_width(item) @scaled_item_widths[item] ||= begin if item.kind_of?(Numeric) -item * scaled_font_size else item.width * scaled_font_size + scaled_character_spacing + (item.apply_word_spacing? ? scaled_word_spacing : 0) end end end
The word spacing scaled appropriately.
# File lib/hexapdf/layout/style.rb, line 1042 def scaled_word_spacing @scaled_word_spacing ||= word_spacing * scaled_horizontal_scaling end
The maximum y-coordinate, calculated using the scaled descender of the font.
# File lib/hexapdf/layout/style.rb, line 1067 def scaled_y_max @scaled_y_max ||= scaled_font_ascender + calculated_text_rise end
The minimum y-coordinate, calculated using the scaled descender of the font.
# File lib/hexapdf/layout/style.rb, line 1062 def scaled_y_min @scaled_y_min ||= scaled_font_descender + calculated_text_rise end
The alpha value applied to stroking operations (e.g. text outlines), defaults to 1 (i.e. 100% opaque).
See: HexaPDF::Content::Canvas#opacity
# File lib/hexapdf/layout/style.rb, line 678
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
# File lib/hexapdf/layout/style.rb, line 697
The color used for stroking (e.g. text outlines), defaults to black.
See: HexaPDF::Content::Canvas#stroke_color
# File lib/hexapdf/layout/style.rb, line 669
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
# File lib/hexapdf/layout/style.rb, line 707
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
# File lib/hexapdf/layout/style.rb, line 717
The line width used for stroking operations (e.g. text outlines), defaults to 1.
See: HexaPDF::Content::Canvas#line_width
# File lib/hexapdf/layout/style.rb, line 688
Render the text as subscript, i.e. lower and in a smaller font size; defaults to false.
If superscript is set, it will be deactivated.
# File lib/hexapdf/layout/style.rb, line 632
Render the text as superscript, i.e. higher and in a smaller font size; defaults to false.
If subscript is set, it will be deactivated.
# File lib/hexapdf/layout/style.rb, line 641
The indentation to be used for the first line of a sequence of text lines, defaults to 0.
# File lib/hexapdf/layout/style.rb, line 754
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.
# File lib/hexapdf/layout/style.rb, line 960
The text rendering mode, i.e. whether text should be filled, stroked, clipped, invisible or a combination thereof, defaults to :fill. The returned values is always a normalized text rendering mode value.
See: HexaPDF::Content::Canvas#text_rendering_mode
# File lib/hexapdf/layout/style.rb, line 621
The text rise, i.e. the vertical offset from the baseline, defaults to 0.
See: HexaPDF::Content::Canvas#text_rise
# File lib/hexapdf/layout/style.rb, line 600
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.
# File lib/hexapdf/layout/style.rb, line 949
A Layers
object containing all the layers that should be drawn under the box; defaults to no layers being drawn.
# File lib/hexapdf/layout/style.rb, line 819
Updates the style's properties using the key-value pairs specified by the properties
hash.
# File lib/hexapdf/layout/style.rb, line 547 def update(**properties) properties.each {|key, value| send(key, value) } self end
The vertical alignment of items (normally text) inside a box, defaults to :top.
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.
# File lib/hexapdf/layout/style.rb, line 741
The word spacing, defaults to 0 (i.e. no additional word spacing).
See: HexaPDF::Content::Canvas#word_spacing
# File lib/hexapdf/layout/style.rb, line 582
Private Instance Methods
Returns the default color for an empty PDF page, i.e. black.
# File lib/hexapdf/layout/style.rb, line 1103 def default_color GlobalConfiguration.constantize('color_space.map', :DeviceGray).new.default_color end