Class Documentation

Name:Print
Version:1.0
ID:ID_PRINT
Status:Stable
Category:Command
Date:June 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. All rights reserved.



Description

The Print class allows you to send text information to the data channel of any object. In the majority of cases it is used in conjunction with the Text class to view text files, but could also be used to print text to computers over a network, to printers, or any object that understands text data.

The following example prints a file to a Text object:

   <print src="athene:documents/readme.txt" object="[mytext]"/>

This example prints "Hello World":

   <print data="Hello World" object="[mytext]"/>

If output messages are required, you may also set the Output field to point to an object that accepts text messages. If any errors occur during the print, a human readable message will be printed to the output object to provide adequate feedback for the user.

Actions

The Print class supports the following actions:

Activate  Performs the printing process.
ClosingTag  If the object is non-static, this action will cause the Print object to activate and then self-destruct.
DataChannel  The Print class accepts text data through this action.

Structure

The Print object consists of the following public fields:

Data  The text information that you want to print.
Location  Set this field if the text originates from a file source.
Object  Refers to the object that will receive the text data.
Output  Result messages will be sent to the object referred to in this field.
Static  Set to TRUE to make the object static.
Action:Activate
Short:Performs the printing process.

Activating a print object results in the internal data or file contents being sent to the object specified in the Object field. If the Object field has not been set then an attempt will be made to send the output to the object referenced in the Output field.


Field:Data
Synonyms:Text
Short:The text information that you want to print.
Type:STRING
Status:Read/Write

The text that you want to be printed should be written to this field. If the text is located in a file, you may use the Location field as an alternative to setting the Data field.

The Data should be formatted as standard, printable ANSI text and may include return codes. Character codes such as backspace and delete are ignored.


Field:Location
Synonyms:Src
Short:Set this field if the text originates from a file source.
Type:STRING
Status:Read/Write

If the printable text is located in a text file, you may specify a pointer to that file by setting this field. If it is discovered that the file name does not exist when the print process takes place, nothing will be printed to the destination object.


Field:Object
Short:Refers to the object that will receive the text data.
Type:OBJECTID
Status:Read/Write

In order to print the text information you will need to specify an object that will accept text data. The object must support the DataChannel action and include specific support for the handling of text data. It is recommended that you check the documentation for the class of the destination object to make sure that it is a suitable candidate. If the object does not meet the necessary requirements, the print process will do nothing.


Field:Output
Short:Result messages will be sent to the object referred to in this field.
Type:OBJECTID
Status:Read/Write

If this field is set to a valid ObjectID, text messages will be sent to the object when the print process executes. This can be helpful for notifying the user that an error has occurred during the print process.

The object receiving the message must be capable of understanding text sent via data channels. In most cases it is recommended that a Text object is used for this purpose.


Field:Static
Short:Set to TRUE to make the object static.
Type:LONG
Status:Read/Init

By default, a Print object will execute itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get the Print object to perform is to call the Activate action.