Specifies the contents of a field, with its text formatting represented as LiveCode styled text array.
# Metadata
Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android Introduced: 5.5 Security:
# Syntax
set the styledText of field to styledArray
# Params
- field : The reference to the field. - styledArray : An array containing the styled text. (Must be correctly constructed as a LiveCode styledText array, see comments)
# Examples
set the styledText of field "White Paper" to tStyledTextArray
set the styledText of field "Dest" to the styledText of field "Source"
# 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] = <first paragraph array> ... tStyledTextArray[<n>] = <last paragraph array>
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] = <first paragraph run array> ... tParagraphContentArray[<n>] = <last paragraph run array>
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
# Tags
# See