Box

[Raku PDF Project] / [PDF-Content Module] / PDF::Content :: Text :: Box

class PDF::Content::Text::Box

simple plain-text blocks

Synopsis

use lib 't';
use PDFTiny;
my $page = PDFTiny.new.add-page;
use PDF::Content;
use PDF::Content::Font::CoreFont;
use PDF::Content::Text::Block;
my PDF::Content::Font::CoreFont $font .= load-font( :family<helvetica>, :weight<bold> );
my $text = "Hello.  Ting, ting-ting. Attention! … ATTENTION! ";
my PDF::Content::Text::Box $text-box .= new( :$text, :$font, :font-size(16) );
my PDF::Content $gfx = $page.gfx;
$gfx.BeginText;
$text-box.render($gfx);
$gfx.EndText;
say $gfx.Str;

Description

Text boxes are used to implement the PDF::Content print and say methods. They usually work "behind the scenes". But can be created as objects and then passed to print and say:

use PDF::Lite;
use PDF::Content;
use PDF::Content::Text::Box;

my PDF::Lite $pdf .= new;

my $font-size = 16;
my $height = 20;
my $text = "Hello.  Ting, ting-ting.";

my PDF::Content::Font::CoreFont $font .= load-font( :family<helvetica>, :weight<bold> );
my PDF::Content::Text::Box $text-box .= new( :$text, :$font, :$font-size, :$height );

say "width:" ~ $text-box.width;
say "height:" ~ $text-box.height;
say "underline-thickness:" ~ $text-box.underline-thickness;
say "underline-position:" ~ $text-box.underline-position;

my $page = $pdf.add-page;

$page.text: {
    .text-position = 10, 20;
    .say: $text-box;
    .text-position = 10, 50;
    .print: $text-box;
}

$pdf.save-as: "test.pdf";

Methods

method text

The text contained in the text box. This is a rw accessor. It can also be used to replace the text contained in a text box.

method width

The constraining width (:$width option), or content-width for the text box.

method height

The constraining height (:$height option), or content-height, for the text box.

method indent

The indentation of the first line (points).

method align

Horizontal alignment left, center, or right.

method valign

Vertical alignment of mutiple-line text boxes: top, center, or bottom.

See also the :baseline option for vertical displacement of the first line of text.

Note that the baseline is implicitely set to the valign option. However the default for valign is top, and the default for baseline is alphabetic.

method baseline

The font baseline to use. This is similar to the HTML Canvas textBaseline property.

method baseline-shift

Vertical displacement, in scaled font units, needed to postions the font to the baseline. 0 for alphabetic baseline.

method lines

An array of PDF::Content::Text::Line objects.

methods margin-left, margin-bottom, margin-right, margin-top

These methods adjust the margin placed around a text box.

They have no direct affect on rendering, except that the PDF::Content print() and say() methods, which returns the bbox around the rendered text. Note that margins can be negative, to trim text boxes.

method offset

A two member array giving the x,y displacement of the text, by default [0, 0]. These can be set to fine-tune the positioning of the text.

method bbox

The text-boxes bounding box, including margin and offset adjustments.

The bbox() method is defined as ```raku [ tb.margin-left, # x0 tb.margin-bottom, # y0 tb.width + tb.offset[1] + tb.margin-top #y1 ]

### method style

```raku
method style() returns PDF::Content::Text::Style

Styling delegate for this text box. See PDF::Content::Text::Style

This method also handles method font, font-size, leading, kern, WordSpacing, CharSpacing, HorizScaling, TextRender, TextRise, baseline-shift, space-width, underline-position, underline-thickness, font-height. For example $tb.font-height is equivalent to $tb.style.font-height.

method content-width

method content-width() returns Numeric

return the actual width of content in the text box

Calculated from the longest line in the text box.

method content-height

method content-height() returns Numeric

return the actual height of content in the text box

Calculated from the number of lines in the text box.

method comb

method comb(
    Str $_
) returns Seq

break a text string into word and whitespace fragments

method clone

method clone(
    :$style = Code.new,
    :$text = Code.new,
    |c
) returns PDF::Content::Text::Box

clone a text box

method width

method width() returns Numeric

return displacement width of a text box

method height

method height() returns Numeric

return displacement height of a text box

method render

method render(
    PDF::Content::Ops:D $gfx,
    Bool :$nl,
    Bool :$preserve = Bool::True
) returns List

render a text box to a content stream at current or given text position

method place-images

method place-images(
    $gfx
) returns Mu

flow any xobject images. This needs to be done after rendering and exiting text block

method Str

method Str() returns Str

return text split into lines