A QAbstractListModel populated with SMTK operation types. More...

#include <qtOperationTypeModel.h>

Inheritance diagram for qtOperationTypeModel:

Collaboration diagram for qtOperationTypeModel:

Classes
struct	Item
	A row in the model's table. More...

Public Types
enum	Column { Column::TypeIndex, Column::TypeName, Column::Label, Column::ButtonLabel, Column::ToolTip, Column::WidgetAction, Column::Associability, Column::Editability, Column::Precedence, Column::Count }
	The columns of the model. More...

Public Slots
virtual void	runOperationWithDefaults (smtk::operation::Operation::Index typeIndex) const
	Run an operation of the given type with its default parameters. More...

virtual void	runOperationWithParameters (const std::shared_ptr< smtk::operation::Operation > &operation) const
	Run the provided operation using a launcher.

virtual void	requestOperationParameterEdits (smtk::operation::Operation::Index typeIndex) const
	Request that parameters for the operation be shown to the user for editing.

Signals
void	runOperation (smtk::operation::Operation::Index)
	One of these signals is emitted when users activate an action this model exposes. More...

void	editOperationParameters (smtk::operation::Operation::Index) const

Public Member Functions
	qtOperationTypeModel (const smtk::view::Information &info, QObject *parent=nullptr)

int	rowCount (const QModelIndex &parent) const override

int	columnCount (const QModelIndex &parent) const override

QVariant	data (const QModelIndex &index, int role) const override

QVariant	headerData (int section, Qt::Orientation orientation, int role) const override

qtOperationAction *	actionFor (const QModelIndex &index) const
	Return the action for a particular operation-type.

template<typename OperationType >
qtOperationAction *	actionFor () const

QModelIndex	findByTypeIndex (smtk::operation::Operation::Index typeIndex) const
	Return the index of the row with the given operation type-index.

template<typename OperationType >
QModelIndex	findByTypeIndex () const

smtk::operation::Operation::Index	typeIndexFromTypeName (const std::string &typeName) const
	Return the type-index of an operation given its type-name. More...

void	setDecorator (const std::shared_ptr< smtk::view::OperationDecorator > &decorator)
	Set/get the operation decorator used to override operation labels, tooltips, etc..

std::shared_ptr< smtk::view::OperationDecorator >	decorator () const

std::shared_ptr< smtk::operation::Operation >	prepareOperation (smtk::operation::Operation::Index typeIndex) const
	Create an operation of the given type and associate it with the current selection.

Static Public Member Functions
static Column	columnEnumFromName (const std::string &colName)
	Convert to/from a Column enumerant.

static std::string	columnNameFromEnum (Column enumerant)

Protected Types
enum	Associability { BadExcess, UglyExcess, GoodExcess, Unneeded, BadIncomplete, UglyIncomplete, GoodIncomplete, BadComplete, UglyComplete, GoodComplete }
	A measure of how well the view::Selection matches an operation's associations. More...

using	EditableParameters = smtk::attribute::utility::EditableParameters

Protected Slots
void	runSendingOperation ()

void	editSendingOperationParameters ()

Protected Member Functions
std::string	associabilityName (const Associability &aa)
	A type-conversion operation to cast Associability enumerants to strings.

Associability	associabilityEnum (const std::string &aa)
	A type-conversion operation to cast strings to Associability enumerants.

void	metadataUpdate (const smtk::operation::Metadata &metadata, bool adding)
	Invoked when operation metadata is added or removed.

void	updateSelectionAssociability (const std::string &source, const std::shared_ptr< smtk::view::Selection > &selection, int first, int last)
	Invoked when the selection changes in order to update associability.

Static Protected Member Functions
static EditableParameters	editabilityFor (const smtk::operation::Metadata &metadata)
	Invoked when creating an Item entry.

Protected Attributes
std::vector< Item >	m_operations

std::shared_ptr< smtk::operation::Manager >	m_operationManager

std::shared_ptr< smtk::view::Manager >	m_viewManager

std::shared_ptr< smtk::view::Selection >	m_selection

std::shared_ptr< smtk::view::OperationDecorator >	m_operationDecorator

int	m_selectionValue { 0x01 }
	Which value or bits in the selection map determine associations? More...

bool	m_selectionExact { false }
	Match the exact value or simply require the value's bits to match? More...

Associability	m_disableMismatchLevel { Associability::GoodIncomplete }
	When associability is worse (lower) than this, disable its corresponding action. More...

smtk::operation::MetadataObservers::Key	m_modelObserverKey

smtk::view::SelectionObservers::Key	m_selectionObserverKey

std::string	m_secondaryColor { "#ffffff" }

smtk::extension::qtOperationLauncher *	m_launcher { nullptr }

Detailed Description

A QAbstractListModel populated with SMTK operation types.

The columns of the model are fixed by the Column enumeration. Operations are ordered by their type index. By using a QSortFilterProxyModel, you can subset and sort operations using a variety of techniques.

The class constructor accepts configuration via an smtk::view::Information instance; it expects to find a configuration component named "Model" in info.configuration()->details().

If you configure the model with a selection instance (i.e., if the Information type-container holds a selection), then it will add a selection observer that updates the Associability column with a measure of how well each operation fits the current selection. The configuration should include either a "SelectionValueLabel" (string) or a "SelectionValue" (integer), that indicate the value(s) in the selection map which should be used to determine operation associability. If "SelectionExact" (a boolean) is true, then only the exact number specified by "SelectionValueLabel" or "SelectionValue" is accepted. Otherwise, any value that has a superset of the selection-value's bits is considered.

By default, when a selection is provided the model will disable actions in its WidgetAction column for operations with an associability of GoodIncomplete or lower. You can override this with the "DisableLevel" configuration attribute (see the example below).

There are two ways to configure the model with an operation decorator:

Insert a std::shared_ptr<OperationDecorator> into a std::shared_ptr<smtk::common::Managers> instance in the Information object passed to configure the model; or
Include XML (deserialized into a Configuration::Component) that specifies the operation decorator. If both are specified, the instance in the smtk::common::Managers will take precedence. Only operations that match entries in the decorator will be presented – and they may have their names, tool-tips, etc. overridden.

If you specify "Autorun" as true (the default is false), then the model will launch operations automatically rather than only emitting the runOperation() signal. (The runOperation() signal will always be emitted.)

Below is an example showing an XML configuration snippet that can be included in a view::Configuration::Component that will be used by the model.

<Model
  DisableLevel="GoodIncomplete"
  SelectionValueLabel="selected"
  SelectionValue="1"
  SelectionExact="false"
  Autorun="false"
  >
  <OperationDecorator ... see class documentation for details ... />
</Model>

Member Enumeration Documentation

◆ Associability

enum qtOperationTypeModel::Associability

protected

A measure of how well the view::Selection matches an operation's associations.

This enumeration can be thought of as the tensor product of 2 states:

Whether all, some, or no selected objects can be associated to the operation.
Whether the operation's associations are
- disallowed (unneeded) because the operation doesn't allow any associations;
- allowed but only partially complete (unmet) because the operation needs more objects;
- allowed and sufficient (fulfilled) because the minimum is met and maximum not exceeded; or
- allowed but only in part (excess) because more objects are selected than the operation allows.

| Match || Unneeded | Unmet | Fulfilled | Excess | +----—++--------------—+---------------—+---------------—+---------------—+ | All || Unneeded | GoodIncomplete | GoodComplete | GoodExcess | | Some || Unneeded | UglyIncomplete | UglyComplete | UglyExcess | | None || Unneeded | BadIncomplete | BadComplete | BadExcess |

Note that the enumerants above are sorted from least desirable to most desirable rather than ordered in the table: excess selection is regarded as the least desirable.

In the table above,

"Good" means that all of the selection is applicable to the operation's association rule;
"Ugly" means that part of the selection is applicable to the operation's association rule;
"Bad" means none of the selection is applicable to the operation's association rule;
"Unneeded" means that the operation has no association rule and is always applicable;
"Complete" means that the selection satisfied the minimum and maximum constraints of the operation's association rule;
"Incomplete" means that the selection fails the minimum constraint of the operation's association rule; and
"Excess" means that the selection fails the maximum constraint of the operation's association rule.

These terms are combined to form descriptions of each specific table entry. Note that "BadComplete" means that the operation's association rule has a minimum constraint of 0 and hence can behave like "Unneeded."

◆ Column

enum qtOperationTypeModel::Column

strong

The columns of the model.

Enumerator
TypeIndex	The type index that uniquely identifies the operation.
TypeName	The operation's type-name (not its label).
Label	The operation's label (either from its XML or an override).
ButtonLabel	A version of the Label column with linebreaks to squarify it.
ToolTip	The operation's tool-tip (either from its XML or an override).
WidgetAction	A QWidgetAction object that users can activate to run the operation.
Associability	Whether the active selection associates properly with the operation.
Editability	Whether the operation has user-editable parameters and default values.
Precedence	An application-provided ordering for sorting.
Count	Not a valid value; when cast to an integer it is the number of columns.

Member Function Documentation

◆ runOperation

void qtOperationTypeModel::runOperation ( smtk::operation::Operation::Index )

signal

One of these signals is emitted when users activate an action this model exposes.

This model has a WidgetAction column whose value is a qtOperationAction* (which inherits QWidgetAction). That class emits two Q_SIGNALS: one for editing an operation's parameters and another for running the operation with the default parameters. The qtOperationTypeModel forwards these signals (from all of its actions) to this signal, which observers can watch for any row's operation action to be activated.

As a convenience, applications that use qtOperationTypeModel may connect the runOperation signal to the runOperationWithDefaults() slot that this class also provides. If your application chooses not to connect this signal/slot pair, then you can use these signals to perform custom processing before running the operation. Configure the view to make the connection by setting the "Autorun" parameter in the view configuration to true.

◆ runOperationWithDefaults

void qtOperationTypeModel::runOperationWithDefaults ( smtk::operation::Operation::Index typeIndex ) const

virtualslot

Run an operation of the given type with its default parameters.

This calls prepareOperation to create an instance of the operation and associate it to the current selection (if available). Then it calls runOperationWithParameters() with the operation it created.

◆ typeIndexFromTypeName()

smtk::operation::Operation::Index qtOperationTypeModel::typeIndexFromTypeName ( const std::string & typeName ) const

Return the type-index of an operation given its type-name.

This is a convenience for tests that must use the operation's type-name since the type-index can vary across platforms.

Member Data Documentation

◆ m_disableMismatchLevel

Associability qtOperationTypeModel::m_disableMismatchLevel { Associability::GoodIncomplete }

protected

When associability is worse (lower) than this, disable its corresponding action.

Set this by specifying an Associability enumerant as the string value of an attribute named "DisableLevel" of the model's configuration. The default is "BadExcess" (i.e., no operations will be disabled).

◆ m_selectionExact

bool qtOperationTypeModel::m_selectionExact { false }

protected

Match the exact value or simply require the value's bits to match?

Set this by specifying a boolean value in the SelectionExact attribute on the model's configuration. The default is false (i.e., only require bits from the value to match).

◆ m_selectionValue

int qtOperationTypeModel::m_selectionValue { 0x01 }

protected

Which value or bits in the selection map determine associations?

Set this by specifying either:

a selection label (see smtk::view::Selection::valueForLabel) as a string attribute named SelectionLabel on the model's configuration; or
a selection value as an integer attribute named SelectionValue on the model's configuration.

If both are present, SelectionLabel is preferred. The default is a value of 1. If the smtk::view::Selection instance passed to the model does not have a selection label you specify, a new value will be allocated.

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/extension/qt/qtOperationTypeModel.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/extension/qt/qtOperationTypeModel.cxx

Classes

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Types

Protected Slots

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Associability

◆ Column

Member Function Documentation

◆ runOperation

◆ runOperationWithDefaults

◆ typeIndexFromTypeName()

Member Data Documentation

◆ m_disableMismatchLevel

◆ m_selectionExact

◆ m_selectionValue