Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible, TCommonCommand
Inherited By:
TAdoptAnchorCommand
TAdoptCanvasGraphicCmd
TAdoptLinkCommand
TChangeCanvasGraphicCmd
TChangeStylesCommand
TCreateAndPublishAnchorCommand
TCreateLinkAtSourceCommand
TDeleteCanvasGraphicsCmd
TOrphanAnchorCommand
TOrphanDataCommand
TOrphanLinkCommand
TPasteAsLinkCommand
TReplaceTextCommand
TTypingCommand
TCommandRequiringDataFixup
TRecursiveModelCommandOn
Purpose:
A Command is an object which encapsulates a change to a target. A command has protocol to do, undo and redo the change. It has protocol for checking preconditions, and notifying of changes in the status of the preconditions. The target is the data upon which the command operates. The target is a parameterized type. Different instantiations of the TCommandOn template use different classes for the target. For a model command the target is usually a class derived from TModelSelection.
Instantiation:
Allocate on the heap or the stack. Normally allocated on heap.
Deriving Classes:
Derived classes must override the pure virtual function HandleDoBegin.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Invariants:
The undo type is immutable. The state must be accurate on the exit of the Do, DoBegin, DoIncrement, DoEnd, Undo, Redo, and Commit member functions.
virtual ~ TCommandOn ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::Do
void Do (ATarget & target)
Interface Category:
API.
Purpose:
Causes the command to be executed. This function is equivalent to DoBegin followed by DoEnd.
Calling Context:
Call this function directly.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kNew. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Causes the command execution to be started.
Calling Context:
Call this function directly.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kNew. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Executes an incremental command step. Must be called after DoBegin and before DoEnd.
Calling Context:
Call this function directly.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kBegun. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Cleans up after execution and sets the command state to done.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kBegun. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Reverses the effect of the command's Do sequence. Must be called after Do or Redo
Calling Context:
Call this function directly.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kBegun or kDone. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Restores the command's effect after an undo. Must be called after an Undo.
Calling Context:
Call this function directly.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kUndone. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Closes the command to further execution. A command that has been committed cannot be undone or redone.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws TCommandException if state is not equal to kBegun, kDone, or kUndone. Passes all other exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Identifies the ability of the command to be executed.
Calling Context:
Call this function directly.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if the command can be executed.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::CanUndo
bool CanUndo (const ATarget & target) const
Interface Category:
API.
Purpose:
Identifies the ability of the command to be undone.
Calling Context:
Call this function directly
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if the command may be undone.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::CanRedo
bool CanRedo (const ATarget & target) const
Interface Category:
API.
Purpose:
Identifies the ability of the command to be redone.
Calling Context:
Call this function directly.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if the command can be redone.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::AddDoInterests
void AddDoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Provides interests for notification for CanDo. Calls HandleAddDoInterests. The caller owns the interests returned in the collection.
Calling Context:
Call this function directly.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest> & fillin -The collection in which to return the interests.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::AddUndoInterests
void AddUndoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Provides interests for notification for CanUndo. Calls HandleAddUndoInterests. The caller owns the interests returned in the collection.
Calling Context:
Call this function directly.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest> & fillin -The collection in which to return the interests.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::AddRedoInterests
void AddRedoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Provides interests for notification for CanRedo. Calls HandleAddRedoInterests. The caller owns the interests returned in the collection.
Calling Context:
Call this function directly.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest> & fillin -The collection in which to return the interests.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::operator>>=
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & -The stream to which the object streams itself out.
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: TCommandOn::operator<<=
virtual TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & -The stream from which the object streams itself in.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library installed.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TCommandOn (TCommonCommand::UndoType)
- TCommandOn (const TCommandOn < ATarget > &)
Interface Category:
API.
Purpose:
- Constructor for use by derived classes.
- Copy constructor.
Calling Context:
- Called by the constructor of derived classes.
- Called to copy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
TCommandOn is an abstract base class--all the constructors are protected. Do not instantiate this class.
Member Function: TCommandOn::operator=
TCommandOn < ATarget > & operator =(const TCommandOn < ATarget > &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
- const const TCommandOn < ATarget > & -The object to be copied.
Return Value:
Returns a const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
TCommandOn is an abstract base class--all the constructors are protected. Do not instantiate this class.
Member Function: TCommandOn::HandleDoBegin
virtual void HandleDoBegin (ATarget & target)
Interface Category:
API.
Purpose:
Starts command execution.
Calling Context:
Called by DoBegin after command state has been verified.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is a pure virtual function and must be overridden by classes deriving from TCommandOn.
Preconditions:
Interface Category:
API.
Purpose:
Override for incremental command functionality. The default implementation of this function does nothing.
Calling Context:
Called by DoIncrement after command state has been verified.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Override this command to undo the effect of a reversible command. The default implementation of this function does nothing.
Calling Context:
Called by Undo after command state has been verified.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Override this function to restore the effect of an undone command. The default implementation of this function does nothing.
Calling Context:
Called by Redo after command state has been verified.
Parameters:
- ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Preconditions:
Interface Category:
API.
Purpose:
Override this function to identify if the command is currently able to be executed on the target.
Calling Context:
Called by CanDo after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if command can be executed on the target. The default implementation of this function returns true.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::HandleCanUndo
virtual bool HandleCanUndo (const ATarget & target) const
Interface Category:
API.
Purpose:
Override this function to identify if the command is currently able to be reversed.
Calling Context:
Called by CanUndo after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if command can be reversed on the target. The default implementation of this function returns true.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::HandleCanRedo
virtual bool HandleCanRedo (const ATarget & target) const
Interface Category:
API.
Purpose:
Override this function to identify if the command is currently able to restore its effect on the target.
Calling Context:
Called by CanRedo after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
Return Value:
Returns true if the command can currently restore its effect on the target. The default implementation of this function returns true.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::HandleAddDoInterests
virtual void HandleAddDoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Override to provide interests for CanDo for notification. The default implementation of this function does nothing.
Calling Context:
Called by AddDoInterests after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest>& -Return interests in this collection.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::HandleAddUndoInterests
virtual void HandleAddUndoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Override to provide interests CanUndo for notification. The default implementation of this function does nothing.
Calling Context:
Called by AddUndoInterests after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest>& -Return interests in this collection.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCommandOn::HandleAddRedoInterests
virtual void HandleAddRedoInterests (const ATarget & target, TCollectionOf<TInterest> & fillin) const
Interface Category:
API.
Purpose:
Override to provide interests CanRedo for notification. The default implementation of this function does nothing.
Calling Context:
Called by AddRedoInterests after the state of the command has been verified.
Parameters:
- const ATarget & target -The context of the call. Matches the type of the class parameter.
- TCollectionOf<TInterest>& -Return interests in this collection.
Return Value:
None.
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.
Copyright©1995 Taligent,Inc. All rights reserved.