Action GUI building blocks
ManiVault Studio provides a set of action GUI building blocks – modular UI components (built on Qt widgets) that plugin developers use to create interactive controls in their plugins 1. These “actions” encapsulate common GUI elements (text fields, sliders, toggles, etc.) along with built-in behaviors for state management and inter-plugin communication. In this guide, we’ll cover what these action blocks are, their purpose in ManiVault, how to customize their behavior and appearance, and how to extend them for new functionality. An example using the StringAction block will illustrate these concepts in practice.
Action GUI building blocks (simply called “actions”) are the fundamental interactive elements for ManiVault plugins. Each action represents a specific type of user interface control combined with logic to handle a parameter or command. Under the hood, actions wrap standard Qt widgets with additional functionality. ManiVault provides a library of built-in actions for common UI needs 1, including:
- StringAction – a text input field (single-line or multi-line) for string parameters.-
- DecimalAction and IntegralAction – numeric inputs for floats or integers (with spinboxes, sliders, or both for adjusting values).
- OptionsAction – a drop-down or list selector for choosing among multiple options.
- ToggleAction – a boolean toggle (e.g. a checkbox or switch) for on/off settings.
- TriggerAction – a push-button to trigger an action or event.
- ColorAction / ColormapAction – color picker controls (single colors or entire color maps).
- FilePickerAction (and DirectoryPickerAction) – file dialog launchers for selecting files or folders.
- SelectionAction – a specialized widget for selecting data points (with modes like brush, lasso, etc., often used in visual analytics)
- DimensionPickerAction – a UI for picking one or multiple data dimensions (e.g. selecting which dimensions of a dataset to use).
- GroupAction – a container that groups other actions under a collapsible panel or section (useful for organizing related controls).
Each action object holds a piece of state (a value or trigger) and automatically generates the appropriate GUI controls to manipulate that state. For example, a StringAction stores a text string and creates a labeled text box widget for users to view or edit that string 1. A DecimalAction holds a numeric value and might create a slider + textbox combo to adjust that number. Developers do not directly create Qt widgets for plugin settings; instead, they instantiate actions (like new StringAction(this, "Label", defaultValue)) and ManiVault takes care of rendering the GUI elements and keeping them in sync with the underlying value
2. This abstraction makes actions building blocks that can be added to a plugin’s interface with minimal effort while ensuring consistency across the whole application.
Actions aren’t just static UI controls – they carry metadata and integration hooks:
Each action has a title (used as its label in the UI) and an internal ID. The title is displayed next to the widget (and is interactive for linking/sharing as discussed later).
Actions know whether they are public or private in scope. A public action’s value can be shared with other plugins, whereas a private action is local to the plugin. By default, most plugin settings actions are private until the user or developer marks them public.
Actions emit signals when their value changes or when other state toggles happen (enabled/disabled, visibility changes, etc.), allowing the plugin logic to react to user input without manual GUI wiring.
All actions are part of a hierarchy within a plugin (often reflecting grouping in the UI). ManiVault’s core can traverse this hierarchy for tasks like saving state or building dynamic dialogs.
In ManiVault Studio’s architecture, actions serve several important purposes:
-
Standardizing Plugin Interfaces
Actions provide a uniform look-and-feel and behavior across all plugins. Because all plugin settings (parameters, toggles, buttons) are built from the same set of action blocks, users get a consistent GUI experience. For instance, a slider looks and behaves the same everywhere. Plugin developers don’t need to design custom controls for common tasks – they leverage these ready-made components, leading to a cohesive interface design across the application. -
Capturing and Restoring State One core use of actions is to make plugin state serializable and easily saved. Each action knows how to serialize its current value and its UI state (whether it’s active, visible, editable, etc.) into a variant/JSON representation (see WidgetAction::toVariantMap(...)) and restore its state from JSON (see WidgetAction::fromVariantMap(...)).
All actions in a plugin form a hierarchical state tree that can be saved to disk (for example, as part of a project file or preset) and later reloaded to restore the plugin’s exact configuration. In practice, this means if you build your plugin UI with actions, you get save/load functionality for free – ManiVault can snapshot the entire actions hierarchy to JSON and reinstate it on demand. This is how ManiVault implements features like presets for plugin settings and even saving the complete application state (the Studio’s “Projects” feature uses action serialization to capture the UI and parameters of every plugin). For example, a developer might let users save a preset of an analysis plugin’s parameters; under the hood ManiVault just writes out the action values to a JSON file and can load them back later, no custom code needed. -
Parameter Linking and Communication Actions are also the mechanism for ManiVault’s interactive linking of parameters between plugins. If two plugins have actions of the same type (e.g. a DecimalAction controlling a certain parameter), ManiVault allows the user to connect them so that one shared value drives both plugins. The system’s messaging API uses actions as the endpoints for these connections. For example, the Mean-Shift clustering plugin and a Scatterplot view plugin might both have a “Sigma” parameter (one in an analysis context, one in a visualization context). In Studio mode, the Sigma action from one plugin is published and subscribed to from the other. From that point on, the two are linked – adjusting the value in one UI automatically updates the other and vice versa.
The underlined labels on actions indicate that an action can be published or subscribed (meaning it’s eligible for linking):
ManiVault italicizes the action’s label once connected:
Users can click an action’s label to get a menu for publishing it to a shared parameter pool or subscribing it to an existing shared parameter:
In summary, actions double as communication conduits: by using actions for plugin parameters, you automatically enable those parameters to be shared and synchronized across modules (a key design goal of ManiVault Studio). -
Exposing Data-Driven Actions
Beyond plugin settings, actions can represent operations attached to data objects. For instance, an analytics plugin might attach a TriggerAction to a data model (say, a “Refine clustering” button attached to a clustering result). Other plugins that deal with that data can detect the attached action and present a GUI control for it in context:
The scatterplot view plugin exposes actions from the HSNE analysis plugin
ManiVault’s core manages these links so that a view plugin can show, for example, a context menu item “Refine Clustering” if it finds that action on a dataset, even though the action’s logic lives in the analytics plugin. This is an advanced use, but it shows that actions are not limited to static plugin panels – they can also enable cross-plugin functionality by surfacing one plugin’s capabilities inside another’s interface. In short, actions help decouple functionality: any plugin can offer actions (parameters or triggers) that other plugins can discover and incorporate, fostering an extensible, interconnected system.
To summarize, ManiVault’s action blocks are used to build plugin UIs that are consistent, easily saved/loaded, and inherently shareable or linkable. They reduce the engineering effort for plugin developers (since common GUI and state-handling code is already done) and empower end-users with flexible workflows (linking parameters on the fly, saving presets, etc.).