TextOutputStream

From Xojo Documentation

Revision as of 18:56, 19 November 2009 by WikiSysop (talk) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Description

In order to write text to a file, you need to create a TextOutputStream object. TextOutputStreams have methods that allow to write to a file and close the file when you are done writing to it. They are created by calling the Create and Append shared methods. If you need to specify the encoding of the text, call ConvertEncoding prior to writing the file.


Super Class

Object

Properties

Name Type Parameters Description
Delimiter String The character used to mark the end of a line of text written to the file. The default is a carriage return.
Handle
Introduced 2005R5
Integer Type as Integer Handle returns a handle of the Type passed or -1 if the requested Type cannot be retrieved.

The class constants given below can be passed as the parameter. 1- HandleTypeWin32Handle. A Windows32 OS handle. 2- HandleTypeFilePointer. A file pointer. 3- HandleTypeFileNumber. A file descriptor. 4- HandleTypeMacFileRefNum. A file reference number. 5- HandleTypeMacFileSpecPointer. An FSSpec.

LastErrorCode
Introduced 5.5
Integer Reports the last file I/O error. Error numbers are given as original file system error codes.


Methods

Name Parameters Result Type Description
Close Closes the TextOutputStream.
WriteLine Text as String Writes the text passed to the TextOutputStream and appends the Delimiter to the end of the line.


Constructors

Name Parameters Description
TextOutputStream Handle as Integer,

Type as Integer

Type is one of the HandleType class constants and Handle is the appropriate handle type specified by the Type parameter.

The HandleType class constants are as follows: 1- HandleTypeWin32Handle. A Windows32 OS handle. 2- HandleTypeFilePointer. A file pointer. 3- HandleTypeFileNumber. A file descriptor. 4- HandleTypeMacFileRefNum. A file reference number. 5- HandleTypeMacFileSpecPointer. An FSSpec. For instance, you can use a Declare to open a file with whatever permissions that you wish, and then pass the Handle to a stream object's constructor.


Class Constants

The following class constants can be used to specify the optional type parameter in the constructor and the Handle property.

Class Constant Description
HandleTypeWin32Handle A Windows 32 OS handle
HandleTypeFilePointer A file pointer.
HandleTypeFileNumber A file descriptor.
HandleTypeMacFileRefNum A file reference number
HandleTypeMacFileSpecPointer An FSSpec.


Shared Methods

Name Parameters Return Type Description
Append file as FolderItem TextOutputStream Opens the passed text file so that text can be appended to existing text. The append is done by calling Write or WriteLine. Call Close when you are finished writing to the file.

An IO error will trigger an IOException. The Append shared method replaces the deprecated FolderItem.AppendToTextFile.

Create
Introduced 2009r4
file as FolderItem TextOutputStream Creates a text file for so that text can be written. The write is done by calling Write or WriteLine. Call Close when you are finished writing to the file.

An IO error will trigger an IOException. The Create shared method replaces the deprecated FolderItem.CreateTextFile.


Interfaces

The TextOutputStream class implements the Writeable class interface. Here are the methods specified by this interface.

Name Parameters Return Type Description
Flush Flushes the contents of the internal buffers to disk, clearing the buffers.
Write Text as String Writes the passed Text to the disk or port.
WriteError Boolean Returns True if there were any errors in the write operation.


Notes

If you need to write the file using a particular encoding, use the ConvertEncoding function to first convert the encoding of the text to the desired encoding before passing the text to the Write or WriteLine methods. Here is an example:

Dim f As FolderItem 
Dim t as TextOutputStream 
f = GetSaveFolderItem(FileTypes1.Text,"Sample.txt")
if f <> Nil then
  t = TextOutputStream.Create(f)
  t.Write ConvertEncoding(TextField1.text, Encodings.WindowsANSI)
  t.close
End if


Creating and Appending to a Text File

Use Append when you want to open an existing text file and append text data to it. Use Create to write to a new text file. The following two examples illustrate the difference. Each example writes the text in TextField1 to the text file.

This example appends the text in TextField1 to the text file that was opened by GetOpenFolderItem:

Dim t as TextOutputStream
If f <> Nil then
  t = -TextOutputStream.Append(f)
  
  t.Write TextField1.text
  t.Close
End if

This example writes to a new text file.

Dim t as TextOutputStream


f=GetSaveFolderItem(FileTypes1.Text,"Create Example.txt")
If f <> Nil then
  t=TextOutputStream.Create(f)
  t.WriteLine(TextField1.text)
  t.Close
End if


Examples

This example displays the Save As dialog box. A text file is then created and the text properties of three TextFields are written to the new file. Finally the file is closed.

Dim fileStream As TextOutputStream
file=GetSaveFolderItem(FileTypes1.Text,"My Info.txt")
if file <> Nil then
fileStream=TextOutputStream.Create(f)
fileStream.WriteLine namefield.text
fileStream.WriteLine addressfield.text
fileStream.WriteLine phonefield.text
fileStream.Close
End if


See Also

BinaryStream, FolderItem, IOException, TextInputStream, TextOutputStream classes; ConvertEncoding function; Encodings module; Writeable class interface.