OpenSWMM::Sdk Namespace Reference

Public header-only ABI for independently compiled native GUI extensions. More...

Classes
struct	ActivityEvent
	Owning deferred process transition or scoped UI invalidation. More...
struct	ActivityEventFilter
	Registration-time event reason and optional process/session selection. More...
class	ActivitySignalAdapter
	Consumer-owned typed QObject projection of one managed IActivityEvents subscription. More...
struct	ActivitySnapshot
	Pure copied retained process/UI metadata at the shared session/view/activity watermark. More...
struct	CommandState
	Calling extension's command or an approved existing built-in dialog command. More...
struct	CompatibilityManifest
struct	DockState
	Copied metadata for one calling extension's registered dock. More...
struct	DocumentState
	Copied global MDI metadata, with actual focus separate from cached model context. More...
struct	Event
	One typed observation published by an extension's host facade. More...
struct	EventFilter
	Immutable-at-registration selection of event kinds and a model identity. More...
class	EventSignalAdapter
	Consumer-owned typed Qt signals backed by one managed host subscription. More...
class	ExtensionHost
struct	ExtensionInfo
	Owning metadata describing a native plugin or one of its hosted child extensions. More...
class	IActivityControls
	Frozen optional typed activity control capability. More...
class	IActivityEvents
	Frozen optional GUI-thread process and UI snapshot/observation capability. More...
class	IComputedAttributeProvider
	Borrowed provider of derived attributes on authored model objects. More...
class	IConsole
	Host-owned plain-text output channel scoped to one extension and forwarded to native Logs. More...
class	IDialogs
	Argument-free built-in dialog commands, exposed through registered application actions. More...
class	IDockPanelFactory
class	IDocumentViewFactory
	Borrowed factory for MDI widgets with JSON project-state persistence. More...
class	IEditScope
class	IEngineLease
class	IGuiExtension
class	IJob
	Borrowed thread-safe handle for a job retained by its extension host. More...
class	IJobContext
	Worker-only progress, cancellation and GUI-continuation interface. More...
class	IModelEvents
	Optional, frozen interface for receiver-scoped typed GUI observations. More...
class	IModelInstance
class	INativeEditScope
class	INetworkPolicy
	Borrowed GUI-thread network service used for catalogue previews and data downloads. More...
class	IPlotService
	Access to existing time-series and profile plot panels. More...
class	IPreferencesPageFactory
	Borrowed factory for extension pages in the host Preferences dialog. More...
class	IPreviewLayers
	Optional GUI-thread lookup of this extension's attached native preview layer. More...
class	IProgress
	Optional host-owned progress service; every method requires the GUI thread. More...
class	IProject
class	IRunRegistry
	Simulation Status facade supporting native and legacy worker runs. More...
class	ISessionEvents
	Frozen optional access to session snapshots and authoritative lifecycle observations. More...
class	ISettings
class	ITimeSeriesLayers
	Optional host-owned import service; all public entry points use the GUI thread. More...
class	IUiHost
class	IViewControls
	Frozen optional validated controller entry point for view changes. More...
class	IViewEvents
	Frozen optional GUI-thread view metadata and deferred domain observation service. More...
struct	JobFinishedEvent
	Copied completion status from one of the owning extension's background jobs. More...
struct	JobProgressEvent
	Copied progress from one of the owning extension's background jobs. More...
struct	LayerViewState
	Copied metadata for one unambiguous current canvas attachment. More...
struct	ModelEvent
	Model discovery, closing, activation, selection, edit or attribute observation. More...
struct	ModelSessionState
	Owning metadata for one open lifetime, distinct from its persistent project identity. More...
struct	ProcessState
	Owning metadata for one unique accepted attempt, independent of row IDs/titles. More...
struct	ResultsEvent
	Active result-source observation without result-reader ownership. More...
struct	ResultsViewState
	Copied state of an attached results layer, separate from run-attempt telemetry. More...
struct	ResultVariableState
	One current rendering channel's selected variable and native unit metadata. More...
struct	RibbonGroupSpec
	One captioned ribbon group using commands already registered by the extension. More...
struct	RibbonTabSpec
	Value-described ribbon contribution suitable for native or future Python-authored UI. More...
struct	RunsEvent
	Simulation Status invalidation; query the run registry for current rows. More...
struct	SaveRequest
	Synchronous, non-vetoing opportunity to collect state before a save writes. More...
struct	SaveState
	Copied outcome and destination for one uniquely identified save operation. More...
class	ScopedEventSubscription
	Move-only owner that disconnects a Qt subscription when its scope ends. More...
struct	SettingsEvent
	One owning extension's settings invalidation. More...
struct	SpatialEvent
	Visible-area, canvas membership or watched vector-boundary observation. More...
struct	StateEvent
	Immutable transition record delivered later on the GUI thread. More...
struct	StateEventFilter
	Copied selection of lifecycle kinds and optionally one open lifetime. More...
struct	StateSnapshot
	Atomic GUI-thread copy of live session metadata and its event watermark. More...
struct	ThemeEvent
	Palette invalidation; query current host theme tokens. More...
struct	TimeSeriesImportRequest
	Owning request referencing a completed local source-neutral import descriptor. More...
struct	TimeSeriesImportResult
	Terminal import outcome delivered on the GUI thread to a guarded receiver. More...
struct	TimeSeriesLayerInfo
	Bounded copied metadata for one attached native collection. More...
struct	UiActivityCommand
	Owning explicit UI action; observers should defer their own state-changing work. More...
struct	UiActivityState
	Copied UI metadata scoped to one main window and the calling extension's contributions. More...
struct	ViewCommand
	Owning bounded request for one native view-controller action. More...
struct	ViewEvent
	Owning deferred observation identifying state to query again. More...
struct	ViewEventFilter
	Registration-time reason, session and runtime-attachment selection. More...
class	ViewSignalAdapter
	Consumer-owned QObject with typed signals from one guarded IViewEvents subscription. More...
struct	ViewSnapshot
	Pure copied current metadata at the shared registry watermark. More...

Typedefs
using	EventPayload = std::variant< ModelEvent, SpatialEvent, ResultsEvent, RunsEvent, SettingsEvent, ThemeEvent, JobProgressEvent, JobFinishedEvent >
	Closed, owning payload alternatives for the frozen IModelEvents event service.

Enumerations
enum class	UiActivityCommandKind : quint32 {   ActivateDocument = 1 ,   SetDockOpen = 2 ,   TriggerCommand = 3 }
	Supported native UI routes with runtime identities rather than object names. More...
enum class	ProcessKind : quint32 {   Run = 1 ,   Job = 2 }
	Native shared simulation attempt or one calling extension's private worker. More...
enum class	ProcessPhase : quint32 {   Queued = 1 ,   Running = 2 ,   Succeeded = 3 ,   Failed = 4 ,   Cancelled = 5 }
	Accepted scheduling/preparation, worker availability and distinct terminal outcomes. More...
enum class	DocumentKind : quint32 {   Model = 1 ,   Extension = 2 ,   Utility = 3 }
	Runtime classification of a mounted MDI document. More...
enum class	ActivityEventKind : quint32 {   OperationAccepted = 1 ,   OperationStarted = 2 ,   OperationProgress = 3 ,   CancellationRequested = 4 ,   OperationFinished = 5 ,   OperationRemoved = 6 ,   ActiveDocumentChanged ,   DocumentChanged = 8 ,   DocumentRemoved = 9 ,   DockChanged = 10 ,   DockRemoved = 11 ,   CommandChanged = 12 ,   CommandRemoved = 13 }
	Stable process transitions and UI invalidation reasons. More...
enum class	LeaseKind {   Read ,   Write }
	Requested access to a GUI-owned model engine. More...
enum class	EventKind : quint32 {   InstanceDiscovered ,   InstanceClosing = 2 ,   InstanceActivated ,   SelectionChanged = 4 ,   ModelEdited = 5 ,   AttributesChanged ,   ViewportChanged = 7 ,   LayersChanged ,   BoundaryChanged = 9 ,   ActiveResultsChanged ,   RunsChanged = 11 ,   SettingsChanged = 12 ,   ThemeChanged = 13 ,   JobProgress = 14 ,   JobFinished = 15 }
	Existing host observations with explicit, stable numeric identities. More...
enum class	ProgressOutcome {   Succeeded ,   Failed ,   Cancelled }
	Terminal classification for an extension-owned progress operation. More...
enum class	SessionStatus : quint32 {   Created = 1 ,   Loading = 2 ,   Ready = 3 ,   Failed = 4 ,   Closing = 5 }
	Current availability of an open model-window session. More...
enum class	StateChange : quint32 {   None = 0 ,   Metadata = 1 ,   Model = 2 ,   Selection = 4 ,   Viewport = 8 ,   Layers = 16 ,   Results = 32 ,   ProjectState = 64 }
	Broad invalidations of queryable state, without claiming changed-field deltas. More...
enum class	StateEventKind : quint32 {   SessionOpened = 1 ,   LoadStarted = 2 ,   ModelReady = 3 ,   LoadFailed = 4 ,   StateChanged = 5 ,   SaveStarted = 6 ,   SaveFinished = 7 ,   SessionClosing = 8 ,   SessionClosed = 9 }
	Lifecycle or save transition recorded by the shared application registry. More...
enum class	SaveKind : quint32 {   Project = 1 ,   Sidecar = 2 ,   Recovery = 3 }
	Meaning of a persisted save destination. More...
enum class	SaveOutcome : quint32 {   None = 0 ,   Started = 1 ,   Succeeded = 2 ,   Failed = 3 }
	Outcome state of a correlated save operation. More...
enum class	ViewCommandKind : quint32 {   RenameLayer = 1 ,   SetLayerVisible = 2 ,   SetLayerOpacity = 3 ,   MoveLayer = 4 ,   RemoveLayer = 5 ,   SetLayerFilter = 6 ,   SelectLayerFeatures = 7 ,   ActivateResults = 8 ,   SetResultsTime ,   SetResultsVariable = 10 }
	Supported, typed view commands without exposing private Qt slots. More...
enum class	ViewEventKind : quint32 {   ModelGeometryChanged = 1 ,   ModelOptionsChanged = 2 ,   ObjectRenamed = 3 ,   AttributeValuesChanged = 4 ,   AttributeSchemaChanged = 5 ,   ModelSelectionChanged = 6 ,   LayerAdded = 7 ,   LayerRemoved = 8 ,   LayerMetadataChanged = 9 ,   LayerOrderChanged = 10 ,   LayerStyleChanged = 11 ,   LayerSchemaChanged = 12 ,   LayerFeaturesChanged = 13 ,   LayerSelectionChanged = 14 ,   LayerFilterChanged = 15 ,   LayerCrsChanged = 16 ,   LayerSourceChanged = 17 ,   ResultsSourceChanged = 18 ,   ResultsActiveChanged = 19 ,   ResultsVariableChanged = 20 ,   ResultsTimeChanged = 21 ,   ProjectUnitsChanged = 22 }
	Stable invalidation reasons, without geometry, selection or result arrays. More...
enum class	ResultAvailability : quint32 {   Empty = 0 ,   Loading = 1 ,   Ready = 2 ,   Failed = 3 }
	Metadata availability of the currently attached results source. More...

Variables
constexpr auto	MODEL_EVENTS_IID = OPENSWMM_MODEL_EVENTS_IID
	Discoverable interface IID, equivalent to OPENSWMM_MODEL_EVENTS_IID.
constexpr auto	SESSION_EVENTS_IID
	Public alias for the frozen discovery identity.
constexpr auto	SDK_API_VERSION
	Public interface major/minor, independently of GUI version.
constexpr auto	GUI_EXTENSION_IID
	Qt plugin root IID.

Detailed Description

Public header-only ABI for independently compiled native GUI extensions.

Typedef Documentation

EventPayload

using OpenSWMM::Sdk::EventPayload = typedef std::variant<ModelEvent, SpatialEvent, ResultsEvent, RunsEvent, SettingsEvent, ThemeEvent, JobProgressEvent, JobFinishedEvent>

Closed, owning payload alternatives for the frozen IModelEvents event service.

Enumeration Type Documentation

ActivityEventKind

enum class OpenSWMM::Sdk::ActivityEventKind : quint32

strong

Stable process transitions and UI invalidation reasons.

Enumerator
OperationAccepted	Unique attempt accepted for preparation/scheduling.
OperationStarted	Native runner/worker entered its start path.
OperationProgress	Coalesced latest progress; query current state for display.
CancellationRequested	A request won before settlement; outcome is still independent.
OperationFinished	Exactly one immutable terminal outcome for an accepted attempt.
OperationRemoved	Retained metadata retired; the UUID is never reassigned.
ActiveDocumentChanged	Actual MDI focus changed, including utility documents/no document.
DocumentChanged	Mounted document metadata changed.
DocumentRemoved	Historical document retirement; target no longer resolves.
DockChanged	Calling extension's logical/exposed dock state changed.
DockRemoved	Calling extension's dock registration retired.
CommandChanged	Own/approved command metadata changed.
CommandRemoved	Own/approved command registration retired.

DocumentKind

enum class OpenSWMM::Sdk::DocumentKind : quint32

strong

Runtime classification of a mounted MDI document.

Enumerator
Model	Native model document with a per-open session identity.
Extension	Successfully mounted extension document, optionally model-bound.
Utility	Other native document, without inventing a model association.

EventKind

enum class OpenSWMM::Sdk::EventKind : quint32

strong

Existing host observations with explicit, stable numeric identities.

Note

Discovery and closing describe facade discovery and the beginning of closure, respectively. They are not loaded/ready or post-destruction events.

Enumerator
InstanceDiscovered	First discovery of a model facade, possibly before loading completes.
InstanceClosing	Model closure has begun; treat the model as unavailable.
InstanceActivated	MDI activation resolved to a model, or a null UUID for another document.
SelectionChanged	Shared authored-model selection changed.
ModelEdited	The native modelEdited observation was emitted.
AttributesChanged	The native attributeChanged observation identified an object or broad invalidation.
ViewportChanged	Visible canvas extent or CRS changed, including resizing.
LayersChanged	Canvas layer membership changed; the affected layer identity is unspecified.
BoundaryChanged	A watched vector boundary source changed in place.
ActiveResultsChanged	Active 1D/2D results source changed, without a playback guarantee.
RunsChanged	Simulation Status metadata or row membership changed.
SettingsChanged	The owning extension wrote or removed one settings key/group.
ThemeChanged	The main-window palette changed.
JobProgress	The owning extension reported background-job progress.
JobFinished	The owning extension's background worker completed.

LeaseKind

enum class OpenSWMM::Sdk::LeaseKind

strong

Requested access to a GUI-owned model engine.

Enumerator
Read	Shared read access, excluding runs and any writer.
Write	Exclusive native access, excluding all other leases and runs.

ProcessKind

enum class OpenSWMM::Sdk::ProcessKind : quint32

strong

Native shared simulation attempt or one calling extension's private worker.

Enumerator
Run	Shared native simulation attempt.
Job	Private extension worker.

ProcessPhase

enum class OpenSWMM::Sdk::ProcessPhase : quint32

strong

Accepted scheduling/preparation, worker availability and distinct terminal outcomes.

Enumerator
Queued	Accepted preparation/scheduling, without claiming engine execution.
Running	Native runner/worker has started its execution path.
Succeeded	Settled successfully; a late cancel cannot change this outcome.
Failed	Settled with an explicit worker/preparation error.
Cancelled	Settled as cancelled; no output rollback is implied.

ProgressOutcome

enum class OpenSWMM::Sdk::ProgressOutcome

strong

Terminal classification for an extension-owned progress operation.

Enumerator
Succeeded	Work completed successfully.
Failed	Work stopped with an error; detail may explain the failure.
Cancelled	Work was cancelled or its receiver lifetime ended.

ResultAvailability

enum class OpenSWMM::Sdk::ResultAvailability : quint32

strong

Metadata availability of the currently attached results source.

Enumerator
Empty	No adopted reader/source.
Loading	A new attached source is being prepared.
Ready	Reader/source metadata is adopted; zero published periods is permitted.
Failed	Latest preparation failed and no usable reader/source remains.

SaveKind

enum class OpenSWMM::Sdk::SaveKind : quint32

strong

Meaning of a persisted save destination.

Enumerator
Project	Normal model/project save transaction.
Sidecar	Standalone project-sidecar write.
Recovery	Independent recovery snapshot/project write.

SaveOutcome

enum class OpenSWMM::Sdk::SaveOutcome : quint32

strong

Outcome state of a correlated save operation.

Enumerator
None	This event does not describe a save.
Started	Save preparation/state collection has begun.
Succeeded	Final intended transaction committed successfully.
Failed	The transaction did not commit successfully.

SessionStatus

enum class OpenSWMM::Sdk::SessionStatus : quint32

strong

Current availability of an open model-window session.

Enumerator
Created	Window exists, with no completed load attempt.
Loading	A particular load generation is being prepared/restored.
Ready	Native readiness barrier completed for the current generation.
Failed	Current load failed; retry is possible while the window remains open.
Closing	Close committed; resolution must not return an actionable model.

StateChange

enum class OpenSWMM::Sdk::StateChange : quint32

strong

Broad invalidations of queryable state, without claiming changed-field deltas.

Enumerator
None	No additional invalidation category.
Metadata	Identity, title, path or dirty metadata changed.
Model	Authored model state or its native edit revision changed.
Selection	Shared model selection changed.
Viewport	Visible area or canvas CRS changed.
Layers	Canvas layer membership changed.
Results	Active result source changed.
ProjectState	Project-owned extension/presentation state changed.

StateEventKind

enum class OpenSWMM::Sdk::StateEventKind : quint32

strong

Lifecycle or save transition recorded by the shared application registry.

Enumerator
SessionOpened	An open lifetime was registered.
LoadStarted	A new accepted load generation started.
ModelReady	The generation's native readiness barrier completed.
LoadFailed	The generation ended without becoming ready.
StateChanged	Broad queryable-state invalidation with merged categories.
SaveStarted	Informational queued save start; state collection uses a separate hook.
SaveFinished	Save transaction succeeded or failed.
SessionClosing	Close committed and resolution is unavailable.
SessionClosed	Session was removed from live state before this record was published.

UiActivityCommandKind

enum class OpenSWMM::Sdk::UiActivityCommandKind : quint32

strong

Supported native UI routes with runtime identities rather than object names.

Enumerator
ActivateDocument	Focus a current mounted document in this main window.
SetDockOpen	Show/raise or hide a calling extension's own dock.
TriggerCommand	Trigger an enabled own action or approved built-in dialog command.

ViewCommandKind

enum class OpenSWMM::Sdk::ViewCommandKind : quint32

strong

Supported, typed view commands without exposing private Qt slots.

Enumerator
RenameLayer	text is the new nonempty title.
SetLayerVisible	enabled is the desired local visibility.
SetLayerOpacity	number is finite and in [0,1].
MoveLayer	index is the absolute bottom-to-top canvas index, within its category group.
RemoveLayer	Detach through the existing native undo route.
SetLayerFilter	text is a validated vector attribute filter, empty clears it.
SelectLayerFeatures	featureIds replaces the vector selection; nonnegative IDs only.
ActivateResults	Select the attached source in its 1D/2D dimension.
SetResultsTime	index is a valid published period ordinal; async display can finish later.
SetResultsVariable	text is a stable variable key; channelId selects the 2D sublayer.

ViewEventKind

enum class OpenSWMM::Sdk::ViewEventKind : quint32

strong

Stable invalidation reasons, without geometry, selection or result arrays.

Enumerator
ModelGeometryChanged	Geometry/topology may have changed; rebuilds are broad.
ModelOptionsChanged	Accepted native option keys, or empty for broad invalidation.
ObjectRenamed	Exact native namespace and old/new name where available.
AttributeValuesChanged	Native/computed values need to be queried again.
AttributeSchemaChanged	Computed/native field descriptors need to be queried again.
ModelSelectionChanged	Canonical shared authored-model selection changed.
LayerAdded	A new runtime attachment is present in the layer snapshot.
LayerRemoved	Historical detach; the attachment no longer resolves.
LayerMetadataChanged	Name, visibility, opacity or layer discriminator changed.
LayerOrderChanged	Top-level or sublayer ordering changed.
LayerStyleChanged	Authored renderer/style configuration changed.
LayerSchemaChanged	Feature field descriptors changed.
LayerFeaturesChanged	Feature content/geometry changed; query the source again.
LayerSelectionChanged	A vector layer's selected feature identities changed.
LayerFilterChanged	The applied vector attribute filter changed.
LayerCrsChanged	Layer coordinate-reference metadata changed.
LayerSourceChanged	Layer source metadata/loading state changed.
ResultsSourceChanged	Attached reader/source epoch, availability or count changed.
ResultsActiveChanged	Session-wide active 1D/2D choice changed, including detachment.
ResultsVariableChanged	Selected result variable/channel changed.
ResultsTimeChanged	Published/displayed cursor changed, not merely a frame request.
ProjectUnitsChanged	Project display units changed; file-native units are separate.

Variable Documentation

GUI_EXTENSION_IID

constexpr auto OpenSWMM::Sdk::GUI_EXTENSION_IID

inlineconstexpr

Initial value:

=
    "io.opensimulator.openswmm.IGuiExtension/1.0"

Qt plugin root IID.

MODEL_EVENTS_IID

constexpr auto OpenSWMM::Sdk::MODEL_EVENTS_IID = OPENSWMM_MODEL_EVENTS_IID

inlineconstexpr

Discoverable interface IID, equivalent to OPENSWMM_MODEL_EVENTS_IID.

SDK_API_VERSION

constexpr auto OpenSWMM::Sdk::SDK_API_VERSION

inlineconstexpr

Initial value:

=
    "1.9"

Public interface major/minor, independently of GUI version.

SESSION_EVENTS_IID

constexpr auto OpenSWMM::Sdk::SESSION_EVENTS_IID

inlineconstexpr

Initial value:

=
    OPENSWMM_SESSION_EVENTS_IID

Public alias for the frozen discovery identity.