#include "steam/control/command.hpp"

Description

Handle object representing a single Command instance to be used by client code.

Commands are accessed through a symbolic ID ; there needs to be a CommandDef somewhere to specify the actual operation and to define, how the effect of the command can be undone. Moreover, the command's definition refers to a HandlingPattern, which describes how the command is actually to be executed (the default is scheduling it within the SteamDispatcher)

Client code usually just

creates a command instance by referring to a command ID
maybe binds to concrete arguments (e.g. a target object)
triggers command execution through operator()
maybe checks the return value for errors

Remarks: lightweight implementation as smart-ptr

Definition at line 124 of file command.hpp.

Public Member Functions
	Command (Symbol cmdID)

	Command ()
	undefined command

	Command (Command &&)=default

	Command (Command const &)=default

template<typename... TYPES>
Command &	bindArg (std::tuple< TYPES... > const &)

Command &	bindArg (lib::diff::Rec const &)

bool	canExec () const

bool	canUndo () const

void	duplicate_detected (Symbol) const

ExecResult	exec ()

ExecResult	exec (HandlingPattern const &execPattern)
	core operation: invoke the command More...

ExecResult	exec (HandlingPattern::ID)

ExecResult	execSync ()
	invoke using a default "synchronous" execution pattern

HandlingPattern::ID	getDefaultHandlingPattern () const

Symbol	getID () const noexcept

bool	isAnonymous () const

Command	newInstance () const
	create independent (anonymous) clone copy of this command

	operator string () const
	diagnostics: shows the commandID, if any, and the degree of definition of this command

ExecResult	operator() ()

Command &	operator= (Command &&)=default

Command &	operator= (Command const &)=default

HandlingPattern::ID	setHandlingPattern (HandlingPattern::ID)
	define a handling pattern to be used by default More...

Command	storeDef (Symbol newCmdID) const
	create a clone definition More...

Command &	unbind ()
	discard any argument data previously bound. More...

ExecResult	undo ()

ExecResult	undo (HandlingPattern const &execPattern)

ExecResult	undo (HandlingPattern::ID)

Public Member Functions inherited from AcceptAnyBind< Command, lib::Handle< CommandImpl >, Command & >
Command &	bind ()
	Accept dummy binding (0 Arg)

Command &	bind (ARGS &&...args)
	mix in `bind` function to create binding of arbitrary arguments

Public Member Functions inherited from Handle< CommandImpl >
	Handle ()=default
	by default create an Null handle. More...

	Handle (CommandImpl *imp)
	directly establish handle from an implementation, which typically way just heap allocated beforehand.

	Handle (Handle const &r)=default

	Handle (Handle &&rr)=default

	Handle (shared_ptr< Y > const &r)

	Handle (shared_ptr< Y > &&srr)

	Handle (weak_ptr< Y > const &wr)

	Handle (unique_ptr< Y > &&urr)

Handle &	activate (CommandImpl *impl, DEL whenDead)
	Activation of the handle by the managing service. More...

Handle &	activate (shared_ptr< CommandImpl > const &impl)
	another way of activating a handle by sharing ownership with an existing smart-ptr

Handle &	activate (shared_ptr< CommandImpl > &&impl)

void	close ()
	deactivate this handle, so it isn't tied any longer to the associated implementation or service object. More...

bool	isValid () const

	operator bool () const

Handle &	operator= (Handle const &r)=default

Handle &	operator= (Handle &&rr)=default

Handle &	operator= (shared_ptr< Y > const &sr)

Handle &	operator= (shared_ptr< Y > &&srr)

Handle &	operator= (unique_ptr< Y > &&urr)

Static Public Member Functions
static bool	canExec (Symbol cmdID)

static bool	canUndo (Symbol cmdID)

static bool	defined (Symbol cmdID)

static size_t	definition_count ()

static Command	get (Symbol cmdID)
	Access existing command for use. More...

static size_t	instance_count ()

static Command	maybeGetNewInstance (Symbol cmdID)
	try to access an existing command definition and immediately create a new clone copy by calling newInstance() More...

static bool	remove (Symbol cmdID)

Friends
class	CommandDef

bool	operator< (Command const &, Command const &)
	allow for sets and associative containers

bool	operator== (Command const &, Command const &)

Protected Member Functions
void	activate (shared_ptr< CommandImpl > &&, Symbol cmdID=0)

Protected Member Functions inherited from Handle< CommandImpl >
CommandImpl &	impl () const

Static Protected Member Functions
static Command	fetchDef (Symbol cmdID)

Private Types
typedef lib::Handle< CommandImpl >	_Handle

Private Member Functions
void	setArguments (Arguments &)

void	setArguments (lib::diff::Rec const &)

Additional Inherited Members
Protected Types inherited from Handle< CommandImpl >
typedef std::shared_ptr< CommandImpl >	SmPtr

Protected Attributes inherited from Handle< CommandImpl >
SmPtr	smPtr_

Member Function Documentation

◆ get()

Command get ( Symbol cmdID )

static

Access existing command for use.

Exceptions

error::Invalid if command not registered or incompletely defined.

Remarks: this function deliberately returns by-value. Returning a reference into the global CommandRegistry would be dangerous under concurrent access.

Definition at line 129 of file command.cpp.

Referenced by WrappedStandardExeBuilder::__call__(), CommandInstanceManager::getInstance(), and RuntimeCheckedCommandInvoker::operator()().

Here is the caller graph for this function:

◆ storeDef()

Command storeDef ( Symbol newCmdID ) const

create a clone definition

create an independent clone copy of this command and register it as new command definition under a different ID

Definition at line 192 of file command.cpp.

Referenced by CommandSetup_test::verify_standardUsage().

Here is the caller graph for this function:

◆ maybeGetNewInstance()

Command maybeGetNewInstance ( Symbol cmdID )

static

try to access an existing command definition and immediately create a new clone copy by calling newInstance()

Returns: when search for this ID was successful, a new anonymous command instance based on the same definition, but not registered in the global CommandRegistry. Otherwise, when search fails, an empty Command instance (as can be tested with bool conversion

Definition at line 149 of file command.cpp.

◆ unbind()

Command & unbind ( )

discard any argument data previously bound.

Remarks: this returns the command into pristine state, just holding the definition but not any further argument data or UNDO state. Contrast this to an defalut constructed Command, which is inactive and not bound to any definition at all.

Definition at line 288 of file command.cpp.

◆ exec()

ExecResult exec ( HandlingPattern const & execPattern )

core operation: invoke the command

Parameters

execPattern describes the individual steps necessary to get this command invoked properly

Definition at line 421 of file command.cpp.

◆ getDefaultHandlingPattern()

HandlingPattern::ID getDefaultHandlingPattern ( ) const

Returns: ID of the execution pattern used by operator()

Definition at line 466 of file command.cpp.

◆ setHandlingPattern()

HandlingPattern::ID setHandlingPattern ( HandlingPattern::ID pattID )

define a handling pattern to be used by default

Returns: ID of the currently defined default pattern

Definition at line 474 of file command.cpp.

Referenced by CompletedDefinition< SIG >::setHandlingPattern().

Here is the caller graph for this function:

◆ definition_count()

size_t definition_count ( )

static

Returns: the number of command definitions currently registered

Definition at line 298 of file command.cpp.

Referenced by CommandInstanceManager::CommandInstanceManager().

Here is the caller graph for this function:

◆ instance_count()

size_t instance_count ( )

static

Returns: number of distinguishable registered command instances

Definition at line 307 of file command.cpp.

◆ isAnonymous()

bool isAnonymous ( ) const

Returns: true when this command (front-end) was never registered with the CommandRegistry; typically this is the case with instances created from a prototype, when calling Command::newInstance instead of invoking Command::storeDef(Symbol).

Definition at line 388 of file command.cpp.

◆ fetchDef()

Command fetchDef ( Symbol cmdID )

staticprotected

just query an existing instance, if any.

Definition at line 159 of file command.cpp.

◆ activate()

void activate	(	shared_ptr< CommandImpl > &&	implFrame,
		Symbol	cmdID = `0`
	)

protected

make a command ready for use. Typically to be invoked through CommandDef during the definition stage, but also used for activating (anonymous) clone instances.

Parameters

cmdID new ID for creating a separate command registration when provided

Exceptions

error::Logic when this is already activated.

Definition at line 171 of file command.cpp.

Referenced by CommandDef::activate().

Here is the caller graph for this function:

◆ setArguments() [1/2]

void setArguments ( Arguments & args )

private

pass a new argument tuple to the CommandImpl without exposing implementation.

Definition at line 260 of file command.cpp.

◆ setArguments() [2/2]

void setArguments ( lib::diff::Rec const & paramData )

private

forward a Record<GenNode>, which was typically received via UI-Bus, down to the CommandImpl.

Remarks: this is how command arguments are actually passed from UI to the Session core

Definition at line 273 of file command.cpp.

Inheritance diagram for Command:

Collaboration diagram for Command:

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

Description

Public Member Functions

Static Public Member Functions

Friends

Protected Member Functions

Static Protected Member Functions

Private Types

Private Member Functions

Additional Inherited Members

Member Function Documentation

◆ get()

◆ storeDef()

◆ maybeGetNewInstance()

◆ unbind()

◆ exec()

◆ getDefaultHandlingPattern()

◆ setHandlingPattern()

◆ definition_count()

◆ instance_count()

◆ isAnonymous()

◆ fetchDef()

◆ activate()

◆ setArguments() [1/2]

◆ setArguments() [2/2]