Rogue Wave Views
Foundation Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Public Attributes
IlvAction Class Referenceabstract

Object class encapsulating the interpretation of an action of the user in a given context. More...

#include <ilviews/base/action.h>

Inheritance diagram for IlvAction:
IlvCommand IlvChangeValueCommand IlvMacroCommand

Public Member Functions

 IlvAction (IlvActionHistory *history=0, IlBoolean repeatable=IlTrue, IlBoolean persistent=IlFalse)
 Constructor. More...
 
 IlvAction (const IlvAction &action)
 Copy constructor used to repeat actions. More...
 
virtual ~IlvAction ()
 Destructor.
 
virtual IlvActionduplicate () const
 Must be implemented in subclasses for the action to be repeatable. More...
 
virtual IlString errorMessage (IlUInt &severity) const
 Returns an error message. More...
 
virtual void execute ()
 Executes the action. More...
 
virtual void executeIt ()=0
 Executes the action (internal interface). More...
 
IlvActionHistorygetContext () const
 Returns the action history of the action or command. More...
 
IlBoolean isCommand () const
 Indicates whether an action is an IlvCommand object. More...
 
IlBoolean isDone () const
 Indicates whether the execute() method has already been called for this action. More...
 
IlBoolean isRepeatable () const
 Indicates whether an action can be repeated. More...
 
virtual void setContext (IlvActionHistory *history)
 Sets the execution context and the history of an action. More...
 
void setDone (IlBoolean d=IlTrue)
 Specifies whether a command or action should be considered as being executed. More...
 
virtual IlString userName () const
 Returns the name of the action in a readable form. More...
 

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.

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 history = 0,
IlBoolean  repeatable = IlTrue,
IlBoolean  persistent = IlFalse 
)

Constructor.

Parameters
historyThe action history defining the context in which the action is performed.
repeatableSpecifies whether the action can be repeated.
persistentSpecifies whether the action is persistent.
IlvAction::IlvAction ( const IlvAction action)

Copy constructor used to repeat actions.

This constructor calls setDone(IlFalse) so that the action can be repeated by copying it and calling execute() on the copy.

Parameters
actionThe action to be copied.

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 final subclasses of IlvAction and should perform the following:

IlvAction* MyAction::duplicate() const
{
return new MyAction(*this);
}
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
severityA value whose interpretation can be defined by the implementer.
Returns
The error message.
virtual void IlvAction::execute ( )
virtual

Executes the action.

Checks the return value of isDone(). If it is 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 actually execute the action.

See also
execute().

Implemented in IlvChangeValueCommand, and IlvMacroCommand.

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.

Returns
The action history of the action or command.
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
historyThe history of this action.
void IlvAction::setDone ( IlBoolean  d = IlTrue)

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, userName() searches the default message database of the display for an entry of the form '&<ActionClass>', and returns the string found.

Reimplemented in IlvChangeValueCommand, and IlvMacroCommand.


© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.