Add a UI feature to request a parameter value from the host

4 files changed, 113 insertions, 1 deletions

diff --git a/lv2/ui/lv2-ui.doap.ttl b/lv2/ui/lv2-ui.doap.ttl
index 7a956fc..ace0a0f 100644
--- a/lv2/ui/lv2-ui.doap.ttl
+++ b/lv2/ui/lv2-ui.doap.ttl
@@ -12,6 +12,15 @@
 	doap:developer <http://lv2plug.in/ns/meta#larsl> ;
 	doap:maintainer <http://drobilla.net/drobilla#me> ;
 	doap:release [
+		doap:revision "2.21" ;
+		doap:created "2020-03-17" ;
+		dcs:blame <http://drobilla.net/drobilla#me> ;
+		dcs:changeset [
+			dcs:item [
+				rdfs:label "Add ui:requestValue feature."
+			]
+		]
+	] , [
 		doap:revision "2.20" ;
 		doap:created "2015-07-25" ;
 		doap:file-release <http://lv2plug.in/spec/lv2-1.14.0.tar.bz2> ;
diff --git a/lv2/ui/manifest.ttl b/lv2/ui/manifest.ttl
index 282b929..72c9d07 100644
--- a/lv2/ui/manifest.ttl
+++ b/lv2/ui/manifest.ttl
@@ -4,6 +4,6 @@
 <http://lv2plug.in/ns/extensions/ui>
 	a lv2:Specification ;
 	lv2:minorVersion 2 ;
-	lv2:microVersion 20 ;
+	lv2:microVersion 21 ;
 	rdfs:seeAlso <ui.ttl> .
 
diff --git a/lv2/ui/ui.h b/lv2/ui/ui.h
index 8e67a36..aba3d5a 100644
--- a/lv2/ui/ui.h
+++ b/lv2/ui/ui.h
@@ -30,6 +30,7 @@
 #define LV2_UI_H
 
 #include "lv2/core/lv2.h"
+#include "lv2/urid/urid.h"
 
 #include <stdbool.h>
 #include <stdint.h>
@@ -59,6 +60,7 @@
 #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__requestValue     LV2_UI_PREFIX "requestValue"      ///< http://lv2plug.in/ns/extensions/ui#requestValue
 #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__resize           LV2_UI_PREFIX "resize"            ///< http://lv2plug.in/ns/extensions/ui#resize
@@ -344,6 +346,94 @@ typedef struct {
 } 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
diff --git a/lv2/ui/ui.ttl b/lv2/ui/ui.ttl
index ecebbf4..763e7b2 100644
--- a/lv2/ui/ui.ttl
+++ b/lv2/ui/ui.ttl
@@ -309,6 +309,19 @@ plugin UI.  This feature corresponds to the LV2UI_Touch struct, which
 should be passed with the URI LV2_UI__touch.</p>
 """ .
 
+ui:requestValue
+	a lv2:Feature ;
+	lv2:documentation """
+<p>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.</p>
+ """ .
+
 ui:idleInterface
 	a lv2:Feature ,
 		lv2:ExtensionData ;