SMTK  @SMTK_VERSION@
Simulation Modeling Tool Kit
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
smtk::task::Task Class Reference

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

#include <Task.h>

Inheritance diagram for smtk::task::Task:
[legend]
Collaboration diagram for smtk::task::Task:
[legend]

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. More...
 

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, const PassedDependencies &dependencies, 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 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< std::string > & style () const
 Set/get style classes for the task. More...
 
bool addStyle (const std::string &styleClass)
 
bool removeStyle (const std::string &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...
 
Taskparent () 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...
 
Observersobservers ()
 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< std::string > 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. More...
 
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.
 
Taskm_parent = nullptr
 If this task is the child of another task, this pointer references its parent. More...
 
std::weak_ptr< smtk::task::Managerm_manager
 If this task is being managed, this will refer to its manager.
 

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 Typedef Documentation

◆ Visitor

Signature of functions invoked when visiting dependencies or children while allowing early termination.

Member Enumeration Documentation

◆ RelatedTasks

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.

◆ 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
UnavailableIncomplete CompletableCompleted
User has not marked task completed
Irrelevant Irrelevant Irrelevant Irrelevant Irrelevant
Unavailable UnavailableUnavailableUnavailableUnavailable
Incomplete Unavailable IncompleteIncomplete Incomplete
Completable Unavailable IncompleteCompletableCompletable
User has marked task completed
Irrelevant Irrelevant Irrelevant Irrelevant Irrelevant
Unavailable UnavailableUnavailableUnavailableUnavailable
Incomplete Unavailable IncompleteIncomplete Incomplete
Completable Unavailable IncompleteCompletableCompleted

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<std::string>& 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_dependencies

std::map<WeakPtr, Observers::Key, std::owner_less<WeakPtr> > smtk::task::Task::m_dependencies
protected

A set of dependent tasks and the keys used to observe their state so that this task can update its state in response.

◆ 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: