TextFlow and ITextLayoutFormat XML

Concept

Most objects within a CHILI document inherit from ?Document Object Model - DocumentBase. These objects are totally under CHILI's own control. To leverage Flex's unmatched text rendering capabilities, however, we have chosen to implement some basic Flex objects within our object model. The most important is the "TextFlow" object, containing the description of a running text and its formatting.

While this is used as the basic object for running texts, it is not a "pure" TextFlow implementation:

• Not all properties of Flex's TextFlow are supported within the context of CHILI documents
• A large amount of additional functionalities have been built around the basic text editing capabilities

Lower on this page you can find a list of the supported properties (both basic and CHILI-extended). In addition to that, TextFrames, ViewPreferences, Story Editor and many more objects contain more settings to influence text editing within those contexts.

Uses

The three main uses for TextFlow objects in XML are:

• On a ?Document Object Model - TextFrame object:
  • textFlow property
  • displayTextFlow property
• On a ?Document Object Model - Variable object:
  • the "value" property can contain a string representing a TextFlow

See ?TextFrame XML and ?Variables XML for more information.

TextFlow

A TextFlow Object consists of XML describing the text and its formatting. It should contain at a minimum the following content:

<TextFlow
   xmlns="http://ns.adobe.com/textLayout/2008"
   whiteSpaceCollapse="preserve"
   >
   <p><span>SOME TEXT</span></p>
</TextFlow>

In this structure, the "TextFlow" root node can contain multiple paragraph ("p") sub-nodes, and each paragraph can contain multiple span nodes.

Basic formatting
The formatting of each individual span can inherit values from the paragraph. Note that a span does NOT inherit values from a previous span (although this would be enforced internally if the user edits text formatting through the Editor which creates a new span)

<TextFlow
   xmlns="http://ns.adobe.com/textLayout/2008"
   whiteSpaceCollapse="preserve"
   >
   <p fontSize="10"><span fontSize="15">15 points, </span><span>10 points, from paragraph</span><span fontSize="20">20 points</span></p>
</TextFlow>

See lower for a list of the various formatting attributes

Special Characters

Each span node can also contain "br" or "tab" nodes to indicate soft returns and tabs within the paragraph:

<TextFlow
   xmlns="http://ns.adobe.com/textLayout/2008"
   whiteSpaceCollapse="preserve"
   >
   <p><span>SOME<tab/>TEXT<br/>Across multiple lines</span></p>
</TextFlow>

Custom Properties

Paragraph and span nodes can contain any custom attribute as well. While these objects do not inherit from DocumentBase (and therefore can't have a "privateData" sub-node, any attribute not recognized during parsing will be maintained:

<TextFlow
   xmlns="http://ns.adobe.com/textLayout/2008"
   whiteSpaceCollapse="preserve"
   >
   <p MY_PROP_1="aaa"><span MY_PROP_2="bbb">Some Text</span></p>
</TextFlow>

IMPORTANT NOTE, however: to prevent conflicts with internal naming (currently in use or to be added in the future), it is STRONGLY recommended to add a unique prefix to the attribute names

Unrecognized sub-nodes will be ignored and lost during serialization (and may in fact even cause errors within the Editor)

ITextLayoutFormat

This object is mainly used as a placeholder for the various formatting options which are TextFlow specific (non-CHILI objects) of Character and Paragraph Styles. In both cases, a "format" property exists, which holds the various supported properties:

<document>
  <paragraphStyles>
    <item id="123-456-789" name="MY_FIRST_PAR_STYLE" applyToNewFrames="true">
      <format fontFamily="Arial_Regular" fontSize="15" />
    </item>
 </paragraphStyles>
  <characterStyles>
    <item id="567-890-123" name="MY_FIRST_CHAR_STYLE" >
      <format fontFamily="Arial_Bold" fontSize="25" />
    </item>
 </characterStyles>
</document>

See lower for a list of the supporrted properties

Property Overview

IMPORTANT NOTE: when a document is saved by CHILI Editor, other values may be added to the TextFlow or format in the document's XML. These should NOT be modified. They contain either values for internal use, or default values of the TextFlow which are not supported/tested within CHILI's context. When creating or updating the XML, you should only use the following list of properties.

Similarly, some property values may appear in other locations (eg: "fontFamily" might also be present in a paragraph node). While this would pose less of an issue, it is recommended to only apply them on the locations marked relevant below.

See ?Fonts XML for more details on referencing fonts.

A color inside a TextFlow consists of two separate attributes:

• my_color: the ID of the CHILI color (in document/colors ), which can be CMYK, RGB, LAB, ...
• color: the "TextFlow" value, which in XML can be either a hex value ("#FF0000") or a uint (0x12345). Google can help you convert hex to uint (and vice versa) in your development environment, if needed. This hex/uint value is the RGB representation of the color, used for display within the editor

Note that setting references to CHILI Objects inside a TextFlow XML in itself is not always enough (currently) to also enforce the application of the various properties/settings of that referenced object. When setting my_color, my_characterStyle or my_paragraphStyle, the safest bet is to also apply the relevant applied settings of those liked objects (the "color" uint/hex value, and the various paragraph/character style format settings).

TextFormat Object

For internal purposes, and for use through the JavaScript API, there is a helper CHILI object which encapsulates most of the supported text properties (and where you can find some more documentation): ?Document Object Model - TextFormat. This object is however NOT used to serialize/deserialize XML. So several differences exist:

• color/characterStyle/paragraphStyle/font can internally be set using CHILI object references, whereas that is NOT the case in XML (except using the matching "my_XXX" properties, as documented higher)
• various properties in TextFormat are of type "unit", whereas in a TextFlow or TextLayoutFormat, they are numeric (point) values. CHILI internally translates those values. See ?General XML Concepts and ?Measurement Units for more information on how you can perform these calculations yourself
• textDecoration does not exist, but is replaced by a "underLine" boolean property