LV2 UI

A UI where the LV2_Widget is a pointer to a NSView, the basic view type for the Cocoa API (formerly OpenStep). This is the native UI type on Mac OS X.

A UI where the LV2_Widget is a pointer to a Gtk+ 3.0 compatible GtkWidget, and the host guarantees that the Gtk+ library has been initialised and the Glib main loop is running before the UI is instantiated. Note that this UI type is not suitable for binary distribution since multiple versions of Gtk can not be used in the same process.

A UI where the LV2_Widget is a pointer to a Gtk+ 2.0 compatible GtkWidget, and the host guarantees that the Gtk+ library has been initialised and the Glib main loop is running before the UI is instantiated. Note that this UI type is not suitable for binary distribution since multiple versions of Gtk can not be used in the same process.

A port notification. This describes which ports the host must send notifications to the UI about. The port can be specific by index, using the portIndex property, or symbol, using the lv2:symbol property. Since port indices are not guaranteed to be stable between different revisions (or even instantiations) of a plugin, symbol is recommended, and index may only be used by UIs shipped in the same bundle as the plugin.

A PortNotification MUST have either a portIndex or a lv2:symbol to indicate which port it refers to.

A PortProtocol defines a method to communicate port data between a UI and plugin.

Any PortProtocol MUST define:

Any PortProtocol for an output port MUST define:

Any PortProtocol for an input port MUST define:

For an example, see floatProtocol or peakProtocol.

PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and lv2:requiredFeature to specify which PortProtocols they want to use.

A UI where the LV2_Widget is a pointer to a Qt4 compatible QWidget, and the host guarantees that the Qt4 library has been initialised and the Qt4 main loop is running before the UI is instantiated. Note that this UI type is not suitable for binary distribution since multiple versions of Qt can not be used in the same process.

A UI where the LV2_Widget is a pointer to a Qt5 compatible QWidget, and the host guarantees that the Qt5 library has been initialised and the Qt5 main loop is running before the UI is instantiated. Note that this UI type is not suitable for binary distribution since multiple versions of Qt can not be used in the same process.

A UI for an LV2 plugin

A UI where the LV2_Widget is a Windows HWND window ID. Note this is actually an unsigned 32-bit integer, i.e. the LV2_Widget is not a pointer to a HWND but should be interpreted as an HWND itself. This is the native UI type on Microsoft Windows.

A UI where the LV2_Widget is an X11 window ID. Note this is actually an integer, i.e. the LV2_Widget is not a pointer to an X11 window ID, but should be itself taken as an integer value. This is the native UI type on most POSIX systems.

The background color of the host's UI. The host can pass this as an option so that UIs can integrate nicely with the host window around it.

Hosts should pass this as an option to UIs with an integer RGBA32 color value. If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but the UI must check the value type and not assume this, to allow for other types of color in the future.

The shared library a UI resides in. This property is redundant, new UIs SHOULD use lv2:binary, however hosts MUST still support ui:binary at this time.

The foreground color of the host's UI. The host can pass this as an option so that UIs can integrate nicely with the host window around it.

Hosts should pass this as an option to UIs with an integer RGBA32 color value. If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but the UI must check the value type and not assume this, to allow for other types of color in the future.

Indicates a particular type that the UI should be notified of. In the case of ports where several types of data can be present (e.g. event ports), this can be used to indicate that only a particular type of data should cause notification. This is useful where port traffic is very dense, but only a certain small number of events are actually of interest to the UI.

The plugin a portNotification applies to.

The index of the port a portNotification applies to.

Indicates that a UI should receive notification (via LV2UI_Descriptor::port_event()) when a particular port's value changes.

For example:

eg:ui
    a ui:GtkUI ;
    ui:portNotification [
        ui:plugin eg:plugin ;
        lv2:symbol "gain" ;
        ui:protocol ui:floatProtocol
    ] .

The protocol to be used for this notification.

HiDPI (High Dots Per Inch) displays have a high resolution on a relatively small form factor. Many systems use a scale factor to compensate for this, so for example, a scale factor of 2 means things are drawn twice as large as normal.

Hosts can pass this as an option to UIs to communicate this information, so that the UI can draw at an appropriate scale.

Relates a plugin to a UI that applies to it.

The target rate, in Hz, to send updates to the UI.

The title for the window shown by LV2UI_Show_Interface.

If a UI requires this feature it indicates the same thing as noUserResize, and additionally it means that the UI will not resize the main widget on its own - it will always remain the same size (e.g. a pixmap based GUI). This feature may not make sense for all UI types. The data pointer for the LV2_Feature for this feature should always be set to NULL.

A protocol for transferring single floating point values. The rules for this protocol are:

A feature that provides a callback for the host to call rapidly to drive the UI. To support this feature, the UI should list it as a lv2:optionalFeature or lv2:requiredFeature in its data, and also as lv2:extensionData. When the UI's extension_data() is called with this URI (LV2_UI__idleInterface), it should return a pointer to an LV2UI_Idle_Interface.

To indicate support, the host should pass a feature to instantiate() with this URI, with NULL for data.

DEPRECATED

This feature was intended to support UIs that link against toolkit libraries which may not be unloaded during the lifetime of the host. This is better achieved by using the appropriate flags when linking the UI, e.g. gcc -Wl,-z,nodelete.

If a UI requires this feature it indicates that it does not make sense to let the user resize the main widget, and the host should prevent that. This feature may not make sense for all UI types. The data pointer for the LV2_Feature for this feature should always be set to NULL.

The parent for the UI.

This feature can be used to pass a parent (e.g. a widget, container, canvas, etc.) the UI should be a child of. The format of data pointer of this feature is determined by the UI type, and is generally the same type as the LV2_Widget the UI would return (e.g. for a GtkUI the data would be a pointer to a GtkWidget which is a GtkContainer). This is particularly useful for cross-toolkit embedding, where the parent often must be known at construction time for embedding to work correctly. UIs should not require this feature unless it is absolutely necessary for them to work at all.

This port protocol defines a way for the host to send continuous peak measurements of the audio signal at a certain port to the UI. The intended use is visualisation, e.g. an animated meter widget that shows the level of the audio input or output.

A contiguous sequence of audio samples for which a peak value has been computed is called a measurement period.

The rules for this protocol are:

A feature for accessing the index of a port by symbol. This makes it possible to implement and distribute UIs separately from the plugin binaries they control. This feature corresponds to the LV2UI_Port_Index struct, which should be passed with the URI LV2_UI__portIndex.

A feature for dynamically subscribing to updates from a port. This makes it possible for a UI to explicitly request a particular style of update from a port at run-time, in a more flexible and powerful way than listing subscriptions statically allows. This feature corresponds to the LV2UI_Port_Subscribe struct, which should be passed with the URI LV2_UI__portSubscribe.

A feature to request a parameter value from the user via the host. This allows a plugin UI to request a new parameter value using the host's UI, for example by showing a dialog or integrating with the host's built-in content browser. This should only be used for complex parameter types where the plugin UI is not capable of showing the expected native platform or host interface to choose a value, such as file path parameters. This feature corresponds to the LV2UI_Request_Value struct, which should be passed with the URI LV2_UI__requestValue.

A feature that allows the UI to notify the host about its current size, or request a size change. This feature corresponds to the LV2UI_Resize struct, which should be passed with the URI LV2_UI__resize. This struct may also be provided by the UI as extension data using the same URI, in which case it is used by the host to request that the UI change its size.

An interface for showing and hiding a window for a UI. This allows UIs to gracefully degrade to separate windows when the host is unable to embed the UI widget for whatever reason. When the UI's extension_data() is called with this URI (LV2_UI__showInterface), it should return a pointer to an LV2UI_Show_Interface.

A feature to notify the host that the user has grabbed a particular port control. This is useful for automation, so the host can allow the user to take control of a port, even if that port would otherwise be automated (much like grabbing a physical morotised fader). It can also be used for MIDI learn or in any other situation where the host needs to do something with a particular control and it would be convenient for the user to select it directly from the plugin UI. This feature corresponds to the LV2UI_Touch struct, which should be passed with the URI LV2_UI__touch.