Action Statement
Read in the contents of a file.
For Textual Regions:
read [colored] file FILE_NAME into TR_NAME
For List Boxes, Combination Boxes, Alphanumeric Spin Buttons, and Tables:
read file ASCII_FILE_NAME into {BOX_NAME|SPIN_NAME|TABLE_NAME}
For Image Regions:
read file BMP_FILE_NAME into IR_NAME [using IMAGE_MAP]
colored
Read a color-attributed file into the textual region. If the region is a colored textual region, individual characters are colored according to the color attributes stored with each character in the file.
FILE_NAME
A string value representing the name, including the extension, of an ASCII text file or a color-attributed file.
TR_NAME
The identifier for a textual region.
ASCII_FILE_NAME
A string value representing the name, including the extension, of an ASCII text file.
BOX_NAME
The identifier for a list box or a combination box.
SPIN_NAME
The identifier for an alphanumeric spin button.
TABLE_NAME
The identifier for a table.
BMP_FILE_NAME
A file containing a bitmapped image. If you do not specify an extension, ESL assumes the extension .BMP. If you do not specify an extension, and there is no file with the extension .BMP, ESL assumes that the file has no extension.
IR_NAME
The identifier for an image region.
using IMAGE_MAP
Associate an image map with the image region. IMAGE_MAP must be a string value representing the identifier for a previously defined image map, which maps the colors of an image.
Description
Use this statement to read the contents of any of the following:
An ASCII text file into a textual region, table, list box, combination box, or alphanumeric spin button.
A color-attributed file into a textual region.
A bitmap file into an image region.
This statement can be used only for textual regions, list boxes, combination boxes, alphanumeric spin buttons, tables, or image regions. Do not use this statement in conjunction with the CText module for the same file.
Valid control characters are \b (or \^H), \t (or \^I), and \n (or \^J). All other control characters contained in the file are ignored. The control character \t is only valid for textual regions. When \t is used, it will be expanded to spaces up to the next tab stop.
You should test the value of the built-in function ioerror after each read statement, to see if the operation was successful.
ESL does not distinguish between colored and uncolored files when you read files into image regions.
Textual Regions
When you read an ASCII file into a textual region, the foreground and background colors of the textual region are those specified in the textual region definition.
When the read statement is executed for a textual region, the text assumes the font specified in the textual region definition (or the default font for the program), and the text is inserted at the current position of the text cursor. If the text cursor is at a position where there is no text, ESL will insert the necessary new blanks up to the position of the text cursor, and then insert the file.
After execution, the text cursor is on the first column of the line immediately following the last line of the read-in file. Any text that was after the text cursor before the read statement was executed is moved to the right and down.
List Boxes and Combination Boxes
When the read statement is executed for a list box, each line from the text file is inserted according to the sort specification. If a sort order was not specified for a list box, the contents of the text file are added to the end of the list.
Alphanumeric Spin Buttons
When the read statement is executed for an alphanumeric spin button, each line from the text file is appended to the existing values in the spin button.
Tables
When you use this statement to read a file and insert rows into a table, ESL starts at the current cell position. This will overwrite rows, starting at the current row. If the file contains sufficient data to extend past the end of the table, then new rows will be added to the table. Note that this is different from the add to table insert row statement, which only inserts rows starting at the first column, ignoring the current cell position.
With read file, no rows above the current row, nor any columns to the left of the current column, will be modified. Each row in the file is read into the next row in a table. If there are more columns in the table than in the file, the other columns are not modified. If there are more columns in the file than in the table, the extras are ignored. For example, reading in a file with tab format where the file has one value per line would result in modifying the contents of the current column, starting at the current row. See column delimiter in the table Object Definition for further information on file formats.
Example
response to Open
read file "Report.txt" into Report
response to SalesSelect
read file TodaySales into ViewerA
# textual region
response to LotusBox
read colored file "Lotus2.col" into ColorMoney
# image region
response to OpenFile
read file "skier" into Display2 using ColorMap2
See Also
insert Drawing Statement
ioerror Action Inquiry Built-in Function
spin button Definition
table Object Definition
write Action Statement
