10 Text

Contents

• 10.1 Introduction
• 10.2 Characters and their corresponding glyphs
• 10.3 Fonts, font tables and baselines
• 10.4 The 'text' element
• 10.5 The 'tspan' element
• 10.6 Text layout
  • 10.6.1 Text layout introduction
  • 10.6.2 Relationship with bidirectionality
  • 10.6.3 The 'direction' property
  • 10.6.4 The 'unicode-bidi' property
• 10.7 Text rendering order
• 10.8 Alignment properties
  • 10.8.1 Text alignment properties
• 10.9 Font selection properties
• 10.10 White space handling
• 10.11 Text in an area
  • 10.11.1 Introduction to text in an area
  • 10.11.2 The 'textArea' element
  • 10.11.3 The 'tbreak' element
  • 10.11.4 The 'line-increment' property
  • 10.11.5 The 'text-align' property
  • 10.11.6 The 'display-align' property
  • 10.11.7 Text in an area layout rules
• 10.12 Editable text fields
  • 10.12.1 The 'editable' attribute
• 10.13 Text selection and clipboard operations
• 10.14 Text search

10.1 Introduction

Text that is to be rendered as part of an SVG document fragment is specified using the text content block elements. The characters to be drawn are expressed as XML content inside the element.

SVG's text content block elements are rendered like other graphics elements. Thus, coordinate system transformations and painting features apply to text elements in the same way as they apply to shapes such as paths and rectangles.

Each 'text' element causes a single string of text to be rendered. The 'text' element performs no automatic line breaking or word wrapping. To achieve the effect of multiple lines of text, use one of the following methods:

• Use the 'textArea' element to specify a rectangular area in which to flow the text.
• Pre-compute the line breaks (which can be done by the author or authoring tool) and use individual 'text' elements to manually place the lines of text. (Note: this is discouraged for accessibility reasons.)
• Express the text to be rendered in another XML namespace such as XHTML [XHTML] embedded inline within a 'foreignObject' element. (Note: the exact semantics of this approach are not completely defined at this time.)

The text strings within 'text' elements shall be rendered in one straight line. SVG supports the following international text processing features for straight line text:

• left-to-right or bidirectional text (i.e., languages which intermix right-to-left and left-to-right text, such as Arabic and Hebrew)
• when SVG fonts are used, automatic selection of the correct glyph corresponding to the current form for Arabic and Han text

The layout rules for straight line text are described in Text layout.

Because SVG text is packaged as XML content:

• Text data in SVG content is readily accessible to the visually impaired (see Accessibility Support)
• In many viewing scenarios, the user will be able to search for and select text strings and copy selected text strings to the system clipboard (see Text search and Text selection and clipboard operations)
• XML-compatible Web search engines will find text strings in SVG content with no additional effort over what they need to do to find text strings in other XML documents

Multi-language SVG content is possible by substituting different text strings based on the user's preferred language.

For accessibility reasons, it is recommended that text which is included in a document have appropriate semantic markup to indicate its function. See SVG accessibility guidelines for more information.

10.2 Characters and their corresponding glyphs

In XML [XML10, XML11], textual content is defined in terms of a sequence of XML characters, where each character is defined by a particular Unicode code point [UNICODE]. Fonts, on the other hand, consist of a collection of glyphs and other associated information, such as font tables. A glyph is a presentable form of one or more characters (or a part of a character in some cases). Each glyph consists of some sort of identifier (in some cases a string, in other cases a number) along with drawing instructions for rendering that particular glyph.

In many cases, there is a one-to-one mapping of Unicode characters (i.e., Unicode code points) to glyphs in a font. For example, it is common for a font designed for Latin languages (where the term Latin is used for European languages such as English with alphabets similar to or derivative to the Latin language) to contain a single glyph for each of the standard ASCII characters (i.e., A-to-Z, a-to-z, 0-to-9, plus the various punctuation characters found in ASCII). Thus, in most situations, the string "XML", which consists of three Unicode characters, would be rendered by the three glyphs corresponding to "X", "M" and "L", respectively.

In various other cases, however, there is not a strict one-to-one mapping of Unicode characters to glyphs. Some of the circumstances when the mapping is not one-to-one:

• Ligatures — For best looking typesetting, it is often desirable that particular sequences of characters are rendered as a single glyph. An example is the word "office". Many fonts will define an "ffi" ligature. When the word "office" is rendered, sometimes the user agent will render the glyph for the "ffi" ligature instead of rendering distinct glyphs (i.e., "f", "f" and "i") for each of the three characters. Thus, for ligatures, multiple Unicode characters map to a single glyph. Note that for proper rendering of many languages, ligatures are required for certain character combinations, and are not optional typographic features. For example, this is the case for most languages throughout South and South East Asia.
• Composite characters — In many situations, commonly used adornments such as diacritical marks will be stored once in a font as a particular glyph and then composed with one or more other glyphs to result in the desired character. For example, it is possible that a font engine might render the é character by first rendering the glyph for e and then rendering the glyph for ´ (the accent mark) such that the accent mark will appear over the e. In this situation, a single Unicode character maps to multiple glyphs.
• Context-sensitive glyph positioning — In many scripts, the precise positioning of the glyph for a given character (especially diacritics) will vary according to the visual context. For example, Thai tone marks are rendered above the base consonant, but need to be moved upwards further if a vowel-sign also appears above the base consonant. The same character is used in memory, but the final location of the glyph is sensitive to context.
• Complex positioning of character glyphs — In scripts such as those used for Indian languages, a combining vowel character that appears after a base consonant in memory may be displayed to the left of the base consonant, or on two sides of the base consonant, (i.e., the left-most glyph in rendered text may not be the first character in a text element.) Indeed, such vowel characters may be rendered to the left of, or on more than one side of, a cluster of consonants that ends with the character they follow in memory. On the other hand, a Hindi RA character at the beginning of a consonant cluster in memory may be displayed over a following vowel sign to the right of the following syllabic cluster. The location, from left to right, in which glyphs are displayed in these scripts can differ significantly from the order of the characters in memory.
• Glyph substitution — Many typography systems examine the nature of the textual content and utilize different glyphs in different circumstances. For example, in Arabic, the same Unicode character might render as any of four different glyphs, depending on such factors as whether the character appears at the start, the end or the middle of a sequence of cursively joined characters. Different glyphs might be used for a punctuation character depending on inline-progression-direction (e.g., horizontal vs. vertical). In these situations, a single Unicode character might map to one of several alternative glyphs.
• In many languages, particular sequences of characters will be converted into multiple glyphs such that parts of a particular character are in one glyph and the remainder of that character is in another glyph.

In many situations, the algorithms for mapping from characters to glyphs are system-dependent, resulting in the possibility that the rendering of text might be (usually slightly) different when viewed in different user environments. If the author of SVG content requires precise selection of fonts and glyphs, then it is recommended that the necessary fonts (potentially subsetted to include only the glyphs needed for the given document) be available either as SVG fonts embedded within the SVG content or as WebFonts posted at the same Web location as the SVG content.

Throughout this chapter, the term character shall be equivalent to the definition of a character in XML [XML11].

10.3 Fonts, font tables and baselines

A font consists of a collection of glyphs together with the information (the font tables) necessary to use those glyphs to present characters on some medium. The combination of the collection of glyphs and the font tables is called the font data. The font tables include the information necessary to map characters to glyphs, to determine the size of glyph areas and to position the glyph area. Each font table consists of one or more font characteristics, such as the 'font-weight' and 'font-style'.

The geometric font characteristics are expressed in a coordinate system based on the EM box. (The EM is a relative measure of the height of the glyphs in the font; see CSS2 em square ([CSS2], section 15.4.3).) The box 1 EM high and 1 EM wide is called the design space. This space is given geometric coordinates by sub-dividing the EM into a number of units-per-em ([CSS2], section 15.3.4).

Note: Units-per-em is a font characteristic. A typical value for units-per-EM is 1000 or 2048.

The coordinate space of the EM box is called the design space coordinate system. For scalable fonts, the curves and lines that are used to draw a glyph are represented using this coordinate system.

Note: Most often, the (0,0) point in this coordinate system is positioned on the left edge of the EM box, but not at the bottom left corner. The Y coordinate of the bottom of a roman capital letter is usually zero. And the descenders on lowercase roman letters have negative coordinate values.

SVG assumes that the font tables will provide at least three font characteristics: an ascent, a descent and a set of baseline-tables. The ascent is the distance to the top of the EM box from the (0,0) point of the font; the descent is the distance to the bottom of the EM box from the (0.0) point of the font. The baseline-table is explained below.

Note: Within an OpenType font, for horizontal writing-modes, the ascent and descent are given by the sTypoAscender and sTypoDescender entries in the OS/2 table. For vertical writing-modes, the descent (the distance, in this case from the (0,0) point to the left edge of the glyph) is normally zero because the (0,0) point is on the left edge. The ascent for vertical writing-modes is either 1 em or is specified by the ideographic top baseline value in the OpenType Base table for vertical writing-modes.

In horizontal writing-modes, the glyphs of a given script are positioned so that a particular point on each glyph, the alignment-point, is aligned with the alignment-points of the other glyphs in that script. The glyphs of different scripts, for example, Western, Northern Indic and Far-Eastern scripts, are typically aligned at different points on the glyph. For example, Western glyphs are aligned on the bottoms of the capital letters, northern indic glyphs are aligned at the top of a horizontal stroke near the top of the glyphs and far-eastern glyphs are aligned either at the bottom or center of the glyph. Within a script and within a line of text having a single font-size, the sequence of alignment-points defines, in the inline-progression-direction, geometric line called a baseline. Western and most other alphabetic and syllabic glyphs are aligned to an "alphabetic" baseline, the northern indic glyphs are aligned to a "hanging" baseline and the far-eastern glyphs are aligned to an "ideographic" baseline.

A baseline-table specifies the position of one or more baselines in the design space coordinate system. The function of the baseline table is to facilitate the alignment of different scripts with respect to each other when they are mixed on the same text line. Because the desired relative alignments may depend on which script is dominant in a line (or block), there may be a different baseline table for each script. In addition, different alignment positions are needed for horizontal and vertical writing modes. Therefore, the font may have a set of baseline tables: typically, one or more for horizontal writing-modes and zero or more for vertical writing-modes.

Note: Some fonts may not have values for the baseline tables. Heuristics are suggested for approximating the baseline tables when a given font does not supply baseline tables.

SVG further assumes that for each glyph in the font data for a font, there is a width value, an alignment-baseline and an alignment-point for horizontal writing-mode. (Vertical writing-mode is not supported in SVG Tiny 1.2.)

In addition to the font characteristics required above, a font may also supply substitution and positioning tables that can be used by a formatter to re-order, combine and position a sequence of glyphs to make one or more composite glyphs. The combination may be as simple as a ligature, or as complex as an indic syllable which combines, usually with some re-ordering, multiple consonants and vowel glyphs.

10.4 The 'text' element

The 'text' element defines a graphics element consisting of text. The XML content within the 'text' element, along with relevant attributes and properties and character-to-glyph mapping tables within the font itself, define the glyphs to be rendered. (See Characters and their corresponding glyphs.) The attributes and properties on the 'text' element indicate such things as the writing direction, font specification and painting attributes which describe how exactly to render the characters. Subsequent sections of this chapter describe the relevant text-specific attributes and properties, in particular text layout and bidirectionality.

Since 'text' elements are rendered using the same rendering methods as other graphics elements, all of the same coordinate system transformations and painting features that apply to shapes such as paths and rectangles also apply to 'text' elements.

Text behaves like other graphical objects, and it is therefore possible to apply a gradient to text. When this facility is applied to text then the object bounding box units are computed relative to the entire 'text' element in all cases, even when different effects are applied to different 'tspan' elements within the same 'text' element.

The 'text' element renders its first glyph (after bidirectionality reordering) at the initial current text position, which is established by the 'x' and 'y' attributes on the 'text' element (with possible adjustments due to the value of the 'text-anchor' property). After the glyph(s) corresponding to the given character is (are) rendered, the current text position is updated for the next glyph. In the simplest case, the new current text position is the previous current text position plus the glyph's advance value. See text layout for a description of glyph placement and glyph advance.

    <define name='text'>
      <element name='text'>
        <ref name='text.AT'/>
        <zeroOrMore><ref name='svg.TextCommon.group'/></zeroOrMore>
      </element>
    </define>

    <define name='text.AT' combine='interleave'>
      <ref name='svg.Properties.attr'/>
      <ref name='svg.Core.attr'/>
      <ref name='svg.Conditional.attr'/>
      <ref name='svg.FocusHighlight.attr'/>
      <ref name='svg.Editable.attr'/>
      <ref name='svg.Focus.attr'/>
      <ref name='svg.Transform.attr'/>
      <optional>
        <attribute name='x' svg:animatable='true' svg:inheritable='false'>
          <ref name='Coordinates.datatype'/>
        </attribute>
      </optional>
      <optional>
        <attribute name='y' svg:animatable='true' svg:inheritable='false'>
          <ref name='Coordinates.datatype'/>
        </attribute>
      </optional>
      <optional>
        <attribute name='rotate' svg:animatable='true' svg:inheritable='false'>
          <ref name='Numbers.datatype'/>
        </attribute>
      </optional>
    </define>

Example text01 below contains the text string "Hello, out there" which will be rendered onto the canvas using the Verdana font family with the glyphs filled with the color blue.

Example: 10_01.svg

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"
     width="10cm" height="3cm" viewBox="0 0 1000 300">

  <desc>Example text01 - 'Hello, out there' in blue</desc>

  <text x="250" y="150" 
        font-family="Verdana" font-size="55" fill="blue">
    Hello, out there
  </text>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2"/>
</svg>

10.5 The 'tspan' element

Within a text content block element, graphic and font properties can be adjusted by including a 'tspan' element.

    <define name='tspan'>
      <element name='tspan'>
        <ref name='tspan.AT'/>
        <zeroOrMore><ref name='svg.TextCommon.group'/></zeroOrMore>
      </element>
    </define>

    <define name='tspan.AT' combine='interleave'>
      <ref name='svg.Properties.attr'/>
      <ref name='svg.FocusHighlight.attr'/>
      <ref name='svg.Core.attr'/>
      <ref name='svg.Conditional.attr'/>
      <ref name='svg.Focus.attr'/>
    </define>

The following examples show basic use of the 'tspan' element.

Example tspan01 uses a 'tspan' element to indicate that the word "not" is to use a bold font and have red fill.

Example: 10_03.svg

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"
     width="10cm" height="3cm" viewBox="0 0 1000 300">

  <desc>Example tspan01 - using tspan to change visual attributes</desc>

  <g font-family="Verdana" font-size="45">
    <text x="200" y="150" fill="blue">
      You are
        <tspan font-weight="bold" fill="red" >not</tspan>
      a banana.
    </text>
  </g>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2"/>
</svg>

Within a text content block element, graphic and font properties can be adjusted by including a 'tspan' element. Positional attributes such as 'x', 'y', and 'rotate' are not available on 'tspan' in SVG Tiny 1.2.

10.6 Text layout

10.6.1 Text layout introduction

This section describes the text layout features supported by SVG. Text layout is described in a general and directionally neutral way, to provide a single reference point for layout information which applies to left-to-right (e.g., Latin scripts), bidirectional (e.g., Hebrew or Arabic) and vertical (e.g., Asian scripts). In SVG Tiny 1.2, vertical writing is not supported. The descriptions in this section assume straight line text (i.e., text that is either strictly horizontal or vertical with respect to the current user coordinate system).

For each text content block element, the SVG user agent determines the current reference orientation. The reference orientation is the vector pointing towards negative infinity in Y within the current user coordinate system. (Note: in the initial coordinate system, the reference orientation is up.)

Based on the reference orientation the SVG user agent determines the current inline-progression-direction. For left-to-right text, the inline-progression-direction points 90 degrees clockwise from the reference orientation vector. For right-to-left text, the inline progression points 90 degrees counter-clockwise from the reference orientation vector.

Based on the reference orientation the SVG user agent determines the current block-progression-direction. For left-to-right and right-to-left text, the block-progression-direction points 180 degrees from the reference orientation vector because the only available horizontal writing modes are lr-tb and rl-tb.

In processing a given text content block element, the SVG user agent keeps track of the current text position. The initial current text position is established by the 'x' and 'y' attributes on the text content block element.

The current text position is adjusted after each glyph to establish a new current text position at which the next glyph shall be rendered. The adjustment to the current text position is based on the current inline-progression-direction, glyph-specific advance values corresponding to the glyph orientation of the glyph just rendered, kerning tables in the font and the current values of various attributes and properties, such as the spacing properties and any 'x' and 'y' attributes on text content block elements. If a glyph does not provide explicit advance values corresponding to the current glyph orientation, then an appropriate approximation should be used. For vertical text, a suggested approximation is the sum of the ascent and descent values for the glyph. Another suggested approximation for an advance value for both horizontal and vertical text is the size of an em (see 'units-per-em').

For each glyph to be rendered, the SVG user agent determines an appropriate alignment-point on the glyph which will be placed exactly at the current text position. The alignment-point is determined based on glyph cell metrics in the glyph itself, the current inline-progression-direction and the glyph orientation relative to the inline-progression-direction. For most uses of Latin text the alignment-point in the glyph will be the intersection of left edge of the glyph cell (or some other glyph-specific x-axis coordinate indicating a left-side origin point) with the Latin baseline of the glyph. For many cases with top-to-bottom vertical text layout, the reference point will be either a glyph-specific origin point based on the set of vertical baselines for the font or the intersection of the center of the glyph with its top line (see [CSS2] section 15.3.8 for a definition of top line). If a glyph does not provide explicit origin points corresponding to the current glyph orientation, then an appropriate approximation should be used, such as the intersection of the left edge of the glyph with the appropriate horizontal baseline for the glyph or intersection of the top edge of the glyph with the appropriate vertical baseline. If baseline tables are not available, user agents should establish baseline tables that reflect common practice.

Adjustments to the current text position are either absolute position adjustments or relative position adjustments. An absolute position adjustment occurs in the following circumstances:

• At the start of a 'text' element
• At the start of a 'textArea' element
• For each character within a 'text' element which has an 'x' or 'y' attribute value assigned to it explicitly

All other position adjustments to the current text position are relative position adjustments.

Each absolute position adjustment defines a new text chunk. Absolute position adjustments impact text layout in the following ways:

• Ligatures only occur when a set of characters which might map to a ligature are all in the same text chunk.
• Each text chunk represents a separate block of text for alignment due to 'text-anchor' property values.
• Reordering of characters due to bidirectionality only occurs within a text chunk. Reordering does not happen across text chunks.

The following additional rules apply to ligature formation:

• As in the discussion of the CSS2 spacing properties ([CSS2], section 16.4), when the resultant space between two characters is not the same as the default letter spacing, user agents should either not use ligatures or not apply letter-spacing depending on their knowledge of which behavior will produce the most coherent results for the script being used (for example, when the letter-spacing is high it is likely that breaking ligatures will produce the best result with Roman scripts, but be less than optimal for Arabic scripts, where ignoring the letter-spacing and maintaining the ligatures will be preferred).
• Ligature formation must only occur between characters that are not separated by element markup, and must still be enabled between characters separated by other XML markup, such as comments, processing instructions, or CDATA sections. Ligature processing must take place only after entity and character references have been resolved. For example, assuming that there is a ligature defined for the string "dahut" and that the '&hu-ent;' entity reference contains the string "hu", in all the following examples the "dahut" ligature will be enabled:
  • <text>Le dahut vit dans les Alpes grenobloises.</text>
  • <text>Le da&hu-ent;t vit dans les Alpes grenobloises.</text>
  • <text>Le da<!-- random comment -->hut vit dans les Alpes grenobloises.</text>
  • <text>Le da<?turn around?>hut vit dans les Alpes grenobloises.</text>
  • <text>Le da<![CDATA[hu]>t vit dans les Alpes grenobloises.</text>

  But it will not be enabled in the following case:

  • <text>Le da<tspan fill='orange'>h</tspan>ut vit dans les Alpes grenobloises.</text>
• As mentioned above, ligature formation should not be enabled for the glyphs corresponding to characters within different text chunks.

10.6.2 Relationship with bidirectionality

The characters in certain scripts are written from right to left. In some documents, in particular those written with the Arabic or Hebrew script, and in some mixed-language contexts, text in a single line may appear with mixed directionality. This phenomenon is called bidirectionality, or "bidi" for short.

The Unicode standard ([UNICODE], specifically [UAX9]) defines a complex algorithm for determining the proper directionality of text. The algorithm consists of an implicit part based on character properties, as well as explicit controls for embeddings and overrides. The SVG user agent applies this bidirectional algorithm when determining the layout of characters within a text content block element.

The 'direction' and 'unicode-bidi' properties allow authors to override the inherent directionality of the content characters and thus explicitly control how the elements and attributes of a document language map to this algorithm. These two properties are applicable to all characters whose glyphs are perpendicular to the inline-progression-direction.

In many cases, the bidirectional algorithm from Unicode [UNICODE] produces the desired result automatically, and in such cases the author does not need to use these properties. For other cases, such as when using right-to-left languages, it may be sufficient to add the 'direction' property to the rootmost 'svg' element, and allow that direction to inherit to all text elements, as in the following example (which may be used as a template):

Example: rtl-text.svg

<svg xmlns="http://www.w3.org/2000/svg"
     width="100%" height="100%" viewBox="0 0 400 400"
     direction="rtl" xml:lang="fa">

  <title direction="ltr" xml:lang="en">Right-to-left Text</title>
  <desc direction="ltr" xml:lang="en">
    A simple example for using the 'direction' property in documents
    that predominantly use right-to-left languages.
  </desc>

  <text x="200" y="200" font-size="20">داستان SVG Tiny 1.2 طولا ني است.</text>

</svg>

Below is another example, where where implicit bidi reordering is not sufficient:

Example: rtl-complex.svg

<?xml version="1.0" encoding="utf-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%" height="100%" viewBox="0 0 400 400"
     direction="rtl" xml:lang="he">

  <title direction="ltr" xml:lang="en">Right-to-left Text</title>
  <desc direction="ltr" xml:lang="en">
    An example for using the 'direction' and 'unicode-bidi' properties
    in documents that predominantly use right-to-left languages.
  </desc>

  <text x="200" y="200" font-size="20"> כתובת 
	MAC:&#x200F;
    	<tspan direction="ltr" unicode-bidi="embed">00-24-AF-2A-55-FC</tspan> 
	</text>

</svg>

Within text content elements, the alignment of text with regards to the 'text-anchor' or 'text-align' properties is determined by the value of the 'direction' property. For example, given a 'text' element with a 'text-anchor' value of "end", for a 'direction' value of "ltr", the text will extend to the left of the position of the 'text' element's 'x' attribute value, while for 'direction' value of "rtl", the text will extend to the right of the position of the 'text' element's 'x' attribute value.

A more complete discussion of bidirectionality can be found in the Text direction section of CSS 2 ([CSS2], section 9.10).

The processing model for bidirectional text is as follows. The user agent processes the characters which are provided in logical order (i.e., the order the characters appear in the original document). The user agent determines the set of independent blocks within each of which it should apply the Unicode bidirectional algorithm. Each text chunk represents an independent block of text. After processing the Unicode bidirectional algorithm and properties 'direction' and 'unicode-bidi' on each of the independent text blocks, the user agent will have a potentially re-ordered list of characters which are now in left-to-right rendering order. While kerning or ligature processing might be font-specific, the preferred model is that kerning and ligature processing occurs between combinations of characters or glyphs after the characters have been re-ordered.

10.6.3 The 'direction' property

This property specifies the base writing direction of text and the direction of embeddings and overrides (see 'unicode-bidi') for the Unicode bidirectional algorithm. For the 'direction' property to have any effect on an element that does not by itself establish a new text chunk (such as the 'tspan' element in SVG 1.2 Tiny), the 'unicode-bidi' property's value must be embed or bidi-override.

Note: though this property can be declared on any element for purposes of inheritance, it only affects text content. It does not effect the coordinate system or the positioning of shapes.

Except for any additional information provided in this specification, the normative definition of the property is found in CSS 2 ([CSS2], section 9.10).

10.6.4 The 'unicode-bidi' property

Except for any additional information provided in this specification, the normative definition of the property is found in CSS 2 ([CSS2], section 9.10).

10.7 Text rendering order

The glyphs associated with the characters within text content block elements are rendered in the logical order of the characters in the original document, independent of any re-ordering necessary for visual display (e.g to implement bidirectionality). Thus, for text that goes right-to-left visually, the glyphs associated with the rightmost character are rendered before the glyphs associated with the other characters, as they come earlier in logical order.

Additionally, each distinct glyph is rendered in its entirety (i.e., it is filled and stroked as specified by the 'fill' and 'stroke' properties) before the next glyph gets rendered.

10.8 Alignment properties

10.8.1 Text alignment properties

The 'text-anchor' property is used to align a string of text relative to a given point, along a given axis. This axis of alignment varies by writing mode; for horizontal writing mode (the norm for Latin or Arabic) the axis is horizontal, while for vertical writing mode (often used for Japanese) the axis is vertical. (Note: SVG Tiny 1.2 does not include support for vertical text.) The point of orientation depends upon the 'text-anchor' property value.

The 'text-anchor' property is applied to each individual text chunk within a given 'text' element. Each text chunk has an initial current text position, which represents the point in the user coordinate system resulting from (depending on context) application of the 'x' and 'y' attributes on the 'text' element assigned explicitly to the first rendered character in a text chunk.

Values have the following meanings (where right, left, top, and bottom refer to alignment in an untransformed coordinate space):

start

The rendered characters are aligned such that the start of the resulting rendered text is at the initial current text position. For an element with a 'direction' property value of "ltr" (typical for most European languages), the left side of the text is rendered at the initial text position. For an element with a 'direction' property value of "rtl" (typical for Arabic and Hebrew), the right side of the text is rendered at the initial text position. For an element with a vertical primary text direction (often typical for Asian text), the top side of the text is rendered at the initial text position. (Note: SVG Tiny 1.2 does not include support for vertical text.)

middle

The rendered characters are aligned such that the geometric middle of the resulting rendered text is at the initial current text position.

end

The rendered characters are aligned such that the end of the resulting rendered text is at the initial current text position. For an element with a 'direction' property value of "ltr" (typical for most European languages), the right side of the text is rendered at the initial text position. For an element with a 'direction' property value of "rtl" (typical for Arabic and Hebrew), the left side of the text is rendered at the initial text position. For an element with a vertical primary text direction (often typical for Asian text), the bottom of the text is rendered at the initial text position. (Note: SVG Tiny 1.2 does not include support for vertical text.)

10.9 Font selection properties

SVG uses the following font specification properties. Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9).

This property indicates which font family is to be used to render the text, specified as a prioritized list of font family names and/or generic family names. Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9.2).

This property specifies whether the text is to be rendered using a normal, italic or oblique face. The font-style value "backslant" defined in XSL 1.1 is not supported. Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9.7).

This property indicates whether the text is to be rendered using the normal glyphs for lowercase characters or using small-caps glyphs for lowercase characters. Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9.8).

This property refers to the boldness or lightness of the glyphs used to render the text, relative to other fonts in the same font family. Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9.9).

Non-numeric values are interpreted as follows:

normal

Same as "400".

bold

Same as "700".

bolder

Specifies the next weight that is assigned to a font that is darker than the inherited one. If there is no such weight, it simply results in the next darker numerical value (and the font remains unchanged), unless the inherited value was "900", in which case the resulting weight is also "900".

lighter

Specifies the next weight that is assigned to a font that is lighter than the inherited one. If there is no such weight, it simply results in the next lighter numerical value (and the font remains unchanged), unless the inherited value was "100", in which case the resulting weight is also "100".

This property refers to the size of the font from baseline to baseline when multiple lines of text are set solid in a multiline layout environment. The SVG user agent processes the <length> as a height value in the current user coordinate system. Percentage values are not supported.

Except for any additional information provided in this specification, the normative definition of the property is in XSL 1.1 ([XSL], section 7.9.4).

10.10 White space handling

SVG supports the standard XML attribute 'xml:space' to specify the handling of white space characters within a given text content block element's character data. Note that any child element of a text content block element may also have an 'xml:space' attribute which will apply to that child element's text content. The SVG user agent has special processing rules associated with this attribute as described below. These are behaviors that occur subsequent to XML parsing [XML11] and do not affect the contents of the Document Object Model (DOM) [DOM3].

The following example illustrates that line indentation can be important when using xml:space="default". The fragment below show two pairs of similar 'text' elements, with both 'text' elements using xml:space='default'. For these examples, there is no extra white space at the end of any of the lines (i.e., the line break occurs immediately after the last visible character).

[01]  <text xml:space='default'>
[02]    WS example
[03]    indented lines
[04]  </text>
[05]  <text xml:space='preserve'>WS example indented lines</text>
[06]
[07]  <text xml:space='default'>
[08]WS example
[09]non-indented lines
[10]  </text>
[11]  <text xml:space='preserve'>WS examplenon-indented lines</text>

The first pair of 'text' elements above show the effect of indented character data. The attribute xml:space='default' in the first 'text' element instructs the SVG user agent to:

• convert all tabs (if any) to space characters,
• strip out all line breaks (i.e., strip out the line breaks at the end of lines [01], [02] and [03]),
• strip out all leading space characters (i.e., strip out space characters before "WS example" on line [02]),
• strip out all trailing space characters (i.e., strip out space characters before "</text>" on line [04]),
• consolidate all intermediate space characters (i.e., the space characters before "indented lines" on line [03]) into a single space character.

The second pair of 'text' elements above show the effect of non-indented character data. The attribute xml:space='default' in the third 'text' element instructs the SVG user agent to:

• convert all tabs (if any) to space characters,
• strip out all line breaks (i.e., strip out the line breaks at the end of lines [07], [08] and [09]),
• strip out all leading space characters (there are no leading space characters in this example),
• strip out all trailing space characters (i.e., strip out space characters before "</text>" on line [10]),
• consolidate all intermediate space characters into a single space character (in this example, there are no intermediate space characters).

Note that XML parsers are required to convert the standard representations for a newline indicator (e.g., the literal two-character sequence "#xD#xA" or the stand-alone literals #xD or #xA) into the single character #xA before passing character data to the application. See XML end-of-line handling ([XML11], section 2.11).

Any features in the SVG language or the SVG DOM that are based on character position number are based on character position after applying the white space handling rules described here. In particular, if xml:space="default", it is often the case that white space characters are removed as part of processing. Character position numbers index into the text string after the white space characters have been removed per the rules in this section.

10.11 Text in an area

10.11.1 Introduction to text in an area

The 'textArea' element allows simplistic wrapping of text content within a given region. This profile of SVG specifies a single rectangular region. Other profiles may allow a sequence of arbitrary shapes.

Text wrapping via the 'textArea' element is available as a lightweight and convenient facility for simple text wrapping where a complete box model layout engine is not required.

The layout of wrapped text is user agent dependent; thus, content developers need to be aware that there might be different results, particularly with regard to where line breaks occur.

The minimal layout facilities required for text in an area are described in text in an area layout rules.

Example textArea01 below contains a text string which will wrap into a rectangular area. Any text which does not fit will not be rendered.

Example: textArea01.svg

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
     version="1.2" baseProfile="tiny" viewBox="0 0 220 320">

  <title>Basic textflow</title>

  <textArea font-size="25" font-family="Georgia" x="10" y="10" width="200" 
        height="300">Tomorrow, and tomorrow, and
        tomorrow; creeps in this petty pace from day to day, until the last syll&#xAD;able of recorded
        time. And all our yesterdays have lighted fools the way to dusty death.</textArea>
  <rect x="5" y="5" width="210" height="310" stroke-width="3" stroke="#777" fill="none"/>
</svg>

10.11.2 The 'textArea' element

    <define name='textArea'>
      <element name='textArea'>
        <ref name='textArea.AT'/>
        <zeroOrMore>
          <choice>
            <element name='tspan'>
              <ref name='tspan.AT'/>
              <zeroOrMore>
                <choice>
                  <ref name='tbreak'/>
                  <ref name='svg.TextCommon.group'/>
                </choice>
              </zeroOrMore>
            </element>
            <ref name='svg.TextCommon.group'/>
          </choice>
        </zeroOrMore>
      </element>
    </define>

    <define name='textArea.AT' combine='interleave'>
      <ref name='svg.Properties.attr'/>
      <ref name='svg.FocusHighlight.attr'/>
      <ref name='svg.Core.attr'/>
      <ref name='svg.Conditional.attr'/>
      <ref name='svg.Focus.attr'/>
      <ref name='svg.Transform.attr'/>
      <ref name='svg.XY.attr'/>
      <ref name='svg.Editable.attr'/>
      <optional>
        <attribute name='width' svg:animatable='true' svg:inheritable='false'>
          <choice>
            <ref name='Length.datatype'/>
            <value>auto</value>
          </choice>
        </attribute>
      </optional>
      <optional>
        <attribute name='height' svg:animatable='true' svg:inheritable='false'>
        <choice>
          <ref name='Length.datatype'/>
          <value>auto</value>
        </choice>
        </attribute>
      </optional>
    </define>

10.11.3 The 'tbreak' element

The 'tbreak' element is an empty element that forcibly breaks the current line of text, even if the current line of text is empty (i.e. multiple consecutive 'tbreak' elements each cause a line break.)

    <define name='tbreak'>
      <element name='tbreak'>
        <ref name='tbreak.AT'/>
        <empty/>
      </element>
    </define>

    <define name='tbreak.AT' combine='interleave'>
      <ref name='svg.Core.attr'/>
      <ref name='svg.Conditional.attr'/>
    </define>

The 'tbreak' element has no attributes aside from the standard core and conditional attributes.

10.11.4 The 'line-increment' property

The 'line-increment' property provides limited control over the size of each line in the block-progression-direction. This property applies to the 'textArea' element, and to child elements of the 'textArea' element. The 'line-increment' property must not have any effect when used on an element which is not, or does not have as an ancestor, a 'textArea' element.

Values for the property have the following meaning:

auto

Subsequent lines are offset from the previous line by the maximum font-size for any glyphs drawn within that line, multiplied by some reasonable value for default line spacing. This specification recommends a value of 1.1 for this multiplier.

<number>

Subsequent lines are offset from the previous line by this amount (in user units). Negative values are unsupported.

10.11.5 The 'text-align' property

Alignment in the inline progression direction in flowing text is provided by the text-align property. It is a modified version of the XSL 1.1 text-align property ([XSL], section 7.16.9).

For details refer to the XSL 1.1 text-align property ([XSL], section 7.16.9). Note that SVG does not require user agents to support the following values for this property: justify, inside, outside, <string>, left, or right. The lacuna value is start.

As with the 'text-anchor' property, the values start and end are dependent on the value of the 'direction' property (typically, as appropriate for the writing system being used).

• For left to right horizontal (French, Russian, Thai, etc.): start is left and end is right
• For right to left horizontal (Hebrew, Arabic, etc.): start is right and end is left
• For top to bottom vertical (vertical Chinese, etc.): start is top and end is bottom (Note: SVG Tiny 1.2 does not include support for vertical text.)

10.11.6 The 'display-align' property

The 'display-align' property specifies the alignment, in the block-progression-direction, of the text content of the 'textArea' element.

Values for the property have the following meaning:

auto

For SVG, auto is equivalent to before.

before

The before-edge of the first line is aligned with the before-edge of the first region.

center

The lines are centered in the block-progression-direction.

after

The after-edge of the last line is aligned with the after-edge of the last region.

The following sentence is informative: For a better understanding of the 'display-align' property this diagram from the XSL specification (the final diagram in [XSL], section 4.2.3) illustrates the correspondence between the various edge names for a mixed writing-mode example (western and japanese writing-mode).

10.11.7 Text in an area layout rules

Text in an area layout is defined as a post processing step to the standard text layout model of SVG.

A conformant SVG user agent can implement a simplistic layout algorithm which consists simply of inserting line breaks whenever the content explicitly specifies a line break with a 'tbreak' element or when the current line cannot fit all of the remaining glyphs. Any lines of glyphs that do not completely fit within the region(s) are not rendered.

SVG user agents should implement a line-breaking algorithm that supports at a minimum the features described below as a post processing step to SVG's standard text layout model.

1. The text is processed in logical order to determine line breaking opportunities between characters, according to Unicode Standard Annex No. 14 [UAX14].
2. Text layout is performed as normal, on one infinitely long line; soft hyphens are included in the line. The result is a set of positioned Glyphs.
3. The first line is positioned such that its before edge is flush against the region's before edge, relative to the block-progression-direction.
4. Glyphs represent a character or characters within a word. Each glyph is associated with the word that contains its respective characters. In cases where characters from multiple words contribute to the same glyph, the words are merged and all the glyphs are treated as part of the earliest word in logical order.
5. The glyphs from a word are collapsed into Glyph Groups. A Glyph Group is comprised of all consecutive glyphs from the same word. In most cases, each word generates one glyph group; however, in some cases the interaction between BIDI and special markup may cause glyphs from one word to have glyphs from other words embedded in it.
6. Each Glyph Group has two extents calculated: its normal extent, and its last in text area extent. Its normal extent is the sum of the advances of all glyphs in the group except soft hyphens. The normal extent is the extent used when a Glyph Group from a later word is in the same text area. The last in text area extent includes the advance of a trailing soft hyphen, but does not include the advance of trailing white space or non-spacing combining marks. The last in text region extent is used when this glyph group is from the last word (in logical order) in this text area. (If the entire line consists of a single word which is not breakable, the SVG user agent may choose to force a break in the line so that at least some text will appear for the given line.)
7. If xml:space="default", any space character that causes a line break in a 'textArea' element will be consumed by the line break and thus not rendered. However, if xml:space="preserve", any space character that causes a line break and subsequent spaces that will not fit on the line shall be included in the next line.
8. Words are added to the current line in logical order. All the Glyph Groups from a word must be in the same line, and all the glyphs from a Glyph Group must be in the same 'textArea'.
9. If 'line-increment' is a number, then each line will be sized in the block-progression-direction to the value of 'line-increment'. If 'line-increment' is auto, then the maximum 'font-size' for any glyph in the line will determine the size of the line in the block-progression-direction. When a word is added, the line increment may increase; it can never decrease from the first word. An increase in the line increment can only reduce the space available for text placement in the span. The span will have the maximum possible number of words. The position of the dominant baseline for a given line is determined by first computing the line-increment value for that line and then choosing a position for the dominant baseline, using the position where the given baseline would appear for the font that will be used to render the first character and an assumed font-size equal to the line-increment value.
10. The Glyphs from the Glyph Groups are then collapsed into the text regions by placing the first selected glyph (in display order) at the start of the text area and each subsequent glyph at the location of the glyph following the preceding selected glyph (in display order).
11. The next word is selected, and the next line location is determined. The next line is positioned such that its before edge is flush against the after edge of the previous line relative to the block-progression-direction. Go to step 8.
12. Any lines which extend outside of the area(s) in the block-progression-direction are not rendered.

10.12 Editable text fields

SVG Tiny 1.2 allows text elements to be edited. Although simple text editing can be implemented directly in script, implementing an intuitive and well internationalized text input system which works on a variety of platforms is complex.Therefore, this functionality is provided by the SVG user agent, which has access to system text libraries. Content authors can build higher level widgets, such as form entry fields, on top of the editable text functionality.

10.12.1 The 'editable' attribute

The text content block elements have an editable attribute which specifies whether the contents of the elements can be edited in place.

    <define name='svg.Editable.attr' combine='interleave'>
      <optional>
        <attribute name='editable' svg:animatable='true' svg:inheritable='false'>
          <choice>
            <value>none</value>
            <value>simple</value>
          </choice>
        </attribute>
      </optional>
    </define>

SVG user agents should allow for the editing of text in-place. However, editing with a modal editing dialog is an alternate possibility, and may be the only option on some platforms. The current editing position should be indicated, for example with a caret. SVG Tiny 1.2 user agents must also support system functions such as copy/paste and drag/drop if they are available to applications on the platform.

To start editing, the current presentation value of the 'editable' attribute must be 'simple', the text content block element must have focus, and it must then be activated, e.g. by using an Enter key or clicking on the text region with a pointer device. When editing text in a text field, all text and key events are dispatched to the SVG user agent, which processes the events for proper handling of text entry.

If a text content block element is editable, then the SVG user agent must not normalize white space in user input when changing the tree according to the input. However, the displayed text must be rendered according to the SVG rules for 'xml:space'.

For editing in-place the following functionality must be made available:

• movement to the next/previous character (in logical order), for example with Left/Right arrows
• in 'textArea' elements, movement to the next/previous line, for example with the Down/Up keys
• movement to the beginning of the line, for example with the Home key
• movement to the end of the line, for example with the End key
• copy/cut/paste, if a clipboard is supported, for example with Copy and Paste keys

The functionality should use the normal key bindings that are used for those tasks on the given platform. For devices without keyboard access, the equivalent system input methods should be used wherever possible to provide the functionality described above.

When doing editing in-place, the content of the DOM nodes that are being edited should be live at all times and reflect the current state of the edited string as it is being edited. When using a modal editing dialog, the content of the DOM nodes will only change once the user commits the edit (for example, by using an Enter key or clicking an "OK" button, or an alike behavior native to the platform), firing a single textInput event.

If an Input Method Editor (IME) is used (for example, to input Kanji text, or to input Latin text using number keys on mobile phones), the text events correspond to the actual text entered (eg the Kanji character, or the Latin character) and not to the keyboard or mouse gestures needed to produce it (such as the sequence of kana characters, or the number of sequential presses of a numeric key).

While text is being edited, the SVG user agent should always make the caret visible to the user as it is moved around the edited text (either due to typing more characters or to moving it within existing text). The precise behavior in which this functionality is supported depends on the SVG user agent.

The behavior of edited text while the caret is placed inside a ligature is implementation dependent. SVG user agents are however encouraged to take into account the notions captured in Character Model for the World Wide Web 1.0: Fundamentals, Section 6.1: String concepts [CHARMOD].

If the text of an editable element is edited, and the element has child elements, the contents of the edited element must first be stripped of all non-'tbreak' elements, preserving the contents of each non-'tbreak' element in place.

If the editable element does not have text content, it may not be possible to activate the editability with a pointer, since there will be no rendered element to click on. In the case of the 'textArea' element, which has inherent 'width' and 'height' geometry, setting the 'pointer-events' property value to boundingBox will allow the user to initiate the editing (see Example textArea02). This functionality does not exist for the 'text' element since it has no inherent geometry without text content.

Example textArea02 below shows how to use the 'pointer-events' property value boundingBox to create a declarative input box that can be activated with a pointer device.

Example: textArea02.svg

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.2" baseProfile="tiny" viewBox="0 0 250 100">

  <title>Editable text input</title>
  <desc>Illustrates how to create an editable input box without script</desc>

  <rect x='0' y='0' width='250' height='100' fill='#87ceeb'>
    <title>background rectangle</title>
  </rect>

  <g id="nameInput" transform='translate(50, 20)'>
    <text x="0" y="20" font-size="18" font-family="Arial" fill="#000080">Name:</text>
    <rect x="0" y="25" width="156" height="26" rx="3" ry="3"
          fill="white" stroke-width="2" stroke="#000080"/>
    <textArea x="3" y="27" width="150" height="20" font-size="18" font-family="Arial"
              editable="simple" focusable="true" pointer-events="boundingBox"/>
  </g>

</svg>

10.13 Text selection and clipboard operations

If SVG viewers support text selection and copy/paste operations then they must support:

• user selection of text strings in SVG content
• the ability to copy selected text strings to the system clipboard

A text selection operation starts when all of the following occur:

• the user positions the pointing device or caret over a glyph that has been rendered as part of a text content block element, initiates a select operation (e.g., pressing the standard system mouse button for select operations) and then moves the current text position while continuing the select operation (e.g., continuing to press the standard system mouse button for select operations);
• no other visible graphics element has been painted above the glyph at the point at which the pointing device was clicked.

As the text selection operation proceeds (e.g., the user continues to press the given mouse button), all associated events with other graphics elements are ignored (i.e., the text selection operation is modal) and the SVG user agent shall dynamically indicate which characters are selected by an appropriate highlighting technique, such as redrawing the selected glyphs with inverse colors. As the current text position is moved during the text selection process, the end glyph for the text selection operation is the glyph within the same 'text' element whose glyph cell is closest to the pointer. All characters within the 'text' element whose position within the 'text' element is between the start of selection and end of selection shall be highlighted, regardless of position on the canvas and regardless of any graphics elements that might be above the end of selection point.

Once the text selection operation ends (e.g., the user releases the given mouse button), the selected text will stay highlighted until an event occurs which cancels text selection, such as a pointer device activation event (e.g., pressing a mouse button).

Detailed rules for determining which characters to highlight during a text selection operation are provided in Text selection implementation notes.

For systems which have system clipboards, the SVG user agent should provide a user interface for initiating a copy of the currently selected text to the system clipboard. It is sufficient for the SVG user agent to post the selected text string in the system's appropriate clipboard format for plain text, but it is preferable if the SVG user agent also posts a rich text alternative which captures the various font properties associated with the given text string.

For bidirectional text, the SVG user agent must support text selection in logical order, which will result in discontinuous highlighting of glyphs due to the bidirectional reordering of characters. SVG user agents can also optionally provide an alternative ability to select bidirectional text in visual rendering order (i.e., after bidirectional text layout algorithms have been applied), with the result that selected character data might be discontinuous logically. In this case, if the user requests that bidirectional text be copied to the clipboard, then the SVG user agent is required to make appropriate adjustments to copy only the visually selected characters to the clipboard.

When feasible, it is recommended that generators of SVG attempt to order their text strings to facilitate properly ordered text selection within SVG viewing applications such as Web browsers.

In addition to discrete text selection, the SVG user agent should provide facility for the mass selection of entire text passages, for whatever text is in scope. If a text content element has focus, such a select-all operation should include only the contents of that element. If no text content element is in focus, the select-all operation should select all the text in the document. This may be a progressive operation, widening the scope with each subsequent operation. For example, a common idiom is to allow a user to select text with a single click on a word, with first the word selected, then the entire passage with a second click, then the entire document with a third click. For purposes of accessibility, the user agent must allow any such operation to be performed by keyboard as well as pointer device (such as in the ctrl/command+A "select-all" keyboard shortcut), and should also expose appropriate accessibility APIs.

10.14 Text search

If the user agent supports searching for text strings, then it must support searching for text strings in SVG content as well. An SVG viewer which supports search must allow the user to find all instances of the searched text string within the document that are in the rendering tree (e.g., those with a 'display' property other than none), and must highlight or otherwise indicate each instance. SVG viewers which allow sequential searches for text strings must pan and zoom the viewport, as appropriate, in order to show the text string in context, and are recommended to adjust the viewport as if there had been a fragment identifier link traversal to the element containing the text string.

In other words, if the containing text content element is too large to be enclosed in the viewport, the SVG user agent is recommended to zoom out, but if the text does fit, the user agent is recommended only to pan, and not to zoom. In order to enable maximum usability, authors should create their content accordingly, breaking text into discrete text content elements that fit within the expected viewport at a readable size, while providing sufficient context. Additionally, users must be provided a way to zoom in on text that is too small for the user to read.

Example 'text_search.svg' below contains a long text string which extends outside of the initial viewport, and which needs to be adjusted when searching for one of the words outside the viewport. The image shows the results of a text search using the Batik SVG toolkit.

Example: text_search.svg

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     width="100%" height="100%" viewBox="0 0 120 60">

  <title>Text Search</title>
  <desc>
    An example of text that extends beyond the viewport,
    requiring the user agent to pan the viewport when 
    words are searched for.
  </desc>  
  
  <!-- 
    This rectangle is the same position and dimensions as the viewBox, 
    illustrating the initial area of the viewport.   
  -->
  <rect x="0" y="0" width="120" height="60" fill="#6495ed" stroke="blue" />
  
  <!-- 
    The contents of this text element extend beyond the initial viewport.   
  -->
  <text x="120" y="35" text-anchor="middle" fill="blue" 
        font-size="10" font-family="Helvetica">
        Seek and you shall find, find and you will search.
  </text>

</svg>