source/includes/lv2/ui.h

   1 /*
   2   LV2 UI Extension
   3   Copyright 2009-2016 David Robillard <d@drobilla.net>
   4   Copyright 2006-2011 Lars Luthman <lars.luthman@gmail.com>
   5
   6   Permission to use, copy, modify, and/or distribute this software for any
   7   purpose with or without fee is hereby granted, provided that the above
   8   copyright notice and this permission notice appear in all copies.
   9
  10   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 */
  18
  19 /**
  20    @defgroup ui User Interfaces
  21
  22    User interfaces of any type for plugins,
  23    <http://lv2plug.in/ns/extensions/ui> for details.
  24
  25    @{
  26 */
  27
  28 #ifndef LV2_UI_H
  29 #define LV2_UI_H
  30
  31 #include <stdint.h>
  32
  33 #include "lv2.h"
  34 #include "urid.h"
  35
  36 #define LV2_UI_URI    "http://lv2plug.in/ns/extensions/ui"  ///< http://lv2plug.in/ns/extensions/ui
  37 #define LV2_UI_PREFIX LV2_UI_URI "#"                        ///< http://lv2plug.in/ns/extensions/ui#
  38
  39 #define LV2_UI__CocoaUI          LV2_UI_PREFIX "CocoaUI"           ///< http://lv2plug.in/ns/extensions/ui#CocoaUI
  40 #define LV2_UI__Gtk3UI           LV2_UI_PREFIX "Gtk3UI"            ///< http://lv2plug.in/ns/extensions/ui#Gtk3UI
  41 #define LV2_UI__GtkUI            LV2_UI_PREFIX "GtkUI"             ///< http://lv2plug.in/ns/extensions/ui#GtkUI
  42 #define LV2_UI__PortNotification LV2_UI_PREFIX "PortNotification"  ///< http://lv2plug.in/ns/extensions/ui#PortNotification
  43 #define LV2_UI__PortProtocol     LV2_UI_PREFIX "PortProtocol"      ///< http://lv2plug.in/ns/extensions/ui#PortProtocol
  44 #define LV2_UI__Qt4UI            LV2_UI_PREFIX "Qt4UI"             ///< http://lv2plug.in/ns/extensions/ui#Qt4UI
  45 #define LV2_UI__Qt5UI            LV2_UI_PREFIX "Qt5UI"             ///< http://lv2plug.in/ns/extensions/ui#Qt5UI
  46 #define LV2_UI__UI               LV2_UI_PREFIX "UI"                ///< http://lv2plug.in/ns/extensions/ui#UI
  47 #define LV2_UI__WindowsUI        LV2_UI_PREFIX "WindowsUI"         ///< http://lv2plug.in/ns/extensions/ui#WindowsUI
  48 #define LV2_UI__X11UI            LV2_UI_PREFIX "X11UI"             ///< http://lv2plug.in/ns/extensions/ui#X11UI
  49 #define LV2_UI__backgroundColor  LV2_UI_PREFIX "backgroundColor"   ///< http://lv2plug.in/ns/extensions/ui#backgroundColor
  50 #define LV2_UI__binary           LV2_UI_PREFIX "binary"            ///< http://lv2plug.in/ns/extensions/ui#binary
  51 #define LV2_UI__fixedSize        LV2_UI_PREFIX "fixedSize"         ///< http://lv2plug.in/ns/extensions/ui#fixedSize
  52 #define LV2_UI__foregroundColor  LV2_UI_PREFIX "foregroundColor"   ///< http://lv2plug.in/ns/extensions/ui#foregroundColor
  53 #define LV2_UI__idleInterface    LV2_UI_PREFIX "idleInterface"     ///< http://lv2plug.in/ns/extensions/ui#idleInterface
  54 #define LV2_UI__noUserResize     LV2_UI_PREFIX "noUserResize"      ///< http://lv2plug.in/ns/extensions/ui#noUserResize
  55 #define LV2_UI__notifyType       LV2_UI_PREFIX "notifyType"        ///< http://lv2plug.in/ns/extensions/ui#notifyType
  56 #define LV2_UI__parent           LV2_UI_PREFIX "parent"            ///< http://lv2plug.in/ns/extensions/ui#parent
  57 #define LV2_UI__plugin           LV2_UI_PREFIX "plugin"            ///< http://lv2plug.in/ns/extensions/ui#plugin
  58 #define LV2_UI__portIndex        LV2_UI_PREFIX "portIndex"         ///< http://lv2plug.in/ns/extensions/ui#portIndex
  59 #define LV2_UI__portMap          LV2_UI_PREFIX "portMap"           ///< http://lv2plug.in/ns/extensions/ui#portMap
  60 #define LV2_UI__portNotification LV2_UI_PREFIX "portNotification"  ///< http://lv2plug.in/ns/extensions/ui#portNotification
  61 #define LV2_UI__portSubscribe    LV2_UI_PREFIX "portSubscribe"     ///< http://lv2plug.in/ns/extensions/ui#portSubscribe
  62 #define LV2_UI__protocol         LV2_UI_PREFIX "protocol"          ///< http://lv2plug.in/ns/extensions/ui#protocol
  63 #define LV2_UI__floatProtocol    LV2_UI_PREFIX "floatProtocol"     ///< http://lv2plug.in/ns/extensions/ui#floatProtocol
  64 #define LV2_UI__peakProtocol     LV2_UI_PREFIX "peakProtocol"      ///< http://lv2plug.in/ns/extensions/ui#peakProtocol
  65 #define LV2_UI__requestValue     LV2_UI_PREFIX "requestValue"      ///< http://lv2plug.in/ns/extensions/ui#requestValue
  66 #define LV2_UI__resize           LV2_UI_PREFIX "resize"            ///< http://lv2plug.in/ns/extensions/ui#resize
  67 #define LV2_UI__scaleFactor      LV2_UI_PREFIX "scaleFactor"       ///< http://lv2plug.in/ns/extensions/ui#scaleFactor
  68 #define LV2_UI__showInterface    LV2_UI_PREFIX "showInterface"     ///< http://lv2plug.in/ns/extensions/ui#showInterface
  69 #define LV2_UI__touch            LV2_UI_PREFIX "touch"             ///< http://lv2plug.in/ns/extensions/ui#touch
  70 #define LV2_UI__ui               LV2_UI_PREFIX "ui"                ///< http://lv2plug.in/ns/extensions/ui#ui
  71 #define LV2_UI__updateRate       LV2_UI_PREFIX "updateRate"        ///< http://lv2plug.in/ns/extensions/ui#updateRate
  72 #define LV2_UI__windowTitle      LV2_UI_PREFIX "windowTitle"       ///< http://lv2plug.in/ns/extensions/ui#windowTitle
  73
  74 /**
  75    The index returned by LV2UI_Port_Map::port_index() for unknown ports.
  76 */
  77 #define LV2UI_INVALID_PORT_INDEX ((uint32_t)-1)
  78
  79 #ifdef __cplusplus
  80 extern "C" {
  81 #else
  82 #    include <stdbool.h>
  83 #endif
  84
  85 /**
  86    A pointer to some widget or other type of UI handle.
  87
  88    The actual type is defined by the type of the UI.
  89 */
  90 typedef void* LV2UI_Widget;
  91
  92 /**
  93    A pointer to UI instance internals.
  94
  95    The host may compare this to NULL, but otherwise MUST NOT interpret it.
  96 */
  97 typedef void* LV2UI_Handle;
  98
  99 /**
 100    A pointer to a controller provided by the host.
 101
 102    The UI may compare this to NULL, but otherwise MUST NOT interpret it.
 103 */
 104 typedef void* LV2UI_Controller;
 105
 106 /**
 107    A pointer to opaque data for a feature.
 108 */
 109 typedef void* LV2UI_Feature_Handle;
 110
 111 /**
 112    A host-provided function that sends data to a plugin's input ports.
 113
 114    @param controller The opaque controller pointer passed to
 115    LV2UI_Descriptor::instantiate().
 116
 117    @param port_index Index of the port to update.
 118
 119    @param buffer Buffer containing `buffer_size` bytes of data.
 120
 121    @param buffer_size Size of `buffer` in bytes.
 122
 123    @param port_protocol Either 0 or the URID for a ui:PortProtocol.  If 0, the
 124    protocol is implicitly ui:floatProtocol, the port MUST be an lv2:ControlPort
 125    input, `buffer` MUST point to a single float value, and `buffer_size` MUST
 126    be sizeof(float).  The UI SHOULD NOT use a protocol not supported by the
 127    host, but the host MUST gracefully ignore any protocol it does not
 128    understand.
 129 */
 130 typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
 131                                      uint32_t         port_index,
 132                                      uint32_t         buffer_size,
 133                                      uint32_t         port_protocol,
 134                                      const void*      buffer);
 135
 136 /**
 137    A plugin UI.
 138
 139    A pointer to an object of this type is returned by the lv2ui_descriptor()
 140    function.
 141 */
 142 typedef struct _LV2UI_Descriptor {
 143         /**
 144            The URI for this UI (not for the plugin it controls).
 145         */
 146         const char* URI;
 147
 148         /**
 149            Create a new UI and return a handle to it.  This function works
 150            similarly to LV2_Descriptor::instantiate().
 151
 152            @param descriptor The descriptor for the UI to instantiate.
 153
 154            @param plugin_uri The URI of the plugin that this UI will control.
 155
 156            @param bundle_path The path to the bundle containing this UI, including
 157            the trailing directory separator.
 158
 159            @param write_function A function that the UI can use to send data to the
 160            plugin's input ports.
 161
 162            @param controller A handle for the UI instance to be passed as the
 163            first parameter of UI methods.
 164
 165            @param widget (output) widget pointer.  The UI points this at its main
 166            widget, which has the type defined by the UI type in the data file.
 167
 168            @param features An array of LV2_Feature pointers.  The host must pass
 169            all feature URIs that it and the UI supports and any additional data, as
 170            in LV2_Descriptor::instantiate().  Note that UI features and plugin
 171            features are not necessarily the same.
 172
 173         */
 174         LV2UI_Handle (*instantiate)(const struct _LV2UI_Descriptor* descriptor,
 175                                     const char*                     plugin_uri,
 176                                     const char*                     bundle_path,
 177                                     LV2UI_Write_Function            write_function,
 178                                     LV2UI_Controller                controller,
 179                                     LV2UI_Widget*                   widget,
 180                                     const LV2_Feature* const*       features);
 181
 182
 183         /**
 184            Destroy the UI.  The host must not try to access the widget after
 185            calling this function.
 186         */
 187         void (*cleanup)(LV2UI_Handle ui);
 188
 189         /**
 190            Tell the UI that something interesting has happened at a plugin port.
 191
 192            What is "interesting" and how it is written to `buffer` is defined by
 193            `format`, which has the same meaning as in LV2UI_Write_Function().
 194            Format 0 is a special case for lv2:ControlPort, where this function
 195            should be called when the port value changes (but not necessarily for
 196            every change), `buffer_size` must be sizeof(float), and `buffer`
 197            points to a single IEEE-754 float.
 198
 199            By default, the host should only call this function for lv2:ControlPort
 200            inputs.  However, the UI can request updates for other ports statically
 201            with ui:portNotification or dynamicaly with ui:portSubscribe.
 202
 203            The UI MUST NOT retain any reference to `buffer` after this function
 204            returns, it is only valid for the duration of the call.
 205
 206            This member may be NULL if the UI is not interested in any port events.
 207         */
 208         void (*port_event)(LV2UI_Handle ui,
 209                            uint32_t     port_index,
 210                            uint32_t     buffer_size,
 211                            uint32_t     format,
 212                            const void*  buffer);
 213
 214         /**
 215            Return a data structure associated with an extension URI, typically an
 216            interface struct with additional function pointers
 217
 218            This member may be set to NULL if the UI is not interested in supporting
 219            any extensions. This is similar to LV2_Descriptor::extension_data().
 220
 221         */
 222         const void* (*extension_data)(const char* uri);
 223 } LV2UI_Descriptor;
 224
 225 /**
 226    Feature/interface for resizable UIs (LV2_UI__resize).
 227
 228    This structure is used in two ways: as a feature passed by the host via
 229    LV2UI_Descriptor::instantiate(), or as an interface provided by a UI via
 230    LV2UI_Descriptor::extension_data()).
 231 */
 232 typedef struct _LV2UI_Resize {
 233         /**
 234            Pointer to opaque data which must be passed to ui_resize().
 235         */
 236         LV2UI_Feature_Handle handle;
 237
 238         /**
 239            Request/advertise a size change.
 240
 241            When provided by the host, the UI may call this function to inform the
 242            host about the size of the UI.
 243
 244            When provided by the UI, the host may call this function to notify the
 245            UI that it should change its size accordingly.  In this case, the host
 246            must pass the LV2UI_Handle to provide access to the UI instance.
 247
 248            @return 0 on success.
 249         */
 250         int (*ui_resize)(LV2UI_Feature_Handle handle, int width, int height);
 251 } LV2UI_Resize;
 252
 253 /**
 254    Feature to map port symbols to UIs.
 255
 256    This can be used by the UI to get the index for a port with the given
 257    symbol.  This makes it possible to implement and distribute a UI separately
 258    from the plugin (since symbol, unlike index, is a stable port identifier).
 259 */
 260 typedef struct _LV2UI_Port_Map {
 261         /**
 262            Pointer to opaque data which must be passed to port_index().
 263         */
 264         LV2UI_Feature_Handle handle;
 265
 266         /**
 267            Get the index for the port with the given `symbol`.
 268
 269            @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
 270            port is found.
 271         */
 272         uint32_t (*port_index)(LV2UI_Feature_Handle handle, const char* symbol);
 273 } LV2UI_Port_Map;
 274
 275 /**
 276    Feature to subscribe to port updates (LV2_UI__portSubscribe).
 277 */
 278 typedef struct _LV2UI_Port_Subscribe {
 279         /**
 280            Pointer to opaque data which must be passed to subscribe() and
 281            unsubscribe().
 282         */
 283         LV2UI_Feature_Handle handle;
 284
 285         /**
 286            Subscribe to updates for a port.
 287
 288            This means that the host will call the UI's port_event() function when
 289            the port value changes (as defined by protocol).
 290
 291            Calling this function with the same `port_index` and `port_protocol`
 292            as an already active subscription has no effect.
 293
 294            @param handle The handle field of this struct.
 295            @param port_index The index of the port.
 296            @param port_protocol The URID of the ui:PortProtocol.
 297            @param features Features for this subscription.
 298            @return 0 on success.
 299         */
 300         uint32_t (*subscribe)(LV2UI_Feature_Handle      handle,
 301                               uint32_t                  port_index,
 302                               uint32_t                  port_protocol,
 303                               const LV2_Feature* const* features);
 304
 305         /**
 306            Unsubscribe from updates for a port.
 307
 308            This means that the host will cease calling calling port_event() when
 309            the port value changes.
 310
 311            Calling this function with a `port_index` and `port_protocol` that
 312            does not refer to an active port subscription has no effect.
 313
 314            @param handle The handle field of this struct.
 315            @param port_index The index of the port.
 316            @param port_protocol The URID of the ui:PortProtocol.
 317            @param features Features for this subscription.
 318            @return 0 on success.
 319         */
 320         uint32_t (*unsubscribe)(LV2UI_Feature_Handle      handle,
 321                                 uint32_t                  port_index,
 322                                 uint32_t                  port_protocol,
 323                                 const LV2_Feature* const* features);
 324 } LV2UI_Port_Subscribe;
 325
 326 /**
 327    A feature to notify the host that the user has grabbed a UI control.
 328 */
 329 typedef struct _LV2UI_Touch {
 330         /**
 331            Pointer to opaque data which must be passed to ui_resize().
 332         */
 333         LV2UI_Feature_Handle handle;
 334
 335         /**
 336            Notify the host that a control has been grabbed or released.
 337
 338            The host should cease automating the port or otherwise manipulating the
 339            port value until the control has been ungrabbed.
 340
 341            @param handle The handle field of this struct.
 342            @param port_index The index of the port associated with the control.
 343            @param grabbed If true, the control has been grabbed, otherwise the
 344            control has been released.
 345         */
 346         void (*touch)(LV2UI_Feature_Handle handle,
 347                       uint32_t             port_index,
 348                       bool                 grabbed);
 349 } LV2UI_Touch;
 350
 351 /**
 352    A status code for LV2UI_Request_Value::request.
 353 */
 354 typedef enum {
 355         /**
 356            Completed successfully.
 357
 358            The host will set the parameter later if the user choses a new value.
 359         */
 360         LV2UI_REQUEST_VALUE_SUCCESS,
 361
 362         /**
 363            Parameter already being requested.
 364
 365            The host is already requesting a parameter from the user (for example, a
 366            dialog is visible), or the UI is otherwise busy and can not make this
 367            request.
 368         */
 369         LV2UI_REQUEST_VALUE_BUSY,
 370
 371         /**
 372            Unknown parameter.
 373
 374            The host is not aware of this parameter, and is not able to set a new
 375            value for it.
 376         */
 377         LV2UI_REQUEST_VALUE_ERR_UNKNOWN,
 378
 379         /**
 380            Unsupported parameter.
 381
 382            The host knows about this parameter, but does not support requesting a
 383            new value for it from the user.  This is likely because the host does
 384            not have UI support for choosing a value with the appropriate type.
 385         */
 386         LV2UI_REQUEST_VALUE_ERR_UNSUPPORTED
 387 } LV2UI_Request_Value_Status;
 388
 389 /**
 390    A feature to request a new parameter value from the host.
 391 */
 392 typedef struct {
 393         /**
 394            Pointer to opaque data which must be passed to request().
 395         */
 396         LV2UI_Feature_Handle handle;
 397
 398         /**
 399            Request a value for a parameter from the host.
 400
 401            This is mainly used by UIs to request values for complex parameters that
 402            don't change often, such as file paths, but it may be used to request
 403            any parameter value.
 404
 405            This function returns immediately, and the return value indicates
 406            whether the host can fulfill the request.  The host may notify the
 407            plugin about the new parameter value, for example when a file is
 408            selected by the user, via the usual mechanism.  Typically, the host will
 409            send a message to the plugin that sets the new parameter value, and the
 410            plugin will notify the UI via a message as usual for any other parameter
 411            change.
 412
 413            To provide an appropriate UI, the host can determine details about the
 414            parameter from the plugin data as usual.  The additional parameters of
 415            this function provide support for more advanced use cases, but in the
 416            simple common case, the plugin will simply pass the key of the desired
 417            parameter and zero for everything else.
 418
 419            @param handle The handle field of this struct.
 420
 421            @param key The URID of the parameter.
 422
 423            @param type The optional type of the value to request.  This can be used
 424            to request a specific value type for parameters that support several.
 425            If non-zero, it must be the URID of an instance of rdfs:Class or
 426            rdfs:Datatype.
 427
 428            @param features Additional features for this request, or NULL.
 429
 430            @return A status code which is 0 on success.
 431         */
 432         LV2UI_Request_Value_Status (*request)(LV2UI_Feature_Handle      handle,
 433                                               LV2_URID                  key,
 434                                               LV2_URID                  type,
 435                                               const LV2_Feature* const* features);
 436
 437 } LV2UI_Request_Value;
 438
 439 /**
 440    UI Idle Interface (LV2_UI__idleInterface)
 441
 442    UIs can provide this interface to have an idle() callback called by the host
 443    rapidly to update the UI.
 444 */
 445 typedef struct _LV2UI_Idle_Interface {
 446         /**
 447            Run a single iteration of the UI's idle loop.
 448
 449            This will be called rapidly in the UI thread at a rate appropriate
 450            for a toolkit main loop.  There are no precise timing guarantees, but
 451            the host should attempt to call idle() at a high enough rate for smooth
 452            animation, at least 30Hz.
 453
 454            @return non-zero if the UI has been closed, in which case the host
 455            should stop calling idle(), and can either completely destroy the UI, or
 456            re-show it and resume calling idle().
 457         */
 458         int (*idle)(LV2UI_Handle ui);
 459 } LV2UI_Idle_Interface;
 460
 461 /**
 462    UI Show Interface (LV2_UI__showInterface)
 463
 464    UIs can provide this interface to show and hide a window, which allows them
 465    to function in hosts unable to embed their widget.  This allows any UI to
 466    provide a fallback for embedding that works in any host.
 467
 468    If used:
 469    - The host MUST use LV2UI_Idle_Interface to drive the UI.
 470    - The UI MUST return non-zero from LV2UI_Idle_Interface::idle() when it has been closed.
 471    - If idle() returns non-zero, the host MUST call hide() and stop calling
 472      idle().  It MAY later call show() then resume calling idle().
 473 */
 474 typedef struct _LV2UI_Show_Interface {
 475         /**
 476            Show a window for this UI.
 477
 478            The window title MAY have been passed by the host to
 479            LV2UI_Descriptor::instantiate() as an LV2_Options_Option with key
 480            LV2_UI__windowTitle.
 481
 482            @return 0 on success, or anything else to stop being called.
 483         */
 484         int (*show)(LV2UI_Handle ui);
 485
 486         /**
 487            Hide the window for this UI.
 488
 489            @return 0 on success, or anything else to stop being called.
 490         */
 491         int (*hide)(LV2UI_Handle ui);
 492 } LV2UI_Show_Interface;
 493
 494 /**
 495    Peak data for a slice of time, the update format for ui:peakProtocol.
 496 */
 497 typedef struct _LV2UI_Peak_Data {
 498         /**
 499            The start of the measurement period.  This is just a running counter
 500            that is only meaningful in comparison to previous values and must not be
 501            interpreted as an absolute time.
 502         */
 503         uint32_t period_start;
 504
 505         /**
 506            The size of the measurement period, in the same units as period_start.
 507         */
 508         uint32_t period_size;
 509
 510         /**
 511            The peak value for the measurement period. This should be the maximal
 512            value for abs(sample) over all the samples in the period.
 513         */
 514         float peak;
 515 } LV2UI_Peak_Data;
 516
 517 /**
 518    Prototype for UI accessor function.
 519
 520    This is the entry point to a UI library, which works in the same way as
 521    lv2_descriptor() but for UIs rather than plugins.
 522 */
 523 LV2_SYMBOL_EXPORT
 524 const LV2UI_Descriptor* lv2ui_descriptor(uint32_t index);
 525
 526 /**
 527    The type of the lv2ui_descriptor() function.
 528 */
 529 typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index);
 530
 531 #ifdef __cplusplus
 532 }
 533 #endif
 534
 535 #endif /* LV2_UI_H */
 536
 537 /**
 538    @}
 539 */