Name: revPrintText

Type: command

Syntax: revPrintText <textToPrint> [, <headerText> [, <footerText> [, <fieldTemplate>]]]

Summary:
Prints formatted or unformatted text.

Associations: printing library

Introduced: 1.0

OS: mac, windows, linux

Platforms: desktop

Security: printing

Example:
revPrintText "Hello world"

Example:
revPrintText myCollectedData,"Confidential" -- header with no footer

Example:
revPrintText (the htmlText of field "Info"),"Info",the time && the date

Example:
revPrintText field 1,,"prepared by John Smith" -- footer, no header

Example:
revPrintText it,tab & myTitle -- centered header

Example:
revPrintText thisText,,,the long name of field "Text"

Parameters:
textToPrint (string):


headerText (string):
If the headerText is empty, no page header is printed.

footerText (string):
If the footerText is empty, no page footer is printed.

fieldTemplate:
Any expression that evaluates to a field reference.

Description:
Use the <revPrintText> <command> to print any text from within a
<handler>. 

>*Important:*  The <revPrintText> <command> does not accept direct
> <object reference|field references> for the <fieldTemplate>
> <parameter>. For example, the following <statement> causes an error
> message: 

    revPrintText myText,,,field "Text" -- CAN'T USE THIS FORM


Instead, use a form that evaluates to a field reference, like this:

    revPrintText myText,,,the name of field "Text" -- use this form
    revPrintText myText,,,("field" && quote & "Text" & quote) -- or this


The <revPrintText> <command> can be used to print either formatted text
(via the <htmlText> <property|property's> format) or plain text. If you
are generating formatted text, see the <htmlText> <property> for a
description of the differences between the <htmlText>
<property|property's> formatting and standard <HTML>.

If the <textToPrint>, <headerText>, or <footerText> contains &lt;p&gt;
or a start/end tag pair, the <revPrintText> <command> assumes the text
is in the same format as the <htmlText> <property>. Otherwise, the
<revPrintText> <command> assumes the text is plain text.

If the text being printed is plain text, and a <fieldTemplate> is
specified, the text is printed with that <field(object)|field's>
<textFont>, <textSize>, and <textStyle>. Otherwise, the text is printed
in plain 12-point, with the default font of the <platform> being used.
(The <field(keyword)> specified in the <fieldTemplate> does not need to
contain any text; only its appearance <properties> are used, not its
contents. If you want to print the contents of the <field(keyword)>, use
the <revPrintField> <command> instead.)

If the <textToPrint>, <headerText>, or <footerText> contains any
<expression|expressions> of the form &lt;%expression%&gt;, the
expression is <evaluate|evaluated> and replaced with the value before
the text is printed. For example, if the <textToPrint> contains the text
Today's date is &lt;%the long date%&gt; the printed text reads Today's
date is Friday, February 15, 2002 (assuming, of course, that the
<revPrintText> <command> is <execute|executed> on that date).

You can also use the special values &lt;%pageNumber%&gt; and
&lt;%numPages%&gt; in the <textToPrint>, <headerText>, or <footerText>.
These expressions are replaced with the current page number or total
number of pages respectively.

The <headerText> and <footerText> can contain up to two tab characters:

* Everything up to the first tab character is left-aligned.
* Everything between the first and second tab characters is centered.
* Everything after the second tab character is right-aligned.

If the <headerText> or <footerText> contain more than two tab
characters, everything after the third tab is ignored.

To show the standard print dialog box, use the revShowPrintDialog
<command> before the <revPrintText> <command>.

>*Tip:*  If the <textToPrint> contains tags, the tags are interpreted as
> text style information. To print tags literally, set the <text> of a
> <field(keyword)> to the text you want to print, then use the
> <HTMLText> of that <field(keyword)> as the <textToPrint>. Converting
> to the <HTMLText> escapes the tags and allows them to be printed.

>*Important:*  The <revPrintText> <command> is part of the 
> <Printing library>. To ensure that the <command> works in a 
> <standalone application>, you must include this 
> <LiveCode custom library|custom library> when you create your 
> <standalone application|standalone>. In the Inclusions pane of the 
> <Standalone Application Settings> window, make sure the "Printing" 
> library checkbox is checked.

Changes:
The fieldTemplate parameter was added in version 2.0.

References: revPrintReport (command), answer printer (command),
revPrintField (command), platform (function), 
LiveCode custom library (glossary), application (glossary), 
standalone application (glossary), evaluate (glossary), 
property (glossary), text (glossary), execute (glossary), HTML (glossary), 
command (glossary), object reference (glossary), expression (glossary), 
main stack (glossary), group (glossary), 
Standalone Application Settings (glossary), message (glossary), 
parameter (glossary), statement (glossary), handler (glossary), 
field (keyword), Printing library (library), library (library), 
startup (message), openBackground (message), preOpenStack (message), 
openStack (message), preOpenCard (message), field (object), 
textStyle (property), properties (property), HTMLText (property), 
textFont (property), textSize (property)

Tags: printing

