f1e77b15e79ed427fd4d6498438f55f28e0fdc5f
[lxde/lxpanel.git] / 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__ */