Add some descriptions to LXPanelPluginInit and lxpanel_plugin_[sg]et_data().
[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 *
44 * Callback @init is called on module loading, only once per application
45 * lifetime.
46 *
47 * Callback @new_instance is called when panel tries to add some plugin.
48 * It should initialize instance data, prepare widget, and return the
49 * widget or %NULL if something went wrong. The @panel and @settings data
50 * are guaranteed to be valid until gtk_widget_destroy() is called on the
51 * instance. Instance own data should be attached to the instance using
52 * lxpanel_plugin_set_data().
53 *
54 * Callback @config is called when user tries to configure the instance
55 * (either via context menu or from plugins selection dialog). It should
56 * create dialog window with configuration options and prepare saving
57 * data when the dialog is closed. See also lxpanel_generic_config_dlg().
58 *
59 * Callback @reconfigure is called when panel configuration was changed
60 * in the panel configuration dialog.
61 */
62 typedef struct {
63 /*< public >*/
64 void (*init)(void); /* optional startup */
65 void (*finalize)(void); /* optional finalize */
66 char *name; /* name to represent in lists */
67 char *description; /* tooltip text */
68 GtkWidget *(*new_instance)(Panel *panel, config_setting_t *settings);
69 void (*config)(Panel *panel, GtkWidget *instance, GtkWindow *parent);
70 void (*reconfigure)(Panel *panel, GtkWidget *instance);
71 gboolean (*button_press_event)(GtkWidget *widget, GdkEventButton *event, Panel *panel);
72 int one_per_system : 1; /* True to disable more than one instance */
73 int expand_available : 1; /* True if "stretch" option is available */
74 int expand_default : 1; /* True if "stretch" option is default */
75 int superseded : 1; /* True if plugin was superseded by another */
76 /*< private >*/
77 gpointer _reserved1;
78 gpointer _reserved2;
79 } LXPanelPluginInit; /* constant data */
80
81 extern LXPanelPluginInit fm_module_init_lxpanel_gtk;
82
83 extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
84 /**
85 * lxpanel_plugin_get_data
86 * @_i: instance widget
87 *
88 * Retrieves instance data attached to the widget.
89 */
90 #define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
91 /**
92 * lxpanel_plugin_set_data
93 * @_i: instance widget
94 * @_data: instance data
95 * @_destructor: destructor for @_data
96 *
97 * Attaches data to the widget instance. The @_destructor callback will
98 * be called on @_data when @_i is destroyed and therefore it should free
99 * any allocated data. The instance widget at that moment is already not
100 * available to use in any way so not rely on it.
101 */
102 #define lxpanel_plugin_set_data(_i,_data,_destructor) g_object_set_qdata_full(G_OBJECT(_i),lxpanel_plugin_qdata,_data,_destructor)
103
104 /* register new plugin type - can be called from plugins init() too */
105 extern gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init);
106
107 /* few helper functions */
108 extern GtkMenu* lxpanel_get_plugin_menu(Panel* panel, GtkWidget* plugin, gboolean use_sub_menu);
109 extern gboolean lxpanel_plugin_button_press_event(GtkWidget *plugin, GdkEventButton *event, Panel *panel);
110 /* Handler for "button_press_event" signal with Plugin as parameter */
111 extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
112 /* Helper to move popup windows away from the panel */
113 extern void lxpanel_plugin_popup_set_position_helper(Panel * p, GtkWidget * near, GtkWidget * popup, GtkRequisition * popup_req, gint * px, gint * py);
114 /* Helper for position-calculation callback for popup menus */
115 extern void plugin_widget_set_background(GtkWidget * plugin, Panel * p);
116 /* Recursively set the background of all widgets on a panel background configuration change */
117 extern gboolean lxpanel_launch_path(Panel *panel, FmPath *path);
118
119 G_END_DECLS
120
121 #endif /* __PLUGIN_H__ */