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

new(**properties) click to toggle source

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

align(direction = nil) click to toggle source

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
      
background_color(color = nil) click to toggle source

The color used for backgrounds, defaults to nil (i.e. no background).

# File lib/hexapdf/layout/style.rb, line 783
      
border(value = nil) click to toggle source

The border around the contents, defaults to no border.

# File lib/hexapdf/layout/style.rb, line 804
      
calculated_font_size() click to toggle source

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
calculated_strikeout_position() click to toggle source

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
calculated_strikeout_thickness() click to toggle source

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
calculated_text_rise() click to toggle source

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
calculated_underline_position() click to toggle source

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
calculated_underline_thickness() click to toggle source

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
character_spacing(amount = nil) click to toggle source

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
      
clear_cache() click to toggle source

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
fill_alpha(alpha = nil) click to toggle source

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
      
fill_color(color = nil) click to toggle source

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
      
font(name = nil) click to toggle source

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
      
font_features(features = nil) click to toggle source

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
      
font_size(size = nil) click to toggle source

The font size, defaults to 10.

See: HexaPDF::Content::Canvas#font_size

# File lib/hexapdf/layout/style.rb, line 564
      
horizontal_scaling(percent = nil) click to toggle source

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
      
initialize_copy(other) click to toggle source

Duplicates the complex properties that can be modified, as well as the cache.

Calls superclass method
# 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
last_line_gap(enable = false) click to toggle source

Add an appropriately sized gap after the last line of text if enabled, defaults to false.

# File lib/hexapdf/layout/style.rb, line 776
      
line_spacing(type = nil, value = nil) click to toggle source
line_spacing(type:, value: 1)

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 and value.

  • Or a hash with the keys type and value.

See LineSpacing for supported types of line spacing.

# File lib/hexapdf/layout/style.rb, line 761
      
margin(value = nil) click to toggle source

The margin around a box, defaults to 0 for all four sides.

# File lib/hexapdf/layout/style.rb, line 797
      
overlays(layers = nil) click to toggle source

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
      
padding(value = nil) click to toggle source

The padding between the border and the contents, defaults to 0 for all four sides.

# File lib/hexapdf/layout/style.rb, line 790
      
position(value = nil) click to toggle source

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
      
position_hint(value = nil) click to toggle source

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
      
scaled_character_spacing() click to toggle source

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
scaled_font_ascender() click to toggle source

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
scaled_font_descender() click to toggle source

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
scaled_font_size() click to toggle source

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
scaled_horizontal_scaling() click to toggle source

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
scaled_item_width(item) click to toggle source

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
scaled_word_spacing() click to toggle source

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
scaled_y_max() click to toggle source

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
scaled_y_min() click to toggle source

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
stroke_alpha(alpha = nil) click to toggle source

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
      
stroke_cap_style(style = nil) click to toggle source

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
      
stroke_color(color = nil) click to toggle source

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
      
stroke_join_style(style = nil) click to toggle source

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
      
stroke_miter_limit(limit = nil) click to toggle source

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
      
stroke_width(width = nil) click to toggle source

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
      
subscript(enable = false) click to toggle source

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
      
superscript(enable = false) click to toggle source

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
      
text_indent(amount = nil) click to toggle source

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
      
text_line_wrapping_algorithm(algorithm = nil) {|items, width_block| block } click to toggle source

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
      
text_rendering_mode(mode = nil) click to toggle source

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
      
text_rise(amount = nil) click to toggle source

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
      
text_segmentation_algorithm(algorithm = nil) {|items| block } click to toggle source

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
      
underlays(layers = nil) click to toggle source

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
      
update(**properties) → style click to toggle source

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
valign(direction = nil) click to toggle source

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
      
word_spacing(amount = nil) click to toggle source

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

default_color() click to toggle source

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