SVG Tiny 1.2 - 20050413

10 Text

Contents

10.1 Introduction

Text that is to be rendered as part of an SVG document fragment is specified using the 'text' or 'textArea' elements. The characters to be drawn are expressed as XML character data [XML10] inside the element.

SVG's 'text' and 'textArea' 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 text strings within 'text' elements can be rendered in a straight line. SVG supports the following international text processing features for straight line text:

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

Because SVG text is packaged as XML character data [XML10]:

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], 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, consists 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 and/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:

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 the recommendation is 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 [XML10].

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 SVGT1.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 [XML10] character data 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.

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

Schema: text
  <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.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>

  <define name='svg.TextCommon.group' combine='choice'>
    <choice>
      <ref name='svg.Desc.group'/>
      <ref name='svg.Animate.group'/>
      <ref name='svg.Handler.group'/>
      <ref name='svg.Discard.group'/>
      <ref name='tspan'/>
      <text/>
      <element name='switch'>
        <ref name='switch.AT'/>
        <zeroOrMore><ref name='svg.TextCommon.group'/></zeroOrMore>
      </element>
      <element name='a'>
        <ref name='a.AT'/>
        <zeroOrMore><ref name='svg.TextCommon-noA.group'/></zeroOrMore>
      </element>
    </choice>
  </define>
    

Attribute definitions:

x = "<coordinate>+"
If a single <coordinate> is provided, then the value represents the new absolute X coordinate for the current text position for rendering the glyphs that correspond to the first character within this element or any of its descendants.

If a comma- or space-separated list of <n> <coordinate>s is provided, then the values represent new absolute X coordinates for the current text position for rendering the glyphs corresponding to each of the first <n> characters within this element or any of its descendants.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>+"
The corresponding list of absolute Y coordinates for the glyphs corresponding to the characters within this element. The processing rules for the 'y' attribute parallel the processing rules for the 'x' attribute.

If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
editable = "true | false"
Whether the given element represents can be edited by the user. If the attribute is not specified, the effect is as if a value of "false" were specified.

Animatable: no.
rotate = "<number>+"
The supplemental rotation about the alignment-point that will be applied to all of the glyphs corresponding to each character within this element.

If a comma- or space-separated list of <number>s is provided, then the first <number> represents the supplemental rotation for the glyphs corresponding to the first character within this element or any of its descendants, the second <number> represents the supplemental rotation for the glyphs that correspond to the second character, and so on.

If more <number>s are provided than there are characters, then the extra <number>s will be ignored.

If more characters are provided than <number>s, then for each of these extra characters: (a) if an ancestor 'text' element specifies a supplemental rotation for the given character via a rotate attribute, then the given supplemental rotation is applied to the given character, else (b) no supplemental rotation occurs.

If the attribute is not specified: (a) if an ancestor 'text' element specifies a supplemental rotation for a given character via a rotate attribute, then the given supplemental rotation is applied to the given character (nearest ancestor has precedence), else (b) no supplemental rotation occurs.

This supplemental rotation has no impact on the rules by which current text position is modified as glyphs get rendered.

Animatable: yes (non-additive, 'set' and 'animate' elements only).

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" standalone="no"?>
<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>
    
Rendering of 10_01.svg

10.5 The 'tspan' element

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

Schema: tspan
  <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.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" standalone="no"?>
<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>
    
Rendering of 10_03.svg

Within a 'text' or 'textArea' element, graphic and font properties can be adjusted by including a 'tspan' element. Positional attributes such as x, y, dx, dy 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. Many of the features here go beyond the functionality provided by the elements in this profile of the SVG specification (for example, vertical text). However, they are described here to provide a single reference point for layout information. The content here includes support for various international writing directions, such as left-to-right (e.g., Latin scripts) and bidirectional (e.g., Hebrew or Arabic) and vertical (e.g., Asian scripts). 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' and 'textArea' 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. For top-to-bottom text, the inline-progression-direction points 180 degrees 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' or 'textArea' 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' or 'textArea' 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' and 'textArea' 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:

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:

The following additional rules apply to ligature formation:

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], section 3.11) 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' or 'textArea' 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' and 'textArea' 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.

'text-anchor'
Value: start | middle | end | inherit
Initial: start
Applies to: 'text' Element
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

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 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 [CSS2-fonts]. Any SVG-specific notes about these properties are contained in the descriptions below.

'font-family'
Value: [[ <family-name> |

<generic-family> ],]* [<family-name> |

<generic-family>] | inherit
Initial: depends on user agent
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

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 [ CSS2-font-family]. The rules for expressing the syntax of CSS property values can be found at [ CSS2-propdef].

'font-style'
Value: normal | italic | oblique | inherit
Initial: normal
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

This property specifies whether the text is to be rendered using a normal, italic or oblique face. Except for any additional information provided in this specification, the normative definition of the property is in [ CSS2-font-style].

'font-variant'
Value: normal | small-caps | inherit
Initial: normal
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

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

'font-weight'
Value: normal | bold | bolder | lighter | 100 | 200 | 300

| 400 | 500 | 600 | 700 | 800 | 900 | inherit
Initial: normal
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

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

'font-size'
Value: <absolute-size> | <relative-size> |

<length> | inherit
Initial: medium
Applies to: text content elements
Inherited: yes, the computed value is inherited
Percentages: N/A
Media: visual
Animatable: yes

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.

Except for any additional information provided in this specification, the normative definition of the property is in [ CSS2-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' 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 [XML10] and any construction of a Document Object Model [DOM2].

xml:space is an inheritable attribute which can have one of two values:

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 user agent to:

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 user agent to:

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. Thus, each newline in SVG will be represented by the single character #xA, no matter what representation for newlines might have been used in the original resource. (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.

The xml:space attribute is:

Animatable: no.

10.11 Text in an area

10.11.1 Intoduction to text in an area

The 'textArea' element allows wrapping text content within a given shape or (for some profiles of the SVG language) a sequence of shapes using a simplistic wrapping algorithm.

Text wrapping via the 'textArea' element is available as a lightweight and convenient facility for simple text wrapping when invocation of a complete box model layout engine is not required. For cases where box model layout is required, it is suggested that a 'foreignObject' element be used which invokes a box model facility such as CSS layout.

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 user agent may choose to implement a simplistic text wrapping algorithm as described in this specification or invoke a sophisticated layout engine (e.g., an engine that supports the CSS or XSL-FO box models). The simplistic wrapping algorithm described in this specification is upwardly compatible with the XSL-FO box model.

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

10.11.2 The 'textArea' element

Schema: textArea
  <define name='textArea'>
    <element name='textArea'>
      <ref name='textArea.AT'/>
      <zeroOrMore><ref name='svg.TextCommon.group'/></zeroOrMore>
    </element>
  </define>

  <define name='textArea.AT' combine='interleave'>
    <ref name='svg.Properties.attr'/>
    <ref name='svg.Core.attr'/>
    <ref name='svg.Conditional.attr'/>
    <ref name='svg.Focus.attr'/>
    <ref name='svg.Transform.attr'/>
    <ref name='svg.XYWH.attr'/>
    <ref name='svg.Editable.attr'/>
  </define>
    

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the text content will be placed. If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the text content will be placed. If the attribute is not specified, the effect is as if a value of "0" were specified.

Animatable: yes.
width = "auto | <coordinate>"
The width of the rectangular region into which the text content will be placed. A value of "auto" indicates that the width of the rectangular region is infinite. If the attribute is not specified, the effect is as if a value of "auto" were specified.

Animatable: yes.
height = "auto | <coordinate>"
The height of the rectangular region into which the text content will be placed. A value of "auto" indicates that the width of the rectangular region is infinite. If the attribute is not specified, the effect is as if a value of "auto" were specified.

Animatable: yes.
editable = "true | false"
Whether the given element represents can be edited by the user. If the attribute is not specified, the effect is as if a value of "false" were specified.

Animatable: no.

10.11.3 The 'tBreak' element

The 'tBreak' element is an empty element that forcibly breaks the current line of text.

Schema: tBreak
  <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. It is a proper subset of the CSS 'line-height' property so that user agents which have a CSS box model engine can use that engine to provide text wrapping.

'line-increment'
Value: auto | <number> | inherit
Initial: auto
Applies to: text content elements
Inherited: yes
Percentages: none
Media: visual
Animatable: yes

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.
<number>
Subsequent lines are offset from the previous line by this amount (in user units).

10.11.5 The 'display-align' property

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

'display-align'
Value: auto| before | center | after | inherit
Initial: start
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Animatable: yes

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.

Below is a recommended algorithm for implementing 'display-align'.

  1. A temporary delta variable, D, is initialized to the height of the textArea bounding box in the text progression direction (the distance between the co-ordinate of the shape closest to the 'after' edge and the co-ordinate of the shape closest to the 'before' edge.) A starting point is chosen as the co-ordinate of the shape closest to the 'before' edge.
  2. The flowed text is laid out inside the textArea.
  3. At the completion of layout, the space remaining in the before direction, B, (the distance from the first line to the co-ordinate of the shape closest to the 'before' edge) is calculated.
  4. The space remaining in the after direction, A (the distance between the last line and the co-ordinate of the shape closest to the 'after' edge) is calculated.
  5. A measure of the difference from exact centering, C, is calculated as the absolute value of A - B.
  6. If C is less than 1px in non-transformed user space for the textArea layout terminates.
  7. If C is greater than D then layout terminates. (This will not happen on the first iteration, but may on subsequent iterations if text is flowed into irregular shapes).
  8. The temporary delta variable, D, is set to C.
  9. A new starting point is chosen, computed as B + 0.5( A - B) and execution returns to step 2.

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

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: it's normal extent, and it's last in text area extent. It's 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 whitespace 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 User Agent may choose to force a break in the line so that at least some text will appear for the given line.)
  7. 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 Text Area.
  8. 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.
  9. 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).
  10. 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 7.
  11. 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 and textArea elements have an editable attribute which specifies whether the contents of the elements can be edited in place.

Schema: editable
  <define name='svg.Editable.attr' combine='interleave'>
    <optional>
      <attribute name='editable' a:defaultValue='false' svg:animatable='false' svg:inheritable='false'>
        <ref name='Boolean.datatype'/>
      </attribute>
    </optional>
  </define>
    
editable = "true" | "false"

If set to "false" the contents of the text or textArea elements are not editable in place through the user agent. If set to "true", the user agent must provide a way for the user to edit the content of the text or textArea elements and all contained subelements which are not hidden (with visibility="hidden") or disabled (through the switch element or display="none"). The user agent must also, (if a clipboard is supported by the platform), provide a way to cut or copy the selected text from the element to the clipboard, and to paste text from the clipboard into the element . If no value is given for this attribute, the default value is "false".

Animatable: Yes.

SVG Tiny 1.2 user agents should allow for the inline WYSIWYG editing 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 pletform.

To start editing , the current animated value of the editable attribute must be "true", the text or textArea elements must have focus, and it must then be activated. When editing text in a text field, all DOM 3 Text and key events [DOM3Events] events are dispatched to the user agent, which processes the events for proper handling of text entry and cancels propagation of those events while editing is taking place.

If a text or textArea element is editable, then the SVG user agent must render whitespace conforming to the SVG language defined behavior for xml:space="preserve" even if the given element has 'xml:space' with a value of "default".

For WYSIWYG editing the following functionality must be made available:

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 WYSIWYG 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 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 whatever the platform normally does).

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

10.13 Text selection and clipboard operations

Conforming SVG viewers which support text selection and copy/paste operations are required to support:

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

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 is required to 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 user agent must support text selection in logical order, which will result in discontinuous highlighting of glyphs due to the bidirectional reordering of characters. 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 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.

10.14 Text Module

The Text Module contains the following elements: