gtk2_ardour/lv2_external_ui.h

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