Class: TCompoundDocument

Declaration: CompoundDocument.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TDocument, MCompoundDocument

Inherited By:

None.

Purpose:

TCompoundDocument adds support for a hierarchy of document components to the base TDocument class. It has persistent storage for document-level data, as well as separate storage of each component. TCompoundDocument also adds support for a command history and a save-always storage model.

Instantiation:

Allocate on the heap or the stack. Generally, it is allocated on the heap by the compound document store at the request of the document session.

Deriving Classes:

Do not derive from TCompoundDocument.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TCompoundDocument::TCompoundDocument

TCompoundDocument (TModel * rootModelToAdopt, TModelPresenterState * rootPresenterStateToAdopt)
TCompoundDocument (TDocumentComponent * rootComonentToAdopt);
TCompoundDocument ()

Interface Category:

API.

Purpose:

Creates a new compound document, given a model and presenter state to use for the root component.
Creates a new compound document for the specified document component.
Default constructor. This is only for internal use by Resurrect.

Calling Context:

Called to construct a new document in memory.
Called to construct a new document for the specified root component.
Only for internal use by Resurrect. Developers should treat as protected.

Parameters:

TModel * rootModelToAdopt -The model for the root component.
TModelPresenterState * -The presenter state for the root component.
TDocumentComponent * rootComponentToAdopt -The root component.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default constructor is protected.

Member Function: TCompoundDocument::~TCompoundDocument

~ TCompoundDocument ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetRootComponentReference

virtual TDocumentComponentReference GetRootComponentReference () const

Interface Category:

API.

Purpose:

Provides access to the root document component of the document. A compound document is a hierarchy of document components. The root component is owned and managed by the document.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the root component of the document.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetRootModelReference

virtual TModelReference GetRootModelReference () const

Interface Category:

API.

Purpose:

Provides access to the model in the root document component of the document. A compound document is a hierarchy of document components. The root component is owned and managed by the document.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the model in the root component of the document.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetRootPresenterStateReference

virtual TPresenterStateReference GetRootPresenterStateReference () const

Interface Category:

API.

Purpose:

Provides access to the presenter state in the root document component of the document. A compound document is a hierarchy of document components. The root component is owned and managed by the document.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the presenter state in the root component of the document.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::AdoptRootComponent

void AdoptRootComponent (TDocumentComponent *)

Interface Category:

API.

Purpose:

Adopts a new root component into the document. The previous root component (and all its embedded components) is replaced.

Calling Context:

Call this function directly.

Parameters:

TDocumentComponent * -The component to be adopted as the root component.

Return Value:

Returns the old root document component.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::AdoptAndDo

void AdoptAndDo (TCommandBinding *)
virtual void AdoptAndDo (TAbstractDocumentComponentCommandBinding *)

Interface Category:

API.

Purpose:

Adopts a document component command binding and executes it. The binding contains a command and a target, which can be a model selection or a presenter state selection. Modify document data only using commands. The command is added to the document history if it modifies the document and is undoable. If it modifies the document and is not undoable, the document history is cleared.

Calling Context:

Call this function directly.

Parameters:

TCommandBinding * -A document component command binding.
TAbstractDocumentComponentCommandBinding * -A document component command binding.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::DoBegin

virtual void DoBegin (TAbstractDocumentComponentCommandBinding &)

Interface Category:

API.

Purpose:

Takes an incremental command and begins execution. The binding contains a command and target, which can be a model selection or a presenter state selection. Modify document data only using commands. The command is added to the document history if it modifies the document and is undoable. If it modifies the document and is not undoable, the document history is cleared. Only one incremental command can be outstanding at any one time. If another command is started, the currently executing incremental command is automatically ended.

Calling Context:

Call this function directly.

Parameters:

TAbstractDocumentComponentCommandBinding & -A document component command binding.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::DoIncrement

virtual void DoIncrement (TAbstractDocumentComponentCommandBinding &)

Interface Category:

API.

Purpose:

Takes an incremental command and continues execution. The command binding must be the same binding used in a previous DoBegin.

Calling Context:

Call this function directly.

Parameters:

TAbstractDocumentComponentCommandBinding & -A document component command binding.

Return Value:

None.

Exceptions:

Throws TCompoundDocumentException::kExpectedDoBegin if DoBegin was not previously called for this command.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (DoBegin previously called for this command).

Member Function: TCompoundDocument::AdoptAndDoEnd

virtual void AdoptAndDoEnd (TAbstractDocumentComponentCommandBinding *)

Interface Category:

API.

Purpose:

Adopts an incremental command and ends execution. The command binding must be the same binding used in a previous DoBegin.

Calling Context:

Call this function directly.

Parameters:

TAbstractDocumentComponentCommandBinding * -A document component command binding.

Return Value:

None.

Exceptions:

Throws TCompoundDocumentException::kExpectedDoBegin if DoBegin was not previously called for this command.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (DoBegin previously called for this command).

Member Function: TCompoundDocument::AddCommandStatusReceiver

void AddCommandStatusReceiver (TCommandStatusReceiver* )

Interface Category:

API.

Purpose:

Adds a command status receiver that is notified when the document executes commands.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::RemoveCommandStatusReceiver

void RemoveCommandStatusReceiver (const TCommandStatusReceiver &)

Interface Category:

API.

Purpose:

Removes a command status receiver so that it is no longer notified when the document executes commands.

Calling Context:

Call this function directly.

Parameters:

const TCommandStatusReceiver & -The receiver to remove.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetUndoRedoStatus

virtual void GetUndoRedoStatus (bool & undoAllowed, bool & redoAllowed) const

Interface Category:

API.

Purpose:

Returns the status on the availability of commands in the command history for undo and redo.

Calling Context:

Call this function directly.

Parameters:

bool & undoAllowed -A command is available for undo.
bool & redoAllowed -A command is available for redo.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetUndoRedoStatusInterest

TInterest GetUndoRedoStatusInterest () const

Interface Category:

API.

Purpose:

Gets an interest in notification on changes to the undo/redo status.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::HistoryFlushCommands

virtual void HistoryFlushCommands ( long numberOfCommandsToKeep )

Interface Category:

API.

Purpose:

Causes the document's command history to be flushed.

Calling Context:

Call this function directly.

Parameters:

long numberOfCommandsToKeep -The number of commands to keep.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::HistoryUndo

virtual void HistoryUndo ()

Interface Category:

API.

Purpose:

Undoes the last command done for the document. This undoes the last command completed or an incremental command that is still in progress. The incremental command is ended before it is undone.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws kNoCommandsToUndo if a command is not available for undo.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion(GetUndoRedoStatus returns undoAllowed ==true).

Member Function: TCompoundDocument::HistoryRedo

virtual void HistoryRedo ()

Interface Category:

API.

Purpose:

Redoes the last command undone for the document.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws kNoCommandsToRedo if a command is not available for redo.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion(GetUndoRedoStatus returns redoAllowed ==true).

Member Function: TCompoundDocument::GetTimeStamp

TPseudoTimeStamp GetTimeStamp () const

Interface Category:

API.

Purpose:

Provides access to the document time stamp. This stamp is updated every time data held by the document is modified. This includes data contained in document components.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the time stamp of the last modification to the document.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetStyleAllChangesInterest

TModelStyleAllChangesInterest GetStyleAllChangesInterest (const TModelStyle & thePatternToMatch)

Interface Category:

API.

Purpose:

Gets an interest in a particular model style that is changed or removed. If you use or inherit model styles, you need to connect for notification of changes in these styles.

Calling Context:

Call this function directly.

Parameters:

const TModelStyle & thePatternToMatch -The style to receive change notification on.

Return Value:

Returns the object representing an interest in a style change notification. This can be added to a notifier connection to receive the notifications.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetStyleChangedInterest

TModelStyleChangedInterest GetStyleChangedInterest (const TModelStyle & thePatternToMatch)

Interface Category:

API.

Purpose:

Gets an interest in a particular model style that is changed. If you use or inherit model styles, you need to connect for notification of changes in these attributes.

Calling Context:

Call this function directly.

Parameters:

const TModelStyle & thePatternToMatch -The style to receive change notification on.

Return Value:

Returns the object representing an interest in a style change notification. This can be added to a notifier connection to receive the notifications.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetStyleRemovedInterest

TModelStyleRemovedInterest GetStyleRemovedInterest (const TModelStyle & thePatternToMatch)

Interface Category:

API.

Purpose:

Gets an interest in a particular model style that is removed. If you use or inherit model styles, you need to connect for notification of removal of these attributes.

Calling Context:

Call this function directly.

Parameters:

const TModelStyle & thePatternToMatch -The style to receive change notification on.

Return Value:

Returns the object representing an interest in a style change notification. This can be added to a notifier connection to receive the notifications.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream the object is streamed out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream the object is streamed in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::IncrementTimeStamp

void IncrementTimeStamp ()

Interface Category:

API.

Purpose:

Increments the document's time stamp. The time stamp is guaranteed to be greater than the old time stamp, but can be incremented by more than 1.

Calling Context:

Called by derived classes that change the document's state.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Postconditions: Assertion (NewTimeStamp >OldTimeStamp).

Member Function: TCompoundDocument::AdoptDocumentState

virtual void AdoptDocumentState (TDocumentState *)

Interface Category:

API.

Purpose:

Adopts the specified document state.

Calling Context:

Call this function directly.

Parameters:

TDocumentState * -The document state to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::GetRootComponent

TDocumentComponent * GetRootComponent ()
const TDocumentComponent * GetRootComponent () const

Interface Category:

API.

Purpose:

Returns the root component for this compound document.
Returns the root component for this compound document.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
Takes no parameters.

Return Value:

Returns a pointer to the root component for this compound document.
Returns a const pointer to the root component for this compound document.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundDocument::CreatePresenter

virtual TDocumentPresenter * CreatePresenter (const TPlaceReference &) const

Interface Category:

API.

Purpose:

Creates a new document presenter at the specified place.

Calling Context:

Call this function directly.

Parameters:

const TPlaceReference & -The place at which to create the new document presenter.

Return Value:

Returns the newly create document presenter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.