Class: HexaPDF::Type::Annotations::Line

Inherits:
MarkupAnnotation show all
Includes:
BorderStyling, InteriorColor, LineEndingStyling
Defined in:
lib/hexapdf/type/annotations/line.rb

Overview

A line annotation is a markup annotation that displays a single straight line.

The style of the line annotation, like adding leader lines, changing the colors and so on, can be customized using the provided convenience methods and those from the included modules.

Note that while BorderStyling#border_style allows special styling of the line (like :beveled), only a simple line dash pattern is supported by the line annotation.

Example:

#>pdf-small
doc.annotations.create_line(doc.pages[0], start_point: [30, 20], end_point: [90, 60]).
  border_style(color: "hp-blue", width: 2, style: [3, 1]).
  leader_line_length(15).
  leader_line_extension_length(10).
  leader_line_offset(5).
  interior_color("hp-orange").
  line_ending_style(start_style: :circle, end_style: :open_arrow).
  captioned(true).
  contents("Caption").
  caption_position(:top).
  caption_offset(0, 5).
  regenerate_appearance
canvas.line(30, 20, 90, 60).stroke

See: PDF2.0 s12.5.6.7, HexaPDF::Type::MarkupAnnotation

Constant Summary collapse

CAPTION_POSITION_MAP =

Maps HexaPDF names to PDF names.

{ # :nodoc:
  Inline: :Inline, inline: :Inline,
  Top: :Top, top: :Top,
}.freeze
CAPTION_POSITION_REVERSE_MAP =

:nodoc:

CAPTION_POSITION_MAP.invert

Constants included from LineEndingStyling

HexaPDF::Type::Annotations::LineEndingStyling::LINE_ENDING_STYLE_MAP, HexaPDF::Type::Annotations::LineEndingStyling::LINE_ENDING_STYLE_REVERSE_MAP

Constants included from DictionaryFields

DictionaryFields::Boolean, DictionaryFields::PDFByteString, DictionaryFields::PDFDate

Instance Attribute Summary

Attributes inherited from Object

#data, #document, #must_be_indirect

Instance Method Summary collapse

Methods included from LineEndingStyling

#line_ending_style

Methods included from InteriorColor

#interior_color

Methods included from BorderStyling

#border_style

Methods inherited from HexaPDF::Type::Annotation

#appearance, #appearance_dict, #contents, #create_appearance, #flags, #must_be_indirect?, #opacity, #regenerate_appearance

Methods included from Utils::BitField

#bit_field

Methods inherited from Dictionary

#[], #[]=, define_field, define_type, #delete, #each, each_field, #empty?, field, #key?, #to_hash, type, #type

Methods inherited from Object

#<=>, #==, #cache, #cached?, #clear_cache, deep_copy, #deep_copy, #document?, #eql?, field, #gen, #gen=, #hash, #indirect?, #initialize, #inspect, make_direct, #must_be_indirect?, #null?, #oid, #oid=, #type, #validate, #value, #value=

Constructor Details

This class inherits a constructor from HexaPDF::Object

Instance Method Details

#caption_offset(x = nil, y = nil) ⇒ Object

:call-seq:

line.caption_offset        => caption_offset
line.caption_offset(x, y)  => line

Returns the caption offset when no argument is given. Otherwise sets the caption offset and returns self.

The caption offset is an array of two numbers that specify the horizontal and vertical offsets of the caption from its normal position. A positive horizontal offset means moving the caption to the right. A positive vertical offset means shifting the caption up.

Example:

#>pdf-small-hide
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  contents("Top text").
  captioned(true).
  caption_position(:top).
  caption_offset(20, 10).
  regenerate_appearance

Also see: #captioned, #caption_position



309
310
311
 
# File 'lib/hexapdf/type/annotations/line.rb', line 309

def caption_offset(x = nil, y = nil)
  x || y ? (self[:CO] = [x || 0, y || 0]; self) : self[:CO].to_ary
end

#caption_position(value = nil) ⇒ Object

:call-seq:

line.caption_position          => caption_position
line.caption_position(value)   => line

Returns the caption position when no argument is given. Otherwise sets the caption position and returns self.

Possible caption positions are (the first one is the HexaPDF name, the second the PDF name):

:inline or :Inline

The caption is centered inside the line (default).

#>pdf-small-hide
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  contents("Inline text").
  captioned(true).
  caption_position(:inline).
  regenerate_appearance
:top or :Top

The caption is on the top of the line.

#>pdf-small-hide
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  contents("Top text").
  captioned(true).
  caption_position(:top).
  regenerate_appearance

Also see: #captioned, #caption_offset



274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/hexapdf/type/annotations/line.rb', line 274

def caption_position(value = nil)
  if value
    value = CAPTION_POSITION_MAP.fetch(value) do
      raise ArgumentError, "Invalid caption position: #{value.inspect}"
    end
    self[:CP] = value
    self
  else
    CAPTION_POSITION_REVERSE_MAP[self[:CP]]
  end
end

#captioned(value = nil) ⇒ Object

:call-seq:

line.captioned          => true or false
line.captioned(value)   => line

Returns true (if the line has a visible caption) or false (no visible caption) when no argument is given. Otherwise sets whether a caption should be visible and returns self.

If a caption should be shown, the text specified by the /Contents or /RC entries is shown in the appearance of the line.

Example:

#>pdf-small-hide
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  contents("Inline text").
  captioned(true).
  regenerate_appearance

Also see: #caption_position, #caption_offset



230
231
232
 
# File 'lib/hexapdf/type/annotations/line.rb', line 230

def captioned(value = nil)
  value ? (self[:Cap] = value; self) : self[:Cap]
end

#leader_line_extension_length(length = nil) ⇒ Object

:call-seq:

line.leader_line_extension_length          => leader_line_extension_length
line.leader_line_extension_length(length)  => line

Returns the leader line extension length when no argument is given. Otherwise sets the leader line extension length and returns self.

Leader line extensions extend from the line into the opposite direction of the leader lines.

The argument length must be non-negative.

If the leader line extension length is set to a positive value, the leader line length also needs to be specified.

Example:

#>pdf-small
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  leader_line_length(15).
  leader_line_extension_length(5).
  regenerate_appearance
canvas.stroke_color("hp-orange").line(20, 20, 80, 60).stroke

Also see: #leader_line_length, #leader_line_offset



176
177
178
179
180
181
182
183
184
 
# File 'lib/hexapdf/type/annotations/line.rb', line 176

def leader_line_extension_length(length = nil)
  if length
    raise ArgumentError, "length must be non-negative" if length < 0
    self[:LLE] = length
    self
  else
    self[:LLE]
  end
end

#leader_line_length(length = nil) ⇒ Object

:call-seq:

line.leader_line_length          => leader_line_length
line.leader_line_length(length)  => line

Returns the leader line length when no argument is given. Otherwise sets the leader line length and returns self.

Leader lines extend from the line’s end points perpendicular to the line. If the length value is positive, the leader lines appear in the clockwise direction, otherwise in the opposite direction.

Note: The “line’s end points” mean the actually drawn line and not the one specified with #line as those two are different when leader lines are involved.

A value of zero means that no leader lines are used.

Example:

#>pdf-small
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  leader_line_length(15).
  regenerate_appearance
canvas.stroke_color("hp-orange").line(20, 20, 80, 60).stroke

Also see: #leader_line_extension_length, #leader_line_offset



146
147
148
 
# File 'lib/hexapdf/type/annotations/line.rb', line 146

def leader_line_length(length = nil)
  length ? (self[:LL] = length; self) : self[:LL]
end

#leader_line_offset(offset = nil) ⇒ Object

:call-seq:

line.leader_line_offset          => leader_line_offset
line.leader_line_offset(number)  => line

Returns the leader line offset when no argument is given. Otherwise sets the leader line offset and returns self.

The leader line offset is a non-negative number that describes the offset of the leader lines from the endpoints of the line.

Example:

#>pdf-small
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  leader_line_length(15).
  leader_line_offset(5).
  regenerate_appearance
canvas.stroke_color("hp-orange").line(20, 20, 80, 60).stroke

Also see: #leader_line_length, #leader_line_extension_length



207
208
209
 
# File 'lib/hexapdf/type/annotations/line.rb', line 207

def leader_line_offset(offset = nil)
  offset ? (self[:LLO] = offset; self) : self[:LLO] || 0
end

#line(x0 = nil, y0 = nil, x1 = nil, y1 = nil) ⇒ Object

:call-seq:

line.line                   => [x0, y0, x1, y1]
line.line(x0, y0, x1, y1)   => line

Returns the start point and end point of the line as an array of four numbers [x0, y0, x1, y1] when no argument is given. Otherwise sets the start and end point of the line and returns self.

This is the only required setting for a line annotation. Note, however, that without setting an appropriate color through #border_style the line will be transparent.

Example:

#>pdf-small
doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  regenerate_appearance



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/hexapdf/type/annotations/line.rb', line 109

def line(x0 = nil, y0 = nil, x1 = nil, y1 = nil)
  if x0.nil? && y0.nil? && x1.nil? && y1.nil?
    self[:L].to_ary
  elsif !x0 || !y0 || !x1 || !y1
    raise ArgumentError, "All four arguments x0, y0, x1, y1 must be provided"
  else
    self[:L] = [x0, y0, x1, y1]
    self
  end
end