<doc>
	<legacy_id>2019</legacy_id>
	<name>formattedText</name>
	<type>property</type>

	<syntax>
		<example>set the formattedText of [<i>chunk</i> of]<i>field </i>to <i>string</i></example>
		<example>get the formattedText of [<i>chunk</i> of]<i>field</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Unwraps hard-wrapped <keyword tag="lines">lines</keyword>, or provides the hard-wrapped contents of a <keyword tag="field">field</keyword>.</summary>

	<examples>
<example>write the formattedText of field 1 to file myTextFile</example>
<example><p>get the formattedText of field "Field"</p><p>answer it with "okay"</p></example>
<example><p>put the formattedText of word 13 of field "list"</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="5.5">Now works at the field chunk level</changed>
<changed version="4.6">4.6</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</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="dontWrap">dontWrap Property</property>
		<property tag="plainText">plainText Property</property>
		<property tag="unicodeFormattedText">unicodeFormattedText Property</property>
		<property tag="unicodePlainText">unicodePlainText Property</property>
	</references>

	<description>
	<overview>Use the <b>formattedText</b> <glossary tag="property">property</glossary> to convert between unwrapped text (suitable for use in most programs) and wrapped text (suitable for use in programs that require fixed line lengths, such as some email systems).</overview>

		<parameters>
		</parameters>

	<value>The <b>formattedText</b> of a <keyword tag="field">field</keyword> is a string.</value>
	<comments>When you get a <keyword tag="field">field's</keyword> <b>formattedText</b>, the <glossary tag="field">field's</glossary> text is converted to hard-wrapped text: An end-of-line <keyword tag="character">character</keyword> is inserted at the end of each screen line, and wherever a <constant tag="return">return</constant> <keyword tag="character">character</keyword> occurs in the <keyword tag="field">field</keyword>, two end-of-line <keyword tag="characters">characters</keyword> are substituted. (If the <glossary tag="field">field's</glossary> <property tag="dontWrap">dontWrap</property> is true, each screen line ends in an end-of-line <keyword tag="character">character</keyword>, so two end-of-line characters are substituted for each <constant tag="return">return</constant> <keyword tag="character">character</keyword> in the field.)<p></p><p>When you set a field's <b>formattedText</b> <glossary tag="property">property</glossary>, the <i>string</i> is unwrapped before being put in the <keyword tag="field">field</keyword>. Double end-of-line <keyword tag="characters">characters</keyword> are converted to a single end-of-line <keyword tag="character">character</keyword>, and single end-of-line characters are converted to spaces.</p><p></p><p>The engine will interpret a numToChar(11) character in a field paragraph as an explicit linebreak when the (effective) dontWrap of the paragraph is false. This allows multiple &lsquo;lines&rsquo; to be displayed within a single paragraph. The <b>formattedText</b> property maps any explicit line breaks to newlines. </p><p></p><note>that since the vGrid property turns dontWrap on for the paragraph, using the line-break char in table paragraphs will have no effect.</note><p></p><p>Any paragraphs with <b>listStyle</b> set are prefixed by an appropriate plain-text form of the bullet or index.</p><p></p><note>The listStyle property is experimental. Please refer to the release notes for further information on this feature.</note></comments>
	</description>
</doc>