commit 18eb8eda8c406f8f9d8ad1c25c37588f68d0408b
parent 3fa74825770a9c500f9d07ad7cb2269fc1b73518
Author: falkTX <falktx@falktx.com>
Date: Mon, 9 Mar 2020 13:32:32 +0000
Update lv2 ui.h header
Signed-off-by: falkTX <falktx@falktx.com>
Diffstat:
| M | distrho/src/lv2/ui.h | | | 216 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------- |
1 file changed, 162 insertions(+), 54 deletions(-)
diff --git a/distrho/src/lv2/ui.h b/distrho/src/lv2/ui.h
@@ -1,6 +1,6 @@
/*
LV2 UI Extension
- Copyright 2009-2014 David Robillard <d@drobilla.net>
+ Copyright 2009-2016 David Robillard <d@drobilla.net>
Copyright 2006-2011 Lars Luthman <lars.luthman@gmail.com>
Permission to use, copy, modify, and/or distribute this software for any
@@ -17,9 +17,12 @@
*/
/**
- @file ui.h User Interface API.
+ @defgroup ui User Interfaces
- For high-level documentation, see <http://lv2plug.in/ns/extensions/ui>.
+ User interfaces of any type for plugins,
+ <http://lv2plug.in/ns/extensions/ui> for details.
+
+ @{
*/
#ifndef LV2_UI_H
@@ -28,39 +31,48 @@
#include <stdint.h>
#include "lv2.h"
-
-#define LV2_UI_URI "http://lv2plug.in/ns/extensions/ui"
-#define LV2_UI_PREFIX LV2_UI_URI "#"
-
-#define LV2_UI__CocoaUI LV2_UI_PREFIX "CocoaUI"
-#define LV2_UI__Gtk3UI LV2_UI_PREFIX "Gtk3UI"
-#define LV2_UI__GtkUI LV2_UI_PREFIX "GtkUI"
-#define LV2_UI__PortNotification LV2_UI_PREFIX "PortNotification"
-#define LV2_UI__Qt4UI LV2_UI_PREFIX "Qt4UI"
-#define LV2_UI__UI LV2_UI_PREFIX "UI"
-#define LV2_UI__WindowsUI LV2_UI_PREFIX "WindowsUI"
-#define LV2_UI__X11UI LV2_UI_PREFIX "X11UI"
-#define LV2_UI__binary LV2_UI_PREFIX "binary"
-#define LV2_UI__fixedSize LV2_UI_PREFIX "fixedSize"
-#define LV2_UI__idleInterface LV2_UI_PREFIX "idleInterface"
-#define LV2_UI__noUserResize LV2_UI_PREFIX "noUserResize"
-#define LV2_UI__notifyType LV2_UI_PREFIX "notifyType"
-#define LV2_UI__parent LV2_UI_PREFIX "parent"
-#define LV2_UI__plugin LV2_UI_PREFIX "plugin"
-#define LV2_UI__portIndex LV2_UI_PREFIX "portIndex"
-#define LV2_UI__portMap LV2_UI_PREFIX "portMap"
-#define LV2_UI__portNotification LV2_UI_PREFIX "portNotification"
-#define LV2_UI__portSubscribe LV2_UI_PREFIX "portSubscribe"
-#define LV2_UI__resize LV2_UI_PREFIX "resize"
-#define LV2_UI__scaleFactor LV2_UI_PREFIX "scaleFactor"
-#define LV2_UI__showInterface LV2_UI_PREFIX "showInterface"
-#define LV2_UI__touch LV2_UI_PREFIX "touch"
-#define LV2_UI__ui LV2_UI_PREFIX "ui"
-#define LV2_UI__updateRate LV2_UI_PREFIX "updateRate"
-#define LV2_UI__windowTitle LV2_UI_PREFIX "windowTitle"
+#include "urid.h"
+
+#define LV2_UI_URI "http://lv2plug.in/ns/extensions/ui" ///< http://lv2plug.in/ns/extensions/ui
+#define LV2_UI_PREFIX LV2_UI_URI "#" ///< http://lv2plug.in/ns/extensions/ui#
+
+#define LV2_UI__CocoaUI LV2_UI_PREFIX "CocoaUI" ///< http://lv2plug.in/ns/extensions/ui#CocoaUI
+#define LV2_UI__Gtk3UI LV2_UI_PREFIX "Gtk3UI" ///< http://lv2plug.in/ns/extensions/ui#Gtk3UI
+#define LV2_UI__GtkUI LV2_UI_PREFIX "GtkUI" ///< http://lv2plug.in/ns/extensions/ui#GtkUI
+#define LV2_UI__PortNotification LV2_UI_PREFIX "PortNotification" ///< http://lv2plug.in/ns/extensions/ui#PortNotification
+#define LV2_UI__PortProtocol LV2_UI_PREFIX "PortProtocol" ///< http://lv2plug.in/ns/extensions/ui#PortProtocol
+#define LV2_UI__Qt4UI LV2_UI_PREFIX "Qt4UI" ///< http://lv2plug.in/ns/extensions/ui#Qt4UI
+#define LV2_UI__Qt5UI LV2_UI_PREFIX "Qt5UI" ///< http://lv2plug.in/ns/extensions/ui#Qt5UI
+#define LV2_UI__UI LV2_UI_PREFIX "UI" ///< http://lv2plug.in/ns/extensions/ui#UI
+#define LV2_UI__WindowsUI LV2_UI_PREFIX "WindowsUI" ///< http://lv2plug.in/ns/extensions/ui#WindowsUI
+#define LV2_UI__X11UI LV2_UI_PREFIX "X11UI" ///< http://lv2plug.in/ns/extensions/ui#X11UI
+#define LV2_UI__backgroundColor LV2_UI_PREFIX "backgroundColor" ///< http://lv2plug.in/ns/extensions/ui#backgroundColor
+#define LV2_UI__binary LV2_UI_PREFIX "binary" ///< http://lv2plug.in/ns/extensions/ui#binary
+#define LV2_UI__fixedSize LV2_UI_PREFIX "fixedSize" ///< http://lv2plug.in/ns/extensions/ui#fixedSize
+#define LV2_UI__foregroundColor LV2_UI_PREFIX "foregroundColor" ///< http://lv2plug.in/ns/extensions/ui#foregroundColor
+#define LV2_UI__idleInterface LV2_UI_PREFIX "idleInterface" ///< http://lv2plug.in/ns/extensions/ui#idleInterface
+#define LV2_UI__noUserResize LV2_UI_PREFIX "noUserResize" ///< http://lv2plug.in/ns/extensions/ui#noUserResize
+#define LV2_UI__notifyType LV2_UI_PREFIX "notifyType" ///< http://lv2plug.in/ns/extensions/ui#notifyType
+#define LV2_UI__parent LV2_UI_PREFIX "parent" ///< http://lv2plug.in/ns/extensions/ui#parent
+#define LV2_UI__plugin LV2_UI_PREFIX "plugin" ///< http://lv2plug.in/ns/extensions/ui#plugin
+#define LV2_UI__portIndex LV2_UI_PREFIX "portIndex" ///< http://lv2plug.in/ns/extensions/ui#portIndex
+#define LV2_UI__portMap LV2_UI_PREFIX "portMap" ///< http://lv2plug.in/ns/extensions/ui#portMap
+#define LV2_UI__portNotification LV2_UI_PREFIX "portNotification" ///< http://lv2plug.in/ns/extensions/ui#portNotification
+#define LV2_UI__portSubscribe LV2_UI_PREFIX "portSubscribe" ///< http://lv2plug.in/ns/extensions/ui#portSubscribe
+#define LV2_UI__protocol LV2_UI_PREFIX "protocol" ///< http://lv2plug.in/ns/extensions/ui#protocol
+#define LV2_UI__floatProtocol LV2_UI_PREFIX "floatProtocol" ///< http://lv2plug.in/ns/extensions/ui#floatProtocol
+#define LV2_UI__peakProtocol LV2_UI_PREFIX "peakProtocol" ///< http://lv2plug.in/ns/extensions/ui#peakProtocol
+#define LV2_UI__requestValue LV2_UI_PREFIX "requestValue" ///< http://lv2plug.in/ns/extensions/ui#requestValue
+#define LV2_UI__resize LV2_UI_PREFIX "resize" ///< http://lv2plug.in/ns/extensions/ui#resize
+#define LV2_UI__scaleFactor LV2_UI_PREFIX "scaleFactor" ///< http://lv2plug.in/ns/extensions/ui#scaleFactor
+#define LV2_UI__showInterface LV2_UI_PREFIX "showInterface" ///< http://lv2plug.in/ns/extensions/ui#showInterface
+#define LV2_UI__touch LV2_UI_PREFIX "touch" ///< http://lv2plug.in/ns/extensions/ui#touch
+#define LV2_UI__ui LV2_UI_PREFIX "ui" ///< http://lv2plug.in/ns/extensions/ui#ui
+#define LV2_UI__updateRate LV2_UI_PREFIX "updateRate" ///< http://lv2plug.in/ns/extensions/ui#updateRate
+#define LV2_UI__windowTitle LV2_UI_PREFIX "windowTitle" ///< http://lv2plug.in/ns/extensions/ui#windowTitle
/**
- The index returned by LV2_UI_Port_Port::port_index() for unknown ports.
+ The index returned by LV2UI_Port_Map::port_index() for unknown ports.
*/
#define LV2UI_INVALID_PORT_INDEX ((uint32_t)-1)
@@ -99,18 +111,21 @@ typedef void* LV2UI_Feature_Handle;
/**
A host-provided function that sends data to a plugin's input ports.
- The @p buffer parameter must point to a block of data, @p buffer_size bytes
- large. The format of this data and how the host should use it is defined by
- the @p port_protocol. This buffer is owned by the UI and is only valid for
- the duration of this call.
+ @param controller The opaque controller pointer passed to
+ LV2UI_Descriptor::instantiate().
+
+ @param port_index Index of the port to update.
- The @p port_protocol parameter should either be 0 or the URID for a
- ui:PortProtocol. If it is 0, the protocol is implicitly ui:floatProtocol,
- the port MUST be an lv2:ControlPort input, @p buffer MUST point to a single
- float value, and @p buffer_size MUST be sizeof(float).
+ @param buffer Buffer containing `buffer_size` bytes of data.
- The UI SHOULD NOT use a protocol not supported by the host, but the host
- MUST gracefully ignore any protocol it does not understand.
+ @param buffer_size Size of `buffer` in bytes.
+
+ @param port_protocol Either 0 or the URID for a ui:PortProtocol. If 0, the
+ protocol is implicitly ui:floatProtocol, the port MUST be an lv2:ControlPort
+ input, `buffer` MUST point to a single float value, and `buffer_size` MUST
+ be sizeof(float). The UI SHOULD NOT use a protocol not supported by the
+ host, but the host MUST gracefully ignore any protocol it does not
+ understand.
*/
typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
uint32_t port_index,
@@ -144,7 +159,7 @@ typedef struct _LV2UI_Descriptor {
@param write_function A function that the UI can use to send data to the
plugin's input ports.
- @param controller A handle for the plugin instance to be passed as the
+ @param controller A handle for the UI instance to be passed as the
first parameter of UI methods.
@param widget (output) widget pointer. The UI points this at its main
@@ -174,18 +189,18 @@ typedef struct _LV2UI_Descriptor {
/**
Tell the UI that something interesting has happened at a plugin port.
- What is "interesting" and how it is written to @p buffer is defined by
- @p format, which has the same meaning as in LV2UI_Write_Function().
+ What is "interesting" and how it is written to `buffer` is defined by
+ `format`, which has the same meaning as in LV2UI_Write_Function().
Format 0 is a special case for lv2:ControlPort, where this function
should be called when the port value changes (but not necessarily for
- every change), @p buffer_size must be sizeof(float), and @p buffer
+ every change), `buffer_size` must be sizeof(float), and `buffer`
points to a single IEEE-754 float.
By default, the host should only call this function for lv2:ControlPort
inputs. However, the UI can request updates for other ports statically
with ui:portNotification or dynamicaly with ui:portSubscribe.
- The UI MUST NOT retain any reference to @p buffer after this function
+ The UI MUST NOT retain any reference to `buffer` after this function
returns, it is only valid for the duration of the call.
This member may be NULL if the UI is not interested in any port events.
@@ -202,7 +217,7 @@ typedef struct _LV2UI_Descriptor {
This member may be set to NULL if the UI is not interested in supporting
any extensions. This is similar to LV2_Descriptor::extension_data().
-
+
*/
const void* (*extension_data)(const char* uri);
} LV2UI_Descriptor;
@@ -227,7 +242,8 @@ typedef struct _LV2UI_Resize {
host about the size of the UI.
When provided by the UI, the host may call this function to notify the
- UI that it should change its size accordingly.
+ UI that it should change its size accordingly. In this case, the host
+ must pass the LV2UI_Handle to provide access to the UI instance.
@return 0 on success.
*/
@@ -248,7 +264,7 @@ typedef struct _LV2UI_Port_Map {
LV2UI_Feature_Handle handle;
/**
- Get the index for the port with the given @p symbol.
+ Get the index for the port with the given `symbol`.
@return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
port is found.
@@ -272,7 +288,7 @@ typedef struct _LV2UI_Port_Subscribe {
This means that the host will call the UI's port_event() function when
the port value changes (as defined by protocol).
- Calling this function with the same @p port_index and @p port_protocol
+ Calling this function with the same `port_index` and `port_protocol`
as an already active subscription has no effect.
@param handle The handle field of this struct.
@@ -292,7 +308,7 @@ typedef struct _LV2UI_Port_Subscribe {
This means that the host will cease calling calling port_event() when
the port value changes.
- Calling this function with a @p port_index and @p port_protocol that
+ Calling this function with a `port_index` and `port_protocol` that
does not refer to an active port subscription has no effect.
@param handle The handle field of this struct.
@@ -333,6 +349,94 @@ typedef struct _LV2UI_Touch {
} LV2UI_Touch;
/**
+ A status code for LV2UI_Request_Value::request.
+*/
+typedef enum {
+ /**
+ Completed successfully.
+
+ The host will set the parameter later if the user choses a new value.
+ */
+ LV2UI_REQUEST_VALUE_SUCCESS,
+
+ /**
+ Parameter already being requested.
+
+ The host is already requesting a parameter from the user (for example, a
+ dialog is visible), or the UI is otherwise busy and can not make this
+ request.
+ */
+ LV2UI_REQUEST_VALUE_BUSY,
+
+ /**
+ Unknown parameter.
+
+ The host is not aware of this parameter, and is not able to set a new
+ value for it.
+ */
+ LV2UI_REQUEST_VALUE_ERR_UNKNOWN,
+
+ /**
+ Unsupported parameter.
+
+ The host knows about this parameter, but does not support requesting a
+ new value for it from the user. This is likely because the host does
+ not have UI support for choosing a value with the appropriate type.
+ */
+ LV2UI_REQUEST_VALUE_ERR_UNSUPPORTED
+} LV2UI_Request_Value_Status;
+
+/**
+ A feature to request a new parameter value from the host.
+*/
+typedef struct {
+ /**
+ Pointer to opaque data which must be passed to request().
+ */
+ LV2UI_Feature_Handle handle;
+
+ /**
+ Request a value for a parameter from the host.
+
+ This is mainly used by UIs to request values for complex parameters that
+ don't change often, such as file paths, but it may be used to request
+ any parameter value.
+
+ This function returns immediately, and the return value indicates
+ whether the host can fulfill the request. The host may notify the
+ plugin about the new parameter value, for example when a file is
+ selected by the user, via the usual mechanism. Typically, the host will
+ send a message to the plugin that sets the new parameter value, and the
+ plugin will notify the UI via a message as usual for any other parameter
+ change.
+
+ To provide an appropriate UI, the host can determine details about the
+ parameter from the plugin data as usual. The additional parameters of
+ this function provide support for more advanced use cases, but in the
+ simple common case, the plugin will simply pass the key of the desired
+ parameter and zero for everything else.
+
+ @param handle The handle field of this struct.
+
+ @param key The URID of the parameter.
+
+ @param type The optional type of the value to request. This can be used
+ to request a specific value type for parameters that support several.
+ If non-zero, it must be the URID of an instance of rdfs:Class or
+ rdfs:Datatype.
+
+ @param features Additional features for this request, or NULL.
+
+ @return A status code which is 0 on success.
+ */
+ LV2UI_Request_Value_Status (*request)(LV2UI_Feature_Handle handle,
+ LV2_URID key,
+ LV2_URID type,
+ const LV2_Feature* const* features);
+
+} LV2UI_Request_Value;
+
+/**
UI Idle Interface (LV2_UI__idleInterface)
UIs can provide this interface to have an idle() callback called by the host
@@ -429,3 +533,7 @@ typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index);
#endif
#endif /* LV2_UI_H */
+
+/**
+ @}
+*/
