#include <Command.h>

Inheritance diagram for Command:

Public Types
enum	CommandDummyArg { kItemList = 1 }

Public Types inherited from ICommand
enum	{ kDefaultIID = IID_ICOMMAND }

enum	CommandState { kNotDone, kDoneDynamic, kDone }

enum	Undoability { kAutoUndo = 0, kRegularUndo }

enum	{ kUniqueCreatorID = ~(int32)0, kPassthroughCreatorID = ~(int32)1 }

enum	Priority { kLowestPriority, kLowPriority, kMediumPriority, kHighPriority, kHighestPriority }

typedef UIDRef	Target

Public Member Functions
	Command (IPMUnknown *boss)

virtual void	GetName (PMString *name) const

virtual void	SetName (const PMString &newName)

virtual bool16	IsNameRequired () const

virtual const UIDList *	GetItemList () const

virtual const UIDList &	GetItemListReference () const

virtual void	SetItemList (const UIDList &newItemList)

virtual void	DoImmediate (bool16 isDynamic=kFalse)

virtual void	LWDoImmediate ()

virtual void	DoDynamic ()

virtual CommandState	GetCommandState () const

virtual bool16	IsDone () const

virtual bool16	CanJoin (const ICommand *pNewCmd) const

virtual void	SetCreatorID (int32 creatorID)

virtual int32	GetCreatorID () const

virtual bool16	LowMemIsOK () const

virtual const Target &	GetTarget () const

virtual Undoability	GetUndoability () const

virtual void	SetUndoability (Undoability newUndoability)

virtual void	SetActive (bool16 isActive)

virtual bool16	IsActive () const

virtual bool8	IsLWProcessed () const

Protected Types
enum	PredefinedTarget { kSessionWorkspaceTarget, kSessionTarget }

Protected Member Functions
virtual void	Do ()=0

virtual void	DoNotify ()

virtual void	SetCommandState (CommandState state)

virtual PMString *	CreateName ()

virtual void	SetUpTarget ()

virtual void	PreVerify (CommandState state)

virtual void	PostVerify (CommandState state)

void	SetTarget (const Target &newTarget)

void	SetTarget (PredefinedTarget newTarget)

void	SetTarget (IDataBase *db)

Protected Attributes
UIDList	fItemList

Detailed Description

Base class for implementing ICommand. If you are defining a new command, inherit

from this class. To implement a new command:



Define a boss in your plug-in that provides a command, for instance:



<pre>

Class { kYourCmdBoss, kInvalidClass, { IID_ICOMMAND, kYourCmdImpl, IID_IYOURDATA, kYourDataImpl, } },

If you require to pass additional parameters to your command aggregate data interfaces on your command boss. For example, you could implement a custom data interface, IYourData as shown above. Or you could re-use a data interface provided by the API.

Provide an implementation of the ICommand interface, for instance:


class YourCmd : public Command

{

public:

    YourCmd(IPMUnknown* boss);

    ~YourCmd();

protected:

    void Do();

    void DoNotify();

    PMString* CreateName();

};

Define bodies for your methods.

add IDs to your your ID.h file. For example:

Once you've done all this, you can add code to your plug-in that

processes your new command using CmdUtils.

See Also: ICommand; IIntData, IBoolData, IRealNumberData, IStringData, IStringListData, IUIDData, IUIDListData, IUIDRefListData; IErrorStringService

Member Enumeration Documentation

enum Command::PredefinedTarget

protected

Identifies a pre-defined target database that contains the objects to be changed by a command.
Enumerator
kSessionWorkspaceTarget
Changes objects that persist in application defaults (kWorkspaceBoss)
kSessionTarget
Changes objects that persist in SavedData

Member Function Documentation

virtual bool16 Command::CanJoin ( const ICommand * pNewCmd ) const

virtual

Join a command to this command. Should return true if the command was able to join the new command pNewCmd.

Parameters

pNewCmd the command to join with.

Returns: kTrue if successful

Implements ICommand.

virtual PMString* Command::CreateName ( )

protectedvirtual

Returns the name that appears in undo or redo menu items to identify this command.

Returns: the name of the command

Reimplemented in BPISetDataCmd, PstLstNewDataCmd, PstLstDeletePageItemCmd, PstLstDeleteDataCmd, PstLstModifyDataCmd, HidTxtModelCopyCmd, FrmLblCmd, NewCdlChartCmd, HidTxtModelCreateCmd, HidTxtModelDeleteCmd, HidTxtModelModifyTextCmd, ModifyCdlChartCmd, WritePDFVTDataSourceInfoCmd, XDocBkImageSizerCmd, XDocBkChangeServiceXMLImportPrefsCmd, PnlTrvChangeOptionsCmd, CusDtLnkChangeOptionsCmd, SnapSetPrefsCmd, XCatHndChangeEntityMappingCmd, XDocBkChangeOptionsCmd, CusCondTxtTagChangeCmd, FrmLblPrintPrefsCmd, and CompoundSequenceCmd.

virtual void Command::Do ( )

protectedpure virtual

Changes the model and must be defined by all commands. If you encounter an error condition within your Do method you normally set the global error code and return.

See Also: ErrorUtils::SetPMGlobalErrorCode

Implemented in BPISetDataCmd, PstLstNewDataCmd, PstLstDeletePageItemCmd, PstLstDeleteDataCmd, HidTxtModelCopyCmd, PstLstModifyDataCmd, NewCdlChartCmd, FrmLblCmd, HidTxtModelCreateCmd, HidTxtModelDeleteCmd, HidTxtModelModifyTextCmd, XDocBkImageSizerCmd, PnlTrvChangeOptionsCmd, SnapSetPrefsCmd, ModifyCdlChartCmd, XDocBkChangeServiceXMLImportPrefsCmd, WritePDFVTDataSourceInfoCmd, SnipRunRestoreLogCmd, XCatHndChangeEntityMappingCmd, CusDtLnkChangeOptionsCmd, XDocBkChangeOptionsCmd, CusCondTxtTagChangeCmd, FrmLblPrintPrefsCmd, CompoundSequenceCmd, and SequenceCmd.

virtual void Command::DoDynamic ( )

virtual

DEPRICATED Avoid using this function if possible - this is legacy and is deprecated.

virtual void Command::DoNotify ( )

protectedvirtual

Initiates notification, commands that want to perform notification define this method. It is called after the Do method has been called.

See Also: ISubject

Reimplemented in BPISetDataCmd, PstLstNewDataCmd, PstLstDeletePageItemCmd, PstLstDeleteDataCmd, PstLstModifyDataCmd, HidTxtModelCopyCmd, FrmLblCmd, HidTxtModelCreateCmd, HidTxtModelDeleteCmd, HidTxtModelModifyTextCmd, ModifyCdlChartCmd, WritePDFVTDataSourceInfoCmd, SnapSetPrefsCmd, CusDtLnkChangeOptionsCmd, PnlTrvChangeOptionsCmd, and CusCondTxtTagChangeCmd.

virtual CommandState Command::GetCommandState ( ) const

virtual

Returns the command state; observers (see IObserver::Update) can check this state is not yet done (pre-notification) or done.

Returns: the command state

Implements ICommand.

virtual int32 Command::GetCreatorID ( ) const

virtual

Get the creator ID

Returns: the creator ID of the command

Implements ICommand.

virtual const UIDList* Command::GetItemList ( ) const

virtual

Get the a pointer to the item list; the item list references the objects (by UID) the command should work on and the target database (IDataBase) that contains them. If the target to be worked on is not passed to the command via this item list then the command must be self targetting (see Command::SetTarget, Command::SetUpTarget).

Returns: pointer to a UIDList

Implements ICommand.

virtual const UIDList& Command::GetItemListReference ( ) const

virtual

Get a reference to the item list.

Returns: reference to a UIDList

See Also: ICommand::GetItemList

Implements ICommand.

virtual void Command::GetName ( PMString * name ) const

virtual

Get the name of the command; commands with the undoability kRegularUndo must have a name, for use in the undo/redo menu items (unless they override IsNameRequired to return kFalse).

Parameters

name	a pointer to the name for the command.

Implements ICommand.

virtual Undoability Command::GetUndoability ( ) const

virtual

Returns the undoability of the command.

Returns: undoability value

Implements ICommand.

virtual bool16 Command::IsDone ( ) const

virtual

Returns kTrue if the command state is kDone or kDoneDynamic, kFalse otherwise.

Returns: kTrue if the command state is kDone or kDoneDynamic, kFalse otherwise.

See Also: ICommand::GetCommandState

Implements ICommand.

virtual bool16 Command::IsNameRequired ( ) const

virtual

Is command required to have a name? By default, the return value is kTrue when undoability is equal kRegularUndo and kFalse otherwise. Override this virtual function when you have a command with regular undo and you want to use the name of another command (nested within the scope of the current one) to appear on the undo menu.

Implements ICommand.

virtual bool16 Command::LowMemIsOK ( ) const

virtual

Tell whether a command can operate under low memory conditions.

Returns: kTrue if the command is able to execute under low memory conditions.

Implements ICommand.

Reimplemented in BPISetDataCmd, PstLstNewDataCmd, PstLstDeletePageItemCmd, PstLstDeleteDataCmd, NewCdlChartCmd, PstLstModifyDataCmd, FrmLblCmd, ModifyCdlChartCmd, and WritePDFVTDataSourceInfoCmd.

virtual void Command::PostVerify ( CommandState state )

protectedvirtual

See Command::PreVerify.

Parameters

state

virtual void Command::PreVerify ( CommandState state )

protectedvirtual

Verification is called from SetCommandState as the command changes state. PreVerify is called as the command changes to kNotDone. PostVerify is called as the state changes to kDone. Verification routines should verify the particular state of an object or document when a change is completed and assert if there is something wrong. Possible additions to this mechanism is the ability to "turn off" verification under certain circumstances. Verification is only called for debug builds. [LDM]

Parameters

state

virtual void Command::SetCommandState ( CommandState state )

protectedvirtual

Sets the command state.

Parameters

state

virtual void Command::SetCreatorID ( int32 creatorID )

virtual

Set the creator ID. The creator id is important in the context of a previewable dialog. The dialog command interceptor uses it to tell whether two commands are the same.

Parameters

creatorID the new creator ID to use

Implements ICommand.

virtual void Command::SetItemList ( const UIDList & newItemList )

virtual

Set the item list.

Parameters

newItemList reference to item list to be copied into command

See Also: ICommand::GetItemList

Implements ICommand.

virtual void Command::SetName ( const PMString & newName )

virtual

Set the name of the command.

Parameters

newName the new name for the command.

Implements ICommand.

void Command::SetTarget ( const Target & newTarget )

protected

See Command::SetTarget(IDataBase*).

Parameters

newTarget

void Command::SetTarget ( PredefinedTarget newTarget )

protected

See Command::SetTarget(IDataBase*).

Parameters

newTarget

void Command::SetTarget ( IDataBase * db )

protected

Call this method from your constructor or your SetUpTarget method if the target of your command is not equivalent to the command manager of the database of the command's item list at the time of processing.

Parameters

db

virtual void Command::SetUndoability ( Undoability newUndoability )

virtual

Set the undoability of the command. This function allows changing the undoability of a command. Typically, SetUndoability is called to override the default undoability. Call this function before the Do() function of the command gets called (we recommend setting the undoability within the constructor of the command interface or within the implementation of the SetupTarget function).

Parameters

newUndoability the new undoability value for the command

Implements ICommand.

virtual void Command::SetUpTarget ( )

protectedvirtual

Sets up the target, the database that contains the objects changed by the command. Define if your command has a target that is not known at construction time and is not equivalent to the database passed in the command's item list when the command is processed.

See Also: Command::SetTarget

Reimplemented in NewCdlChartCmd, HidTxtModelCopyCmd, and CompoundSequenceCmd.

Member Data Documentation

UIDList Command::fItemList

protected

The command's item list.

Enumerator
kSessionWorkspaceTarget	Changes objects that persist in application defaults (kWorkspaceBoss)
kSessionTarget	Changes objects that persist in SavedData

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation