#include <berryCommand.h>

Inheritance diagram for berry::Command:

Collaboration diagram for berry::Command:

Public Member Functions
	berryObjectMacro (Command)

void	AddCommandListener (ICommandListener *commandListener)

void	AddExecutionListener (IExecutionListener *executionListener)

void	AddState (const QString &id, const SmartPointer< State > &state) override

bool	operator< (const Object *object) const override

void	Define (const QString &name, const QString &description, const SmartPointer< CommandCategory > category, const QList< SmartPointer< IParameter > > &parameters=QList< SmartPointer< IParameter > >(), const SmartPointer< ParameterType > &returnType=SmartPointer< ParameterType >(nullptr), const QString &helpContextId="")

Object::Pointer	ExecuteWithChecks (const SmartPointer< const ExecutionEvent > event)

SmartPointer< IHandler >	GetHandler () const

QString	GetHelpContextId () const

SmartPointer< IParameter >	GetParameter (const QString &parameterId) const

QList< SmartPointer< IParameter > >	GetParameters () const

SmartPointer< ParameterType >	GetParameterType (const QString &parameterId) const

SmartPointer< ParameterType >	GetReturnType () const

bool	IsEnabled () const

void	SetEnabled (const Object::Pointer &evaluationContext)

bool	IsHandled () const

void	RemoveCommandListener (ICommandListener *commandListener)

void	RemoveExecutionListener (IExecutionListener *executionListener)

void	RemoveState (const QString &stateId) override

bool	SetHandler (const SmartPointer< IHandler > handler)

QString	ToString () const override

void	Undefine () override

Public Member Functions inherited from berry::NamedHandleObjectWithState
	berryObjectMacro (berry::NamedHandleObjectWithState) void AddState(const QString &stateId

QString	GetDescription () const override

QString	GetName () const override

SmartPointer< State >	GetState (const QString &stateId) const override

QList< QString >	GetStateIds () const override

void	RemoveState (const QString &id) override

Public Member Functions inherited from berry::NamedHandleObject
	berryObjectMacro (NamedHandleObject)

Public Member Functions inherited from berry::HandleObject
	berryObjectMacro (HandleObject)

bool	operator== (const Object *object) const override

QString	GetId () const

virtual uint	HashCode () const override

bool	IsDefined () const

Public Member Functions inherited from berry::Object
virtual QString	GetClassName () const

virtual Reflection::TypeInfo	GetTypeInfo () const

virtual QList< Reflection::TypeInfo >	GetSuperclasses () const

virtual void	Delete ()

QDebug	Print (QDebug os, Indent Indent=0) const

void	Register () const

void	UnRegister (bool del=true) const

int	GetReferenceCount () const

void	SetReferenceCount (int)

void	AddDestroyListener (const MessageAbstractDelegate<> &delegate) const

void	RemoveDestroyListener (const MessageAbstractDelegate<> &delegate) const

Public Member Functions inherited from berry::IObjectWithState
	berryObjectMacro (berry::IObjectWithState) virtual void AddState(const QString &id

Static Public Attributes
static bool	DEBUG_COMMAND_EXECUTION

static bool	DEBUG_HANDLERS

static QString	DEBUG_HANDLERS_COMMAND_ID

Protected Member Functions
	Command (const QString &id)

Protected Member Functions inherited from berry::NamedHandleObjectWithState
	NamedHandleObjectWithState (const QString &id)

Protected Member Functions inherited from berry::NamedHandleObject
	NamedHandleObject (const QString &id)

Protected Member Functions inherited from berry::HandleObject
	HandleObject (const QString &id)

Protected Member Functions inherited from berry::Object
	Object ()

virtual	~Object ()

virtual QDebug	PrintSelf (QDebug os, Indent indent) const

virtual QDebug	PrintHeader (QDebug os, Indent indent) const

virtual QDebug	PrintTrailer (QDebug os, Indent indent) const

Additional Inherited Members
Public Types inherited from berry::Object
typedef Object	Self

typedef berry::SmartPointer< Self >	Pointer

typedef berry::SmartPointer< const Self >	ConstPointer

typedef berry::WeakPointer< Self >	WeakPtr

typedef berry::WeakPointer< const Self >	ConstWeakPtr

Static Public Member Functions inherited from berry::Object
static const char *	GetStaticClassName ()

static Reflection::TypeInfo	GetStaticTypeInfo ()

static QList< Reflection::TypeInfo >	GetStaticSuperclasses ()

Public Attributes inherited from berry::NamedHandleObjectWithState
const SmartPointer< State > &state	override

Public Attributes inherited from berry::IObjectWithState
const SmartPointer< State > &	state

Protected Attributes inherited from berry::NamedHandleObject
QString	description

QString	name

Protected Attributes inherited from berry::HandleObject
bool	defined

const QString	id

QString	str

Protected Attributes inherited from berry::Object
QAtomicInt	m_ReferenceCount

QMutex	m_ReferenceCountLock

Detailed Description

A command is an abstract representation for some semantic behaviour. It is not the actual implementation of this behaviour, nor is it the visual appearance of this behaviour in the user interface. Instead, it is a bridge between the two.

The concept of a command is based on the command design pattern. The notable difference is how the command delegates responsibility for execution. Rather than allowing concrete subclasses, it uses a handler mechanism (see the handlers extension point). This provides another level of indirection.

A command will exist in two states: defined and undefined. A command is defined if it is declared in the XML of a resolved plug-in. If the plug-in is unloaded or the command is simply not declared, then it is undefined. Trying to reference an undefined command will succeed, but trying to access any of its functionality will fail with a NotDefinedException. If you need to know when a command changes from defined to undefined (or vice versa), then attach a command listener.

Commands are mutable and will change as their definition changes.

Definition at line 64 of file berryCommand.h.

Constructor & Destructor Documentation

berry::Command::Command ( const QString & id )

protected

Constructs a new instance of Command based on the given identifier. When a command is first constructed, it is undefined. Commands should only be constructed by the CommandManager to ensure that the identifier remains unique.

Parameters

id	The identifier for the command. This value must not be `null`, and must be unique amongst all commands.

Definition at line 44 of file berryCommand.cpp.

Member Function Documentation

void berry::Command::AddCommandListener ( ICommandListener * commandListener )

Adds a listener to this command that will be notified when this command's state changes.

Parameters

commandListener The listener to be added; must not be null.

Definition at line 49 of file berryCommand.cpp.

References berry::ICommandListener::Events::AddListener().

void berry::Command::AddExecutionListener ( IExecutionListener * executionListener )

Adds a listener to this command that will be notified when this command is about to execute.

Parameters

executionListener The listener to be added; must not be null.

Definition at line 58 of file berryCommand.cpp.

References berry::IExecutionListenerWithChecks::Events::AddListener().

void berry::Command::AddState	(	const QString &	id,
		const SmartPointer< State > &	state
	)

override

Adds a state to this command. This will add this state to the active handler, if the active handler is an instance of IObjectWithState.

A single instance of State cannot be registered with multiple commands. Each command requires its own unique instance.

Parameters

id	The identifier of the state to add; must not be `null`.
state	The state to add; must not be `null`.

Definition at line 67 of file berryCommand.cpp.

berry::Command::berryObjectMacro ( Command )

void berry::Command::Define	(	const QString &	name,
		const QString &	description,
		const SmartPointer< CommandCategory >	category,
		const QList< SmartPointer< IParameter > > &	parameters = `QList<SmartPointer<IParameter> >()`,
		const SmartPointer< ParameterType > &	returnType = `SmartPointer<ParameterType>(nullptr)`,
		const QString &	helpContextId = `""`
	)

Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes true.

Notification is sent to all listeners that something has changed.

Parameters

name	The name of this command; must not be `null`.
description	The description for this command; may be `null`.
category	The category for this command; must not be `null`.
parameters	The parameters understood by this command. This value may be either `null` or empty if the command does not accept parameters.
returnType	The type of value returned by this command. This value may be `null` if the command does not declare a return type.
helpContextId	The identifier of the help context to associate with this command; may be `null` if this command does not have any help associated with it.

Definition at line 109 of file berryCommand.cpp.

References berry::HandleObject::defined, berry::NamedHandleObject::description, and berry::NamedHandleObject::name.

Object::Pointer berry::Command::ExecuteWithChecks ( const SmartPointer< const ExecutionEvent > event )

Executes this command by delegating to the current handler, if any. If the debugging flag is set, then this method prints information about which handler is selected for performing this command. This does checks to see if the command is enabled and defined. If it is not both enabled and defined, then the execution listeners will be notified and an exception thrown.

Parameters

event An event containing all the information about the current state of the application; must not be null.

Returns: The result of the execution; may be null. This result will be available to the client executing the command, and execution listeners.

Exceptions

ExecutionException	If the handler has problems executing this command.
NotDefinedException	If the command you are trying to execute is not defined.
NotEnabledException	If the command you are trying to execute is not enabled.
NotHandledException	If there is no handler.

Definition at line 153 of file berryCommand.cpp.

References berry::HandleObject::GetId(), berry::HandleObject::IsDefined(), IsEnabled(), and SetEnabled().

IHandler::Pointer berry::Command::GetHandler ( ) const

Returns the current handler for this command. This is used by the command manager for determining the appropriate help context identifiers and by the command service to allow handlers to update elements.

This value can change at any time and should never be cached.

Returns: The current handler for this command; may be null.

Definition at line 285 of file berryCommand.cpp.

QString berry::Command::GetHelpContextId ( ) const

Returns the help context identifier associated with this command. This method should not be called by clients. Clients should use CommandManager#getHelpContextId(Command) instead.

Returns: The help context identifier for this command; may be null if there is none.

Definition at line 290 of file berryCommand.cpp.

IParameter::Pointer berry::Command::GetParameter ( const QString & parameterId ) const

Returns the parameter with the provided id or null if this command does not have a parameter with the id.

Parameters

parameterId The id of the parameter to retrieve.

Returns: The parameter with the provided id or null if this command does not have a parameter with the id.

Exceptions

NotDefinedException If the handle is not currently defined.

Definition at line 295 of file berryCommand.cpp.

References berry::HandleObject::IsDefined().

Referenced by GetParameterType().

QList< SmartPointer< IParameter > > berry::Command::GetParameters ( ) const

Returns the parameters for this command. This call triggers provides a copy of the array, so excessive calls to this method should be avoided.

Returns: The parameters for this command. This value might be null, if the command has no parameters.

Exceptions

NotDefinedException If the handle is not currently defined.

Definition at line 314 of file berryCommand.cpp.

References berry::HandleObject::IsDefined().

ParameterType::Pointer berry::Command::GetParameterType ( const QString & parameterId ) const

Returns the ParameterType for the parameter with the provided id or null if this command does not have a parameter type with the id.

Parameters

parameterId The id of the parameter to retrieve the ParameterType of.

Returns: The ParameterType for the parameter with the provided id or null if this command does not have a parameter type with the provided id.

Exceptions

NotDefinedException If the handle is not currently defined.

Definition at line 325 of file berryCommand.cpp.

References berry::SmartPointer< TObjectType >::Cast(), and GetParameter().

ParameterType::Pointer berry::Command::GetReturnType ( ) const

Returns the ParameterType for the return value of this command or null if this command does not declare a return value parameter type.

Returns: The ParameterType for the return value of this command or null if this command does not declare a return value parameter type.

Exceptions

NotDefinedException If the handle is not currently defined.

Definition at line 335 of file berryCommand.cpp.

References berry::HandleObject::IsDefined().

bool berry::Command::IsEnabled ( ) const

Returns whether this command has a handler, and whether this handler is also handled and enabled.

Returns: true if the command is handled; false otherwise.

Definition at line 346 of file berryCommand.cpp.

Referenced by ExecuteWithChecks(), SetHandler(), and Undefine().

bool berry::Command::IsHandled ( ) const

Returns whether this command has a handler, and whether this handler is also handled.

Returns: true if the command is handled; false otherwise.

Definition at line 364 of file berryCommand.cpp.

bool berry::Command::operator< ( const Object * object ) const

overridevirtual

Compares this command with another command by comparing each of its non-transient attributes.

Parameters

object The object with which to compare; must be an instance of Command.

Returns: false if the object is equal to or greater than this command.

Reimplemented from berry::Object.

Definition at line 77 of file berryCommand.cpp.

References berry::HandleObject::defined, berry::NamedHandleObject::description, berry::HandleObject::id, and berry::NamedHandleObject::name.

void berry::Command::RemoveCommandListener ( ICommandListener * commandListener )

Removes a listener from this command.

Parameters

commandListener The listener to be removed; must not be null.

Definition at line 374 of file berryCommand.cpp.

References berry::ICommandListener::Events::RemoveListener().

void berry::Command::RemoveExecutionListener ( IExecutionListener * executionListener )

Removes a listener from this command.

Parameters

executionListener The listener to be removed; must not be null.

Definition at line 392 of file berryCommand.cpp.

References berry::IExecutionListenerWithChecks::Events::RemoveListener().

void berry::Command::RemoveState ( const QString & stateId )

overridevirtual

Removes a state from this command. This will remove the state from the active handler, if the active handler is an instance of IObjectWithState.

Parameters

stateId The identifier of the state to remove; must not be null.

Implements berry::IObjectWithState.

Definition at line 402 of file berryCommand.cpp.

References berry::NamedHandleObjectWithState::RemoveState().

Referenced by Undefine().

void berry::Command::SetEnabled ( const Object::Pointer & evaluationContext )

Called be the framework to allow the handler to update its enabled state.

Parameters

evaluationContext the state to evaluate against. May be null which indicates that the handler can query whatever model that is necessary. This context must not be cached.

Definition at line 356 of file berryCommand.cpp.

Referenced by ExecuteWithChecks().

bool berry::Command::SetHandler ( const SmartPointer< IHandler > handler )

Changes the handler for this command. This will remove all the state from the currently active handler (if any), and add it to handler. If debugging is turned on, then this will also print information about the change to System.out.

Parameters

handler The new handler; may be null if none.

Returns: true if the handler changed; false otherwise.

Definition at line 411 of file berryCommand.cpp.

References berry::SmartPointer< TObjectType >::Cast(), DEBUG_HANDLERS, DEBUG_HANDLERS_COMMAND_ID, berry::NamedHandleObjectWithState::GetState(), berry::NamedHandleObjectWithState::GetStateIds(), IsEnabled(), berry::CommandTracing::PrintTrace(), and berry::HandleObject::str.

QString berry::Command::ToString ( ) const

overridevirtual

The string representation of this command – for debugging purposes only. This string should not be shown to an end user.

Returns: The string representation; never null.

Reimplemented from berry::Object.

Definition at line 485 of file berryCommand.cpp.

References berry::HandleObject::defined, berry::NamedHandleObject::description, berry::NamedHandleObject::name, and berry::HandleObject::str.

void berry::Command::Undefine ( )

overridevirtual

Makes this command become undefined. This has the side effect of changing the name and description to null. This also removes all state and disposes of it. Notification is sent to all listeners.

Implements berry::HandleObject.

Definition at line 505 of file berryCommand.cpp.

References berry::HandleObject::defined, berry::NamedHandleObject::description, berry::NamedHandleObjectWithState::GetState(), berry::NamedHandleObjectWithState::GetStateIds(), IsEnabled(), berry::NamedHandleObject::name, RemoveState(), berry::IObjectWithState::state, and berry::HandleObject::str.

Member Data Documentation

bool berry::Command::DEBUG_COMMAND_EXECUTION

static

This flag can be set to true if commands should print information to System.out when executing.

Definition at line 75 of file berryCommand.h.

bool berry::Command::DEBUG_HANDLERS

static

This flag can be set to true if commands should print information to System.out when changing handlers.

Definition at line 81 of file berryCommand.h.

Referenced by SetHandler().

QString berry::Command::DEBUG_HANDLERS_COMMAND_ID

static

This flag can be set to a particular command identifier if only that command should print information to System.out when changing handlers.

Definition at line 88 of file berryCommand.h.

Referenced by SetHandler().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation