Name: styledText

Type: property

Syntax: set the styledText of <field> to <styledArray>

Summary:
Specifies the contents of a field, with its text formatting represented
as LiveCode styled text array.

Associations: field

Introduced: 5.5

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
set the styledText of field "White Paper" to tStyledTextArray

Example:
set the styledText of field "Dest" to the styledText of field "Source"

Parameters:
field:
The reference to the field.

styledArray (array):
An array containing the styled text. (Must be correctly constructed as a
LiveCode styledText array, see comments)


The result:
The engine flattens any nested numeric arrays within the tree; then
iterates through the result ignoring any empty entries. If an array has
a 'runs' key it is treated as an independent paragraph; otherwise it is
assumed to be a 'run' and the styled text it contains is appended to the
current paragraph. Note that the 'text' field of a run can contain
newlines the presence of which cause paragraph breaks at the appropriate
points - if such a break is made, the paragraph attributes are copied
across the break.

Value:
The <styledText> property returns a numerically-indexed array of
paragraphs. 

Description:
Use the <styledText> property to access and programatically manipulate
the styled contents of a field.

The <styledText> property is similar to rtfText and htmlText in that it
provides a script-processable representation of the field's styled
content. It differs from these two formats in two ways:

1) It is a fully faithful representation (set the <styledText> of field
to the <styledText> of field results in no change to the field). 2) It
is array-based.

The <styledText> property returns a numerically-indexed array of
paragraphs, each index representing each paragraph in the field in
order: 

   tStyledTextArray[1] = &lt;first paragraph array&gt;
   ...
   tStyledTextArray[&lt;n&gt;] = &lt;last paragraph array&gt; 

Each paragraph array has up to two keys:

- "style" : array containing paragraph-level styles 
- "runs" : paragraph content array

The style array contains the values for each of the paragraph styles set
on that paragraph. The list of styles that are supported are: textAlign,
listStyle, listDepth, listIndent, firstIndent, leftIndent, rightIndent,
spaceAbove, spaceBelow, tabStops, tabAlign, backgroundColor, borderWidth,
borderColor, hGrid, vGrid, dontWrap, padding and hidden.

The paragraph content array is a numerically-indexed array of runs, each
index representing each run in the paragraph in order:

   tParagraphContentArray[1] = &lt;first paragraph run array&gt;
   ...
   tParagraphContentArray[&lt;n&gt;] = &lt;last paragraph run array&gt;

Each paragraph run array has up to three keys:

- "style" : array containing character-level styles for the
run
- "metadata" : metadata of the run (if present)
- "text" (or "unicodeText") : text content of run

The style array contains the values for each of the characters styles
set on that run. The list of styles that are supported are: textFont,
textSize, textStyle, textShift, textColor, backgroundColor, linkText,
imageSource. 

If a run has Unicode text in it then the run array has a "unicodeText"
key containing its content encoded as UTF-16. Otherwise, the run array
has a "text" key containing its content encoded in the native text
encoding. 

For example, take the following content consisting of two paragraphs:

Centered Hello World

Left-aligned Hello unicodeString

This would transpire as the following array:

    1 =
      style = { textAlign = center }
      runs =
        1 = { text = Centered  }
        2 =
          style = { textStyle = bold }
          text = Hello
        3 = { text =  World }
    2 =
      runs =
        1 = { text = Left-aligned  }
        2 =
          style = { textColor = 255,0,0 }
          text = Hello
        3 = { unicodeText = unicodeString }

[ For brevity, single element arrays are represented using { ... }
notation ]

When setting the styledText property, the engine uses a very permissive
algorithm to parse the arrays as follows:

    parseStyledTextArray pStyledText
       repeat for each element tEntry of pStyledText
          if tEntry is a sequence then
             parseStyledTextArray tEntry
          else if tEntry has key runs then
             begin paragraph with style tEntry[style]
                parseStyledTextRunArray tEntry[runs]
             end paragraph
          else if tEntry is an array then
             append tEntry[text] with style tEntry[style]

             parseStyledTextRunArray pRun
             repeat for each element tRun in pRuns
                if tRun is a sequence then
                    parseStyledTextRunArray tRun
                else
                    append tRun[text] with style tEntry[style]
                end if
             end repeat
         end if
      end repeat
    end parseStyledTextArray

Changes:
Support for the <tabAlign> paragraph style was added in version 8.1.2

Changes:
Support for the <tabAlign> paragraph style was added in version 8.1.2

References: HTMLText (property), textSize (property), flagged (property),
textShift (property), metadata (property), textFont (property),
RTFText (property), textStyle (property)

Tags: text processing
