Adding upstream version 0.7.2.
[debian/lxpanel.git] / src / plugin.h
CommitLineData
6b775dbb
AG
1/*
2 * Copyright (c) 2014 LxDE Developers, see the file AUTHORS for details.
6cc5e1a6
DB
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
6b775dbb
AG
19#ifndef __PLUGIN_H__
20#define __PLUGIN_H__ 1
6cc5e1a6 21
6b775dbb 22#include <libfm/fm.h>
6cc5e1a6 23
6cc5e1a6 24#include "panel.h"
6b775dbb
AG
25#include "conf.h"
26
27G_BEGIN_DECLS
6cc5e1a6 28
6b775dbb 29/* New plugins style which uses FmModule loader, our module type is "lxpanel_gtk" */
9a3614f5 30
6b775dbb 31#define FM_MODULE_lxpanel_gtk_VERSION 1 /* version of this API */
2ba86315 32
6b775dbb
AG
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 * @update_context_menu: (allow-none): callback to update context menu
45 * @control: (allow-none): callback to pass messages from lxpanelctl
46 *
47 * Callback @init is called on module loading, only once per application
48 * lifetime.
49 *
50 * Callback @new_instance is called when panel tries to add some plugin.
51 * It should initialize instance data, prepare widget, and return the
52 * widget or %NULL if something went wrong. The @panel and @settings data
53 * are guaranteed to be valid until gtk_widget_destroy() is called on the
54 * instance. Instance own data should be attached to the instance using
55 * lxpanel_plugin_set_data().
56 *
57 * Callback @config is called when user tries to configure the instance
58 * (either via context menu or from plugins selection dialog). It should
59 * create dialog window with instance configuration options. Returned
60 * dialog will be destroyed on responce or on instance destroy and any
61 * changed settings will be saved to the panel configuration file. See
62 * also lxpanel_generic_config_dlg().
63 *
64 * Callback @reconfigure is called when panel configuration was changed
65 * in the panel configuration dialog so the instance may change layout of
66 * own subwidgets appropriately to new geometry.
67 *
68 * Callback @button_press_event is a handler for "button-press-event"
69 * signal on the plugin instance. This callback would never receive any
70 * right-clicks without modifier keys because panel itself will handle it
71 * showing context menu.
72 *
73 * Callback @show_system_menu is called when lxpanel received a message
74 * by 'lxpanelctl menu' command. It will be sent to each instance if more
75 * than one with this callback available exists.
76 *
77 * Callback @update_context_menu is called when panel context menu being
78 * composed. The @menu contains only item for plugin instance config. The
79 * callback can append or prepend own items to the menu. The callback
80 * should return %TRUE if panel's common menu should be moved into the
81 * submenu 'Panel' (therefore context menu will contain 'Settings' item,
82 * any added ones, and 'Panel') and %FALSE if panel's common menu items
83 * should be in this menu after separator.
84 *
85 * Callback @control is called when command was sent via the lxpanelctl.
86 * The message will be sent to only one instance of plugin. Some messages
87 * are handled by lxpanel: "DEL" will remove plugin from panel, "ADD"
88 * will create new instance if there is no instance yet. (TODO)
89 */
6cc5e1a6 90typedef struct {
6b775dbb
AG
91 /*< public >*/
92 void (*init)(void); /* optional startup */
93 void (*finalize)(void); /* optional finalize */
94 char *name; /* name to represent in lists */
95 char *description; /* tooltip text */
96 GtkWidget *(*new_instance)(LXPanel *panel, config_setting_t *settings);
97 GtkWidget *(*config)(LXPanel *panel, GtkWidget *instance);
98 void (*reconfigure)(LXPanel *panel, GtkWidget *instance);
99 gboolean (*button_press_event)(GtkWidget *widget, GdkEventButton *event, LXPanel *panel);
100 void (*show_system_menu)(GtkWidget *widget);
101 gboolean (*update_context_menu)(GtkWidget *plugin, GtkMenu *menu);
102 gboolean (*control)(GtkWidget *plugin, const char *cmd); /* not implemented */
103 /*< private >*/
104 gpointer _reserved1;
105 gpointer _reserved2;
106 gpointer _reserved3;
107 /*< public >*/
108 int one_per_system : 1; /* True to disable more than one instance */
109 int expand_available : 1; /* True if "stretch" option is available */
110 int expand_default : 1; /* True if "stretch" option is default */
111 int superseded : 1; /* True if plugin was superseded by another */
112} LXPanelPluginInit; /* constant data */
113
114/*
115 * This descriptor instance should be defined in each plugin code as main
116 * entry point for plugin creation. Primitive plugin example follows:
117 *
118 * #include <lxpanel/plugin.h>
119 *
120 * GtkWidget *test_new_instance(LXPanel *panel, config_setting_t *settings)
121 * {
122 * return gtk_image_new_from_stock(GTK_STOCK_OK, panel_get_icon_size(panel));
123 * }
124 *
125 * FM_DEFINE_MODULE(lxpanel_gtk, test)
126 *
127 * LXPanelPluginInit fm_module_init_lxpanel_gtk = {
128 * .name = "Test plugin",
129 * .description = "An image with OK icon",
130 * .new_instance = test_new_instance
131 * }
132 */
133extern LXPanelPluginInit fm_module_init_lxpanel_gtk;
134
135extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
136/**
137 * lxpanel_plugin_get_data
138 * @_i: instance widget
139 *
140 * Retrieves instance data attached to the widget.
141 *
142 * Returns: (transfer none): pointer to the data.
143 */
144#define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
145
146/**
147 * lxpanel_plugin_set_data
148 * @_i: instance widget
149 * @_data: instance data
150 * @_destructor: destructor for @_data
151 *
152 * Attaches data to the widget instance. The @_destructor callback will
153 * be called on @_data when @_i is destroyed and therefore it should free
154 * any allocated data. The instance widget at that moment is already not
155 * available to use in any way so not rely on it or its children.
156 */
157#define lxpanel_plugin_set_data(_i,_data,_destructor) g_object_set_qdata_full(G_OBJECT(_i),lxpanel_plugin_qdata,_data,_destructor)
158
159/**
160 * lxpanel_register_plugin_type
161 * @name: name of new plugin type
162 * @init: plugin-specific type descriptor
163 *
164 * Register new plugin type. Can be called from plugins init() callback too.
165 *
166 * Returns: %TRUE in case of success.
167 */
168extern gboolean lxpanel_register_plugin_type(const char *name, const LXPanelPluginInit *init);
169
170/**
171 * lxpanel_get_plugin_menu
172 * @panel: panel instance pointer
173 * @plugin: plugin instance pointer
174 * @use_sub_menu: %TRUE if panel management options should be in separated submenu
175 *
176 * Creates context menu for given @panel and @plugin.
177 *
178 * Returns: (transfer full): new menu widget.
179 */
180extern GtkMenu* lxpanel_get_plugin_menu(LXPanel* panel, GtkWidget* plugin, gboolean use_sub_menu);
181
182/**
183 * lxpanel_plugin_adjust_popup_position
184 * @popup: a widget to adjust position
185 * @plugin: a plugin instance
186 *
187 * Adjusts the position of a @popup window to ensure that it is not hidden
188 * by the panel and moves @popup near @plugin if possible.
189 */
190extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
191
192/**
193 * lxpanel_plugin_popup_set_position_helper
194 * @p: a panel instance
195 * @near: a widget to position the popup
196 * @popup: a widget to calculate position
197 * @px: (out): pointer to receive X coordinate
198 * @py: (out): pointer to receive Y coordinate
199 *
200 * Calculates desired position of @popup to be placed right to the widget
201 * @near accordingly to position of panel @p and returns its coordinates.
202 * Can be used in position-calculation callback for popup menus.
203 */
204extern void lxpanel_plugin_popup_set_position_helper(LXPanel * p, GtkWidget * near, GtkWidget * popup, gint * px, gint * py);
205
206/**
207 * plugin_widget_set_background
208 * @widget: a widget
209 * @p: a panel instance
210 *
211 * Recursively set the background of @widget and its children. Can be
212 * used on a panel background configuration change.
213 */
214extern void plugin_widget_set_background(GtkWidget * widget, LXPanel * p);
215
216/**
217 * lxpanel_launch_path
218 * @panel: a panel instance
219 * @path: a path to launch
220 *
221 * Launches the @path either itself, or using default application.
222 *
223 * Returns: %TRUE if launch was successful.
224 */
225extern gboolean lxpanel_launch_path(LXPanel *panel, FmPath *path);
226
227/**
228 * lxpanel_plugin_show_config_dialog
229 * @plugin: a plugin instance
230 *
231 * Calls config() callback and shows configuration window.
232 */
233extern void lxpanel_plugin_show_config_dialog(GtkWidget* plugin);
234
235/**
236 * PluginConfType:
237 *
238 * Type of variable passed to lxpanel_generic_config_dlg().
239 */
240typedef enum {
241 CONF_TYPE_STR,
242 CONF_TYPE_INT,
243 CONF_TYPE_BOOL,
244 CONF_TYPE_FILE,
245 CONF_TYPE_FILE_ENTRY,
246 CONF_TYPE_DIRECTORY_ENTRY,
247 CONF_TYPE_TRIM
248} PluginConfType;
249
250/**
251 * lxpanel_generic_config_dlg
252 * @title: (allow-none): optional title of dialog window
253 * @panel: a panel instance
254 * @apply_func: (allow-none): function to apply changes to the plugin
255 * @plugin: (allow-none): an argument for @apply_func
256 * @name: variable-size list of options to configure, terminated with %NULL
257 *
258 * Creates a generic dialog widget to configure the plugin parameters.
259 * The dialog widget may be used for plugin's callback config() then.
260 * Variable-size list of options consists of three arguments for each
261 * option:
262 * - const char* name: text representing the option in dialog
263 * - gpointer ret_value: (out): pointer to the option value
264 * - PluginConfType type: type of the option
265 *
266 * Returns: (tranfer full): new created dialog widget.
267 */
268/* Parameters: const char* name, gpointer ret_value, PluginConfType type, ....NULL */
269extern GtkWidget *lxpanel_generic_config_dlg(const char *title, LXPanel *panel,
270 GSourceFunc apply_func,
271 GtkWidget *plugin,
272 const char *name, ...);
273
274G_END_DECLS
6cc5e1a6 275
6b775dbb 276#endif /* __PLUGIN_H__ */