10 Text

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:

• The 'textArea' element
• The author or authoring package needs to pre-compute the line breaks and use individual 'text' elements to manually place the line. (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 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 [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 some languages, ligatures are required for certain character combinations.)
• Composite characters - In various 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.
• Glyph substitution - Some 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 some 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.) The box 1 EM high and 1 EM wide is called the design space. This space is given a geometric coordinates by sub-dividing the EM into a number of units-per-em.

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, a 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, 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 character. In the simplest case, the new current text position is the previous current text position plus the glyphs' 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 width="10cm" height="3cm" viewBox="0 0 1000 300"
     xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny">
  <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 width="10cm" height="3cm" viewBox="0 0 1000 300"
     xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny">
  <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. For top-to-bottom text, the block-progression-direction always points 90 degrees counter-clockwise from the reference orientation vector because the only available top-to-bottom writing mode is tb-rl.

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-topline] 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 [CSS2-spacing], 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 UAX#9) 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.

A more complete discussion of bidirectionality can be found in the "Cascading Style Sheets (CSS) level 2" specification [CSS2-direction].

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

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 (start-, middle- or end-alignment) a string of text relative to a given point.

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:

start

The rendered characters are aligned such that the start of the text string is at the initial current text position. For Latin or Arabic, which is usually rendered horizontally, this is comparable to left alignment. For Asian text with a vertical primary text direction, this is comparable to top alignment.

middle

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

end

The rendered characters are aligned such that the end of the text string is at the initial current text position. For Latin text in its usual orientation, this is comparable to right alignment.

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 [XSL11-common-font-properties].

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 [ XSL11-font-family].

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-font-style].

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-font-variant].

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 [ XSL11-font-weight].

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 [ XSL11-font-size].

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

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 version="1.2" baseProfile="tiny"  viewBox="0 0 220 320"
    xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <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 (ie. 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'/>
    </define>
      

No 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 Extensible Stylesheet Language text-align property [XSL].

For details refer to the XSL text-align property. Note that SVG does not require user-agents to support the following values for this property: "justify", "inside", "outside", <string>, "left", or "right". When an unsupported value is encountered it must be treated as the property had not been specified.

The values "start" and "end" are dependent on the writing system being used.

• For left to right horizontal (English, French, etc): start=left and end=right
• For right to left horizontal (Hebrew, Arabic, etc): start=right and end=left
• For top to bottom vertical (vertical Chinese, etc): start=up and end=down

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 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
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 hyphens but does not include the advance of trailing white space or 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. Goto 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 Tiny 1.2 user agents should allow for the editing in-place of text. 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 DOM3 Events text and key events [DOM3Events] 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 DOM 3 text 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 returned by DOM 3 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 agent 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.

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 version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg"
  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 ECMAScript:

myTextEl.textContent = myTextEl.textContent;

In Java:

myTextEl.setTextContent(myTextEl.getTextContent());