IlvCommandHistory Class Reference

A command stack allowing the implementation of the undo/redo functionality. More...

#include <ilviews/base/command.h>

Inheritance diagram for IlvCommandHistory:

List of all members.

Public Member Functions
	IlvCommandHistory (IlUInt n=64)
	Constructor.
void	add (IlvAction *c)
	Adds an action or a command to the history.
virtual IlBoolean	canRedo (IlUInt=1) const
	Specifies whether there are at least n commands that can be redone.
virtual IlBoolean	canUndo (IlUInt n=1) const
	Specifies whether there are at least n commands that can be undone.
void	closeMacro ()
	Closes the macro that is currently open, if any, and places it on top of the stack of added commands.
IlBoolean	isMacroRecording () const
	Specifies whether calls to add, undo, and redo are currently delegated to an internally opened macro, or are handled by the history itself.
IlvCommand *	lastUndoneCommand ()
	Returns the last undone command.
void	openMacro (const IlString &name)
	Opens a macro for storing a list of commands that can be undone or redone in a single operation.
virtual void	redo (IlUInt=1)
	Redoes the last n undone commands.
void	setMacroName (const IlString &name)
	Sets the user name of the internal macro that is currently open, if there is one.
virtual void	undo (IlUInt n=1)
	Undoes the last n commands added to the history.

---

Detailed Description

A command stack allowing the implementation of the undo/redo functionality.

Library: views

The class IlvCommandHistory handles a stack of commands that are applied to objects held by a manager or any object holder, such as a document class, and lets you undo and redo these commands.

A request for undo pops a command out of the stack, and applies its inverse command. The redo operation redoes the last undone command and puts it back on top of the stack. The repeat operation takes the last command or action executed, duplicates it, and puts it on top of the stack.

See also:

IlvActionHistory, IlvCommand, IlvCommandHistory

---

Constructor & Destructor Documentation

IlvCommandHistory::IlvCommandHistory

(

IlUInt

n = 64

)

Constructor.

For the command history to be fully functional, you should attach it to an IlvActionSelectionHandler object by calling setSelectionHandler after it has been created.

Parameters:

n

The maximum number of commands that can be stored in the history list.

---

Member Function Documentation

void IlvCommandHistory::add

(

IlvAction *

c

)

[virtual]

Adds an action or a command to the history.

If the action is a command, it is executed, if necessary, and added to the list. If it is not command, the action is executed and deleted if it has not been reparented (that is, it has not been added to another IlvActionHistory by an external observer).
If a macro is currently open, the command is added to this macro. Otherwise it is simply added to the list. If there are undone commands left in the stack, these commands are destroyed.

Parameters:

c

The action or command to be added to the history.

Reimplemented from IlvActionHistory.

virtual IlBoolean IlvCommandHistory::canRedo

(

IlUInt

= 1

)

const [virtual]

Specifies whether there are at least n commands that can be redone.

This includes any commands added to the internally opened macro command, if there is one.

virtual IlBoolean IlvCommandHistory::canUndo

(

IlUInt

n = 1

)

const [virtual]

Specifies whether there are at least n commands that can be undone.

Parameters:

n

The number of commands that are checked.

Returns:

IlTrue if the last n commands can be undone, or IlFalse if at least one of the last n command cannot be undone.

void IlvCommandHistory::closeMacro

(

)

Closes the macro that is currently open, if any, and places it on top of the stack of added commands.

If a macro is currently open, the method simply decrements an internal counter. If this counter equals 0, the macro is closed and put back on top of the stack.

IlvCommand* IlvCommandHistory::lastUndoneCommand

(

)

Returns the last undone command.

Returns:

A pointer to the last command that was undone, or 0 if there is none.

void IlvCommandHistory::openMacro

(

const IlString &

name

)

Opens a macro for storing a list of commands that can be undone or redone in a single operation.

If a macro is currently open, the method simply increments an internal counter and returns. Otherwise, it creates an IlvMacroCommand object, to which all subsequent calls to add, undo, and redo) will be delegated, until a call to closeMacro closes the internal macro command and put it on the stack of executed commands.

Parameters:

name

The user name to be used in commands. This name is searched for in the message database associated with the display.

See also:

IlvMacroCommand

virtual void IlvCommandHistory::redo

(

IlUInt

= 1

)

[virtual]

Redoes the last n undone commands.

This method takes the last undone command added to the undo stack, calls its redo method, notifies all the observers of the command history that it has been redone, and pushes the command back on top of the stack of added commands, thus allowing it to be undone again. If a macro is currently open, the redo operation is delegated to the internally opened IlvMacroCommand. The operation is repeated n times.

Parameters:

n

The number of commands to be redone.

void IlvCommandHistory::setMacroName

(

const IlString &

name

)

Sets the user name of the internal macro that is currently open, if there is one.

Parameters:

name

The string that identifies, for the end user, the name of the currently opened macro.

virtual void IlvCommandHistory::undo

(

IlUInt

n = 1

)

[virtual]

Undoes the last n commands added to the history.

This method takes the last added command, calls its undo method, and notifies all the observers of the command history that it has been undone. Then, it adds the undone command on top of the stack of undone commands. This operation is repeated for the last n added commands. If a macro is currently open, the undo operation is delegated to the internally opened IlvMacroCommand.

Parameters:

n

The number of commands to be undone.