IlvAction Class Reference

Object class encapsulating the interpretation of an action of the user in a given context. Similar in principle to callbacks, with added features. More...

#include <ilviews/base/action.h>

Inheritance diagram for IlvAction:

List of all members.

Public Member Functions
	IlvAction (const IlvAction &a)
	Copy constructor used to repeat actions.
	IlvAction (IlvActionHistory *h=0, IlBoolean r=((IlBoolean) 1), IlBoolean p=((IlBoolean) 0))
	Constructor.
virtual IlvAction *	duplicate () const
	Must be implemented in subclasses for the action to be repeatable.
virtual IlString	errorMessage (IlUInt &severity) const
	Returns an error message.
virtual void	execute ()
	Executes the action (external interface).
virtual void	executeIt ()=0
	Executes the action (internal interface).
IlvActionHistory *	getContext () const
	Returns the action history of the action or command.
IlBoolean	isCommand () const
	Indicates whether an action is an IlvCommand object.
IlBoolean	isDone () const
	Indicates whether the execute method has already been called for this action.
IlBoolean	isRepeatable () const
	Indicates whether an action can be repeated.
virtual void	setContext (IlvActionHistory *history)
	Sets the execution context and the history of an action.
void	setDone (IlBoolean d=((IlBoolean) 1))
	Specifies whether a command or action should be considered as being executed.
virtual IlString	userName () const
	Returns the name of the action in a readable form.
Public Attributes
IlvActionFlags	_flags
	Action flags. Can be set directly by subclasses to change the status of the action.

---

Detailed Description

Object class encapsulating the interpretation of an action of the user in a given context. Similar in principle to callbacks, with added features.

Library: views

The IlvAction class implements actions performed by the user. An action is often the result of the interpretation of a series of events by an interactor. For example, a "move object" interactor intercepts events such as pressing, dragging, and releasing the mouse and transforms them to a "move object" action. Generally, interactors, such as the button interactor, generate callbacks instead of actions. An action is the object equivalent of a callback that provides access to more features. The IlvAction class has an important subclass, IlvCommand, which defines actions that cause the data structure to be modified, and that the user should be able to undo.

See also:

IlvActionHistory, IlvCommand, IlvCommandHistory.

---

Constructor & Destructor Documentation

IlvAction::IlvAction	(	IlvActionHistory *	h = 0,
		IlBoolean	r = ((IlBoolean)1),
		IlBoolean	p = ((IlBoolean)0)
	)

Constructor.

Parameters:

	h	The action history defining the context in which the action is performed.
	r	A Boolean value specifying whether the action can be repeated.
	p	A Boolean value specifying whether the action is persistent.

IlvAction::IlvAction

(

const IlvAction &

a

)

Copy constructor used to repeat actions.

This constructor calls the member function setDone with IlFalse as its parameter, so that the action can be repeated by copying it and calling execute on the copy.

---

Member Function Documentation

virtual IlvAction* IlvAction::duplicate

(

)

const [virtual]

Must be implemented in subclasses for the action to be repeatable.

Most of the time, this member function is implemented by terminal classes of IlvAction and should perform the following:

 IlvAction* MyAction::duplicate() const
 { 
     return new MyAction(*this);
 }

Reimplemented in IlvMacroCommand, and IlvChangeValueCommand.

virtual IlString IlvAction::errorMessage

(

IlUInt &

severity

)

const [virtual]

Returns an error message.

This method should be redefined in action subclasses to generate error messages in case of failure.

Parameters:

severity

A value whose interpretation can be defined by the implementer.

virtual void IlvAction::execute

(

)

[virtual]

Executes the action (external interface).

Checks the return value of isDone. If it returns IlFalse, execute calls executeIt and informs all the observers associated with the action class or the action history that an action has been performed.

virtual void IlvAction::executeIt

(

)

[pure virtual]

Executes the action (internal interface).

This method must be implemented in subclasses to execute the action.

Implemented in IlvMacroCommand, and IlvChangeValueCommand.

IlvActionHistory* IlvAction::getContext

(

)

const

Returns the action history of the action or command.

An IlvActionHistory object is a context that stores the actions and commands that have been executed. It can be used to store additional information that can be used to simplify the execution of further actions. For example, this context can store the arguments provided to past commands to facilitate the implementation of a smart repeat mechanism.

IlBoolean IlvAction::isCommand

(

)

const

Indicates whether an action is an IlvCommand object.

Returns:

IlTrue if this action is a command and IlFalse otherwise.

IlBoolean IlvAction::isDone

(

)

const

Indicates whether the execute method has already been called for this action.

This flag is set by the execute method so that the same action is not executed twice. It is especially useful for IlvCommand objects because it indicates whether a command has been successfully executed (and therefore can be undone) or has been undone (and therefore can be redone).

IlBoolean IlvAction::isRepeatable

(

)

const

Indicates whether an action can be repeated.

Returns:

IlTrue if this action can be repeated, and IlFalse otherwise.

virtual void IlvAction::setContext

(

IlvActionHistory *

history

)

[virtual]

Sets the execution context and the history of an action.

Parameters:

history

The history of this action.

void IlvAction::setDone

(

IlBoolean

d = ((IlBoolean)1)

)

Specifies whether a command or action should be considered as being executed.

When an action or command is created and added to an IlvActionHistory, the action history will check isDone to see if the command has been done. If it is IlFalse it will call the execute method. You can call setDone(IlTrue) to prevent the action history from calling execute. When a command is undone, setDone(IlFalse) is called to indicate that the command can be executed again (IlvCommand::execute) or redone IlvCommand::redo.

virtual IlString IlvAction::userName

(

)

const [virtual]

Returns the name of the action in a readable form.

By default, the method userName searches the default message database of the display for an entry of the form '&<ActionClass>', and returns the string found.

Reimplemented in IlvMacroCommand, and IlvChangeValueCommand.