src/calf/lv2_external_ui.h

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