Event Handling

The ManiVault core facilitates communication between plugins through the means of events. Any class written in projects that link the ManiVault public library will be able to subscribe to these events.

Events in ManiVault are handled by an EventManager in the core. From your plugin class, you can interact with this EventManager through the function events(). It provides the following events:

Event Type	Description	Function call
Dataset Added	Notify the system that a new dataset has been added	notifyDatasetAdded(dataset)
Dataset About To Be Removed	Notify the system that a dataset is about to be removed	notifyDatasetAboutToBeRemoved(dataset)
Dataset Removed	Notify the system that a dataset has been removed	notifyDatasetRemoved(datasetGuid, dataType)
Dataset Data Changed	Notify the system that the data contained in a dataset has changed	notifyDatasetDataChanged(dataset)
Dataset Dimensions Changed	Notify the system that the dimensions of a dataset have changed	notifyDatasetDataDimensionsChanged(dataset)
Dataset Selection Changed	Notify the system that the selection of a dataset has changed	notifyDatasetDataSelectionChanged(dataset, ignoreDatasets)
Dataset Locked	Notify the system that a new dataset has been added	notifyDatasetLocked(dataset)
Dataset Unlocked	Notify the system that a new dataset has been added	notifyDatasetUnlocked(dataset)
Register Event Listener	Notify the system that a new dataset has been added	registerEventListener(eventListener)
Unregister Event Listener	Notify the system that a new dataset has been added	unregisterEventListener(eventListener)

Subscribing to events

Any class that extends itself from the EventListener class can register for a variety of events using the registerDataEvent or registerDataEventByType functions. The general syntax of these functions is as follows:

registerDataEvent(DataEventHandler callback);
registerDataEvent(DataType dataType, DataEventHandler callback);

where DataEventHandler is a generic C++ function object and DataType is a HDPS data type that every DataPlugin provides (Some of the data plugins included in HDPS have types such as PointType, ImageType, ClusterType).

An example function call could look similar to this:

// Register for events involving only point data, events are sent to custom onDataEvent callback function with one argument
registerDataEventByType(PointType, std::bind(&YourOwnPlugin::onDataEvent, this, std::placeholders::_1));

If the syntax of the second argument is unfamiliar, it is possible to read more about it here.

Handling events

The plugin calling this registration function can provide its own callback function with the following syntax:

void onDataEvent(hdps::DataEvent* dataEvent);

of which an example implementation handling four types of events is provided with the ExampleViewPlugin:

void ExampleViewPlugin::onDataEvent(hdps::DataEvent* dataEvent)
{
    // The data event has a type so that we know what type of data event occurred (e.g. data added, changed, removed, renamed, selection changes)
    switch (dataEvent->getType()) {

        // A points dataset was added
        case EventType::DataAdded:
        {
            // Cast the data event to a data added event
            const auto dataAddedEvent = static_cast<DataAddedEvent*>(dataEvent);

            // Get the name of the added points dataset
            const auto pointsDatasetName = dataAddedEvent->dataSetName;

            // Print to the console
            qDebug() << pointsDatasetName << "was added";

            break;
        }

        // Points dataset data has changed
        case EventType::DataChanged:
        {
            // Cast the data event to a data changed event
            const auto dataChangedEvent = static_cast<DataChangedEvent*>(dataEvent);

            // Get the name of the points dataset of which the data changed
            const auto pointsDatasetName = dataChangedEvent->dataSetName;

            // Print to the console
            qDebug() << pointsDatasetName << "data changed";

            break;
        }

        // Points dataset data was removed
        case EventType::DataRemoved:
        {
            // Cast the data event to a data removed event
            const auto dataRemovedEvent = static_cast<DataRemovedEvent*>(dataEvent);

            // Get the name of the removed points dataset
            const auto pointsDatasetName = dataRemovedEvent->dataSetName;

            // Print to the console
            qDebug() << pointsDatasetName << "was removed";

            break;
        }

        // Points dataset selection has changed
        case EventType::SelectionChanged:
        {
            // Cast the data event to a selection changed event
            const auto selectionChangedEvent = static_cast<SelectionChangedEvent*>(dataEvent);

            // Get the name of the points dataset of which the selection changed
            const auto pointsDatasetName = selectionChangedEvent->dataSetName;

            // Get points dataset
            const auto& changedDataSet = _core->requestData<Points>(dataEvent->dataSetName);

            // Get the selection set that changed
            const auto& selectionSet = changedDataSet.getSelection();

            // Print to the console
            qDebug() << pointsDatasetName << "selection has changed";

            break;
        }

        default:
            break;
    }
}