From c11adc705f7028eeff2e8fcd6cbf6b9d5ee97206 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Tue, 20 Nov 2018 23:26:49 +0100
Subject: Add a UI feature to request a parameter value from the host

---
 lv2/ui/ui.h | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

(limited to 'lv2/ui/ui.h')

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
@@ -343,6 +345,94 @@ typedef struct {
 	              bool                 grabbed);
 } 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)
 
-- 
cgit v1.2.1