Copyright 1992, 1993  by Allegheny College

FileSaver

INHERITS FROM	Object

DECLARED IN	FileSaver.h

WRITTEN BY	Charles G. Fleming and Judy D. Halchin

CLASS DESCRIPTION

A FileSaver is an object that performs most of the steps needed to allow a user to save data to a file.  It has save: and saveAs: methods which perform the actions for the standard Save and Save As menu choices.   Methods are also provided for saving files programmatically (see save, setFilname: and setDirectory:).  

A FileSaver must have a dataDelegate which implements the writeDataToStream: method.  It is the responsibility of the dataDelegate to write the data to be saved to the stream provided as an argument to this method.  A FileSaver may also have a delegate, which will receive the message dataWasWritten:success:errorCode: informing the delegate as to whether or not the data was successfully saved.   An associated FileRetriever instance is also optional.

INSTANCE VARIABLES

Inherited from Object	Class	isa;

Declared in FileSaver	id	delegate;
	id	dataDelegate;
	id	fileRetriever;
	char 	*filename;
	char 	*directory;

delegate 	The object that will receive notification of whether a file was saved. 

dataDelegate 	The object responsible for providing the data to be saved.

fileRetriever 	The FileRetriever that works with this instance of FileSaver. 

filename 	The name of the data file.

directory 	The full path to the directory of the data file.

METHOD TYPES

Initializing a new FileSaver	- init

Saving data	- save
	- save:
- saveAs: 

Setting and retrieving the filename	- filename
	- setFileName:
	- directory
	- setDirectory:

Assigning delegates	- setDelegate: 
- delegate
- setDataDelegate:
- dataDelegate

Assigning a FileRetriever	- setFileRetriever: 
- fileRetriever

INSTANCE METHODS

dataDelegate
- dataDelegate

Returns the object that furnishes the data to be saved to a file.  The FileSaver must have a dataDelegate which responds to a writeDataToStream: message.

See also:  ± setDataDelegate:

delegate
- delegate

Returns the object that receives the dataWasWritten:success:errorCode: message, or nil if there is no delegate.  The delegate is optional.

See also:  ± setDelegate:

directory
- (char *)directory

Returns the full path of the directory containing the data file, or an empty string if no file has been set yet.  

See also:  ± setDirectory:,  ± filename, ± setFilename

filename
- (char *)filename

Returns the name of the data file, or an empty string if no name has been set yet.  This name does not include the path.

See also: ± setFilename:,  ± directory, ± setDirectory

fileRetriever
- fileRetriever

Returns a pointer to the fileRetriever, or nil if there is not an associated FileRetriever.  The FileSaver will send the fileRetriever setFilename: and setDirectory: messages whenever a file is saved.    

See also:  ± setFileRetriever:, setFilename: (FileRetriever), setDirectory: (FileRetriever)

init
- init

Initializes and returns the receiver, a new FileSaver instance.  This method initializes filename and directory to the empty string.

save
- (BOOL)save

Writes the data provided by the dataDelegate to the file filename in the directory directory. The filename and directory must be previously set (with one of the methods save: and saveAs:, or with the pair setFilename: and setDirectory:).  A stream is opened and the dataDelegate is sent a writeDataToStream: message requesting it to write its data to the stream.  The stream is then written to the file.  After the file is written, the delegate is sent a dataWasWritten:success:errorCode: message if there is a delegate which implements that method.  The fileRetriever, if there is one, is sent setFilename: and setDirectory: messages.  Returns YES if the data was successfully saved; otherwise, it returns NO.

See also:  ± save:,  ± saveAs:

save:
- save:sender

Writes the data provided by the dataDelegate to the file filename in the directory directory.   If filename is the empty string, a SavePanel is displayed to the user to get a file name.  A stream is opened and the dataDelegate is sent a writeDataToStream: message requesting it to write its data to the stream.  The stream is then written to the file.  After the file is written, the delegate is sent a dataWasWritten:success:errorCode: message if there is a delegate which implements that method.  The fileRetriever, if there is one, is sent setFilename: and setDirectory: messages.
Returns self.

See also:  ± save,  ± saveAs:

saveAs:
- saveAs:sender

Writes the data provided by the dataDelegate to a file chosen by the user.   A SavePanel is displayed to the user to choose a file.  A stream is then opened and the dataDelegate is sent a writeDataToStream: message requesting it to write its data to the stream.  The stream is then written to the file that was chosen.  After the file is written, the delegate is sent a dataWasWritten:success:errorCode: message if there is a delegate which implements that method.  The fileRetriever, if there is one, is sent setFilename: and setDirectory: messages.
Returns self.

See also:  ± save,  ± save:

setDataDelegate:
- setDataDelegate:anObject

Sets a pointer to the object which will be responsible for supplying the data to be saved whenever the FileSaver receives a save, save: or saveAs: message.  Returns self.

See also:  ± dataDelegate

setDelegate:
- setDelegate:anObject

Sets a pointer to the object which will receive a dataWasWritten:success:errorCode: message after the FileSaver has attempted to save data to a file.  The delegate is optional.  Returns self.

See also:  ± delegate

setDirectory:
- setDirectory:(char *)path

Sets the contents of the directory instance variable.  This message may be sent by an associated FileRetriever.  Returns self.

See also:  ± directory,  ± filename,  ± setFilename:

setFilename:
- setFilename:(char *)name

Sets the contents of the filename instance variable.  name should be the name of the file and should not include the path to the file.  This message may be sent by an associated FileRetriever.  Returns self.

See also:  ± filename,  ± directory,  ± setDirectory:

setFileRetriever:
- setFileRetriever:anObject

Sets a pointer to an instance of FileRetriever.  fileRetriever will be sent setFilename: and setDirectory: messages whenever a file is saved.  Returns self.

See also:  ± fileRetriever

METHOD IMPLEMENTED BY THE DELEGATE

dataWasWritten:success:errorCode:
- dataWasWritten:sender success:(BOOL) flag errorCode:(int)code

This message notifies the delegate whether or not the FileSaver has successfully saved  to a file the data supplied by the dataDelegate.  Error codes are listed below.  Returns self.

METHOD IMPLEMENTED BY THE DATADELEGATE

writeDataToStream:
- (BOOL)writeDataToStream:(NXStream *)stream

This message requests that the dataDelegate write its the data to stream.  This method is called from the save, save: and saveAs: methods of FileSaver.  This method should return YES if the dataDelegate was able to write the data and NO if it was not.

CONSTANTS (defined in SaverAndRetriever.h)

	noStream 			= NX_APPBASE,
	noDataDelegate 		= NX_APPBASE+1
	doesNotRespondToMethod 	= NX_APPBASE+2
	cancelButtonPushed 		= NX_APPBASE+3
	dataNotWritten 		= NX_APPBASE+4
	dataNotRead 			= NX_APPBASE+5
	unableToSaveStreamToFile 	= NX_APPBASE+6
	noFile 			= NX_APPBASE+7
	noError 			= NX_APPBASE+8