LDocument

LDocument is a PowerPlant class that is used for opening, saving, closing, reverting, and printing a document. LDocument is an abstract class which provides a framework for supporting standard document operations via AppleEvents.

Methods :

The methods in this class are:

LDocument()	~LDocument()
AskSaveAs()	AttemptClose()
AttemptQuitSelf()	Close()
DoAEClose()	DoAESave()
DoPrint()	DoRevert()
DoSave()	FindByFileSpec()
FindCommandStatus()	FindNamedDocument()
GetAEProperty()	GetDescriptor()
GetDocumentList()	HandleAppleEvent()
IsModified()	MakeCurrent()
MakeSelfSpecifier()	ObeyCommand()
SendAEClose()	SendAESaveAs()
SetModified()	UsesFileSpec()

Data Members:

The data members in this class are:

sDocumentList	mPrintRecordH
mIsModified	mIsSpecified

Operation:

You probably won't need to override all of these methods in a normal application, as many of them are complete.

Methods related to saving, reverting, and printing a document are empty, and need to be overrided.

Source files:

(Commander Classes)

LDocument.h

LDocument.cp

Ancestors:

LAttachable

LCommander

LModelObject

LDocument()

Purpose:

The constructors create objects from the passed-in parameters.

Access:

Public

Prototype:

LDocument();

LDocument( LCommander *inSuper );

The parameter for these constructors is:

LCommander*

inSuper

The pointer to the Supercommander.

~LDocument()

Purpose:

The destructor destroys the object.

Access:

Virtual, Public

Prototype:

virtual ~LDocument();

AskSaveAs()

Purpose:

Ask the user to save a Document and give it a name.

Access:

Virtual, Public

Prototype:

virtual Boolean AskSaveAs(

FSSpec &outFSSpec,

Boolean inRecordIt );

The parameters for this method are:

FSSpec&	outFSSpec	The reference to the file we are working with.
Boolean	inRecordIt	Unused.

Return:

Returns false if the user cancels the operation, else it returns true.

AttemptClose()

Purpose:

Attempt to close a document. The Document might not close if it is modified and the user cancels the operation when asked whether to save the changes.

Access:

Virtual, Public

Prototype:

virtual void AttemptClose( Boolean inRecordIt );

The parameter for this method is:

Boolean

inRecordIt

Unused.

Return:

None

AttemptQuitSelf()

Purpose:

Try to close a Document when quitting the program.

Access:

Virtual, Public

Prototype:

virtual Boolean AttemptQuitSelf(

SInt32 inSaveOption );

The parameter for this method is:

SInt32

inSaveOption

The save options for the document.

Return:

Return false if the user cancels when asked whether to save changes to a modified Document.

Close()

Purpose:

Close a document.

Access:

Public

Prototype:

virtual void Close();

None

Return:

None

DoAEClose()

Purpose:

Close a document in response to a close AppleEvent.

Access:

Virtual, Public

Prototype:

virtual void DoAEClose(

const AppleEvent &inCloseAE );

The parameter for this method is:

const   AppleEvent&

inCloseAE

The reference to the AppleEvent received.

Return:

None

DoAESave()

Purpose:

Save a Document in a particular file. This is equivalent to a "Save As" operation.

Subclasses should override this function to save the file, and should set mIsSpecified to true.

Access:

Virtual, Public

Prototype:

virtual void DoAESave(

FSSpec& inFileSpec,

OSType inFileType );

The parameters for this method are:

FSSpec&	inFileSpec	The reference to the file we are working with.
OSType	inFileType	The resource type for the file.

Return:

None

DoPrint()

Purpose:

Print a document.

Access:

Virtual, Public

Prototype:

virtual void DoPrint();

None

Return:

None

DoRevert()

Purpose:

Revert a document to its last saved version.

Access:

Virtual, Public

Prototype:

virtual void DoRevert();

None

Return:

None

DoSave()

Purpose:

Save a Document, which must already be specified. Subclasses should override this method to save a document to an existing file.

Access:

Virtual, Public

Prototype:

virtual void DoSave();

None

Return:

None

FindByFileSpec()

Purpose:

Return the document that uses the specified FSSpec.

Access:

Static, Public

Prototype:

static LDocument* FindByFileSpec(

const FSSpec &inFileSpec );

The parameters for this method are:

const FSSpec&

inFileSpec

The reference to the file we are working with.

Return:

A pointer to the LDocument that corresponds to the file we're interesting in.

FindCommandStatus()

Purpose:

Return whether a command is enabled and/or marked in a Menu. This method is an override of FindCommandStatus() in LCommander.

FindNamedDocument()

Purpose:

Return the document with the specified name.

Access:

Static, Public

Prototype:

static LDocument* FindNamedDocument(

ConstStringPtr inName );

The parameter for this method is:

ConstStringPtr

inName

The string pointer for the name to be found.

Return:

A pointer to the LDocument we are interested in, or nil if not found.

GetAEProperty()

Purpose:

This method returns an AppleEvent property.

Access:

Virtual, Public

Prototype:

virtual void GetAEProperty(

DescType inProperty,

const AEDesc &inRequestedType,

AEDesc &outPropertyDesc ) const;

The parameters for this method are:

DescType	inProperty	The descriptor type for the property.
const AEDesc&	inRequestedType	The AppleEvent descriptor type.
AEDesc&	outPropertyDesc	The property descriptor.

Return:

None

GetDescriptor()

Purpose:

This method is a pure virtual method that must be implemented in your subclass. It returns the AppleEvent descriptor.

Access:

Pure Virtual, Public

Prototype:

virtual StringPtr GetDescriptor(

Str255 outDescriptor ) const = 0;

The parameter for this method is:

Str255

outDescriptor

The string.

Return:

A StringPtr to the descriptor string.

GetDocumentList()

Purpose:

Returns the value of the sDocumentList data member.

Access:

Static, Public

Prototype:

static TArray<LDocument*>& GetDocumentList();

None

Return:

Returns the value of the sDocumentList.

HandleAppleEvent()

Purpose:

This method handles an AppleEvent.

Access:

Virtual, Public

Prototype:

virtual void HandleAppleEvent(

const AppleEvent &inAppleEvent,

AppleEvent &outAEReply,

AEDesc &outResult,

long inAENumber );

The parameters for this method are:

const   AppleEvent&	inAppleEvent	The reference to the AppleEvent.
AppleEvent&	outAEReply	The AppleEvent reply.
AEDesc&	outResult	The AppleEvent result.
long	inAENumber	The AppleEvent number.

Return:

None

IsModified()

Purpose:

Return whether a document has been modified since it was last saved.

Access:

Virtual, Public

Prototype:

virtual Boolean IsModified();

None

Return:

None

MakeCurrent()

Purpose:

Make this Document the current one. You should override this method to do what makes sense for a particular kind of document. In most cases, this means selecting the main window for a document.

Access:

Virtual, Public

Prototype:

virtual void MakeCurrent();

None

Return:

None

MakeSelfSpecifier()

Purpose:

AppleEvent Object Model Support

Access:

Virtual, Public

Prototype:

virtual void MakeSelfSpecifier(

AEDesc &inSuperSpecifier,

AEDesc &outSelfSpecifier ) const;

The parameters for this method are:

AEDesc&	inSuperSpecifier	The AppleEvent super specifier.
AEDesc&	outSelfSpecifier	The AppleEvent self specifier.

Return:

None

ObeyCommand()

Purpose:

Respond to commands.

Access:

Virtual, Public

Prototype:

virtual Boolean ObeyCommand( CommandT inCommand,

void *ioParam );

The parameters for this method are:

CommandT	inCommand	Command passed to this method.
void*	ioParam	The data block accompanying the command.

Return:

Return true if the command was handled, else return false.

SendAEClose()

Purpose:

Sends the close AppleEvent.

Access:

Virtual, Public

Prototype:

virtual void SendAEClose(

SInt32 inSaveOption,

FSSpec &inFileSpec,

Boolean inExecute );

The parameters for this method are:

SInt32	inSaveOption	The save options.
FSSpec&	inFileSpec	The reference to the file we are working with.
Boolean	inExecute	The value passed to SendAppleEvent().

Return:

None

SendAESaveAs()

Purpose:

Sends the Save As AppleEvent.

Access:

Virtual, Public

Prototype:

virtual void SendAESaveAs(

FSSpec &inFileSpec,

OSType inFileType,

Boolean inExecute );

The parameters for this method are:

OSType	inFileType	The resource type for the file.
FSSpec&	inFileSpec	The reference to the file we are working with.
Boolean	inExecute	The value passed to SendAppleEvent().

Return:

None

SetModified()

Purpose:

Specify whether a document has been modified since it was last saved.

Access:

Virtual, Public

Prototype:

virtual void SetModified( Boolean inModified );

The parameter for this method is:

Boolean

inModified

The value to set in mIsModified.

Return:

None

UsesFileSpec()

Purpose:

Return whether the Document has a file that uses the specified FSSpec.

Access:

Virtual, Public

Prototype:

virtual Boolean UsesFileSpec(

const FSSpec& inFileSpec) const;

The parameter for this method is:

const FSSpec&

inFileSpec

The reference to the file we are working with.

Return:

Return true if the document has a file with the FSSpec, else return false.

sDocumentList

Purpose:

The static document list of pointers to LDocument objects.

Access:

Static, Protected

Prototype:

static TArray<LDocument*> sDocumentList;

mPrintRecordH

Purpose:

The handle to the print record.

Access:

Protected

Prototype:

THPrint mPrintRecordH;

mIsModified

Purpose:

Indicates whether a document is modified (dirty) or not.

Access:

Protected

Prototype:

Boolean mIsModified;

mIsSpecified

Purpose:

Indicates whether a document has the specified information to save without interacting with the user first.

Access:

Protected

Prototype:

Boolean mIsSpecified;