UI Instances

typedef struct SuilInstanceImpl SuilInstance

An instance of an LV2 plugin UI.

typedef void *SuilHandle

Opaque pointer to a UI handle.

typedef void *SuilWidget

Opaque pointer to a UI widget.

unsigned suil_ui_supported(const char *host_type_uri, const char *ui_type_uri)

Check if suil can wrap a UI type.

Parameters

  • host_type_uri – The URI of the desired widget type of the host, corresponding to the type_uri parameter of suil_instance_new().

  • ui_type_uri – The URI of the UI widget type.

Returns

0 if wrapping is unsupported, otherwise the quality of the wrapping where 1 is the highest quality (direct native embedding with no wrapping) and increasing values are of a progressively lower quality and/or stability.

SuilInstance *suil_instance_new(SuilHost *host, SuilController controller, const char *container_type_uri, const char *plugin_uri, const char *ui_uri, const char *ui_type_uri, const char *ui_bundle_path, const char *ui_binary_path, const LV2_Feature *const *features)

Instantiate a UI for an LV2 plugin.

This funcion may load a suil module to adapt the UI to the desired toolkit. Suil is configured at compile time to load modules from the appropriate place, but this can be changed at run-time via the environment variable SUIL_MODULE_DIR. This makes it possible to bundle suil with an application.

Note that some situations (Gtk in Qt, Windows in Gtk) require a parent container to be passed as a feature with URI LV2_UI__parent (http://lv2plug.in/ns/extensions/ui#ui) in order to work correctly. The data must point to a single child container of the host widget set.

Parameters

  • host – Host descriptor.

  • controller – Opaque host controller pointer.

  • container_type_uri – URI of the desired host container widget type.

  • plugin_uri – URI of the plugin to instantiate this UI for.

  • ui_uri – URI of the specifically desired UI.

  • ui_type_uri – URI of the actual UI widget type.

  • ui_bundle_path – Path of the UI bundle.

  • ui_binary_path – Path of the UI binary.

  • features – NULL-terminated array of supported features, or NULL.

Returns

A new UI instance, or NULL if instantiation failed.

void suil_instance_free(SuilInstance *instance)

Free a plugin UI instance.

The caller must ensure all references to the UI have been dropped before calling this function (e.g. it has been removed from its parent).

SuilHandle suil_instance_get_handle(SuilInstance *instance)

Get the handle for a UI instance.

Returns the handle to the UI instance. The returned handle has opaque type to insulate the Suil API from LV2 extensions, but in practice it is currently of type LV2UI_Handle. This should not normally be needed.

The returned handle is shared and must not be deleted.

SuilWidget suil_instance_get_widget(SuilInstance *instance)

Get the widget for a UI instance.

Returns an opaque pointer to a widget, the type of which matches the container_type_uri parameter of suil_instance_new(). Note this may be a wrapper widget created by Suil, and not necessarily the widget directly implemented by the UI.

void suil_instance_port_event(SuilInstance *instance, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer)

Notify the UI about a change in a plugin port.

This function can be used to notify the UI about any port change, but in the simplest case is used to set the value of lv2:ControlPort ports. For simplicity, this is a special case where format is 0, buffer_size is 4, and buffer should point to a single float.

The buffer must be valid only for the duration of this call, the UI must not keep a reference to it.

Parameters

  • instance – UI instance.

  • port_index – Index of the port which has changed.

  • buffer_size – Size of buffer in bytes.

  • format – Format of buffer (mapped URI, or 0 for float).

  • buffer – Change data, e.g. the new port value.

const void *suil_instance_extension_data(SuilInstance *instance, const char *uri)

Return a data structure defined by some LV2 extension URI.