ICommand Class Reference

#include <ICommand.h>

Inheritance diagram for ICommand:

Public Types
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
virtual void	GetName (PMString *name) const =0
virtual void	SetName (const PMString &newName)=0
virtual bool16	IsNameRequired () const =0
virtual const UIDList *	GetItemList () const =0
virtual const UIDList &	GetItemListReference () const =0
virtual void	SetItemList (const UIDList &newItemList)=0
virtual CommandState	GetCommandState () const =0
virtual bool16	IsDone () const =0
virtual Undoability	GetUndoability () const =0
virtual void	SetUndoability (Undoability newUndoability)=0
virtual void	SetCreatorID (int32 creatorID)=0
virtual int32	GetCreatorID () const =0
virtual bool16	CanJoin (const ICommand *pNewCmd) const =0
virtual bool16	LowMemIsOK () const =0
virtual const Target &	GetTarget () const =0
virtual void	DoImmediate (bool16 isDynamic=kFalse)=0
virtual void	LWDoImmediate ()=0
virtual void	SetActive (bool16 isActive)=0
virtual bool16	IsActive () const =0
virtual bool8	IsLWProcessed () const =0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

Design pattern documentation defines the intent of a command as "Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undoable operations"; within InDesign, commands are used to modify objects that persist in an InDesign database that supports undo. A command can only change data in one database.

Commands are created and processed using the utility CmdUtils. Parameters are passed in and out of the command via:

• data interfaces on the command.
• the item list. Most commands expect the objects to be operated on and the InDesign database that contains these objects to be passed via the item list. Some commands are however self targetting and either work on objects from one well known database, or, a database that is passed using a data interface on the command. See ICommand::GetItemList.

See Also

CmdUtils::CreateCommand

CmdUtils::ProcessCommand

CmdUtils::ScheduleCommand

CmdUtils

Command the base class used by command implementations; if you add objects that persist in an InDesign database that supports undoable operations you must also add commands that modify these objects.

ICommandMgr

IDataBase

Member Enumeration Documentation

anonymous enum

Unique creator ID.

Enumerator
kUniqueCreatorID	A magic value that isn't even considered equal to itself
kPassthroughCreatorID	Special value for a command that is passed through a previewable dialog independent of preview state. WARNING: Should only be used for commands that don't modify persistent data.

enum ICommand::CommandState

Command states. The command state tells observers in what execution state the command currently is. It is also used by the command processor in order to figure out in what way cascading commands relate to each other.

Enumerator
kNotDone	before or while the command is done
kDoneDynamic	during dynamic execution
kDone	after the command is done

enum ICommand::Priority

Command priority. Scheduled cmds are processed acording to their priority. Cmds with kHighPriority, kHighestPriority are processed at the next possible moment when the cmdprocessor has finished all currently processed commands

Enumerator
kLowestPriority	lowest
kLowPriority	low
kMediumPriority	medium
kHighPriority	high
kHighestPriority	highest

enum ICommand::Undoability

Undoability of a command. The undoability of a command specifies if it is meant to be a single undo step of it's own (kRegularUndo) or if it needs to be undone/redone with the previous/next undo step (kAutoUndo case).

Enumerator
kAutoUndo	The command does not show up in undo / redo menu items, it is always undone / redone with some other step.
kRegularUndo	Default: The command shows up in undo /redo menu items in its own distinct step (if it is not part of a sequence).

Member Function Documentation

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

pure 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

Implemented in Command.

virtual CommandState ICommand::GetCommandState ( ) const

pure 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

Implemented in Command.

virtual int32 ICommand::GetCreatorID ( ) const

pure virtual

Get the creator ID

Returns

the creator ID of the command

Implemented in Command.

virtual const UIDList* ICommand::GetItemList ( ) const

pure 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

Implemented in Command.

virtual const UIDList& ICommand::GetItemListReference ( ) const

pure virtual

Get a reference to the item list.

Returns

reference to a UIDList

See Also

ICommand::GetItemList

Implemented in Command.

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

pure 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.

Implemented in Command.

virtual Undoability ICommand::GetUndoability ( ) const

pure virtual

Returns the undoability of the command.

Returns

undoability value

Implemented in Command.

virtual bool16 ICommand::IsDone ( ) const

pure 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

Implemented in Command.

virtual bool16 ICommand::IsNameRequired ( ) const

pure 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.

Implemented in Command.

virtual bool16 ICommand::LowMemIsOK ( ) const

pure virtual

Tell whether a command can operate under low memory conditions.

Returns

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

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

virtual void ICommand::SetCreatorID ( int32  creatorID )

pure 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

Implemented in Command.

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

pure virtual

Set the item list.

Parameters

newItemList

reference to item list to be copied into command

See Also

ICommand::GetItemList

Implemented in Command.

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

pure virtual

Set the name of the command.

Parameters

newName

the new name for the command.

Implemented in Command.

virtual void ICommand::SetUndoability ( Undoability  newUndoability )

pure 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

Implemented in Command.