<doc>
	<legacy_id></legacy_id>
	<name>styledText</name>
	<type>property</type>

	<syntax>
		<example>set the styledText of <i>field</i> to <i>styledArray</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Specifies the contents of a field, with its text formatting represented as LiveCode styled text array.</summary>

	<examples>
<example>set the styledText of field &quot;White Paper&quot; to tStyledTextArray</example>
<example>set the styledText of field &quot;Dest&quot; to the styledText of field &quot;Source&quot;</example>
	</examples>

	<history>
		<introduced version="5.5">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version=""></changed>
	</history>

	<objects>
		<field/>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Text and Data Processing</category>
	</classification>

	<references>
		<property tag="RTFText">RTFText Property</property>
		<property tag="HTMLText">HTMLText Property</property>
		<property tag="textFont">textFont Property</property>
		<property tag="textSize">textSize Property</property>
		<property tag="flagged">flagged Property</property>
		<property tag="textStyle">textStyle Property</property>
		<property tag="textShift">textShift Property</property>
		<property tag="metadata">metadata Property</property>
	</references>

	<description>
	<overview>Use the <b>styledText</b> property to access and programatically manipulate the styled contents of a field.</overview>

		<parameters>
  <parameter>
    <name>field</name>
    <description>The reference to the field.</description>
  </parameter>
  <parameter>
    <name>styledArray</name>
    <description>An array containing the styled text. (Must be correctly constructed as a LiveCode styledText array, see comments)</description>
  </parameter>		</parameters>

	<value>The <b>styledText</b> property returns a numerically-indexed array of paragraphs.</value>
	<comments>The <b>styledText</b> 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: <p></p><p>1) It is a fully faithful representation (set the <b>styledText</b> of field to the <b>styledText</b> of field results in no change to the field).</p><p>2) It is array-based.</p><p></p><p>The <b>styledText</b> property returns a numerically-indexed array of paragraphs, each index representing each paragraph in the field in order:</p><p></p><p>&#9;tStyledTextArray[1] = &lt;first paragraph array&gt;</p><p>&#9;...</p><p>&#9;tStyledTextArray[&lt;n&gt;] = &lt;last paragraph array&gt; </p><p></p><p>Each paragraph array has up to two keys:</p><p></p><p>&#9;tParagraphArray[&quot;style&quot;] = &lt;array containing paragraph-level styles&gt;</p><p>&#9;tParagraphArray[&quot;runs&quot;] = &lt;paragraph content array&gt;</p><p></p><p>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, backgroundColor, borderWidth, borderColor, hGrid, vGrid, dontWrap, padding.</p><p></p><p>The paragraph content array is a numerically-indexed array of runs, each index representing each run in the paragraph in order:</p><p></p><p>&#9;tParagraphContentArray[1] = &lt;first paragraph run array&gt;</p><p>&#9;...</p><p>&#9;tParagraphContentArray[&lt;n&gt;] = &lt;last paragraph run array&gt;</p><p></p><p>Each paragraph run array has up to three keys:</p><p></p><p>&#9;tRunArray[&quot;style&quot;] = &lt;array containing character-level styles for the run&gt;</p><p>&#9;tRunArray[&quot;metadata&quot;] = &lt;metadata of the run (if present)&gt;</p><p>&#9;tRunArray[&quot;text&quot; (or &quot;unicodeText&quot;)] = &lt;text content of run&gt;</p><p></p><p>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.</p><p></p><p>If a run has Unicode text in it then the run array has a &quot;unicodeText&quot; key containing its content encoded as UTF-16. Otherwise, the run array has a &quot;text&quot; key containing its content encoded in the native text encoding. </p><p></p><p>For example, take the following content consisting of two paragraphs:</p><p></p><p>&#9;Centered <b>Hello</b> World</p><p></p><p>Left-aligned Hello <i>unicodeString</i></p><p></p><p>This would transpire as the following array:</p><p>&#9;1 =</p><p>&#9;&#9;style = { textAlign = center }</p><p>&#9;&#9;runs =</p><p>&#9;&#9;&#9;1 = { text = Centered  }</p><p>&#9;&#9;&#9;2 =</p><p>&#9;&#9;&#9;&#9;style = { textStyle = bold }</p><p>&#9;&#9;&#9;&#9;text = Hello</p><p>&#9;&#9;&#9;3 = { text =  World }</p><p>&#9;2 =</p><p>&#9;&#9;runs =</p><p>&#9;&#9;&#9;1 = { text = Left-aligned  }</p><p>&#9;&#9;&#9;2 =</p><p>&#9;&#9;&#9;&#9;style = { textColor = 255,0,0 }</p><p>&#9;&#9;&#9;&#9;text = Hello</p><p>&#9;&#9;&#9;3 = { unicodeText = <i>unicodeString</i> }</p><p></p><p>[ For brevity, single element arrays are represented using { ... } notation ]</p><p></p><p>When setting the styledText property, the engine uses a very permissive algorithm to parse the arrays as follows:</p><p></p><p>&#9;parseStyledTextArray pStyledText</p><p>&#9;&#9;repeat for each element tEntry of pStyledText</p><p>&#9;&#9;&#9;if tEntry is a sequence then</p><p>&#9;&#9;&#9;&#9;parseStyledTextArray tEntry</p><p>&#9;&#9;&#9;else if tEntry has key runs then</p><p>&#9;&#9;&#9;&#9;begin paragraph with style tEntry[style]</p><p>&#9;&#9;&#9;&#9;parseStyledTextRunArray tEntry[runs]</p><p>&#9;&#9;&#9;&#9;end paragraph</p><p>&#9;&#9;&#9;else if tEntry is an array then</p><p>&#9;&#9;&#9;&#9;append tEntry[text] with style tEntry[style]</p><p></p><p>&#9;parseStyledTextRunArray pRun</p><p>&#9;&#9;repeat for each element tRun in pRuns</p><p>&#9;&#9;&#9;if tRun is a sequence then</p><p>&#9;&#9;&#9;&#9;parseStyledTextRunArray tRun</p><p>&#9;&#9;&#9;else</p><p>&#9;&#9;&#9;&#9;append tRun[text] with style tEntry[style]</p><p></p><p>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.</p></comments>
	</description>
</doc>