Name: revPrintText

Type: command

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

Summary: Prints formatted or unformatted text.

Introduced: 1.0

OS: mac,windows,linux

Platforms: desktop,web

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.>*Important:* The revPrintText command does not accept direct 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

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 <Revolution custom library|custom library> when you create your <standalone application|standalone>. In the Inclusions section on the General screen of the <Standalone Application Settings> window, make sure that "Printing" is selected in the list of script libraries.

>*Note:* When included in a <standalone application>, the <Printing library> is implemented as a hidden <group> and made available when the <group> receives its first <openBackground> message. During the first part of the <application|application's> startup process, before this <message> is sent, the <revPrintText> <command> is not yet available. This may affect attempts to use this <command> in <startup>, <preOpenStack>, <openStack>, or <preOpenCard> <handler|handlers> in the <main stack>. Once the <application> has finished starting up, the <library> is available and the <revPrintText> <command> can be used in any <handler>.

Changes:
The fieldTemplate parameter was added in version 2.0.

References: textStyle (property), properties (property), HTMLText (property), textFont (property), textSize (property), startup (message), openBackground (message), preOpenStack (message), openStack (message), preOpenCard (message), revPrintField (library), Revolution custom library (library), Printing library (library), library (library), field (keyword), field (object), 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), revPrintReport (command), answer printer (command), platform (function)

Tags: printing
