SMTK
@SMTK_VERSION@
Simulation Modeling Tool Kit
|
A class to manage linked selections in a context. More...
#include <Selection.h>
Public Types | |
using | Observer = SelectionObserver |
using | Observers = SelectionObservers |
using | Component = smtk::resource::Component |
using | Object = smtk::resource::PersistentObject |
using | SelectionMap = std::map< Object::Ptr, int > |
This is the underlying storage type that holds selections. | |
using | SelectionFilter = std::function< bool(Object::Ptr, int, SelectionMap &)> |
Selection filters take functions of this form. More... | |
Public Member Functions | |
smtkTypeMacroBase (Selection) | |
smtkCreateMacro (Selection) | |
Selection (const Selection &)=delete | |
Selection & | operator= (const Selection &)=delete |
bool | registerSelectionSource (std::string name) |
Selection sources. More... | |
bool | unregisterSelectionSource (std::string name) |
Unregister a selection source; if false is returned, the source was not recognized. | |
const std::set< std::string > & | getSelectionSources () const |
Populate a set with the names of all registered selection sources. | |
void | getSelectionSources (std::set< std::string > &selectionSources) const |
Populate a set with the names of all registered selection sources. | |
bool | registerSelectionValue (const std::string &valueLabel, int value, bool valueMustBeUnique=true) |
Selection values. More... | |
bool | unregisterSelectionValue (const std::string &valueLabel) |
Unregister a selection value. If the value was not registered, returns false. | |
bool | unregisterSelectionValue (int value) |
Unregister a selection value. If the value was not registered, returns false. | |
const std::map< std::string, int > & | selectionValueLabels () const |
Return the map of selection values. | |
int | selectionValueFromLabel (const std::string &label) const |
Return the selection value for the given label, or 0 if there is no such label registered. | |
int | findOrCreateLabeledValue (const std::string &label) |
Return the selection value for the given label, registering a new value if needed. | |
template<typename T > | |
bool | modifySelection (const T &objects, const std::string &source, int value, SelectionAction action=SelectionAction::DEFAULT, bool bitwise=false, bool postponeNotification=false) |
Modify the current selection. More... | |
bool | resetSelectionBits (const std::string &source, int value) |
Reset values in the selection map so no entries contain the given bit value. More... | |
bool | setDefaultAction (const SelectionAction &action) |
Default selection action. More... | |
SelectionAction | defaultAction () const |
Return the current method used to modify selections when. | |
void | setDefaultActionToReplace () |
void | setDefaultActionToAddition () |
void | setDefaultActionToSubtraction () |
void | visitSelection (std::function< void(Object::Ptr, int)> visitor) |
Querying the current selection. More... | |
SelectionMap & | currentSelection (SelectionMap &selection) const |
Return the current selection as a map from objects to integer selection values. | |
const SelectionMap & | currentSelection () const |
template<typename T > | |
T & | currentSelectionByValue (T &selection, int value, bool exactMatch=true) const |
Return the subset of selected elements that match the given selection value. | |
template<typename T > | |
T & | currentSelectionByValue (T &selection, const std::string &valueLabel, bool exactMatch=true) const |
template<typename T > | |
T | currentSelectionByValueAs (int value, bool exactMatch=true) const |
template<typename T > | |
T | currentSelectionByValueAs (const std::string &valueLabel, bool exactMatch=true) const |
Observers & | observers () |
Return the observers associated with this phrase model. | |
const Observers & | observers () const |
void | setFilter (const SelectionFilter &fn, bool refilterSelection=true) |
Selection filtering. More... | |
bool | configureItem (const std::shared_ptr< smtk::attribute::ReferenceItem > &item, int value, bool exactMatch=false, bool clearItem=true) const |
Convenience functions. More... | |
Static Public Member Functions | |
static Ptr | instance () |
Protected Member Functions | |
bool | performAction (smtk::resource::PersistentObjectPtr comp, int value, SelectionAction action, SelectionMap &suggested, bool bitwise) |
Perform the action (ignoring m_defaultAction!!!), returning true if it had an effect. | |
bool | refilter (const std::string &source) |
Protected Attributes | |
SelectionAction | m_defaultAction { SelectionAction::FILTERED_REPLACE } |
bool | m_meshSetMask |
std::set< std::string > | m_selectionSources |
std::map< std::string, int > | m_selectionValueLabels |
SelectionMap | m_selection |
Observers | m_observers |
SelectionFilter | m_filter |
A class to manage linked selections in a context.
This class allows multiple UI elements to share a selection by providing methods to modify and filter the selection as well as receive signals when the selection is updated by others.
The major use case is to support a single, application-wide selection but it is possible to create multiple instances of this class if your application wishes to manage different selections depending upon some context. The instance() method supports application-wide selections by returning the first selection instance which has been created (or creates a new instance if its weak pointer is null).
A selection is a map from PersistentObjects to integers that indicate the type of selection that the object is participating in. Integers are application-specific and managed in this class by registering them. Applications are free to interpret the integer as a bitmask, so that the same object may be in multiple selections at a time; or as a unique values that indicate the "level of selection" for each object. An example of the latter would be an application that registers 1 to indicate a transient highlight to preview mouseovers and 2 to indicate permanent selection. The latter is how modelbuilder uses SMTK selections.
When an object is assigned the special integer 0, the object is considered "unselected" and is removed from the map.
First, your application should create a selection instance for each separate context in which a separate selection is allowed. If your application will be making changes to resources by invoking operators, you should register the operation manager with the selection so that as persistent objects are created and destroyed the selection can be updated.
After creating a selection, each UI element of your application that will (a) share the selection and (b) modify the selection should register itself as a source of selections by providing a unique string name to registerSelectionSource().
Similarly, each UI element of your application that will (a) share the selection and (b) present the selection or otherwise need to be informed of changes to the selection should register as an observer by providing a callback to observe().
When the selection changes, Observer functions subscribed to updates will be called with the name of the UI elements that caused the event (or "selection" if a change inside the selection itself caused the event). A pointer to the selection is also provided so you can query the selection inside the Observer function. You should not modify the selection inside a Observer as that can cause infinite recursion.
The Observer may be called under a variety of circumstances:
While Observers are not usually informed when attempted changes to the selection have no effect, it is possible to get called when the selection is entirely replaced with an identical selection.
Often, observers may wish to make use of an updated selection by applying it to an attribute ReferenceItem (and particularly when a ReferenceItem is an operation-parameter's associations). The selection provides the configureItem() method to support this use case.
using smtk::view::Selection::SelectionFilter = std::function<bool(Object::Ptr, int, SelectionMap&)> |
Selection filters take functions of this form.
Given an object and its selection "value", return true if the object should be included in the action (replacement, addition to, or removal from the selection). Otherwise return false.
The filter may also insert objects into the map (the 3rd argument) which will unconditionally be included in the action. This is intended to handle use cases where related objects (e.g., edges, faces, vertices) may be geometrically picked by a user but the desired selection is on objects not directly rendered (e.g., volumes, models). The filter can return false (indicating that the edge, face, or vertex should not be considered) but add the related entities (the volume or model) to the map for action.
bool smtk::view::Selection::configureItem | ( | const std::shared_ptr< smtk::attribute::ReferenceItem > & | item, |
int | value, | ||
bool | exactMatch = false , |
||
bool | clearItem = true |
||
) | const |
Convenience functions.
Replace the reference item's membership with values from the selection.
Objects in the currentSelection() are added to the item when
By default, the item's pre-existing membership is cleared before the selection is added to the item. (This can be changed by passing false to clearItem.)
If the item is optional, it will be disabled if no entries in the selection match and (if clearItem is false) there are no pre-existing entries retained. Otherwise, the item will be enabled. Note that if no values in the item are modified, no change will be made to the item's isEnabled() status.
This method returns true if the item's membership was changed and false otherwise. If true, you may wish to run the smtk::attribute::Signal operation so that user interface components can be properly notified.
bool smtk::view::Selection::modifySelection | ( | const T & | objects, |
const std::string & | source, | ||
int | value, | ||
SelectionAction | action = SelectionAction::DEFAULT , |
||
bool | bitwise = false , |
||
bool | postponeNotification = false |
||
) |
Modify the current selection.
Returns true if the arguments result in a change to the selection.
action specifies indicates whether the list of objects should replace the selection, be added to it, or be removed from it. value indicates the "level" at which the objects should be selected (except when the action is a subtraction operation, in which case value is ignored). source indicates which UI element is responsible for the selection modification. bitwise indicates whether, treating value as a bit-vector, the selection should only modify those bits.
When bitwise is true, then actions which ADD to the selection will insert new entries into the selection with value bits set unless those objects were already present, in which case their values will be OR-ed with value. Actions which SUBTRACT from the selection will remove entries whose bits are a strict subset of those in value; otherwise objects will have value's bits removed from the selection map but will remain in the map. Actions which REPLACE the selection will remove any objects already in the selection map whose bits are a subset of value, insert objects not already present in the map (with the given value), and OR value into the bits of any present in both the selection and the "replacement" objects.
If bitwise is false, then actions which ADD to the selection will overwrite any existing selection-map entry for matching objects with the given value. Actions which SUBTRACT from the selection, will remove entries from the selection only when their mapped value exactly matches value. Actions which REPLACE the selection will erase the entire selection map and then insert the provided objects with the given value.
|
inline |
Selection sources.
Selections are modified by UI elements, each of which is considered a source of the selection. The selection provides a way for these UI elements to register in order to verify that their name is unique (within the selection).
Register a selection source.
If false is returned, the name is already in use; try again with a different name.
bool smtk::view::Selection::registerSelectionValue | ( | const std::string & | valueLabel, |
int | value, | ||
bool | valueMustBeUnique = true |
||
) |
Selection values.
Selected objects each take on a non-zero integer value that is application-defined.
The methods in this section are used to register particular values or bits that the application wishes to use. Each value is tied to a string name. Register a selection value. If the value was already registered, returns false.
bool smtk::view::Selection::resetSelectionBits | ( | const std::string & | source, |
int | value | ||
) |
Reset values in the selection map so no entries contain the given bit value.
This method assumes each value in the selection map is a bit vector.
This will remove objects from the selection entirely if their selection value is a subset of the bits set in value.
bool smtk::view::Selection::setDefaultAction | ( | const SelectionAction & | action | ) |
Default selection action.
Some applications need to separate the choice of which SelectionAction to use from the choice of objects in the selection. The selection keeps a default SelectionAction value as state so that when modifySelection is called with the action set to SelectionAction::DEFAULT, the selection's state is used in its stead.
The methods in this section provide a way to set and query the action used when SelectionAction::DEFAULT is passed to modifySelection. Obviously, SelectionAction::DEFAULT is not allowed. You are strongly encouraged only to allow FILTERED and not UNFILTERED actions as the default.
The initial value for the default action is FILTERED_REPLACE. Set the selection modifier. Returns true if action was valid; false otherwise.
void smtk::view::Selection::setFilter | ( | const SelectionFilter & | fn, |
bool | refilterSelection = true |
||
) |
Selection filtering.
Set the filter to apply to each persistent object.
|
inline |
Querying the current selection.
You can obtain the current selection in bulk or objects selected with a particular value. If you are using selection values as independent bits in a it vector, pass exactMatch = false. Visit every selected object with the given functor.