A Block of Text Placed on the Page

Set text inside a chosen rectangle, with its font, size and colour, and give one word in the middle of a sentence a style of its own.

See It in a Real PDF

Fonts Embedded in the File

Text set in a font embedded in the file, cut down to the letters actually used, and still searchable, copyable and readable aloud.

Open the PDF The Whole Example

Also shown in: Words That Follow a Curve · Prices Crossed out, a Shadow behind the Title · Text That Keeps to a Shape

Summary

As if the frame had been drawn in pencil: you say what goes inside, and the text arranges itself there, line after line, to the last word. On the way, a word can be picked out — bigger, bold, underlined, another colour — without breaking the sentence around it. This is the piece used everywhere, from the heading of an invoice to the small print at the foot of the page.

Technically

Asked for with "type": "text"

A text item lays a block of text inside a rectangle given in points, in page coordinates: the origin sits at the bottom left and the vertical axis goes up. The runs go into the page content stream between BT and ET, in the font resources the request declared. The content is a list of runs: a plain string takes the block's style, while an object overrides, for itself alone, the font, the size, the leading, the colour, the rules (underline, strikethrough, overline) or the stroke drawn round its letters. A run can also ask the server for the moment of rendering, formatted with a strftime pattern in the named time zone. The text accepts the pagination placeholders, resolved once the last page exists, which gives a footer reading "page 3 of 12" written once for the whole document.

Request Schema

Required keys: rect, an object of four coordinates llx, lly, urx, ury, each a number or a quoted expression (+ - * / ( ), variables {page_width}, {page_height}, {current_page}, {total_pages}, {llx}, {lly}, {urx}, {ury}, maximum depth 100); content, an array of runs; font, a string naming a font the request declared (standard_fonts, fonts, type1_fonts, type3_fonts, font_chains, font_variants); font_size, a number of points. A run takes three shapes: a bare string; an object {"text": …} with optional font, font_size, leading, underline, strikethrough, overline, color and outline, each holding for that run alone; an object {"date": "strftime pattern"} with an optional zone (an IANA name; absent, the moment is stamped in universal time). Optional keys on the block: align (left by default, right, center, justify); overlong (overflow by default, an over-wide word runs past the edge; break cuts it); leading (default 1.2 × font_size); break_after, the characters a line may break after (by default breaks happen at spaces and soft hyphens); break_at_punctuation, a boolean at false, which lets a line also break where its punctuation allows, after a slash or a hyphen inside a word; replacing, an object whose keys are single characters, each mapped to {"each": "…"}, put in place of every occurrence, or to {"run": "…"}, put once in place of every run of it, before the lines are broken, an empty string taking the character out; the runs are read as one text: what replaces a character is set in the style of the run it stands in, and a run of the character crossing from one run into the next gives way once, in the style of the run it starts in; underline, strikethrough, overline, booleans at false; color (default black); outline, an object of width, a required number of points, color (default black) and filled (default false), the stroke drawn round the letters of every run that names none of its own, hollow unless filled draws them solid as well; shadow, an object whose dx, dy and color are all required; pages, an array of one-based integers, default empty, meaning every page; id, a string another item refers to; relative_to, an object of id, edge (top or bottom), offset and an optional part (default: the last part laid); transform, six numbers; rotate, degrees counter-clockwise about the centre of the rectangle; layer, the name of a declared layer; clip, an object with a required segments and a rule (nonzero by default, even_odd), the shape the block is seen through; graphics_state, the name of a declared state the whole block, shadow included, is drawn under. Cross refusals: transform together with rotate; a clip whose segments are empty. Each of underline, strikethrough and overline, on the block or on a run, also takes an object {"position": …, "thickness": …} in place of true: the rule is then drawn with its top that many points from the baseline, below it where the number is negative, and that thick. Three more keys set how the letters stand: character_spacing, a number of points every glyph takes on top of the width the font gives it, above nought pushing the letters apart and below it pulling them together; horizontal_scaling, a percentage of that width the glyphs are drawn at, 80 narrowing them to four fifths and 120 widening them by a fifth, their height untouched, a scaling at or below nought refused; cut_mark, one character drawn at the end of a line where "overlong": "break" cuts a word too wide for the box, its width kept free when the cut is placed. The lines are broken to the widths the first two make. invisible, a boolean at false, true placing every letter where it would be drawn and painting none of it, so the words are selected, searched and copied and never seen: the layer of words laid over the picture of a scanned page, whatever outline the block states. described, where no element of the structure tree owns the block, an object of expansion, actual_text, alt and lang, what the run says for itself; it is refused beside tag or artifact. Three more keys set what a block shares with a flowed text block: last_align, how the last line of each paragraph is aligned, as align by default and flush left under justify; first_baseline, where the first baseline sits below the top of the rectangle, one of leading (default), ascender, cap_height or {"points": …}; tabs, an object of method, size, ruler, alignments and align_char saying where the tabulations the runs contain take the pen, a tabulation being set as a blank when it is absent. Two more keys come from a flowed text block too: leader, what is repeated across the gap a tabulation opens and across the room the last line of a paragraph leaves, one character set in the font, size and colour of the run beside it, or the object a flow block's leader takes, absent leaving those gaps empty; line_height, which of the styles a line passes through gives the line its height, tallest (default) or first, the style the line opens in, a leading stated winning over either.

A Whole Request That Creates a PDF

{
  "standard_fonts": [{"name": "sans", "face": "helvetica"}],
  "items": [
    {
      "type": "text",
      "rect": {"llx": 72, "lly": 740, "urx": 523, "ury": 780},
      "content": ["Invoice 1964413", {"text": " — paid", "color": [0.1, 0.45, 0.25]}],
      "font": "sans",
      "font_size": 16,
      "outline": {"width": 0.4, "color": [0.1, 0.45, 0.25], "filled": true}
    }
  ]
}

The line that sends it, in three languages

Text

Text in Paragraphs, with Indents and Tab Stops A Stamp Laid across the Page A Line of Words Set Along a Path A Row of Glyphs Asked for by Their Number Blocks Laid One under the Other, Page After Page

Where to Go Next

Every JSON key of a request, in one page The other twenty-two things you can draw

See the Prices See the Examples