This interface binds the UI Delegate of an Asset Management System into OpenAssetIO. More...

#include <UIDelegateInterface.hpp>

Public Types
using	Ptr = UIDelegateInterfacePtr

using	ConstPtr = UIDelegateInterfaceConstPtr

using	HostSessionPtr = openassetio::managerApi::HostSessionPtr

Public Member Functions
	UIDelegateInterface ()

virtual	~UIDelegateInterface ()=default
	Polymorphic destructor. More...

virtual InfoDictionary	info ()
	Returns other information that may be useful about this UI delegate. More...

UI Delegate Identification
These functions provide hosts with general identity information about the UI delegate itself. These may all be called before initialize has been called.
virtual Str	identifier () const =0
	Returns an identifier to uniquely identify a specific UI delegate. More...

virtual Str	displayName () const =0
	Returns a human-readable name to be used to reference this specific UI delegate in user-facing messaging. More...

Initialization
virtual InfoDictionary	settings (const HostSessionPtr &hostSession)
	Retrieve settings currently applied to this UI delegate. More...

virtual void	initialize (InfoDictionary uiDelegateSettings, const HostSessionPtr &hostSession)
	Prepares for interaction with a host. More...

virtual void	close (const HostSessionPtr &hostSession)
	Dispose of all active references to delegated UI. More...

Policy
virtual trait::TraitsDataPtr	uiPolicy (const trait::TraitSet &uiTraitSet, access::UIAccess uiAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession)
	Retrieve the policy for UI delegation with respect to different kinds of UI request. More...

UI population
virtual std::optional< UIDelegateStateInterfacePtr >	populateUI (const trait::TraitsDataConstPtr &uiTraitsData, access::UIAccess uiAccess, UIDelegateRequestPtr uiRequest, const ContextConstPtr &context, const HostSessionPtr &hostSession)
	Populate a UI element on behalf of the host. More...

Detailed Description

This interface binds the UI Delegate of an Asset Management System into OpenAssetIO.

It is not called directly by a host, but by the middleware that presents a more object-oriented model of this to the host - namely, the UIDelegate.

Logging and Error Handling

The supplied HostSession object provides access to a logger that allow messages and progress to be reported back to the user. All logging should go through these methods otherwise it may not be correctly presented to the user. The loose term "user" also covers developers, who may need to see log output for debugging and other purposes.

See also: HostSession.logger; LoggerInterface

Exceptions should be thrown to handle any in-flight errors that occur. The error should be mapped to a derived class of errors::OpenAssetIOException, and thrown. All exceptions of this kind will be correctly passed across the plug-in C boundary, and re-thrown. Other exceptions should not be used.

See also: errors

Hosts

Sometimes you may need to know more information about the API host. A Host object is available through the HostSession object passed to each method of this class. This provides a standardised interface that all API hosts guarantee to implement. This can be used to identify exactly which host you are being called for, and query various entity related specifics of the hosts data model.

See also: Host

Initialization

The constructor makes a new instance, but at this point it is not ready for use. Instances of this class should be lightweight to create, but don't have to be lightweight to initialize. The informational methods must be available pre-initialization, so that queries can be made relatively cheaply to provide users with a list of UI delegates and their settings. None of the UI-related methods will be called until after initialize has been called. The following methods must be callable prior to initialization:

See also: initialize

Note: OpenAssetIO makes use of shared pointers to facilitate object lifetime management across multiple languages. Instances passed into API methods via shared pointer may have their lifetimes extended beyond that of your code.

Member Typedef Documentation

using ConstPtr = UIDelegateInterfaceConstPtr

using HostSessionPtr = openassetio::managerApi::HostSessionPtr

using Ptr = UIDelegateInterfacePtr

Constructor & Destructor Documentation

UIDelegateInterface ( )

virtual ~UIDelegateInterface ( )

virtualdefault

Polymorphic destructor.

Member Function Documentation

virtual void close ( const HostSessionPtr & hostSession )

virtual

Dispose of all active references to delegated UI.

Called automatically on destruction of the hostApi::UIDelegate middleware in use by the host, but the host may call this independently in order to re-use this instance.

Warning: When this is called during destruction of a Python hostApi::UIDelegate instance, the Python GIL will be held for the duration of the call.

Any UI elements created by this UI delegate should be considered unsafe for access when this method is called. Any dangling state should be cleaned up to prevent memory leaks and/or potential access to destroyed objects.

The default implementation is a no-op.

Parameters

hostSession The API session.

virtual Str displayName ( ) const

pure virtual

Returns a human-readable name to be used to reference this specific UI delegate in user-facing messaging.

One instance of its use may be in a host's preferences UI or logging. For example:

"OpenAssetIO Test Manager UI"

Returns: UI delegate's display name.

virtual Str identifier ( ) const

pure virtual

Returns an identifier to uniquely identify a specific UI delegate.

Note: This must match the identifier of the corresponding Manager Plugin.

The UI delegate will typically be instantiated using settings from the same configuration file as is used for the manager plugin, and so expect the same identifier as the manager plugin.

See also: hostApi::UIDelegateFactory::defaultUIDelegateForInterface

Returns: Unique identifier of the UI delegate.

See also: ManagerInterface.identifier.

virtual InfoDictionary info ( )

virtual

Returns other information that may be useful about this UI delegate.

This can contain arbitrary key/value pairs. For example:

{ 'version' : '1.1v3', 'server' : 'assets.openassetio.org' }

There are certain optional keys that may be used by a host or the API:

constants::kInfoKey_SmallIcon (upto 32x32)
constants::kInfoKey_Icon (any size)

The constants::kInfoKey_IsPython constant is used to signal to the host that the UI delegate is written in Python, and therefore any UIDelegateRequest::nativeData and UIDelegateStateInterface::nativeData will/must be a CPython PyObject*. The Python base class implementation sets kInfoKey_IsPython: True.

Returns: Map of info string key to primitive value.

virtual void initialize	(	InfoDictionary	uiDelegateSettings,
		const HostSessionPtr &	hostSession
	)

virtual

Prepares for interaction with a host.

This method is passed a settings dictionary, that can be used to configure required local state to service requests. For example, determining the authoritative back-end service managing asset data. This is also a good opportunity to initialize any connections or fetch pre-requisite data. It is fine for this call to block for a period of time.

If an exception is raised by this call, it signifies to the host that a fatal error occurred, and this UI delegate is not available with the current settings.

If no exception is raised, it can be assumed that the UI delegate is ready. It is the implementations responsibility to deal with transient connection errors (if applicable) once initialized.

If called on an already initialized instance, re-initialize with any updated settings that are provided. If an error was raised previously, then initialization should be re-attempted.

Note: This will always be called prior to any UI related calls. An exception should be raised if this is not the case. However, the following functions may be called prior to initialization:

Parameters

uiDelegateSettings	Settings to apply to the UI delegate on initialisation.
hostSession	The API session.

virtual std::optional<UIDelegateStateInterfacePtr> populateUI	(	const trait::TraitsDataConstPtr &	uiTraitsData,
		access::UIAccess	uiAccess,
		UIDelegateRequestPtr	uiRequest,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession
	)

virtual

Populate a UI element on behalf of the host.

If the request is not supported, then an unset optional (None in Python) should be returned.

The nature of the UI to populate, how it should be populated, and what communication channels should be set up with the host, is determined by considering all the parameters.

In particular, the UI-specific traits determine the kind of UI that the host wants to present, and the access mode determines whether that UI is for a read or publishing operation. The documentation of the traits must be consulted to understand their meaning.

Once the kind of UI is determined, the data used to initialise it (e.g. the target entities) can be extracted from the request object.

The request object may also provide a host or UI framework-specific native data object that should be used as part of, or to contain, any newly constructed UI. The UI-specific traits, combined with the host's own documentation, determine how such native data should be used.

Finally, the request object may contain a callback for notifying the host of updates to the state of the UI (e.g. through user interaction).

The initial returned state from this method should contain the initially selected/populated entities and/or trait data, if any.

The returned state may also contain a native data object - again, how this should be used is determined by the UI traits and host-specific documentation.

Finally, the returned state may contain a callback allowing the host to update the initial request with changes, e.g. the target selection of entities.

Parameters

uiTraitsData	UI-specific traits (and their associated properties, if any) determining the kind of UI to create.
uiAccess	The host's intended usage of the output from the UI element.
uiRequest	The request object containing UI-specific parameters, as well as a callback hook for communicating asynchronous UI state changes.
context	The calling context.
hostSession	The API session.

Returns: Empty optional if this request is not supported (None in Python), otherwise the initial state of the UI.

virtual InfoDictionary settings ( const HostSessionPtr & hostSession )

virtual

Retrieve settings currently applied to this UI delegate.

Parameters

hostSession The API session.

Returns: Any settings relevant to the function of the UI delegate with their current values (or their defaults if initialize has not yet been called).

The default implementation returns an empty dictionary.

virtual trait::TraitsDataPtr uiPolicy	(	const trait::TraitSet &	uiTraitSet,
		access::UIAccess	uiAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession
	)

virtual

Retrieve the policy for UI delegation with respect to different kinds of UI request.

The set of UI-specific traits indicates the kind of UI element requested, and the access mode determines if the request is for a read or publishing operation.

A return value of an empty TraitsData indicates to the host that UI delegation requests of this kind are not supported, and it should not attempt populateUI calls with these arguments.

This method is usually called early on by a host to determine whether to attempt to present OpenAssetIO related UI elements to the user, and to retrieve other sundry UI related metadata that is not specific to an individual request.

Note that even if this method returns positively, populateUI may refuse to provide a UI element, based on the specific request.

Consult the relevant traits library to discover the available UI policy-specific traits. For example, the OpenAssetIO-MediaCreation project provides traits related to computer graphics and media production. In particular, imbuing the return value with the Managed UI policy trait from the MediaCreation library indicates to the host that UI delegation requests are likely to succeed.

As well as determining whether a request is likely to be supported, additional metadata that may be used by the host can be populated in the returned TraitsData. For example, this could include a "display name" that the host may use in the titles of tabs or windows that contain the delegated UI element(s).

This method is opt-in - hosts may call populateUI without first consulting this method. It is therefore important that correct behaviour is not reliant on this method being called. Any additional metadata offered in the returned policy may be useful in optimising the user experience, but cannot be considered a requirement.

Parameters

uiTraitSet	The set of UI-specific traits determining the kind of UI element the host may wish to delegate.
uiAccess	Type of operation that the delegated UI will be used for.
context	The calling context.
hostSession	The API session.

Returns: Policy-specific traits with their associated properties filled, if applicable. The default implementation returns an empty response, indicating UI delegation is not supported.

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

/src/src/openassetio-ui/include/openassetio/ui/managerApi/UIDelegateInterface.hpp

Public Types

Public Member Functions

Detailed Description

Logging and Error Handling

Hosts

Initialization

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation