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/lv2-ui.doap.ttl | 9 +++++
lv2/ui/manifest.ttl | 2 +-
lv2/ui/ui.h | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++
lv2/ui/ui.ttl | 13 ++++++++
4 files changed, 113 insertions(+), 1 deletion(-)
(limited to 'lv2/ui')
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
@@ -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)
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 ;
--
cgit v1.2.1