smtk::task::SubmitOperation Class Reference

SubmitOperation helps users prepare and optionally run an operation. More...

#include <SubmitOperation.h>

Inheritance diagram for smtk::task::SubmitOperation:

Collaboration diagram for smtk::task::SubmitOperation:

Classes
struct	ParameterSpec
	Per-parameter configuration of item values. More...

Public Types
enum	RunStyle { Iteratively, Once, OnCompletion }
	Specify how users interact with the operation. More...
enum	ConfiguredBy { ConfiguredBy::Task, ConfiguredBy::Adaptor, ConfiguredBy::User }
	Specify what is allowed to configure an operation parameter. More...
enum	ItemVisibility { ItemVisibility::Off, ItemVisibility::RecursiveOff, ItemVisibility::On }
	Specify whether an item and its children should be visible to users. More...
using	ParameterSpecVisitor = std::function< smtk::common::Visit(ParameterSpec &)>
	Signatures of functors that visit resources-by-role predicates.
using	ConstParameterSpecVisitor = std::function< smtk::common::Visit(const ParameterSpec &)>
Public Types inherited from smtk::task::Task
enum	RelatedTasks { RelatedTasks::Depend, RelatedTasks::Child }
	The types of related tasks to visit. More...
using	Observer = std::function< void(Task &, State, State)>
	A task's state changes may be observed.
using	Observers = smtk::common::Observers< Observer >
	The collection of all observers of this task instance.
using	Dependencies = std::map< WeakPtr, typename Observers::Key, std::owner_less< WeakPtr > >
	A task's dependencies are other tasks stored as weak pointers.
using	PassedDependencies = std::set< Ptr >
	A task's dependencies are other tasks passed as shared pointers.
using	Configuration = nlohmann::json
	Tasks are configured with arbitrary JSON objects, though this may change.
using	Visitor = std::function< smtk::common::Visit(Task &)>
	Signature of functions invoked when visiting dependencies or children while allowing early termination.
Public Types inherited from smtk::resource::Component
typedef std::function< void(const ComponentPtr &)>	Visitor
typedef detail::ComponentLinks	Links
typedef detail::ComponentProperties	Properties

Public Member Functions
	smtkTypeMacro (smtk::task::SubmitOperation)
	smtkSuperclassMacro (smtk::task::AgentlessTask)
	smtkCreateMacro (smtk::resource::PersistentObject)
	SubmitOperation (const Configuration &config, Manager &taskManager, const smtk::common::Managers::Ptr &managers=nullptr)
	SubmitOperation (const Configuration &config, const PassedDependencies &dependencies, Manager &taskManager, const smtk::common::Managers::Ptr &managers=nullptr)
void	configure (const Configuration &config)
	Parse configuration information to initialize this instance.
bool	markCompleted (bool completed) override
	We override this method in order to launch the operation when the task's RunStyle is OnCompletion.
smtk::operation::Operation *	operation () const
	Return the operation this task requires users to configure and submit.
RunStyle	runStyle () const
	Return the manner in which this task expects users to submit the operation.
smtk::common::Visit	visitParameterSpecs (ConstParameterSpecVisitor visitor) const
	Visit the specification for each item this task potentially configures.
smtk::common::Visit	visitParameterSpecs (ParameterSpecVisitor visitor)
ParameterSpec &	associationSpec ()
	Return the specification for the associations of the operation this task configures. More...
ParameterSpec	associationSpec () const
void	configureHiddenItems (smtk::view::ConfigurationPtr view, const nlohmann::json &jItemArray) const
	Modify view to hide items specified in task's style.
bool	runSinceEdited () const
	True if the operation has successfully run since its parameters were last edited.
bool	setNeedsToRun ()
	Force the task into an incomplete state because its input parameters have changed. More...
bool	editableCompletion () const override
	Return whether or not users are allowed to mark a task completed. More...
Public Member Functions inherited from smtk::task::AgentlessTask
	smtkTypeMacro (smtk::task::AgentlessTask)
	smtkSuperclassMacro (smtk::task::Task)
	smtkCreateMacro (smtk::resource::PersistentObject)
	AgentlessTask (const Configuration &config, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)
	AgentlessTask (const Configuration &config, const PassedDependencies &dependencies, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)
bool	updateAgentState (const Agent *agent, State prev, State next, bool signal) override
	Updates the state of the task based on the change of an agent. More...
State	internalState () const
Public Member Functions inherited from smtk::task::Task
	smtkTypeMacro (smtk::task::Task)
	smtkSuperclassMacro (smtk::resource::Component)
	smtkCreateMacro (smtk::resource::PersistentObject)
	Task (const Configuration &config, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)
	Task (const Configuration &config, const PassedDependencies &dependencies, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)
void	configure (const Configuration &config)
	A method called by all constructors passed Configuration information. More...
const common::UUID &	id () const override
	Set/get the task's unique identifier.
bool	setId (const common::UUID &newId) override
	Assign an ID to this object (used by readers; not for arbitrary reuse). More...
std::string	name () const override
	Return the task's name.
virtual void	setName (const std::string &name)
const std::shared_ptr< resource::Resource >	resource () const override
	Components are required to return their owning resource (if any). More...
const std::string &	title () const
	Return the title of the task (if one was provided).
void	setTitle (const std::string &title)
	Set the title of the task to be presented to users. More...
virtual std::string	information (const InformationOptions &opts=InformationOptions()) const
	Return user-presentable information about the task in XHTML form. More...
void	setDescription (const std::string &description)
	Set/get a description of the task provided by workflow designers. More...
const std::string &	description () const
std::string &	description ()
virtual const std::unordered_map< smtk::string::Token, Port * > &	ports () const
	Return a set of ports for this task indexed by their function (a descriptive string).
bool	changePortName (Port *port, const std::string &newName, std::function< bool()> fp)
	Change the Name of a Port. More...
virtual std::shared_ptr< PortData >	portData (const Port *port) const
	Given a port owned by this task, return data to be transmitted over the port. More...
virtual void	portDataUpdated (const Port *port)
	Accept notification that data on the given port has been updated. More...
const std::unordered_set< smtk::string::Token > &	style () const
	Set/get style classes for the task. More...
bool	addStyle (const smtk::string::Token &styleClass)
bool	removeStyle (const smtk::string::Token &styleClass)
bool	clearStyle ()
virtual bool	getViewData (smtk::common::TypeContainer &configuration) const
	Populate a type-container with view-related data for configuration. More...
virtual State	state () const
	Get the state. More...
bool	isCompleted () const
	Return whether or not the task has been marked completed.
State	agentState () const
	Returns the state of a task's agents.
State	childrenState () const
	Returns the state of a task's children.
State	dependencyState () const
	Returns the state of a task's dependencies.
bool	areDependenciesStrict () const
	Return true if this task has been configured with strict dependency enforcement. More...
PassedDependencies	dependencies () const
	Return the tasks which this task depends upon. More...
bool	canAddDependency (const std::shared_ptr< Task > &dependency)
	Check whether inserting a dependency would induce a cycle. More...
bool	addDependency (const std::shared_ptr< Task > &dependency)
	Add a dependency. More...
template<typename Container >
bool	addDependencies (const Container &tasks)
	Add a container of task-pointers as dependencies. More...
bool	removeDependency (const std::shared_ptr< Task > &dependency)
	Remove a dependency. More...
template<typename Container >
bool	removeDependencies (const Container &tasks)
	Remove a container of task-pointers as dependencies. More...
Task *	parent () const
	Return a parent task if one exists; null otherwise.
std::unordered_set< const Task * >	ancestors () const
	Returns the ancestral tasks related to this one. More...
std::vector< Task * >	lineage () const
	Returns the lineage of this task. More...
virtual smtk::common::Visit	visit (RelatedTasks relation, Visitor visitor) const
	Visit children. More...
virtual bool	hasChildren () const
	Return whether or not the task has children.
bool	canAddChild (const std::shared_ptr< Task > &child) const
	Check whether adding a child task would induce a cycle.
bool	addChild (const std::shared_ptr< Task > &child)
	Add a child task. More...
template<typename Container >
bool	addChildren (const Container &tasks)
	Add a container of task-pointers as children. More...
bool	removeChild (const std::shared_ptr< Task > &child)
	Remove a child task. More...
template<typename Container >
bool	removeChildren (const Container &tasks)
	Remove a container of task-pointers as children. More...
const std::unordered_set< Task * > &	children () const
	Return the children of the task.
std::unordered_set< Agent * >	agents () const
	Return the agents of the task. More...
Observers &	observers ()
	Return this object's observers so other classes may insert themselves.
bool	acceptsChildCategories (const std::set< std::string > &cats) const
	Evaluates a set of categories that are associated with a potential child task and return true if the the categories pass the task's agent check. More...
Manager *	manager () const
	Return the tasks's manager (or null if unmanaged).
std::shared_ptr< smtk::common::Managers >	managers () const
	Return the application-state container. More...
bool	hasInternalPorts () const
	Returns true if the task contains any internal ports.
bool	canAcceptWorklets () const
	Return true if the task can accept any worklets.
Public Member Functions inherited from smtk::resource::Component
	smtkTypeMacro (smtk::resource::Component)
	smtkSuperclassMacro (smtk::resource::PersistentObject)
	smtkSharedFromThisMacro (smtk::resource::PersistentObject)
Resource *	parentResource () const override
	Return a raw (not shared) pointer to the resource that owns this component. More...
template<typename ResourceType >
ResourceType *	parentResourceAs () const
	This variant of parentResource casts the result to the given ResourceType.
Links &	links () override
	Return the links that connect this component to external resources/components.
const Links &	links () const override
Properties &	properties () override
	Return properties defined on this component.
const Properties &	properties () const override
Public Member Functions inherited from smtk::resource::PersistentObject
	smtkTypeMacroBase (smtk::resource::PersistentObject)
template<typename T >
T::Ptr	as ()
	Attempt to cast this object to a subclass.
template<typename T >
T::ConstPtr	as () const
	Attempt to cast this object to a subclass.

Static Public Member Functions
static smtk::string::Token	ConfiguredByToken (ConfiguredBy value)
	Convert to/from a ConfigureBy enumerant.
static ConfiguredBy	ConfiguredByValue (smtk::string::Token token)
static smtk::string::Token	ItemVisibilityToken (ItemVisibility value)
	Convert to/from an ItemVisibility enumerant.
static ItemVisibility	ItemVisibilityValue (smtk::string::Token token)
static smtk::string::Token	RunStyleToken (RunStyle value)
	Convert to/from a RunStyle enumerant.
static RunStyle	RunStyleValue (smtk::string::Token token)

Protected Member Functions
int	update (const smtk::operation::Operation &op, smtk::operation::EventType event, smtk::operation::Operation::Result result)
	Respond to operations that may change task state.
bool	applyParameterSpecifications ()
	Apply the task's parameter specifications to the operation.
bool	applyParameterSpecification (const ParameterSpec &spec, const std::shared_ptr< smtk::attribute::Item > &item)
	Apply a parameter specification to the given item.
State	computeInternalState () const override
	Check m_resourcesByRole to see if all requirements are met.
Protected Member Functions inherited from smtk::task::AgentlessTask
State	computeAgentState () const override
	Compute the state based on state of the task's agents.
bool	internalStateChanged (State next)
Protected Member Functions inherited from smtk::task::Task
bool	changeState (State previous, State next)
	Indicate the state of this task has changed. More...
bool	addChild (const std::shared_ptr< Task > &child, const std::unordered_set< const Task * > &taskSet)
	Adds a child to a task. More...
virtual bool	updateDependencyState (Task &dependency, State prev, State next)
	Update our state because a dependent task has changed state or a subclass has marked the internal state as changed. More...
virtual bool	updateChildrenState (const Task *child, State prev, State next)
	Updates the state of the task based on the change of a child task. More...
virtual State	computeDependencyState () const
	Compute the state based on the state of the task's dependencies. More...
virtual State	computeChildrenState () const
	Compute the state based on the state of the task's children.
std::shared_ptr< PortData >	outputPortData (const Port *port) const
	Produce port data for an output port of this task by querying its agents.
std::shared_ptr< PortData >	inputPortData (const Port *port) const
	Produce port data for an input port of this task by querying its connections.

Protected Attributes
smtk::common::Managers::Ptr	m_managers
smtk::operation::Observers::Key	m_observer
std::vector< ParameterSpec >	m_parameterSpecs
ParameterSpec	m_associationSpec
RunStyle	m_runStyle { RunStyle::Iteratively }
bool	m_runSinceEdited { false }
std::shared_ptr< smtk::operation::Operation >	m_operation
Protected Attributes inherited from smtk::task::Task
std::string	m_name
	A task name to present to the user.
std::string	m_description
	A description of the task provided by a workflow designer.
std::unordered_set< smtk::string::Token >	m_style
	The set of style classes for this task.
bool	m_completed = false
	Whether the user has marked the task completed or not.
std::map< WeakPtr, Observers::Key, std::owner_less< WeakPtr > >	m_dependencies
	A set of dependent tasks and the keys used to observe their state so that this task can update its state in response.
bool	m_strictDependencies = false
	Should dependencies be strictly enforced?
std::set< WeakPtr, std::owner_less< WeakPtr > >	m_dependents
	Tasks upon which this task depends. More...
Observers	m_observers
	The set of observers of this task's state.
Task *	m_parent = nullptr
	If this task is the child of another task, this pointer references its parent. More...
std::weak_ptr< smtk::task::Manager >	m_manager
	If this task is being managed, this will refer to its manager.
smtk::common::UUID	m_id
	The unique identifier for this task.
std::unordered_set< Task * >	m_children
	The children of the task.
std::unordered_set< std::unique_ptr< Agent > >	m_agents
	The agents of the task.
std::unordered_map< smtk::string::Token, Port * >	m_ports
	The ports of the Task.
State	m_agentState = State::Completable
State	m_dependencyState = State::Irrelevant
State	m_childrenState = State::Irrelevant

Friends
class	adaptor::ResourceAndRole
class	adaptor::ConfigureOperation

Detailed Description

SubmitOperation helps users prepare and optionally run an operation.

This task creates an operation, optionally pre-configures a subset of its parameters, and may allow users to run the operation once or repeatedly. See the user's guide for more information on how to configure this operation.

Member Enumeration Documentation

ConfiguredBy

enum smtk::task::SubmitOperation::ConfiguredBy

strong

Specify what is allowed to configure an operation parameter.

Note that this enumeration does not include a value for specifying that an item may only be configured by a user. For that behavior, simply omit the item's path from the task configuration.

Enumerator
Task	Static task configuration (not an adaptor) provides values.
Adaptor	An adaptor is allowed to modify the parameter whenever it runs.
User	Tasks, adaptors, and the user are allowed to edit the parameter.

ItemVisibility

enum smtk::task::SubmitOperation::ItemVisibility

strong

Specify whether an item and its children should be visible to users.

Enumerator
Off	Hide this item but not its children.
RecursiveOff	Recursively hide this item and its children.
On	Show this item and its children.

RunStyle

enum smtk::task::SubmitOperation::RunStyle

Specify how users interact with the operation.

Enumerator
Iteratively	Users edit parameters and run the operation, possibly repeatedly.
Once	Users run the operation once (at which point the task is marked complete).
OnCompletion	Users do not run the operation; the task launches it when marked complete.

Member Function Documentation

associationSpec()

ParameterSpec& smtk::task::SubmitOperation::associationSpec ( )

inline

Return the specification for the associations of the operation this task configures.

Note that if the operation is not intended to auto-configure the associations, the m_itemPath member of the parameters should be set to "-ignore-" (rather than empty or populated with the name of the association's ReferenceItem).

editableCompletion()

bool smtk::task::SubmitOperation::editableCompletion ( ) const

overridevirtual

Return whether or not users are allowed to mark a task completed.

User interfaces (e.g., qtDiagramView) should check this to decide whether to enable UI elements that accept user completion. Subclasses of Task that automate completion (e.g., SubmitOperation when RunStyle is set to Once) can override this method to prevent users from explicitly marking completion. The default implementation returns true when the task state is completable or completed.

Reimplemented from smtk::task::Task.

setNeedsToRun()

bool smtk::task::SubmitOperation::setNeedsToRun

(

)

Force the task into an incomplete state because its input parameters have changed.

This is invoked by configureHiddenItems() if any items are modified. The returned value is true if the call had any effect (i.e., m_runSinceEdited was true before the call and false afterward).

Calling this method will generally result in a state change (to Incomplete) if true is returned.

---

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

• /home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/release/smtk/task/SubmitOperation.h
• /home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/release/smtk/task/SubmitOperation.cxx