Name: formattedText

Type: property

Syntax: set the formattedText of [<chunk> of] <field> to <string>

Syntax: get the formattedText of [<chunk> of] <field>

Summary:
Unwraps hard-wrapped <lines>, or provides the hard-wrapped contents of a
<field>. 

Associations: field

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
local myTextFile
write the formattedText of field 1 to file myTextFile

Example:
get the formattedText of field "Field"
answer it with "okay"

Example:
put the formattedText of word 13 of field "list"

Value:
The <formattedText> of a <field> is a string.

Description:
Use the <formattedText> <property> 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). 

When you get a <field(keyword)|field's> <formattedText>, the
<field(object)|field's> text is converted to hard-wrapped text: An
end-of-line <character> is inserted at the end of each screen line, and
wherever a <return> <character> occurs in the <field(keyword)>, two
end-of-line <characters> are substituted. (If the
<field(object)|field's> <dontWrap> is true, each screen line ends in an
end-of-line <character>, so two end-of-line characters are substituted
for each <return> <character> in the field.)

When you set a field's <formattedText> <property>, the <string> is
unwrapped before being put in the <field(keyword)>. Double end-of-line
<characters> are converted to a single end-of-line <character>, and
single end-of-line characters are converted to spaces.

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 <formattedText> property maps
any explicit line breaks to newlines.

>*Note:* that since the vGrid property turns dontWrap on for the
> paragraph, using the line-break char in table paragraphs will have no
> effect. 

Any paragraphs with <listStyle> set are prefixed by an appropriate
plain-text form of the bullet or index.


References: chunk (glossary), return (constant), property (glossary), 
character (keyword), characters (keyword), field (keyword), 
lines (keyword), field (object), dontWrap (property), 
listStyle (property), plainText (property), 
unicodeFormattedText (property), unicodePlainText (property)

Tags: text processing

