rwlogo
Rogue Wave Views 5.6

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. Similar in principle to callbacks, with added features. More...

#include <ilviews/base/action.h>

Inheritance diagram for IlvAction:
IlvCommand IlvChangeValueCommand IlvMacroCommand

Public Member Functions

 IlvAction (IlvActionHistory *h=0, IlBoolean r=IlTrue, IlBoolean p=IlFalse)
 Constructor. More...
 
 IlvAction (const IlvAction &a)
 Copy constructor used to repeat actions. More...
 
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 (external interface). 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. 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 = IlTrue,
IlBoolean  p = IlFalse 
)

Constructor.

Parameters
hThe action history defining the context in which the action is performed.
rA Boolean value specifying whether the action can be repeated.
pA 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);
}
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.
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 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.

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, 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 IlvChangeValueCommand, and IlvMacroCommand.


© Copyright 2012, 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.