Adding upstream version 0.8.2.
[debian/lxpanel.git] / src / plugin.h
CommitLineData
6b775dbb 1/*
0688b017
AG
2 * Copyright (C) 2006-2008 Hong Jen Yee (PCMan) <pcman.tw@gmail.com>
3 * 2006-2008 Jim Huang <jserv.tw@gmail.com>
4 * 2009-2010 Marty Jack <martyj19@comcast.net>
5 * 2014 Andriy Grytsenko <andrej@rep.kiev.ua>
6 *
7 * This file is a part of LXPanel project.
6cc5e1a6
DB
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 */
23
6b775dbb
AG
24#ifndef __PLUGIN_H__
25#define __PLUGIN_H__ 1
6cc5e1a6 26
6b775dbb 27#include <libfm/fm.h>
6cc5e1a6 28
6cc5e1a6 29#include "panel.h"
6b775dbb
AG
30#include "conf.h"
31
32G_BEGIN_DECLS
6cc5e1a6 33
6b775dbb 34/* New plugins style which uses FmModule loader, our module type is "lxpanel_gtk" */
9a3614f5 35
6b775dbb 36#define FM_MODULE_lxpanel_gtk_VERSION 1 /* version of this API */
2ba86315 37
6b775dbb
AG
38/**
39 * LXPanelPluginInit:
40 * @init: (allow-none): callback on lxpanel start
41 * @finalize: (allow-none): callback on lxpanel exit
42 * @name: name to represent plugin in lists
43 * @description: tooltip on the plugin in lists
44 * @new_instance: callback to create new plugin instance in panel
45 * @config: (allow-none): callback to show configuration dialog
46 * @reconfigure: (allow-none): callback to apply panel configuration change
47 * @button_press_event: (allow-none): callback on "button-press-event" signal
48 * @show_system_menu: (allow-none): callback to queue show system menu
49 * @update_context_menu: (allow-none): callback to update context menu
50 * @control: (allow-none): callback to pass messages from lxpanelctl
51 *
52 * Callback @init is called on module loading, only once per application
53 * lifetime.
54 *
55 * Callback @new_instance is called when panel tries to add some plugin.
56 * It should initialize instance data, prepare widget, and return the
57 * widget or %NULL if something went wrong. The @panel and @settings data
58 * are guaranteed to be valid until gtk_widget_destroy() is called on the
59 * instance. Instance own data should be attached to the instance using
60 * lxpanel_plugin_set_data().
61 *
62 * Callback @config is called when user tries to configure the instance
63 * (either via context menu or from plugins selection dialog). It should
64 * create dialog window with instance configuration options. Returned
65 * dialog will be destroyed on responce or on instance destroy and any
66 * changed settings will be saved to the panel configuration file. See
67 * also lxpanel_generic_config_dlg().
68 *
69 * Callback @reconfigure is called when panel configuration was changed
70 * in the panel configuration dialog so the instance may change layout of
71 * own subwidgets appropriately to new geometry.
72 *
73 * Callback @button_press_event is a handler for "button-press-event"
74 * signal on the plugin instance. This callback would never receive any
75 * right-clicks without modifier keys because panel itself will handle it
76 * showing context menu.
77 *
78 * Callback @show_system_menu is called when lxpanel received a message
79 * by 'lxpanelctl menu' command. It will be sent to each instance if more
80 * than one with this callback available exists.
81 *
82 * Callback @update_context_menu is called when panel context menu being
83 * composed. The @menu contains only item for plugin instance config. The
84 * callback can append or prepend own items to the menu. The callback
85 * should return %TRUE if panel's common menu should be moved into the
86 * submenu 'Panel' (therefore context menu will contain 'Settings' item,
87 * any added ones, and 'Panel') and %FALSE if panel's common menu items
88 * should be in this menu after separator.
89 *
90 * Callback @control is called when command was sent via the lxpanelctl.
91 * The message will be sent to only one instance of plugin. Some messages
92 * are handled by lxpanel: "DEL" will remove plugin from panel, "ADD"
93 * will create new instance if there is no instance yet. (TODO)
94 */
6cc5e1a6 95typedef struct {
6b775dbb
AG
96 /*< public >*/
97 void (*init)(void); /* optional startup */
98 void (*finalize)(void); /* optional finalize */
99 char *name; /* name to represent in lists */
100 char *description; /* tooltip text */
101 GtkWidget *(*new_instance)(LXPanel *panel, config_setting_t *settings);
102 GtkWidget *(*config)(LXPanel *panel, GtkWidget *instance);
103 void (*reconfigure)(LXPanel *panel, GtkWidget *instance);
104 gboolean (*button_press_event)(GtkWidget *widget, GdkEventButton *event, LXPanel *panel);
105 void (*show_system_menu)(GtkWidget *widget);
106 gboolean (*update_context_menu)(GtkWidget *plugin, GtkMenu *menu);
107 gboolean (*control)(GtkWidget *plugin, const char *cmd); /* not implemented */
108 /*< private >*/
109 gpointer _reserved1;
110 gpointer _reserved2;
111 gpointer _reserved3;
112 /*< public >*/
113 int one_per_system : 1; /* True to disable more than one instance */
114 int expand_available : 1; /* True if "stretch" option is available */
115 int expand_default : 1; /* True if "stretch" option is default */
116 int superseded : 1; /* True if plugin was superseded by another */
117} LXPanelPluginInit; /* constant data */
118
119/*
120 * This descriptor instance should be defined in each plugin code as main
121 * entry point for plugin creation. Primitive plugin example follows:
122 *
123 * #include <lxpanel/plugin.h>
124 *
125 * GtkWidget *test_new_instance(LXPanel *panel, config_setting_t *settings)
126 * {
127 * return gtk_image_new_from_stock(GTK_STOCK_OK, panel_get_icon_size(panel));
128 * }
129 *
130 * FM_DEFINE_MODULE(lxpanel_gtk, test)
131 *
132 * LXPanelPluginInit fm_module_init_lxpanel_gtk = {
133 * .name = "Test plugin",
134 * .description = "An image with OK icon",
135 * .new_instance = test_new_instance
136 * }
137 */
138extern LXPanelPluginInit fm_module_init_lxpanel_gtk;
139
140extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
141/**
142 * lxpanel_plugin_get_data
143 * @_i: instance widget
144 *
145 * Retrieves instance data attached to the widget.
146 *
147 * Returns: (transfer none): pointer to the data.
148 */
149#define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
150
151/**
152 * lxpanel_plugin_set_data
153 * @_i: instance widget
154 * @_data: instance data
f7ecd6ce 155 * @_destructor: (allow-none): destructor for @_data
6b775dbb
AG
156 *
157 * Attaches data to the widget instance. The @_destructor callback will
158 * be called on @_data when @_i is destroyed and therefore it should free
159 * any allocated data. The instance widget at that moment is already not
160 * available to use in any way so not rely on it or its children.
161 */
162#define lxpanel_plugin_set_data(_i,_data,_destructor) g_object_set_qdata_full(G_OBJECT(_i),lxpanel_plugin_qdata,_data,_destructor)
163
164/**
165 * lxpanel_register_plugin_type
166 * @name: name of new plugin type
167 * @init: plugin-specific type descriptor
168 *
169 * Register new plugin type. Can be called from plugins init() callback too.
170 *
171 * Returns: %TRUE in case of success.
172 */
173extern gboolean lxpanel_register_plugin_type(const char *name, const LXPanelPluginInit *init);
174
175/**
176 * lxpanel_get_plugin_menu
177 * @panel: panel instance pointer
178 * @plugin: plugin instance pointer
179 * @use_sub_menu: %TRUE if panel management options should be in separated submenu
180 *
181 * Creates context menu for given @panel and @plugin.
182 *
183 * Returns: (transfer full): new menu widget.
184 */
185extern GtkMenu* lxpanel_get_plugin_menu(LXPanel* panel, GtkWidget* plugin, gboolean use_sub_menu);
186
187/**
188 * lxpanel_plugin_adjust_popup_position
189 * @popup: a widget to adjust position
190 * @plugin: a plugin instance
191 *
192 * Adjusts the position of a @popup window to ensure that it is not hidden
193 * by the panel and moves @popup near @plugin if possible.
194 */
195extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
196
197/**
198 * lxpanel_plugin_popup_set_position_helper
199 * @p: a panel instance
200 * @near: a widget to position the popup
201 * @popup: a widget to calculate position
202 * @px: (out): pointer to receive X coordinate
203 * @py: (out): pointer to receive Y coordinate
204 *
205 * Calculates desired position of @popup to be placed right to the widget
206 * @near accordingly to position of panel @p and returns its coordinates.
207 * Can be used in position-calculation callback for popup menus.
208 */
209extern void lxpanel_plugin_popup_set_position_helper(LXPanel * p, GtkWidget * near, GtkWidget * popup, gint * px, gint * py);
210
211/**
212 * plugin_widget_set_background
213 * @widget: a widget
214 * @p: a panel instance
215 *
216 * Recursively set the background of @widget and its children. Can be
217 * used on a panel background configuration change.
218 */
219extern void plugin_widget_set_background(GtkWidget * widget, LXPanel * p);
220
221/**
222 * lxpanel_launch_path
223 * @panel: a panel instance
224 * @path: a path to launch
225 *
226 * Launches the @path either itself, or using default application.
227 *
228 * Returns: %TRUE if launch was successful.
229 */
230extern gboolean lxpanel_launch_path(LXPanel *panel, FmPath *path);
231
232/**
233 * lxpanel_plugin_show_config_dialog
234 * @plugin: a plugin instance
235 *
236 * Calls config() callback and shows configuration window.
237 */
238extern void lxpanel_plugin_show_config_dialog(GtkWidget* plugin);
239
240/**
241 * PluginConfType:
f7ecd6ce
AG
242 * @CONF_TYPE_STR: string entry, pointer is char **
243 * @CONF_TYPE_INT: spin entry (range 0...1000), pointer is gint *
244 * @CONF_TYPE_BOOL: check button, pointer is gboolean *
245 * @CONF_TYPE_FILE: file chooser, pointer is char **
246 * @CONF_TYPE_FILE_ENTRY: file path entry, pointer is char **
247 * @CONF_TYPE_DIRECTORY_ENTRY: directory path entry, pointer is char **
248 * @CONF_TYPE_TRIM: just a text in italic, pointer is ignored
249 * @CONF_TYPE_EXTERNAL: (since 0.8) provided by caller, pointer is GtkWidget *
6b775dbb
AG
250 *
251 * Type of variable passed to lxpanel_generic_config_dlg().
252 */
253typedef enum {
254 CONF_TYPE_STR,
255 CONF_TYPE_INT,
256 CONF_TYPE_BOOL,
257 CONF_TYPE_FILE,
258 CONF_TYPE_FILE_ENTRY,
259 CONF_TYPE_DIRECTORY_ENTRY,
f7ecd6ce
AG
260 CONF_TYPE_TRIM,
261 CONF_TYPE_EXTERNAL
6b775dbb
AG
262} PluginConfType;
263
264/**
265 * lxpanel_generic_config_dlg
266 * @title: (allow-none): optional title of dialog window
267 * @panel: a panel instance
268 * @apply_func: (allow-none): function to apply changes to the plugin
269 * @plugin: (allow-none): an argument for @apply_func
270 * @name: variable-size list of options to configure, terminated with %NULL
271 *
272 * Creates a generic dialog widget to configure the plugin parameters.
273 * The dialog widget may be used for plugin's callback config() then.
274 * Variable-size list of options consists of three arguments for each
275 * option:
276 * - const char* name: text representing the option in dialog
f7ecd6ce 277 * - gpointer ret_value: (in out): pointer to the option value
6b775dbb 278 * - PluginConfType type: type of the option
f7ecd6ce
AG
279 * Note that for type CONF_TYPE_EXTERNAL the name argument is ignored and
280 * therefore empty string ("") have to be passed.
6b775dbb
AG
281 *
282 * Returns: (tranfer full): new created dialog widget.
283 */
284/* Parameters: const char* name, gpointer ret_value, PluginConfType type, ....NULL */
285extern GtkWidget *lxpanel_generic_config_dlg(const char *title, LXPanel *panel,
286 GSourceFunc apply_func,
287 GtkWidget *plugin,
288 const char *name, ...);
289
f7ecd6ce
AG
290/**
291 * panel_config_int_button_new
292 * @name: text representing the option in dialog
293 * @min: minimal spin button value
294 * @max: maximal spin button value
295 * @val: (in out): pointer to the option value
296 *
297 * Widget to use as CONF_TYPE_EXTERNAL instead of CONF_TYPE_INT if plugin
298 * wants to customize range for lxpanel_generic_config_dlg(). The default
299 * widget uses range 0...1000 and here you can set custom range. This API
300 * should be never used outside of lxpanel_generic_config_dlg() arguments
301 * since it uses callbacks specific to that API.
302 *
303 * See also: lxpanel_generic_config_dlg().
304 *
305 * Returns: (transfer full): new widget.
306 *
307 * Since: 0.8.0
308 */
309extern GtkWidget *panel_config_int_button_new(const char *name, gint *val,
310 gint min, gint max);
311
312/*
313 * panel_config_hotkey_button_new
314 * @label: text representing the option in dialog
315 * @hotkey: (allow-none): current hotkey
316 *
317 * Creates a #GtkFrame derived widget which can select hotkey binding.
318 * The widget emits "changed" signal when some new combination selected
319 * gboolean callback(PanelCfgInputButton *, char *, gpointer);
320 * Caller should test if keybinding can be used in the callback and then
321 * return test result as %TRUE or %FALSE.
322 * Widget can be used for lxpanel_generic_config_dlg as CONF_TYPE_EXTERNAL
323 *
324 * Returns: (transfer full): a created widget.
325 *
326 * Since: 0.8.0
327 */
328extern GtkWidget *panel_config_hotkey_button_new(const char *label, const char *hotkey);
329extern GtkWidget *panel_config_click_button_new(const char *label, const char *click);
330
331/**
332 * lxpanel_apply_hotkey
333 * @hkptr: (in out) (transfer full): pointer to hotkey string
334 * @keystring: (allow-none): new hotkey
335 * @handler: callback to assign to hotkey
336 * @user_data: data to provide for @handler
337 * @show_error: %TRUE to show error window if assignment failed
338 *
339 * Function designed to use in callback on "changed" signal from widget
340 * created by panel_config_hotkey_button_new(). Should be also used on
341 * initial binding and on unbinding when module unloaded (in latter case
342 * @keystring should be %NULL). In case of success returns %TRUE, unbinds
343 * previous hotkey from @hkptr, and updates @hkptr. The @hkptr contains
344 * allocated string.
345 *
346 * Returns: %TRUE on success.
347 *
348 * Since: 0.8.0
349 */
350extern gboolean lxpanel_apply_hotkey(char **hkptr, const char *keystring,
351 void (*handler)(const char *keystring, gpointer user_data),
352 gpointer user_data, gboolean show_error);
353
354/**
355 * panel_config_click_parse
356 * @keystring: string to parse
357 * @mods: (out): return location for modifier
358 *
359 * Parses click string received in "changed" signal emission of widget
360 * created with panel_config_click_button_new() and returns button and
361 * modifier that can be compared with GdkEventButton data when required.
362 *
363 * Returns: button number or 0 if @keystring is invalid.
364 *
365 * Since: 0.8.0
366 */
367extern guint panel_config_click_parse(const char *keystring, GdkModifierType *mods);
368
6b775dbb 369G_END_DECLS
6cc5e1a6 370
6b775dbb 371#endif /* __PLUGIN_H__ */