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 the text rendering capabilities, however, we have chosen to implement some basic 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 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
On a FormattedText Variable:
- 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:

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:

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.

Name	p	span	ITextLayoutFormat	Description

Name	p	span	ITextLayoutFormat	Description
fontFamily	no	yes	yes	A reference to a font within the document, using that font's family + "_" + style. So, for <fonts><item id="xxx" name="Arial Bold" family="Arial" style="Bold" /></fonts>, the "fontFamily" in a textFlow should be "Arial_Bold". (see lower)
fontSize	no	yes	yes	The font size. Default = 12 Value must be a number (points are assumed)
baselineShift	no	yes	yes	The baseline shift of the characters. Valid values are: - a number - "superscript" - "subscript"
color my_color	no	yes	Only "color", as an uint/hex value The reference to the CHILI color is maintained on the containing style as a separate property.	The "color" and "my_color" properties should be combined in a textFlow, with: - my_color containing the ID of the CHILI color (NOTE: gradient colors are not currently supported) - color containing the uint/hex RGB display value of that color
my_characterStyle	no	yes	no	ID of the linked CHILI CharacterStyle (see lower)
my_paragraphStyle	yes	no	no	ID of the linked CHILI ParagraphStyle (see lower)
lineHeight	no	yes	yes	Matches the "leading" setting in the editor (Character Settings Panel) Default = "120%" Only percentage values are allowed
trackingRight	no	yes	yes	Matches the "tracking" setting in CHILI Editor (Character Settings Panel) Default = 0 Value must be a number (points are assumed)
textAlign textAlignLast	yes	no	par. style only	Alignment of the text in a paragraph (and alignment of the last line of a paragraph) Valid values are: - left - center - right - justify
typographicCase	no	yes	yes	Matches the "Case" setting in CHILI Editor (Character Settings Panel) Valid values are: - default - uppercase - lowercase
paragraphSpaceBefore paragraphSpaceAfter	yes	no	par. style only	Additional space (vertically) before and after the paragraph Default = 0 Value must be a number (points are assumed)
textIndent paragraphStartIndent paragraphEndIndent	yes	no	par. style only	Indent settings (horizontal) for the paragraph. These respectively match the following in CHILI Editor (Paragraph Styles Panel): - Indent - Left Margin - Right Margin Default = 0 Value must be a number (points are assumed)
direction	yes	no	par. style only	Text direction Default = ltr Valid values are: - ltr - rtl for Left to Right and Right to Left text rendering
alignToBaseLine	yes	no	par. style only	If set to "true", the paragraph will be aligned to the appropriate baseline grid (from the TextFrame or Document)
id	yes	yes	no	For paragraphs: matches the "tag" setting in CHILI Editor (Paragraph Settings Panel) Any string is valid
textOverprint	no	yes	yes	If "true", the text will be set to overprint when exporting to PDF
kerning	no	yes	yes	Mathes the "Enable Kerning" checkbox in CHILI Editor Default = on Valid Values are: - on (or empty) - off
lineThrough	no	yes	yes	If "true", the text has a strike-through effect
textDecoration	no	yes	yes	if "underline", the text has an underline effect
ANY_CUSTOM_PROP	yes	yes	no	When serializing/deserializing a TextFlow, all other attributes are maintained (see higher, under "TextFlow", for more details)

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