DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

lv2_external_ui.h (3504B)

      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 */