previous   next   contents  

8. The SMIL 3.0 SMILtext Modules

Editors for SMIL 3.0
Dick Bulterman, CWI
Sjoerd Mullender, CWI
Samuel Cruz-Lara, INRIA

Table of contents

8.1 Changes for SMIL 3.0

This section is informative.

This module defines new functionality for SMIL 3.0. It extends the media types available for SMIL, but does not alter any other existing functionality from SMIL 2.1 or earlier versions.

8.2 Open Issues in This Version

This section is informative.

The open issues at the time of writing this version of the SMILtext modules are:

8.3 Introduction

This section is informative.

The functionality described in these modules provide a new media type for use in SMIL presentations. This functionality is called SMILtext. Unlike other media types defined in the media object module, all of which are synonyms of the ref element, the SMILtext modules provide a text container element with an explicit content model for defining in-line text, and a set of additional elements and attributes to control explicit in-line text rendering. SMILtext content is processed in a manner consistent with other SMIL media. This means, among other aspects, that the SMILtext respects SMIL timing and layout behavior, including the semantics of the fit and fill attributes of SMIL Layout.

The SMILtext Modules are composed of a BasicText module and two modules with additional functionality that build on top of the BasicText module: the TextStyling and TextFlow modules. These modules contain elements and attributes used to define in-line text content. Since the SMILtext elements and attributes are defined in a series of modules, designers of other markup languages can reuse these modules when they need to include a simple form of timed text functionality into their language.

8.3.1 Motivation

The purpose of including text content functionality into SMIL 3.0 is to allow authors to define small amounts of (lightly-formatted) text within the context of a SMIL presentation. Such text can be used, among other things, for labels within a presentation or for incidental captions. Users who wish to use large amounts of structured text (with or without temporal markup) should consider the use of external text media objects encoded in formats such as XHTML or the DFXP profile of TimedText.

All versions of SMIL have had support for the text element, which is defined as an alias of the generic SMIL ref media reference element. A typical use of the text element is:

    <text region="Title" src="Headline.html" dur="10s" >

Users new to SMIL are often surprised that the text element does not have a content model -- that is, an ability to specify the content text along with the element, such as in:

    <text region="Title" dur="10s" >
       Willemijn's 11th Birthday Party
    </text>
 

More advanced users of SMIL found that they were able to insert in-line text content into the SMIL file using a data URL, such as:

    <text src="data:,Willemijn's%2011th%20Birthday%20Party" 
          region="Title" dur="10s" >
 

However, the strict syntax of this approach, plus the limited styling options available, make it a less-than-optimal way of including incidental text content into a SMIL presentation. A more author-friendly approach to text inclusion was a requirement for SMIL 3.0.

The implementation of SMIL on a wide range of devices, from set-top boxes and mobile devices to conventional desktop computers, means that care needed to be taken in defining the complexity of the SMILtext modules. The motivation of the SMIL's in-line text facility was not to provide complete support for all types of text, but to provide a balance between authoring convenience and player complexity. SMILtext was also designed to differentiate text styling from general layout and positioning so that SMILtext could be used efficiently with SMIL Layout. Both of these motivations, plus the desire to define a media facility that could be used across all of SMIL's implementation platforms, has resulted in a simple text specification that can meet many of the requirements for incidental text within a SMIL document.

SMILtext has been designed as a functional subset of the W3C Timed Text format DFXP. While users familiar with DFXP will recognize the functionality included in this specification, the differences in temporal and layout specifications between SMIL and DFXP have resulted in a slightly different syntax in the two languages. The SYMM working group has strived to minimize these differences. A complete list of differences between SMILtext and DFXP is presented in Appendix A.

8.3.2 The SMILtext Rendering Model

In order for text content to be compatible with the SMIL timing semantics, a general text processing model has been defined for SMILtext. In this model, text is classified as a discrete media type, with no inherent duration. All text content is processed as if it were first rendered to an off-screen bitmap; this bitmap is then used as the basis for inclusion into a SMIL presentation much as if it were an actual image. (There are some exceptions to this model; these are discussed in the Examples section of FlowModel module in this document.

The dimensions used in constructing the off-screen bitmap representation of SMILtext will depend on a number of factors. In general, the layout model used to define a drawing area for the text content will provide initial values for the extents of the text area. The default text-wrap behavior for SMILtext is to wrap the text content based on region width. In this case, the region will determine the text-area width and the text content will determine the effective off-screen bitmap height. If the wrap behavior is set to disallow automatic text wrapping (which is only possible if the TextStyle module is supported by the profile implementing SMILtext), the effective height is determined based on the number of lines of text (which in turn is determined by the number of manual line breaks created via the br element) and constrained by the region height, while the text content determines the off-screen bitmap width.

In most cases, content defined in a smilText element will define a new off-screen bitmap pseudo-image that will replace any existing content in the target region. If multiple smilText elements are active simultaneously and target the same layout region, the behavior is fully defined by the semantics of the SMIL timing model. Users of SMILtext are encouraged to study the examples at the end of each module description to better understand the impact of SMIL timing on text rendering with SMILtext.

8.4 SMIL 3.0 BasicText Module

This section is normative.

This section defines the elements and attributes that make up the functionality in the SMIL 3.0 BasicText module. Languages implementing elements and attributes found in the BasicText Module must implement all elements and attributes defined in this section.

8.4.1 Elements and Attributes

The SMIL 3.0 BasicText module defines two elements and one attribute which, together, provide basic support for in-line text within a SMIL presentation. The functionality provided by these elements and attributes represent the minimum level of text processing that can be required by a user agent implementing SMILtext.

The elements defined in this module are:

smilText
br

The attribute defined in this module is:

textWrapOption

In addition, this module extends the definition of the SMIL Layout region element to include the textWrapOption attribute.

For profiles that support only the BasicText module, all in-line text content styling and processing is defined and controlled by the SMIL user agent rendering the text. Additional content styling elements and attributes are defined in the TextStyling and TextFlow modules; support for this extended functionality is profile dependent.

The smilText Element

The smilText element functions as a logical and temporal structuring element that allows the inclusion of in-line text content into a SMIL presentation. When rendering in-line text, the smilText element provides a top-level container for timing semantics. No timing semantics may be defined on the content within the smilText element.

When text is rendered into an associated region, the existing contents of the region is replaced by the element content. The properties of the region will determine the extents of the rendering area and the clipping behavior of text placed in the region. The effective value of the textWrapOption attribute will determine if lines wrap if they are wider than the space provided. In-line text is considered to be rendered instanteously at the beginning of the simple duration of the text element. In SMILtext, extra white space between characters is ignored.

Anchors and links may be attached to content within the smilText element. In these cases, the syntax and semantics of SMIL Linking will be expected, including temporal attributes on anchors.

Element attributes

This element accepts the textWrapOption attribute, which will override the effective value for the attribute defined on the layout region. Profiles including the smilText element must define which other SMIL attributes may be attached to this element.

Element Content

The smilText element may contain character content. If this content is present, it will be rendered as text in a player-dependent fashion. If no content is present, the smilText element must still observe all SMIL timing properties.

The br Element

The br element functions as a forced line break within in-line content defined in a smilText element. The br element is only valid within as content of a smilText element and has no temporal semantics other than those of its parent smilText element.

Element attributes

This element does not accept any attributes.

Element content

This element has no content.

The textWrapOption Attribute

The textWrapOption attribute specifies whether text content that is larger than the effective space available on one line in a region wraps. This attribute may be used on the smilText element or as a default on the region element.

Values:

wrap (default)
Text is wrapped across lines within a region.
noWrap
Text is not wrapped across lines within a region.
inherit
The effective value of this attribute is used.

If this attribute is defined on the the smilText element, the text wrap option will be applied to all content visible within the region.

Examples

This section is informative.

General Use of SMILtext

The smilText element provides a temporal wrapper for in-line text:

    <smilText>
       Hello world!
    </smilText>

The smilText element is the equivalent of allowing a data URL that contains text content, such as: <ref src="data:,Hello world!" ... > .

In this simple form, the text will be rendered based on the default layout properties defined for the user agent. If SMIL Layout is used, the default behavior is: a dynamic region will be defined that contains the text content of the element. All styling information -- including font, font size, font style and font color -- will be determined by the SMIL player.

If the SMIL Layout BasicLayout module is also supported by the profile implementing this module, the rendering extent and the clipping behavior of the text rendered in a SMIL region will be determined by the effective value of SMIL's layout attributes.

<smil ...>
 <head>
   ...
   <layout>
     ...
     <region id="Title" top="5px" left="10%" width="80%" height="30px" />
     ...
   </layout>
  </head>
  <body>
   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party
    </smilText>
   ...
  </body>
</smil>

This is equivalent to specifying: <ref region="Title" src="data:,Hello world!" ... >. In both cases, the properties associated with the region named Title will be used when positioning the text.

If the rendering space for the content of the smilText element is greater than the horizontal extent of one line, the effective value of the textWrapOption attribute will determine whether content will be clipped or wrapped:

<smil ...>
 <head>
     ...
     <region id="Title" top="5px" left="10%" width="80%" height="30px" 
          textWrapOption="wrap"/>
     ...
  </head>
  <body>
   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party was held six weeks late. (Again!)
    </smilText>
   ...
  </body>
</smil>

Line breaks within SMILtext content may be forced by using the br element within text content:

   ...
    <smilText region="Title" dur"10s">
       Willemijn's 11th Birthday Party
was held six weeks late.
(Again!) </smilText> ... </body> </smil>
Timing Consequences of SMILtext

The following fragment illustrates use of basic SMILtext in a SMIL sequence:

 <smil ...>
  <head>
     ...
    <layout>
     <root-layout width="400" height="300"/>
      <region id="Contents" top="5px" left="10%" width="80%" height="300"/>
    </layout>
   </head>
   <body>
      ...
       <seq id="S0">
        <smilText id="TS01" region="Contents" dur="5s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TS02" region="Contents" begin="2s" dur="5s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TS03" region="Contents" begin="4s"  end="3s">
           (Again!)
        </smilText>
       </seq>
         ...
   </body>
 </smil>

The element TS01 starts the sequence and displays text for 5s. Since an explicit duration is declared, the text content will be removed from view after 5 seconds. Since element TS02 defines an explicit begin delay, the region containing the text will be empty for 2s. After this, TS02 will render the second text in the layout region for 5s. Element TS03 begins after a 4s delay, during which the content from TS02 remains visible because of an explicit fill="freeze". Finally, TS03 will be activated and removed after 3s.

The following example is used to illustrate SMILtext behavior when used with the SMIL parallel time container:

      ...
       <par id="P0">
        <smilText id="TP01" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP02" region="Contents" begin="2s" dur="7s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP03" region="Contents" begin="4s"  end="3s">
           (Again!)
        </smilText>
       </par>
         ...

In this example, all three children of the parallel container P0 are activated together. Element TP01 starts with no begin delay and renders its text for 5s. After 2s, element TP02 begins and replaces the content displayed by TP01. After 2s (at a total of 4s into the parallel container), element TP03 starts, replacing the contents of the region with its text. Three seconds later, TP03 ends -- at this point, because of the explicit end time, the contents of TP03 are removed and replaced with those of TP02 (which is still active for another 2s.) When TP02 ends, TP02's text is not removed -- even though TP01 still has 1s of display time left -- because of the explicit fill value defined on TP02.

The most pertinent SMIL timing rules governing text with effective remove semantics are:

Layout and Rendering Consequences of SMILtext

In terms of visual behavior, the value of the fit attribute will determine clipping behavior of the text. Since not all user agents can be expected to dynamically scale plain text, fit="slice" will be the expected default behavior with basic SMILtext.

In terms of the rendering semantics defined in the TextFlow module, the only behavior defined by basic SMILtext is the replace text flow semantic.

8.4.2 Integration Requirements

If the including profile supports the XMLBase functionality [XMLBase] , the values of the longdesc attribute (of present) on the smilText element must be interpreted in the context of the relevant XMLBase URI prefix.

All of the attributes specified for media within the SMIL MediaParam module must be supported by implementations integrating this module.

8.5 SMIL 3.0 TextStyling Module

This section is normative.

This section defines the elements and attributes that make up the SMIL TextStyling Module. Languages implementing the elements and attributes in the TextStyling Module must implement all elements and attributes defined below, as well as those defined in the BasicText module.

8.5.1 Elements and Attributes

The TextStyling module defines the following three elements:

span
textStyle
textStyling

The TextStyling module defines the following eight attributes:

textAlign
textBackgroundColor
textColor
textDirection
textFontFamily
textFontSize
textFontWeight
textStyle

In addition, this module extends the definition of the SMIL Layout region element to include the TextStyling attributes listed above.

The span Element

The span element functions as a logical container for in-line formatting attributes defined within a smilText element. The span element may not be nested within another span element The span element is only valid within as content of a smilText element and has no temporal semantics other than those of its parent smilText element.

Element attributes

The span element may (re)specify values for any of the SMIL styling attributes defined in this module. All other attributes are ignored.

Element content

This element accepts as content zero or more characters to which the specified styling is applied. Any styling attributes changed within the scope of this element must be restored to their previous values outside the scope of this element.

The textStyle Element

The textStyle element is used to define a set of text style attributes in the document head section. The style group defined with this element may be used within a SMIL layout region to define default styles for text elements in that region, or within the smilText and span in-line content elements in a SMIL body section.

Element attributes

All of the styling attributes defined in this module (with the exception of the textStyle attribute) may be specified within a textStyle element in the head section. Note that if text style attributes are referenced on an element to which they do not apply, they are ignored. If multiple instances of the same styling attribute are defined, the value associated with the lexically-last instance are used.

In addition, this attribute defines:

IDREF
The ID of the textStyle definition.
Element content

This element has no content.

The textStyling Element

The textStyling element deliniates a set of textStyle elements in the document head section.

Element attributes

This attribute accepts no attributes.

Element content

This element contains one or more textStyle elements as children.

The textAlign Attribute

The textAlign attribute specifies how text is aligned within the region specified by the text element. This attribute may be used on the smilText element or as a default on the region element. The semantics of this attribute are a subset of those defined in XSL 1.1.

Values:

start (default)
The text is left-aligned in the region if the effective value of the textDirection attribute is ltr, or right-aligned otherwise.
end
The text is right-aligned in the region if the effective value of the textDirection attribute is ltr, or left-aligned otherwise.
left
The text is left-aligned in the region.
right
The text is right-aligned in the region.
center
The text is centered in the region.
inherit
The effective value defined for the region is used.

If this attribute is defined on the the smilText element, the new alignment mode will be applied to all text displayed in the region.

The textBackgroundColor Attribute

The textBackgroundColor attribute is identical to the "background-color" property in the XSL 1.1 specification. As such, support for CSS2 system colors is required. This attribute specifies the background color used to fill the area around text content that falls within a player-defined bounding box. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

CSS2 color specification
The textBackgroundColor attribute may take on the CSS value inherit. This means that the background color used for text will be that of the backgroundColor attribute defined for the region specified by the parent text element. If no color has been specified, the default is transparent.

If this attribute is defined on the the smilText or span elements, the new background color will be applied only to the content within the scope of that element.

The textColor Attribute

The textColor attribute is identical to the "color" property in the XSL 1.1 specification. As such, support for CSS2 system colors is required. This attribute specifies the color used to render text content in the region specified by the parent text element. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

CSS2 color specification
The textColor attribute may take on the CSS value inherit. This means that the color used for text will be that of the color attribute defined for the region specified by the parent text element. If no color has been specified, the default is transparent.

If this attribute is defined on the the smilText or span elements, the new color will be applied only to the content within the scope of that element.

The textDirection Attribute

The textDirection attribute specifies the direction of text added to a region based on the Unicode Bidirectional algorithm. The semantics of this attribute are defined in XSL 1.1. Note that only simple text direction control is available in SMILtext; for more elaborate text processing (including tb-lr), an external text formatting language is required. This attribute may be used on the smilText element, on the span elements or as a default on the region element.

Values:

inherit (default)
The text is written in the direction defined for the region referenced in the text element. If no direction was defined, the default is ltr.
ltr
The text is written in a left-to-right direction
rtl
The text is written in a right-to-left direction

If this attribute is defined on the smilText element, the new alignment mode will be applied to all text displayed in the region. If this attribute is applied to the span element, it only will be applied to the content within the scope of that element.

The textFontFamily Attribute

This attribute defines the family of font used to render text. The resolution of a generic family name to a specific font instance is not defined by this specification, but may be defined by a profile implementing this module. In order to reduce implementation burden, only generic font families may be specified in SMILtext. If an unrecognized font family is defined, then monospace can be expected. The sansSerif and serif fonts are expected to be proportional. See XSL 1.1 for font family details. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

monospace (default)
sansSerif
serif
inherit

If this attribute is defined on the the smilText or span elements, the new font family will be applied only to the content within the scope of that element.

The textFontSize Attribute

This attribute defines the size of the font to be used. In order to reduce implementation burden and to provide scalability across device classes, only absolute and relative sizes (as defined in XSL 1.1) are supported by SMILtext. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

length (default)
absolute-size (default)
absolute-size represents a set of absolute font sizes, maintained by the SMIL player (and possible influenced by the player user agent). Expected absolute sizes are: [ xx-small | x-small | small | medium | large | x-large | xx-large ]. As recommended in XSL 1.1, it is expected that each of the absolute sizes will differ by a factor of 1.2. The default absolute size is medium.
relative-size (default)
relative-size represents a relative increase or reduction in the absolute font size value. Expected values are: [ larger | smaller ]. Effective font sizes larger than the absolute-sez xx-large or smaller than the absolute-size xx-small will not be supported.
inherit

If this attribute is defined on the the smilText or span elements, the new font size will be applied only to the content within the scope of that element.

The textFontStyle Attribute

This attribute defines the style (italic, oblique, reverseOblique or normal) of the text displayed. If the specified style is not available, a style of normal will be used. This attribute may be used on the smilText element, on the span element or as a default on the region element. Of the values defined in XSL 1.1, only the options defined in the following list will be supported by SMILtext.

Values:

normal (default)
italic
oblique
reverseOblique
inherit

If this attribute is defined on the the smilText or span elements, the new font style will be applied only to the content within the scope of that element.

The textFontWeight Attribute

This attribute defines the weight (bold or regular) of text displayed. If the specified weight is not available, a weight of normal will be used. This attribute may be used on the smilText element, on the span element or as a default on the region element. Of the values defined in XSL 1.1, only the options defined in the following list will be supported by SMILtext.

Values:

normal (default)
The normal font weight for the font family selected is used.
bold
The bold font weight for the font family selected is used.
inherit
The effective font weight for the font family selected, as defined on the text element or the referenced region, is used.

If this attribute is defined on the the smilText or span elements, the new font weight will be applied only to the content within the scope of that element.

The textStyle Attribute

The attribute references a text style set defined using the textStyle element in the document head. This attribute may be used on the smilText element, on the span element or as a default on the region element.

Values:

IDREF
The ID of a textStyle definition. If the IDREF specified as a value does not refer to a valid textStyle set definition, this attributed is ignored.

If this attribute is defined on the the smilText or span elements, the set of styling attributes will be applied only to the content within the scope of that element.

Examples

This section is informative.

The following example provides an indication of the use of SMILtext within a profile that provides support for the TextStyling module (such as the SMIL 3.0 Language profile).

00 <smil ...>
01  <head>
     ...
02    <textStyling>
03      <textStyle id="HeadlineStyle" textFontFamily="serif" textFontSize="12px" 
             textFontWeight="Bold" textFontstyle="italic"          
             textWrapOption="noWrap" textColor="Blue" textBackgroundColor="white">
04    </textStyling>
05    <layout>
06      <region id="Title" top="5px" left="10%" width="80%" height="25px"
             textStyle="HeadlineStyle" />
07      <region id="Captions" top="215px" left="10%" width="80%" height="35px" 
          textFontFamily="serif" textColor="orange"  backgroundColor="blue"/>
08      <region id="Slides" top="10px" left="5%" width="90%" height="200px" />
09    </layout>
10   </head>
11   <body>
      ...
12    <par>
13     <smilText region="Title" fontfamily="sansSerif" fill="freeze">
14        Willemijn's 11th Birthday Party
15     </smilText>
16     <seq>
17       <par>
18         <img region="slides" src="p001.jpg" begin="1s" dur="9s"/>
19         <seq>
20           <smilText region="Captions" textAlign="left" dur="2s">
21              Shortly <span textFontStyle="italic">before</span> dawn ...
22           </smilText>
23           <smilText region="Captions" textColor="green" begin="0.5s" end="4.5s">
24              just as the clock began
25              <br/>
26              to chime six times...
27           </smilText>
28           <smilText region="Captions" textAlign="right" dur="3s">
29              our trusty dog Gretchen barked. 
30           </smilText>
31          </seq>
32       </par>
         ...
33       <par>
34         <img region="slides" src="p128.jpg" dur="7s"/>
35         <text region="Captions" src="c128.html" dur="7s"/>
36       </par>
37     <seq>
38     <audio src="Commentary.mp3" />
39    </par>
40   </body>
41 </smil>

In this example, one text style is defined (on line 03) and three layout regions are defined, one of which (on line 06) references a style definition with local overrides, and another of which (on line 07) uses mostly default style. In the body of the presentation, a parallel container is defined that contains a text title (on line 13); most of the styling attributes are defined on the region via the text style attribute. Later in the presentation, a sequence of images are defined that are each accompanied by one or more text captions. The text definition on line 13 illustrates that text, like images, has no inherit duration, but that by using the SMIL fill attribute, the content of the smilText element remains visible until the end of the parent time container (in this case, the par that is defined on line 12). The three smilText elements that accompany the image defined on line 18 illustrate that the in-line text object can use the standard SMIL timing attributes, plus several new attributes to explicitly control text placement and styling. Finally, the text element on line 35 illustrates that it is possible to mix in-line and external text in a single document.

8.5.2 Integration Requirements

Any profile that integrates the erase attribute must define what is meant by "display area" and further define the interaction. See the definition of erase for more details.

8.6 SMIL 3.0 TextFlow Module

This section is normative.

This section defines the elements and attributes that make up the SMIL TextFlow Module. Languages implementing the elements and attributes in the TextFlow Module must implement all elements and attributes defined below, as well as those defined in the BasicText module.

8.6.1 Elements and Attributes

This section defines the elements and attributes that make up the functionality in the SMIL 3.0 TextFlow module.

This module does not define any new elements.

The attribute defined by the TextFlow module is:

textFlowMode

If the TextStyling module is used in the profile implementing this module, then the textStyle element is extended to include the textFlowMode attribute. In addition, this module extends the definition of the SMIL Layout region element to include the textFlowMode attribute.

The textFlowMode Attribute

The textFlowMode attribute specifies how text in a smilText element is added to a region. It may be used on the smilText element or as a default on the region.

Values:

replace (default)
The text replaces the content in the region.
append
The text is added to the content in the region, if any.
inherit
The effective value defined for the region is used.

If this attribute is defined on the the smilText element, the new flow mode will be applied to all text displayed in the region.

Examples

This section is informative.

The text flow rendering behavior of within this module has been designed to be consistent with other types of media processed by a SMIL user agent. The example below illustrates the processing of SMILtext when the textFlowMode attribute is set to append and used in a SMIL sequential container:

 <smil ...>
  <head>
     ...
    <layout>
        ...
      <region id="Contents" top="5px" left="10%" width="80%" height="300px"
             textFlowMode="append" />
    </layout>
   </head>
   <body>
      ...
       <seq id="S2">
        <smilText id="TS21" region="Contents" >
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TS22" region="Contents" begin="5s" fill="hold">
           was held six weeks late.
        </smilText>
        <smilText id="TS23" region="Contents" begin="9s" dur="3s">
           (Again!)
        </smilText>
       </seq>
         ...
   </body>
 </smil>

This example starts with the addition of the textFlowMode attribute to the region definition. The region is referenced by the sequence labelled S2. Element TS21 places a line of text in the region; the default fill behavior of freeze keeps this text visible until TS22 starts. The text in TS22 is not appended to the region, but replaces the existing content because all existing content is removed when an element's active duration ends. When TS23 begins 9s later, the new text is appended to the text from TS22 because of the use of the fill="hold" attribute. All text is removed when S2 ends.

The following fragment illustrates the behavior of append mode when placed in a parallel container:

 <smil ...>
  <head>
     ...
    <layout>
        ...
      <region id="Contents" top="5px" left="10%" width="80%" height="300px"
             textFlowMode="append" />
    </layout>
   </head>
   <body>
      ...
       <par id="P2" dur="15s">
        <smilText id="TP21" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP22" region="Contents" begin="2s" end="6s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP23" region="Contents" begin="4s" dur="3s">
           (Again!)
        </smilText>
       </par>
         ...
   </body>
 </smil>

When element P2 begins, it establishes a common timeline for the three text elements shown in the example. Element TP21 starts immediately and appends a text fragment to the region Contents. After 2s, element TP22 appends a line of text to the current contents of the region. Element TP23 adds an additional text fragment 2s later (at 4s into P2). After 3s, the active duration of TP23 ends and its contents is removed; this leaves the content from TP21 and TP22 in the region. TP22 ends 1s later, but the fill="freeze" forces its content to remain in the region until the end of the parent container (P2). At 10s after the start of P2, TP21 ends its active duration. The content associated with TP21 is removed from the region, leaving only the content from TP22.

In the following example, the value of the textFlowMode attribute is overridden by parts of the presentation body (with all other parts of the previous example remaining the same):

 <smil ...>
   ...
       <par id="P2" dur="15s">
        <smilText id="TP21" region="Contents" dur="10s">
           Willemijn's 11th Birthday Party
        </smilText>
        <smilText id="TP22" region="Contents" begin="2s" end="6s" fill="freeze">
           was held six weeks late.
        </smilText>
        <smilText id="TP23" region="Contents" begin="4s" dur="3s"
            textFlowMode="replace">
           (Again!)
   ...
 </smil>

The presentation logic of this example follows the previous discussion up to the start of TP23. When TP23 starts, it explicitly clears the region by specifying a textFlowMode="replace". The content of TP23 is placed alone in the region. After 3s, TP23 ends; at this point, the contents of TP21 and TP22 are restored into the region and processing proceeds as above.

8.6.2 Integration Requirements

Any profile that integrates the erase attribute must define what is meant by "display area" and further define the interaction. See the definition of erase for more details.

The value of the fit attribute will determine how text rendered within the region is processed.

8.7 Extended Examples

This section is informative.

This section provides a set of extended examples that motivate and illustrate SMILtext behavior.

8.7.1 General Behavior of SMILtext

All versions of SMIL have had support for the text element, which is defined as an alias of the generic SMIL ref media reference element. A typical use of the original SMIL text element is:

   ...
    <text region="Title" src="Headline.txt" dur="10s" >
   ...

The rendering semantic of the SMIL ref element -- and its aliases, such as img, audio, video, text, textstream -- is that content in the external file referenced by the src attribute is processed by an appropriate media renderer and replaces the contents of the layout region for the temporal duration of the element (including its fill period).

The following fragment illustrates the use of external text within a SMIL seq container:

  ...
  <layout>
    ...
    <region id="Title" height="80px" width="240px" fit="hidden"/>
  </layout>
  ...
  <seq id="S1" dur="25s" >
    <text id="T1" region="Title" src="Headline1.txt" dur="10s" />
    <text id="T2" region="Title" src="Headline2.txt" dur="10s" fill="freeze" />
  </seq>
 

This fragment renders the contents of T1 in the region Title for 10 seconds, under control of SMIL's layout rules. In this example, these rules determine that the media is positioned at the top-left edge of the region and that the text is clipped or wrapped (depending on the SMIL player) if it extends beyond the horizontal extent of the region and clipped if it extends beyond the vertical extent of the region. After 10 seconds, the contents of the region is replaced with that referenced in T2. Note that in both T1 and T2, all of the text is rendered at once, at the beginning of each element's active duration. After another 10 seconds, the active duration of T2 ends, but its parent remains active for an additional 5 seconds; since the fill behavior of T2 is freeze, the contents of T2 will remain visible at least until the end of S1.

The following fragment extends the previous example, using a par container instead of a seq:

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"/>
  </layout>
  ...
  <par isd="P1" dur="20s" >
    <text id="T3" region="Title" src="Headline1.txt" begin="0s"  dur="15s" />
    <text id="T4" region="Title" src="Headline2.txt" begin="5s"  dur="5s"  />
  </par>
 

In this fragment, T3 starts at the same time as the parent P1. It fills the Title region in a manner identical to that described for T1, above. After 5 seconds, the rendering of T4 starts. The contents of T4 will be placed "on top" of the contents of T3 for a period of 5 seconds. (Whether the contents of T3 is fully obscured is player dependent.) At the end of T4's 5-second active duration its content will be removed and the content associated with T3 will reappear for 5 seconds. In this example, the effective fill behavior for T3 is remove, which means that the region will be empty (expect for the backgroundColor) for the final 5 seconds. Note that similar behavior is expected when the text objects are replaced with images containing the text.

SMILtext uses the same model to render text as was described above.

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"/>
  </layout>
  ...
  <par isd="P2" dur="20s" >
    <smilText id="T5" region="Title" begin="0s"  dur="15s" fill="freeze" >
       This is a relatively long string of character text, which fills much of
       the target region.
    </smilText>
    <smilText id="T6" region="Title" begin="5s"  dur="5s"  >
       This is a relatively short string of text.
    </smilText>
  </par>
 

In this example, T5's content will be rendered started at time 0, followed by the content of T6 "on top" of the content of T5 during the interval between 5 and 10 seconds. The content in T6 will not be appended to that in T5, nor will the text in T5 reflow at anytime during this fragment. In order to keep SMILtext consistent with earlier versions of SMIL, this has been defined as default behavior within the BasicText module. There should be no functional difference in terms of layout and timing between rendering text via an external renderer and as in-line SMILtext.

There are some instances when it would be useful to allow text to append to the end of existing text in a region. Similarly, it may be useful to allow text to reflow if the active duration of a portion of text content ends while others remain active. To accommodate these cases, SMILtext defines the textAppend attribute in the TextFlow module. Consider the following fragment:

  ...
  <layout>
    ...
    <region id="Title" height="20px" width="200px" fit="hidden"
      textAppend="append" /> 
  </layout>
  ...
  <par isd="P3" dur="20s" >
    <smilText id="T7" region="Title" begin="0s"  dur="7s" >
       This is a relatively long string of character text, 
    </smilText>
    <smilText id="T8" region="Title" begin="0s"  dur="15s" >
       which fills much of the target region.
    </smilText>
    <smilText id="T9" region="Title" begin="5s"  dur="5s"  >
       This is a relatively short string of text.
    </smilText>
  </par>
 

Here, the contents of T7 and T8 are rendered at the start of P3. Since both T7 and T8 start at the same time, document order determines that T7 is rendered first, after which T8 is appended. After 5 seconds, the contents of T9 is appended to the contents in the region. At 7 seconds after the start of P3, T7's duration ends and its text is removed from the region, causing the contents to reflow. After an additional 3 second, T9 ends, causing its contents to be removed. Only T8 remains rendered. Note that this functionality is only relevant when multiple active text objects write into a region that has the textAppend attribute set: the attribute has no effect in, for example, a seq unless the effective fill semantics are hold. The use of textAppend allows a limited degree of dynamic content reflow, but it is not the intent of this attribute (or SMILtext) to provide extensive dynamic reflow capabilities; users interested in extensive text processing are expected to use external text rendering formats. Note also that support for this module is profile dependent.

Various attributes determine how text content is rendered in a region. In its most basic form, SMILtext provides a single attriute: textWrap. This attribute is a property of the region, but may be overridden on the text element. BasicText also supports a textBr element, for forcing a line break within text content. If the TextStyling module is included in the profile, an additional set of styling attributes are available, as is the textSpan element (which allows most styling attributes to be overriden within the span). In general, all styling attributes are properties of the rendering region, and most may be overriden on the text or textSpan elements. To make the specification of common styling elements more readable, the TextStyling module also defines a textStyle element within a textStyling section of the document head. The textStyle attribute allows these style sets to be applied to either regions, text elements or textSpan elements. An example of the definnition of style sets is:

  ...
  <textStyling>
    <textStyle id="Plain" textColor="black" textBackgroundColor="white"
                  textFontFamily="sansserif" textFontSize="medium" />
    <textStyle id="Fancy" textColor="orange" textBackgroundColor="blue"
                  textFontFamily="serif" textFontWeight="bold" />
  </textStyling>
  <layout>
    ...
    <region id="Title" height="20px" width="200px" textStyle="Plain"/>
  </layout>
  ...
  <smilText id="T5" region="Title" begin="0s"  dur="15s" textFontStyle="italic" >
     This is a relatively long string of 
     <span textStyle="fancy" textFontSize="large">character</span>
     text, which fills much of the target region.
  </smilText>
 

One of the common uses of text in a media presentation is to provide a crawling text string in one of the regions of a presentation. In SMIL NxG, this functionality is not a property of the text element, but a general function of the visual rendering model supported by SMIL layout. The following example illustrates how this is applied to SMILtext:

  <layout>
    ...
    <region id="News" height="20px" width="200px" fit="scroll" crawlRate="-10px"/>
    <region id="Credits" height="20px" width="200px" fit="scroll" scrollRate="5px"/>
  </layout>

In this example, any text written into the region News will be crawled at a rate of 10 pixels per second in the direction opposite to the expected direction specified by the textDirection attribute (this is the meaning of the minus sign). Any text written into the Credits region will be scrolled from bottom to top. For more details on the behavior of scrollRate and crawlRate, please refer to the definition in the Layout module.

8.8 Appendices

This section is informative.

8.8.1 Appendix A: Differences with the DFXP Specification

While SMILtext has been modelled as a functional subset of the DFXP profile of W3C TimedText, there are several differences between the languages. In this section, we review the components taken from DFXP, the components not taken from DFXP and the extensions defined that are not in DFXP.

Components Taken From DFXP for SMILtext

The following elements and attributes have been taken from DFXP and are included in SMILtext. Note that relevant attribute names from DFXP are preceded with 'text' to avoid conflict with attributes used in SMIL layout.

Component DFXP Name SMILtext Name Differences
Content br
span
br
span
The br element is identical in use.
The span element may not be nested in SMILtext.
Styling elements style
styling
textStyle
textStyling
These elements are declared in the document head.
SMILtext allows styles to be associated with layout regions as default values.
Styling attributes textAlign
BackgroundColor
Color
Direction
FontFamily
FontSize
FontWeight
Style
WrapOption
textAlign
textBackgroundColor
textColor
textDirection
textFontFamily
textFontSize
textFontWeight
textStyle
textWrapOption
SMILtext limits the range of values permitted for some of these attributes. The basic functionality is the same in all cases.

Components Not Taken From DFXP for SMILtext

The following elements and attributes are not included in SMILtext.

Additions in SMILtext Not in DFXP

The following elements and attributes are included in SMILtext but are not directly available in DFXP:


previous   next   contents