Livecode Wiki
Advertisement

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

set the styledText of <field> to <styledArray>

Examples:

set the styledText of field "White Paper" to tStyledTextArray
set the styledText of field "Dest" to the styledText of field "Source"

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] = <first paragraph array>
  • ...
  • tStyledTextArray[<n>] = <last paragraph array>

Each paragraph array has up to two keys:

  • tParagraphArray["style"] = <array containing paragraph-level

styles>

  • tParagraphArray["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.

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

  • tParagraphContentArray[1] = <first paragraph run array>
  • ...
  • tParagraphContentArray[<n>] = <last paragraph run array>

Each paragraph run array has up to three keys:

  • tRunArray["style"] = <array containing character-level styles for the

run>

  • tRunArray["metadata"] = <metadata of the run (if present)>
  • tRunArray["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.
  • UnicodeText
  • Text

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:

Hello World

Hello, this is another line

This would transpire as the following array temp:

put the styledText of field 1 into temp
  • temp[1][style][textAlign] = "center"
  • temp[1][runs][1][text] = "Hello world"
  • temp[1][runs][1][Style][textStyle] = "bold"
  • temp[2][runs][1][Style][textColor] ="255,0,0"
  • temp[2][runs][1][text]="Hello, this is another line"


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

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.

Parameters:

  • field: The reference to the field.
  • styledArray (array): An array containing the styled text. (Must be correctly constructed as aLiveCode styledText array, see comments)
  • The result:The engine flattens any nested numeric arrays within the tree; theniterates through the result ignoring any empty entries. If an array hasa 'runs' key it is treated as an independent paragraph; otherwise it isassumed to be a 'run' and the styled text it contains is appended to thecurrent paragraph. Note that the 'text' field of a run can containnewlines the presence of which cause paragraph breaks at the appropriatepoints - if such a break is made, the paragraph attributes are copiedacross the break.
  • Value: The styledText property returns a numerically-indexed array ofparagraphs.

See also: textShift (property),metadata (property),textFont (property),RTFText (property),textStyle (property),

Advertisement