Repository navigation
PDF Spec 09 Text Objects
Part of: PDF-Spec-09-Text
Navigation: PDF-Spec-09-Text-State | PDF-Spec-Index | PDF-Spec-09-Fonts
A PDF text object consists of operators that may show text strings, move the text position, and set text state and certain other parameters. In addition, three parameters may be specified only within a text object and shall not persist from one text object to the next:
- T m , the text matrix
- T lm , the text line matrix
- T rm , the text rendering matrix , which is actually just an intermediate result that combines the effects of text state parameters, the text matrix (T m ) , and the current transformation matrix
A text object begins with the BT operator and ends with the ET operator, as shown in the Example, and described in Table 107.
EXAMPLE
BT
… Zero or more text operators or other allowed operators …
ET
Table 107 - Text object operators
| Operands | Operator | Description |
|---|---|---|
| - | BT | Begin a text object, initializing the text matrix, T m , and the text line matrix, T lm , to the identity matrix. Text objects shall not be nested; a second BT shall not appear before an ET . |
| - | ET | End a text object, discarding the text matrix. |
These specific categories of text-related operators may appear in a text object:
- Text state operators , described in 9.3, "Text State Parameters and Operators"
- Text-positioning operators , described in 9.4.2, "Text-Positioning Operators"
- Text-showing operators , described in 9.4.3, "Text-Showing Operators"
The latter two sub-clauses also provide further details about these text object parameters. The other operators that may appear in a text object are those related to the general graphics state, colour, and marked content, as shown in Figure 9.
If a content stream does not contain any text, the Text procedure set may be omitted (see 14.2, "Procedure Sets"). In those circumstances, no text operators (including operators that merely set the text state) shall be present in the content stream, since those operators are defined in the same procedure set.
NOTE Although text objects cannot be statically nested, text might be shown using a Type 3 font whose glyph descriptions include any graphics objects, including another text object. Likewise, the current colour might be a tiling pattern whose pattern cell includes a text object.
Text space is the coordinate system in which text is shown. It shall be defined by the text matrix, T m , and the text state parameters T fs , T h , and T rise , which together shall determine the transformation from text space to user space. Specifically, the origin of the first glyph shown by a text-showing operator shall be placed at the origin of text space. If text space has been translated, scaled, or rotated, then the position, size, or orientation of the glyph in user space shall be correspondingly altered.
The text-positioning operators shall only appear within text objects.
Table 108 - Text-positioning operators
| Operands | Operator | Description |
|---|---|---|
| t x t y | Td | Move to the start of the next line, offset from the start of the current line by ( t x , t y ). t x and t y shall denote numbers expressed in unscaled text space units. More precisely, this operator shall perform these assignments: T m T lm 1 0 0 0 1 0 t x t y 1 T lm × = = |
| t x t y | TD | Move to the start of the next line, offset from the start of the current line by ( t x , t y ). As a side effect, this operator shall set the leading parameter in the text state. This operator shall have the same effect as this code: - t y TL t x t y Td |
Table 108 - Text-positioning operators (continued)
| Operands | Operator | Description |
|---|---|---|
| a b c d e f | Tm | Set the text matrix, T m , and the text line matrix, T lm : The operands shall all be numbers, and the initial value for T m and T lm shall be the identity matrix, [1 0 0 1 0 0]. Although the operands specify a matrix, they shall be passed to Tm as six separate numbers, not as an array. The matrix specified by the operands shall not be concatenated onto the current text matrix, but shall replace it. T m T lm a b 0 c d 0 e f 1 = = |
| - | T* | Move to the start of the next line. This operator has the same effect as the code 0 -T l Td where T l denotes the current leading parameter in the text state. The negative of T l is used here because T l is the text leading expressed as a positive number. Going to the next line entails decreasing the y coordinate. |
At the beginning of a text object, T m shall be the identity matrix; therefore, the origin of text space shall be initially the same as that of user space. The text-positioning operators , described in Table 108, alter T m and thereby control the placement of glyphs that are subsequently painted. Also, the text-showing operators , described in Table 109, update T m (by altering its e and f translation components) to take into account the horizontal or vertical displacement of each glyph painted as well as any character or word-spacing parameters in the text state.
Additionally, within a text object, a conforming reader shall keep track of a text line matrix, T lm , which captures the value of T m at the beginning of a line of text. The text-positioning and text-showing operators shall read and set T lm on specific occasions mentioned in Tables 108 and 109.
NOTE This can be used to compactly represent evenly spaced lines of text.
The text-showing operators (Table 109) shall show text on the page, repositioning text space as they do so. All of the operators shall interpret the text string and apply the text state parameters as described in Table 109.
The text-showing operators shall only appear within text objects.
Table 109 - Text-showing operators
| Operands | Operator | Description |
|---|---|---|
| string | Tj | Show a text string. |
| string | ' | Move to the next line and show a text string. This operator shall have the same effect as the code T* string Tj |
Table 109 - Text-showing operators (continued)
| Operands | Operator | Description |
|---|---|---|
| a w a c string | " | Move to the next line and show a text string, using a w as the word spacing and a c as the character spacing (setting the corresponding parameters in the text state). a w and a c shall be numbers expressed in unscaled text space units. This operator shall have the same effect as this code: a w Tw a c Tc string ' |
| array | TJ | Show one or more text strings, allowing individual glyph positioning. Each element of array shall be either a string or a number. If the element is a string, this operator shall show the string. If it is a number, the operator shall adjust the text position by that amount; that is, it shall translate the text matrix, T m . The number shall be expressed in thousandths of a unit of text space (see 9.4.4, "Text Space Details"). This amount shall be subtracted from the current horizontal or vertical coordinate, depending on the writing mode. In the default coordinate system, a positive adjustment has the effect of moving the next glyph painted either to the left or down by the given amount. Figure 46 shows an example of the effect of passing offsets to TJ . |
Figure 46 - Operation of the TJ operator in horizontal writing
| [ (AWAY again) ] TJ | AWAY again |
|---|---|
| [ (A) 120 (W) 120 (A) 95 (Y again) ] TJ | AWAYagain |
A string operand of a text-showing operator shall be interpreted as a sequence of character codes identifying the glyphs to be painted.
With a simple font, each byte of the string shall be treated as a separate character code. The character code shall then be looked up in the font's encoding to select the glyph, as described in 9.6.6, "Character Encoding".
With a composite font (PDF 1.2) , multiple-byte codes may be used to select glyphs. In this instance, one or more consecutive bytes of the string shall be treated as a single character code. The code lengths and the mappings from codes to glyphs are defined in a data structure called a CMap , described in 9.7, "Composite Fonts".
The strings shall conform to the syntax for string objects. When a string is written by enclosing the data in parentheses, bytes whose values are equal to those of the ASCII characters LEFT PARENTHESIS (28h), RIGHT PARENTHESIS (29h), and REVERSE SOLIDUS (5Ch) (backslash) shall be preceded by a REVERSE SOLIDUS) character. All other byte values between 0 and 255 may be used in a string object. These rules apply to each individual byte in a string object, whether the string is interpreted by the text-showing operators as single-byte or multiple-byte character codes.
Strings presented to the text-showing operators may be of any length-even a single character code per string-and may be placed on the page in any order. The grouping of glyphs into strings has no significance for the display of text. Showing multiple glyphs with one invocation of a text-showing operator such as Tj shall produce the same results as showing them with a separate invocation for each glyph.
- NOTE 6 The performance of text searching (and other text extraction operations) is significantly better if the text strings are as long as possible and are shown in natural reading order.
- NOTE 7 In some cases, the text that is extracted can vary depending on the grouping of glyphs into strings. See, for example, 14.8.2.3.3, "Reverse-Order Show Strings".
As stated in 9.4.2, "Text-Positioning Operators", text shall be shown in text space , defined by the combination of the text matrix, T m , and the text state parameters T fs , T h , and T rise . This determines how text coordinates are transformed into user space. Both the glyph's shape and its displacement (horizontal or vertical) shall be interpreted in text space.
- NOTE 1 Glyphs are actually defined in glyph space, whose definition varies according to the font type as discussed in 9.2.4, "Glyph Positioning and Metrics". Glyph coordinates are first transformed from glyph space to text space before being subjected to the transformations described in Note 2.
- NOTE 2 Conceptually, the entire transformation from text space to device space may be represented by a text rendering matrix , T rm :
T rm is a temporary matrix; conceptually, it is recomputed before each glyph is painted during a text-showing operation.
After the glyph is painted, the text matrix shall be updated according to the glyph displacement and any spacing parameters that apply. First, a combined displacement shall be computed, denoted by t x in horizontal writing mode or t y in vertical writing mode (the variable corresponding to the other writing mode shall be set to 0):
where w0 and w1 denote the glyph's horizontal and vertical displacements
T j denotes a number in a TJ array, if any, which specifies a position adjustment
T fs and T h denote the current text font size and horizontal scaling parameters in the graphics state
T c and T w denote the current character- and word-spacing parameters in the graphics state, if applicable
The text matrix shall then be then updated as follows:
A font shall be represented in PDF as a dictionary specifying the type of font, its PostScript name, its encoding, and information that can be used to provide a substitute when the font program is not available. Optionally, the font program may be embedded as a stream object in the PDF file.
The font types are distinguished by the Subtype entry in the font dictionary. Table 110 lists the font types defined in PDF. Type 0 fonts are called composite fonts ; other types of fonts are called simple fonts . In addition to fonts, PDF supports two classes of font-related objects, called CIDFonts and CMaps , described in 9.7.2, "CID-Keyed Fonts Overview". CIDFonts are listed in Table 110 because, like fonts, they are collections of glyphs; however, a CIDFont shall not be used directly but only as a component of a Type 0 font.
Table 110 - Font types
| Type | Subtype Value | Description |
|---|---|---|
| Type 0 | Type0 | (PDF 1.2) A composite font-a font composed of glyphs from a descendant CIDFont (see 9.7, "Composite Fonts") |
| Type 1 | Type1 | A font that defines glyph shapes using Type 1 font technology (see 9.6.2, "Type 1 Fonts"). |
| MMType1 | A multiple master font-an extension of the Type 1 font that allows the generation of a wide variety of typeface styles from a single font (see 9.6.2.3, "Multiple Master Fonts") | |
| Type 3 | Type3 | A font that defines glyphs with streams of PDF graphics operators (see 9.6.5, "Type 3 Fonts") |
| TrueType | TrueType | A font based on the TrueType font format (see 9.6.3, "TrueType Fonts") |
| CIDFont | CIDFontType0 | (PDF 1.2) A CIDFont whose glyph descriptions are based on Type 1 font technology (see 9.7.4, "CIDFonts") |
| CIDFontType2 | (PDF 1.2) A CIDFont whose glyph descriptions are based on TrueType font technology (see 9.7.4, "CIDFonts") |
For all font types, the term font dictionary refers to a PDF dictionary containing information about the font; likewise, a CIDFont dictionary contains information about a CIDFont. Except for Type 3, this dictionary is distinct from the font program that defines the font's glyphs. That font program may be embedded in the PDF file as a stream object or be obtained from some external source.
- NOTE 1 This terminology differs from that used in the PostScript language. In PostScript, a font dictionary is a PostScript data structure that is created as a direct result of interpreting a font program. In PDF, a font program is always treated as if it were a separate file, even when its content is embedded in the PDF file. The font program is interpreted by a specialized font interpreter when necessary; its contents never materialize as PDF objects.
- NOTE 2 Most font programs (and related programs, such as CIDFonts and CMaps) conform to external specifications, such as the Adobe Type 1 Font Format . This standard does not include those specifications. See the Bibliography for more information about the specifications mentioned in this clause.
- NOTE 3 The most predictable and dependable results are produced when all font programs used to show text are embedded in the PDF file. The following sub-clauses describe precisely how to do so. If a PDF file refers to font programs that are not embedded, the results depend on the availability of fonts in the conforming reader's environment. The following sub-clauses specify some conventions for referring to external font programs. However, some details of font naming, font substitution, and glyph selection are implementation-dependent and may vary among different conforming readers, writers and operating system environments.
Navigation: PDF-Spec-09-Text-State | PDF-Spec-Index | PDF-Spec-09-Fonts