Task is a base class for all SMTK tasks. More...

#include <Task.h>

Inheritance diagram for smtk::task::Task:

Collaboration diagram for smtk::task::Task:

Public Types
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 Member Functions
	smtkTypeMacroBase (smtk::task::Task)

	smtkCreateMacro (smtk::task::Task)

	Task (const Configuration &config, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)

	Task (const Configuration &config, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)

	Task (const Configuration &config, const PassedDependencies &dependencies, 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)

smtk::string::Token	id () const
	Return a unique, ephemeral identifier for this task. More...

void	configure (const Configuration &config)
	A method called by all constructors passed Configuration information. 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...

const std::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	markCompleted (bool completed)
	This public method allows user-interface components to indicate when the user marks a task complete (or unmarks it). More...

PassedDependencies	dependencies () const
	Return the tasks which this task depends upon. 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.

virtual bool	hasChildren () const
	Return whether or not the task has children. More...

virtual smtk::common::Visit	visit (RelatedTasks relation, Visitor visitor) const
	Visit children. More...

Observers &	observers ()
	Return this object's observers so other classes may insert themselves.

State	internalState () const
	Return the internal state of the task. More...

Protected Member Functions
bool	changeState (State previous, State next)
	Indicate the state has changed. More...

virtual bool	updateState (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...

bool	internalStateChanged (State next)
	Update the internal state, possibly transitioning the task's final state. More...

Protected Attributes
std::string	m_title
	A task name to present to the user.

std::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.

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::string::Token	m_id
	The unique identifier for this task.

Friends
SMTKCORE_EXPORT void	workflowsOfTask (Task , std::set< smtk::task::Task > &, std::set< smtk::task::Task * > &)
	Free functions that populate a set of workflow "head" tasks for an input task (this is the set of tasks that task ultimately depends on but are not themselves dependent on any task). More...

Detailed Description

Task is a base class for all SMTK tasks.

SMTK tasks are nodes in a graph whose arcs connect them to dependencies. The state of each task and its dependencies determine the set of available (or reachable) tasks. An application's user interface typically gets reconfigured when the active task changes to help direct users through a workflow, although tasks should not attempt to modify the user interface themselves. Instead, tasks should be solely focused on determining whether conditions are met for them to be (a) accessible to users and (b) marked completed by users. Once the first set of conditions is met, users are allowed to undertake the task. Once the second set of conditions is met, users are allowed to mark the task complete and thus gain access to those tasks which depend on it.

Subclasses of Task are responsible for monitoring the application's state; the base class provides no methods to aid in this other than access to the application's managers at construction. Once the subclass has determined conditions are met, it should call the internalStateChanged() method. The base class will determine if this results in a state transition or not (based on dependencies blocking the change) and notify observers as needed.

Member Enumeration Documentation

◆ RelatedTasks

enum smtk::task::Task::RelatedTasks

strong

The types of related tasks to visit.

Enumerator
Depend	Visit tasks this task depends upon.
Child	Visit child tasks.

Member Function Documentation

◆ addDependencies()

template<typename Container >

bool smtk::task::Task::addDependencies ( const Container & tasks )

Add a container of task-pointers as dependencies.

Returns true if all dependencies were added, false if any already existed or were null. This method will invoke observers if adding the dependencies changes this task's state.

◆ addDependency()

bool smtk::task::Task::addDependency ( const std::shared_ptr< Task > & dependency )

Add a dependency.

Returns true if the dependency was added, false if it already existed or is null. This method will invoke observers if adding the dependency changes this task's state.

◆ changeState()

bool smtk::task::Task::changeState	(	State	previous,
		State	next
	)

protected

Indicate the state has changed.

This method invokes observers if and only if previous and next are different. It will also update m_completed to match the new state.

It returns false if previous == next and true otherwise.

◆ configure()

void smtk::task::Task::configure ( const Configuration & config )

A method called by all constructors passed Configuration information.

In general, this method should set member variables directly instead of calling set/get methods since those may invoke observers with an uninitialized object.

Depedendencies (if they were provided) will already have been added when this method is called.

◆ dependencies()

Task::PassedDependencies smtk::task::Task::dependencies ( ) const

Return the tasks which this task depends upon.

WARNING: The returned set is read-only (modifying it does not modify this Task); however, modifying tasks in the returned set can affect this Task's state.

◆ getViewData()

bool smtk::task::Task::getViewData ( smtk::common::TypeContainer & configuration ) const

virtual

Populate a type-container with view-related data for configuration.

Subclasses should override this method. Generally, views will want access to a resource and potentially components in the resource that are the subject of the view. Other view configuration will come from view style() (see above) or smtk::common::Managers.

This method will return true when the configuration was modified and false otherwise.

Reimplemented in smtk::task::FillOutAttributes.

◆ hasChildren()

virtual bool smtk::task::Task::hasChildren ( ) const

inlinevirtual

Return whether or not the task has children.

By default, tasks do not support children.

Reimplemented in smtk::task::Group.

◆ id()

smtk::string::Token smtk::task::Task::id ( ) const

inline

Return a unique, ephemeral identifier for this task.

The identifier is ephemeral in the sense that closing and reloading the document that owns the task manager will not preserve the ID. Thus, you must not serialize the ID.

◆ internalState()

State smtk::task::Task::internalState ( ) const

inline

Return the internal state of the task.

This should not generally be used; instead, call state(). This state does not include dependencies or user-completion; it only reports whether the application has met conditions inherent for the task itself.

◆ internalStateChanged()

bool smtk::task::Task::internalStateChanged ( State next )

protected

Update the internal state, possibly transitioning the task's final state.

This method returns true if the task's final state changed and false otherwise. If true is returned, observers have been invoked.

◆ markCompleted()

bool smtk::task::Task::markCompleted ( bool completed )

This public method allows user-interface components to indicate when the user marks a task complete (or unmarks it).

This method has no effect and returns false if the task's current state is unavailable or incomplete. Returns true if the task's current state changes (from Completable to Completed if completed is true or Completed to Completable if completed is false). If true is returned, this method invoked its observers.

Be aware that if this task transitions from State::Completed to State::Incomplete or State::Unavailable, m_completed will be reset to false and this method must be invoked again.

◆ removeDependencies()

template<typename Container >

bool smtk::task::Task::removeDependencies ( const Container & tasks )

Remove a container of task-pointers as dependencies.

Returns true if all dependencies were removed, false otherwise. This method will invoke observers if removing the dependencies changes this task's state.

◆ removeDependency()

bool smtk::task::Task::removeDependency ( const std::shared_ptr< Task > & dependency )

Remove a dependency.

Returns true if the dependency was removed, false if not. This method will invoke observers if removing the dependency changes this task's state.

◆ setTitle()

void smtk::task::Task::setTitle ( const std::string & title )

Set the title of the task to be presented to users.

This is not intended to be a unique identifier.

◆ state()

State smtk::task::Task::state ( ) const

virtual

Get the state.

This state is a composition of m_internalState – updated by subclasses as needed – and the state of any dependencies. Because m_internalState is initialized to State::Completable, the default behavior is to become Completable once all dependencies are met (i.e., Completable or Completed) and Completed only if dependencies are met and markCompleted(true) has been called. Thus, the implementation in this base class will never return Incomplete. If a subclass marks the internal state as Incomplete, then this method may return Incomplete.

State "truth table" given internal and dependency states
Dependencies/ Internal	Unavailable	Incomplete	Completable	Completed
User has not marked task completed
Irrelevant	Irrelevant	Irrelevant	Irrelevant	Irrelevant
Unavailable	Unavailable	Unavailable	Unavailable	Unavailable
Incomplete	Unavailable	Incomplete	Incomplete	Incomplete
Completable	Unavailable	Incomplete	Completable	Completable
User has marked task completed
Irrelevant	Irrelevant	Irrelevant	Irrelevant	Irrelevant
Unavailable	Unavailable	Unavailable	Unavailable	Unavailable
Incomplete	Unavailable	Incomplete	Incomplete	Incomplete
Completable	Unavailable	Incomplete	Completable	Completed

Note that the internal state does not include State::Completed; only the user may mark a task completed and the base class implements a method to handle user input. A subclass that wishes to autocomplete might invoke the base-class method although this could frustrate users.

◆ style()

const std::set<smtk::string::Token>& smtk::task::Task::style ( ) const

inline

Set/get style classes for the task.

A style class specifies how applications should present the task (e.g., what type of view to provide the user, what rendering mode to use, what objects to list or exclude).

◆ updateState()

bool smtk::task::Task::updateState	(	Task &	dependency,
		State	prev,
		State	next
	)

protectedvirtual

Update our state because a dependent task has changed state or a subclass has marked the internal state as changed.

Returns true if this task's state changed and false otherwise. This method will invoke observers if it returns true.

◆ visit()

smtk::common::Visit smtk::task::Task::visit	(	RelatedTasks	relation,
		Visitor	visitor
	)		const

virtual

Visit children.

If hasChildren returns false, this will return immediately.

For the signature taking a Visitor, this method returns smtk::common::Visit::Halt if iteration was terminated.

Subclasses that override hasChildren should override these methods.

Reimplemented in smtk::task::Group.

Friends And Related Function Documentation

◆ workflowsOfTask

SMTKCORE_EXPORT void workflowsOfTask	(	Task *	,
		std::set< smtk::task::Task * > &	,
		std::set< smtk::task::Task * > &
	)

friend

Free functions that populate a set of workflow "head" tasks for an input task (this is the set of tasks that task ultimately depends on but are not themselves dependent on any task).

The variant that accepts visited can be used to efficiently accumulate workflows across several tasks (by pruning visited nodes from its traversal).

Member Data Documentation

◆ m_dependents

std::set<WeakPtr, std::owner_less<WeakPtr> > smtk::task::Task::m_dependents

protected

Tasks upon which this task depends.

This set is maintained by other Task instances when addDependency/removeDependency is called.

◆ m_parent

Task* smtk::task::Task::m_parent = nullptr

protected

If this task is the child of another task, this pointer references its parent.

The parent is responsible for updating this pointer as needed. m_parent is not a weak pointer because it must be initialized in the child during the parent's construction (when no shared pointer may exist).

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/Task.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/Task.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ RelatedTasks

Member Function Documentation

◆ addDependencies()

◆ addDependency()

◆ changeState()

◆ configure()

◆ dependencies()

◆ getViewData()

◆ hasChildren()

◆ id()

◆ internalState()

◆ internalStateChanged()

◆ markCompleted()

◆ removeDependencies()

◆ removeDependency()

◆ setTitle()

◆ state()

◆ style()

◆ updateState()

◆ visit()

Friends And Related Function Documentation

◆ workflowsOfTask

Member Data Documentation

◆ m_dependents

◆ m_parent