LV2 UI interface cleanups.

Documentation reorganization.
Updated LV2 spec (1.0beta5).


git-svn-id: http://svn.drobilla.net/lad/slv2@775 a436a847-0d15-0410-975c-d299462d15a1

13 files changed, 40 insertions, 124 deletions

diff --git a/slv2/Makefile.am b/slv2/Makefile.am
index a3f9a0d..89d0cd0 100644
--- a/slv2/Makefile.am
+++ b/slv2/Makefile.am
@@ -1,7 +1,6 @@
 slv2includedir = $(includedir)/slv2
 
 slv2include_HEADERS = \
-	ui.h \
 	lv2.h \
 	lv2_gui.h \
 	plugin.h \
diff --git a/slv2/lv2.h b/slv2/lv2.h
index 953c459..14c25ca 100644
--- a/slv2/lv2.h
+++ b/slv2/lv2.h
@@ -1,5 +1,5 @@
 /* LV2 - LADSPA (Linux Audio Developer's Simple Plugin API) Version 2.0
- * *** PROVISIONAL ***
+ * *** PROVISIONAL Revision 1.0beta5 (2007-09-23) ***
  *
  * Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
  *                         Stefan Westerfeld.
diff --git a/slv2/plugin.h b/slv2/plugin.h
index 97d830f..fa82bae 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -241,8 +241,7 @@ bool
 slv2_plugin_has_latency(SLV2Plugin p);
 
 
-/** Return the index of the plugin's latency port, or the empty string if the
- * plugin has no latency.
+/** Return the index of the plugin's latency port.
  *
  * It is a fatal error to call this on a plugin without checking if the port
  * exists by first calling slv2_plugin_has_latency.
@@ -345,14 +344,14 @@ slv2_plugin_get_port_by_symbol(SLV2Plugin  plugin,
 /** Get a list of all UIs available for this plugin.
  *
  * Note this returns the URI of the UI, and not the path/URI to its shared
- * library, use slv2_plugin_ui_get_library_uri with the values returned
+ * library, use slv2_ui_get_library_uri with the values returned
  * here for that.
  *
  * \param plugin The plugin to get the UIs for. 
  *
  * Time = Query
  */
-SLV2PluginUIs
+SLV2UIs
 slv2_plugin_get_uis(SLV2Plugin plugin);
 
 
diff --git a/slv2/pluginclasses.h b/slv2/pluginclasses.h
index b407ede..e95710b 100644
--- a/slv2/pluginclasses.h
+++ b/slv2/pluginclasses.h
@@ -25,8 +25,7 @@
 extern "C" {
 #endif
 
-/** \defgroup plugin_classes Plugin classes
- * 
+/** \addtogroup collections
  * @{
  */
 
diff --git a/slv2/plugins.h b/slv2/plugins.h
index 5663d6a..1ca4cc7 100644
--- a/slv2/plugins.h
+++ b/slv2/plugins.h
@@ -26,12 +26,7 @@
 extern "C" {
 #endif
 
-/** \defgroup plugins Collections of plugins
- * 
- * These functions work with lists of plugins which come from an
- * SLV2World.  These lists contain only a weak reference to an LV2 plugin
- * in the Model.
- *
+/** \addtogroup collections
  * @{
  */
 
diff --git a/slv2/pluginui.h b/slv2/pluginui.h
index 7297431..cd5fd3a 100644
--- a/slv2/pluginui.h
+++ b/slv2/pluginui.h
@@ -23,8 +23,7 @@
 extern "C" {
 #endif
 
-/** \defgroup ui Plugin user interfaces
- *
+/** \addtogroup data
  * @{
  */
 
@@ -36,27 +35,28 @@ extern "C" {
  * Time = O(1)
  */
 const char*
-slv2_plugin_ui_get_uri(SLV2PluginUI ui);
+slv2_ui_get_uri(SLV2UI ui);
 
 
-/** Get the URI of the a Plugin UI.
+/** Get the types (URIs of RDF classes) of a Plugin UI.
  *
  * \param ui The Plugin UI
  *
  * Time = O(1)
  */
 SLV2Values
-slv2_plugin_ui_get_types(SLV2PluginUI ui);
+slv2_ui_get_types(SLV2UI ui);
 
 
 /** Check whether a plugin UI is a given type.
  *
- * \param ui The Plugin UI
+ * \param ui       The Plugin UI
+ * \param type_uri The URI of the LV2 UI type to check this UI against
  *
  * Time = O(1)
  */
 bool
-slv2_plugin_ui_is_type(SLV2PluginUI ui, const char* type_uri);
+slv2_ui_is_type(SLV2UI ui, const char* type_uri);
 	
 
 /** Get the URI for a Plugin UI's bundle.
@@ -66,7 +66,7 @@ slv2_plugin_ui_is_type(SLV2PluginUI ui, const char* type_uri);
  * Time = O(1)
  */
 const char*
-slv2_plugin_ui_get_bundle_uri(SLV2PluginUI ui);
+slv2_ui_get_bundle_uri(SLV2UI ui);
 
 
 /** Get the URI for a Plugin UI's shared library.
@@ -76,8 +76,10 @@ slv2_plugin_ui_get_bundle_uri(SLV2PluginUI ui);
  * Time = O(1)
  */
 const char*
-slv2_plugin_ui_get_binary_uri(SLV2PluginUI ui);
+slv2_ui_get_binary_uri(SLV2UI ui);
+
 
+/** @} */
 
 #ifdef __cplusplus
 }
diff --git a/slv2/pluginuiinstance.h b/slv2/pluginuiinstance.h
index 0a3d8d7..8a87761 100644
--- a/slv2/pluginuiinstance.h
+++ b/slv2/pluginuiinstance.h
@@ -28,13 +28,7 @@ extern "C" {
 #include <slv2/lv2_gui.h>
 #include <slv2/plugin.h>
 
-/** \defgroup lib Plugin UI library access
- *
- * An SLV2UIInstance is an instantiated UI for a SLV2Plugin. UI instances
- * are loaded from dynamically loaded libraries.  These functions interact 
- * with the UI code in the binary library only, they do not read data files
- * in any way.
- * 
+/** \addtogroup lib
  * @{
  */
 
@@ -72,14 +66,14 @@ typedef struct _SLV2UIInstance {
  * \return NULL if instantiation failed.
  */
 SLV2UIInstance
-slv2_plugin_ui_instantiate(SLV2Plugin                     plugin,
-                           SLV2PluginUI                   gui,
-                           LV2UI_Write_Function           write_function,
-                           LV2UI_Command_Function         command_function,
-                           LV2UI_Program_Change_Function  program_function,
-                           LV2UI_Program_Save_Function    save_function,
-                           LV2UI_Controller               controller,
-                           const LV2_Host_Feature* const* host_features);
+slv2_ui_instantiate(SLV2Plugin                     plugin,
+                    SLV2UI                         ui,
+                    LV2UI_Write_Function           write_function,
+                    LV2UI_Command_Function         command_function,
+                    LV2UI_Program_Change_Function  program_function,
+                    LV2UI_Program_Save_Function    save_function,
+                    LV2UI_Controller               controller,
+                    const LV2_Host_Feature* const* host_features);
 
 
 /** Free a plugin UI instance.
diff --git a/slv2/pluginuis.h b/slv2/pluginuis.h
index 06c38b7..f3eb699 100644
--- a/slv2/pluginuis.h
+++ b/slv2/pluginuis.h
@@ -26,11 +26,7 @@
 extern "C" {
 #endif
 
-/** \defgroup plugins Collections of plugins
- * 
- * These functions work with lists of plugins which come from an
- * SLV2World.  These lists contain only a weak reference to an LV2 plugin
- * in the Model.
+/** \addtogroup collections
  *
  * @{
  */
@@ -42,13 +38,13 @@ extern "C" {
  * are owned by the world).  \a list is invalid after this call.
  */
 void
-slv2_plugin_uis_free(SLV2PluginUIs list);
+slv2_uis_free(SLV2UIs list);
 
 
 /** Get the number of plugins in the list.
  */
 unsigned
-slv2_plugin_uis_size(SLV2PluginUIs list);
+slv2_uis_size(SLV2UIs list);
 
 
 /** Get a plugin from the list by URI.
@@ -60,9 +56,9 @@ slv2_plugin_uis_size(SLV2PluginUIs list);
  * 
  * \return NULL if plugin with \a url not found in \a list.
  */
-SLV2PluginUI
-slv2_plugin_uis_get_by_uri(SLV2PluginUIs list,
-                           const char*   uri);
+SLV2UI
+slv2_uis_get_by_uri(SLV2UIs     list,
+                    const char* uri);
 
 
 /** Get a plugin from the list by index.
@@ -76,9 +72,9 @@ slv2_plugin_uis_get_by_uri(SLV2PluginUIs list,
  *
  * \return NULL if \a index out of range.
  */
-SLV2PluginUI
-slv2_plugin_uis_get_at(SLV2PluginUIs list,
-                       unsigned      index);
+SLV2UI
+slv2_uis_get_at(SLV2UIs  list,
+                unsigned index);
 
 
 /** @} */
diff --git a/slv2/slv2.h b/slv2/slv2.h
index dbb98e3..8aaf958 100644
--- a/slv2/slv2.h
+++ b/slv2/slv2.h
@@ -24,7 +24,6 @@ extern "C" {
 #endif
 
 #include <slv2/types.h>
-#include <slv2/ui.h>
 #include <slv2/world.h>
 #include <slv2/pluginclass.h>
 #include <slv2/plugin.h>
diff --git a/slv2/types.h b/slv2/types.h
index b906899..df818ce 100644
--- a/slv2/types.h
+++ b/slv2/types.h
@@ -69,13 +69,6 @@ typedef enum _SLV2URIType {
 } SLV2URIType;
 
 
-/** A type of plugin UI (corresponding to some LV2 UI extension).
- */
-typedef enum _SLV2UIType {
-	SLV2_UI_TYPE_GTK2 ///< http://ll-plugins.nongnu.org/lv2/ext/gui/dev/1#GtkGUI
-} SLV2UIType;
-
-
 /** A port on a plugin.  Opaque, but valid to compare to NULL. */
 typedef struct _SLV2Port* SLV2Port;
 
@@ -109,11 +102,11 @@ typedef void* SLV2Values;
 
 
 /** A plugin UI */
-typedef struct _SLV2PluginUI* SLV2PluginUI;
+typedef struct _SLV2UI* SLV2UI;
 
 
 /** A collection of plugin UIs. */
-typedef void* SLV2PluginUIs;
+typedef void* SLV2UIs;
 
 
 #ifdef __cplusplus
diff --git a/slv2/ui.h b/slv2/ui.h
deleted file mode 100644
index ff6c394..0000000
--- a/slv2/ui.h
+++ /dev/null
@@ -1,60 +0,0 @@
-/* SLV2
- * Copyright (C) 2007 Dave Robillard <http://drobilla.net>
- *  
- * This library is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 2 of the License, or (at your option)
- * any later version.
- *
- * This library is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
- * for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- */
-
-#ifndef __SLV2_GUI_H__
-#define __SLV2_GUI_H__
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <stdint.h>
-#include <stdbool.h>
-#include <assert.h>
-#include <slv2/types.h>
-#include <slv2/port.h>
-#include <slv2/values.h>
-
-/** \defgroup ui Plugin GUI helpers
- *
- * SLV2 provides access to plugin GUIs, but does not depend on any widget sets
- * itself.  Paths to libraries and opaque pointers to objects are returned, but
- * the GUI extension itself (the URI of which can be had with slv2_ui_get_uri)
- * defines the specifics of how to use these objects/files/etc.
- *
- * @{
- */
-
-/** Return the URI of the GUI type (ontology) this GUI corresponds to.
- * 
- * Returned string is shared and must not be freed by the caller.
- *
- * Time = O(1)
- */
-const char*
-slv2_ui_type_get_uri(SLV2UIType type);
-
-
-/** @} */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* __SLV2_GUI_H__ */
-
diff --git a/slv2/values.h b/slv2/values.h
index 3a46583..2535bdd 100644
--- a/slv2/values.h
+++ b/slv2/values.h
@@ -26,9 +26,9 @@
 extern "C" {
 #endif
 
-/** \defgroup values Collections of values
+/** \defgroup collections Collections of values/objects
  *
- * SLV2Values is an ordered collection of typed values which is fast for random
+ * Ordered collections of typed values which are fast for random
  * access by index (i.e. a fancy array).
  *
  * @{
diff --git a/slv2/world.h b/slv2/world.h
index e4e135d..01e671c 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -27,7 +27,7 @@
 extern "C" {
 #endif
 
-/** \defgroup world Library
+/** \defgroup world Global library state
  * 
  * The "world" represents all library state, and the data found in bundles'
  * manifest.ttl (ie it is an in-memory index of all things LV2 found).