class HexaPDF::Type::Annotations::Line

Parent	MarkupAnnotation
Included Modules	HexaPDF::Type::Annotations::BorderStyling

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.

Note that changing the line width and color is done using the included BorderStyling#border_style. While that method allows special styling of the line (like :beveled), only a simple line dash pattern is supported by the line annotation.

Example:

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

Constants

LineEndingStyle¶

Describes the line ending style for a line annotation, i.e. the start_style and the end_style.

See Line#line_ending_style for more information.

Public Instance Methods

caption_offset → caption_offset ¶

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:

Also see: captioned, caption_position

caption_position → caption_position ¶

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).

:top or :Top

The caption is on the top of the line.

Also see: captioned, caption_offset

captioned → true or false ¶

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:

Also see: caption_position, caption_offset

interior_color → color or nil ¶

interior_color(*color) → line ¶

Returns the interior color or nil (in case the interior color should be transparent) when no argument is given. Otherwise sets the interior color and returns self.

The interior color is used to fill the line endings depending on the line ending styles.

color

The interior color. See HexaPDF::Content::ColorSpace.device_color_from_specification for information on the allowed arguments.

If the special value :transparent is used when setting the color, no color is used for filling the line endings.

Also see: line_ending_style

leader_line_extension_length → leader_line_extension_length ¶

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:

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

leader_line_length → leader_line_length ¶

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:

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

leader_line_offset → leader_line_offset ¶

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:

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

line → [x0, y0, x1, y1] ¶

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:

doc.annotations.
  create_line(doc.pages[0], start_point: [20, 20], end_point: [80, 60]).
  regenerate_appearance

line_ending_style → style ¶

line_ending_style(start_style: :none, end_style: :none) → line ¶

Returns a LineEndingStyle instance holding the current line ending styles when no argument is given. Otherwise sets the line ending style of the line and returns self.

When returning the styles, unknown line ending styles are mapped to :none.

When setting the line ending style, arguments that are not provided will use the currently defined value or fall back to the default of :none.

Possible line ending styles (the first one is the HexaPDF name, the second the PDF name):

:square or :Square

A square filled with the annotation’s interior colour, if any.

:circle or :Circle

A circle filled with the annotation’s interior colour, if any.

:diamond or :Diamond

A diamond shape filled with the annotation’s interior colour, if any.

:open_arrow or :OpenArrow

Two short lines meeting in an acute angle to form an open arrowhead.

:closed_arrow or :ClosedArrow

Two short lines meeting in an acute angle as in the :open_arrow style and connected by a third line to form a triangular closed arrowhead filled with the annotation’s interior colour, if any.

:none or :None