source/includes/lv2/lv2_external_ui.h

   1 /*
   2   LV2 External UI extension
   3   This work is in public domain.
   4
   5   This file is distributed in the hope that it will be useful,
   6   but WITHOUT ANY WARRANTY; without even the implied warranty of
   7   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   8
   9   If you have questions, contact Filipe Coelho (aka falkTX) <falktx@falktx.com>
  10   or ask in #lad channel, FreeNode IRC network.
  11 */
  12
  13 /**
  14    @file lv2_external_ui.h
  15    C header for the LV2 External UI extension <http://kxstudio.sf.net/ns/lv2ext/external-ui>.
  16 */
  17
  18 #ifndef LV2_EXTERNAL_UI_H
  19 #define LV2_EXTERNAL_UI_H
  20
  21 #include "ui.h"
  22
  23 #define LV2_EXTERNAL_UI_URI     "http://kxstudio.sf.net/ns/lv2ext/external-ui"
  24 #define LV2_EXTERNAL_UI_PREFIX  LV2_EXTERNAL_UI_URI "#"
  25
  26 #define LV2_EXTERNAL_UI__Host   LV2_EXTERNAL_UI_PREFIX "Host"
  27 #define LV2_EXTERNAL_UI__Widget LV2_EXTERNAL_UI_PREFIX "Widget"
  28
  29 /** This extension used to be defined by a lv2plug.in URI */
  30 #define LV2_EXTERNAL_UI_DEPRECATED_URI "http://lv2plug.in/ns/extensions/ui#external"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * When LV2_EXTERNAL_UI__Widget UI is instantiated, the returned
  38  * LV2UI_Widget handle must be cast to pointer to LV2_External_UI_Widget.
  39  * UI is created in invisible state.
  40  */
  41 typedef struct _LV2_External_UI_Widget {
  42   /**
  43    * Host calls this function regulary. UI library implementing the
  44    * callback may do IPC or redraw the UI.
  45    *
  46    * @param _this_ the UI context
  47    */
  48   void (*run)(struct _LV2_External_UI_Widget * _this_);
  49
  50   /**
  51    * Host calls this function to make the plugin UI visible.
  52    *
  53    * @param _this_ the UI context
  54    */
  55   void (*show)(struct _LV2_External_UI_Widget * _this_);
  56
  57   /**
  58    * Host calls this function to make the plugin UI invisible again.
  59    *
  60    * @param _this_ the UI context
  61    */
  62   void (*hide)(struct _LV2_External_UI_Widget * _this_);
  63
  64 } LV2_External_UI_Widget;
  65
  66 #define LV2_EXTERNAL_UI_RUN(ptr)  (ptr)->run(ptr)
  67 #define LV2_EXTERNAL_UI_SHOW(ptr) (ptr)->show(ptr)
  68 #define LV2_EXTERNAL_UI_HIDE(ptr) (ptr)->hide(ptr)
  69
  70 /**
  71  * On UI instantiation, host must supply LV2_EXTERNAL_UI__Host feature.
  72  * LV2_Feature::data must be pointer to LV2_External_UI_Host.
  73  */
  74 typedef struct _LV2_External_UI_Host {
  75   /**
  76    * Callback that plugin UI will call when UI (GUI window) is closed by user.
  77    * This callback will be called during execution of LV2_External_UI_Widget::run()
  78    * (i.e. not from background thread).
  79    *
  80    * After this callback is called, UI is defunct. Host must call LV2UI_Descriptor::cleanup().
  81    * If host wants to make the UI visible again, the UI must be reinstantiated.
  82    *
  83    * @note When using the depreated URI LV2_EXTERNAL_UI_DEPRECATED_URI,
  84    *       some hosts will not call LV2UI_Descriptor::cleanup() as they should,
  85    *       and may call show() again without re-initialization.
  86    *
  87    * @param controller Host context associated with plugin UI, as
  88    *                   supplied to LV2UI_Descriptor::instantiate().
  89    */
  90   void (*ui_closed)(LV2UI_Controller controller);
  91
  92   /**
  93    * Optional (may be NULL) "user friendly" identifier which the UI
  94    * may display to allow a user to easily associate this particular
  95    * UI instance with the correct plugin instance as it is represented
  96    * by the host (e.g. "track 1" or "channel 4").
  97    *
  98    * If supplied by host, the string will be referenced only during
  99    * LV2UI_Descriptor::instantiate()
 100    */
 101   const char * plugin_human_id;
 102
 103 } LV2_External_UI_Host;
 104
 105 #ifdef __cplusplus
 106 } /* extern "C" */
 107 #endif
 108
 109 #endif /* LV2_EXTERNAL_UI_H */