Add a callback into plugin init struct for panel context menu update.
[lxde/lxpanel.git] / src / plugin.h
CommitLineData
17fab6e5
AG
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
27G_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
e56f2fdd 33/**
4c38fa66 34 * LXPanelPluginInit:
e56f2fdd
AG
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
dd731fde 43 * @show_system_menu: (allow-none): callback to queue show system menu
4c38fa66
AG
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
131514c9
AG
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().
4c38fa66
AG
61 *
62 * Callback @reconfigure is called when panel configuration was changed
9c843a52
AG
63 * in the panel configuration dialog so the instance may change layout of
64 * own subwidgets appropriately to new geometry.
eb1762e5
AG
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.
e56f2fdd 73 */
17fab6e5
AG
74typedef 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);
131514c9 81 GtkWidget *(*config)(Panel *panel, GtkWidget *instance, GtkWindow *parent);
17fab6e5 82 void (*reconfigure)(Panel *panel, GtkWidget *instance);
e56f2fdd 83 gboolean (*button_press_event)(GtkWidget *widget, GdkEventButton *event, Panel *panel);
dd731fde 84 void (*show_system_menu)(GtkWidget *widget);
eb1762e5 85 gboolean (*update_context_menu)(GtkWidget *plugin, GtkMenu *menu);
17fab6e5
AG
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 */
ae4e6dc6 89 int superseded : 1; /* True if plugin was superseded by another */
17fab6e5
AG
90 /*< private >*/
91 gpointer _reserved1;
92 gpointer _reserved2;
93} LXPanelPluginInit; /* constant data */
94
95extern LXPanelPluginInit fm_module_init_lxpanel_gtk;
96
97extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
4c38fa66
AG
98/**
99 * lxpanel_plugin_get_data
100 * @_i: instance widget
101 *
102 * Retrieves instance data attached to the widget.
103 */
17fab6e5 104#define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
4c38fa66
AG
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 */
17fab6e5
AG
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 */
119extern gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init);
120
121/* few helper functions */
122extern GtkMenu* lxpanel_get_plugin_menu(Panel* panel, GtkWidget* plugin, gboolean use_sub_menu);
e56f2fdd 123extern gboolean lxpanel_plugin_button_press_event(GtkWidget *plugin, GdkEventButton *event, Panel *panel);
17fab6e5
AG
124 /* Handler for "button_press_event" signal with Plugin as parameter */
125extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
126 /* Helper to move popup windows away from the panel */
127extern void lxpanel_plugin_popup_set_position_helper(Panel * p, GtkWidget * near, GtkWidget * popup, GtkRequisition * popup_req, gint * px, gint * py);
128 /* Helper for position-calculation callback for popup menus */
129extern void plugin_widget_set_background(GtkWidget * plugin, Panel * p);
130 /* Recursively set the background of all widgets on a panel background configuration change */
3b847d8b 131extern gboolean lxpanel_launch_path(Panel *panel, FmPath *path);
131514c9
AG
132extern void lxpanel_plugin_show_config_dialog(Panel* panel, GtkWidget* plugin);
133 /* Calls config() callback and shows configuration window */
17fab6e5
AG
134
135G_END_DECLS
136
137#endif /* __PLUGIN_H__ */