src/plugin.h

   1 /*
   2  * Copyright (c) 2014 LxDE Developers, see the file AUTHORS for details.
   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 Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17  */
  18
  19 #ifndef __PLUGIN_H__
  20 #define __PLUGIN_H__ 1
  21
  22 #include <libfm/fm.h>
  23
  24 #include "panel.h"
  25 #include "conf.h"
  26
  27 G_BEGIN_DECLS
  28
  29 /* New plugins style which uses FmModule loader, our module type is "lxpanel_gtk" */
  30
  31 #define FM_MODULE_lxpanel_gtk_VERSION 1 /* version of this API */
  32
  33 /**
  34  * LXPanelPluginInit:
  35  * @init: (allow-none): callback on lxpanel start
  36  * @finalize: (allow-none): callback on lxpanel exit
  37  * @name: name to represent plugin in lists
  38  * @description: tooltip on the plugin in lists
  39  * @new_instance: callback to create new plugin instance in panel
  40  * @config: (allow-none): callback to show configuration dialog
  41  * @reconfigure: (allow-none): callback to apply panel configuration change
  42  * @button_press_event: (allow-none): callback on "button-press-event" signal
  43  * @show_system_menu: (allow-none): callback to queue show system menu
  44  *
  45  * Callback @init is called on module loading, only once per application
  46  * lifetime.
  47  *
  48  * Callback @new_instance is called when panel tries to add some plugin.
  49  * It should initialize instance data, prepare widget, and return the
  50  * widget or %NULL if something went wrong. The @panel and @settings data
  51  * are guaranteed to be valid until gtk_widget_destroy() is called on the
  52  * instance. Instance own data should be attached to the instance using
  53  * lxpanel_plugin_set_data().
  54  *
  55  * Callback @config is called when user tries to configure the instance
  56  * (either via context menu or from plugins selection dialog). It should
  57  * create dialog window with instance configuration options. Returned
  58  * dialog will be destroyed on responce or on instance destroy and any
  59  * changed settings will be saved to the panel configuration file. See
  60  * also lxpanel_generic_config_dlg().
  61  *
  62  * Callback @reconfigure is called when panel configuration was changed
  63  * in the panel configuration dialog so the instance may change layout of
  64  * own subwidgets appropriately to new geometry.
  65  *
  66  * Callback @update_context_menu is called when panel context menu being
  67  * composed. The @menu contains only item for plugin instance config. The
  68  * callback can append or prepend own items to the menu. The callback
  69  * should return %TRUE if panel's common menu should be moved into the
  70  * submenu 'Panel' (therefore context menu will contain 'Settings' item,
  71  * any added ones, and 'Panel') and %FALSE if panel's common menu items
  72  * should be in this menu after separator.
  73  */
  74 typedef struct {
  75     /*< public >*/
  76     void (*init)(void);         /* optional startup */
  77     void (*finalize)(void);     /* optional finalize */
  78     char *name;                 /* name to represent in lists */
  79     char *description;          /* tooltip text */
  80     GtkWidget *(*new_instance)(Panel *panel, config_setting_t *settings);
  81     GtkWidget *(*config)(Panel *panel, GtkWidget *instance, GtkWindow *parent);
  82     void (*reconfigure)(Panel *panel, GtkWidget *instance);
  83     gboolean (*button_press_event)(GtkWidget *widget, GdkEventButton *event, Panel *panel);
  84     void (*show_system_menu)(GtkWidget *widget);
  85     gboolean (*update_context_menu)(GtkWidget *plugin, GtkMenu *menu);
  86     int one_per_system : 1;     /* True to disable more than one instance */
  87     int expand_available : 1;   /* True if "stretch" option is available */
  88     int expand_default : 1;     /* True if "stretch" option is default */
  89     int superseded : 1;         /* True if plugin was superseded by another */
  90     /*< private >*/
  91     gpointer _reserved1;
  92     gpointer _reserved2;
  93 } LXPanelPluginInit; /* constant data */
  94
  95 extern LXPanelPluginInit fm_module_init_lxpanel_gtk;
  96
  97 extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
  98 /**
  99  * lxpanel_plugin_get_data
 100  * @_i: instance widget
 101  *
 102  * Retrieves instance data attached to the widget.
 103  */
 104 #define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
 105 /**
 106  * lxpanel_plugin_set_data
 107  * @_i: instance widget
 108  * @_data: instance data
 109  * @_destructor: destructor for @_data
 110  *
 111  * Attaches data to the widget instance. The @_destructor callback will
 112  * be called on @_data when @_i is destroyed and therefore it should free
 113  * any allocated data. The instance widget at that moment is already not
 114  * available to use in any way so not rely on it.
 115  */
 116 #define lxpanel_plugin_set_data(_i,_data,_destructor) g_object_set_qdata_full(G_OBJECT(_i),lxpanel_plugin_qdata,_data,_destructor)
 117
 118 /* register new plugin type - can be called from plugins init() too */
 119 extern gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init);
 120
 121 /* few helper functions */
 122 extern GtkMenu* lxpanel_get_plugin_menu(Panel* panel, GtkWidget* plugin, gboolean use_sub_menu);
 123 extern gboolean lxpanel_plugin_button_press_event(GtkWidget *plugin, GdkEventButton *event, Panel *panel);
 124                         /* Handler for "button_press_event" signal with Plugin as parameter */
 125 extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
 126                         /* Helper to move popup windows away from the panel */
 127 extern void lxpanel_plugin_popup_set_position_helper(Panel * p, GtkWidget * near, GtkWidget * popup, gint * px, gint * py);
 128                         /* Helper for position-calculation callback for popup menus */
 129 extern void plugin_widget_set_background(GtkWidget * plugin, Panel * p);
 130                         /* Recursively set the background of all widgets on a panel background configuration change */
 131 extern gboolean lxpanel_launch_path(Panel *panel, FmPath *path);
 132 extern void lxpanel_plugin_show_config_dialog(Panel* panel, GtkWidget* plugin);
 133                         /* Calls config() callback and shows configuration window */
 134
 135 G_END_DECLS
 136
 137 #endif /* __PLUGIN_H__ */