2 * pluginutils.c - this file is part of Geany, a fast and lightweight IDE
4 * Copyright 2009-2012 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
5 * Copyright 2009-2012 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License along
18 * with this program; if not, write to the Free Software Foundation, Inc.,
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 /** @file pluginutils.h
23 * Plugin utility functions.
24 * These functions all take the @ref geany_plugin symbol as their first argument. */
32 #include "pluginutils.h"
35 #include "geanyobject.h"
36 #include "keybindings.h"
37 #include "keybindingsprivate.h"
38 #include "plugindata.h"
39 #include "pluginprivate.h"
47 /** Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item.
48 * A separator is added on the first call to this function, and will be shown when @a item is
49 * shown; hidden when @a item is hidden.
50 * @note You should still destroy @a item yourself, usually in @ref plugin_cleanup().
51 * @param plugin Must be @ref geany_plugin.
52 * @param item The item to add. */
54 void plugin_add_toolbar_item(GeanyPlugin
*plugin
, GtkToolItem
*item
)
56 GtkToolbar
*toolbar
= GTK_TOOLBAR(main_widgets
.toolbar
);
58 GeanyAutoSeparator
*autosep
;
60 g_return_if_fail(plugin
);
61 autosep
= &plugin
->priv
->toolbar_separator
;
67 pos
= toolbar_get_insert_position();
69 sep
= gtk_separator_tool_item_new();
70 gtk_toolbar_insert(toolbar
, sep
, pos
);
71 autosep
->widget
= GTK_WIDGET(sep
);
73 toolbar_item_ref(sep
);
77 pos
= gtk_toolbar_get_item_index(toolbar
, GTK_TOOL_ITEM(autosep
->widget
));
78 g_return_if_fail(pos
>= 0);
81 gtk_toolbar_insert(toolbar
, item
, pos
+ autosep
->item_count
+ 1);
82 toolbar_item_ref(item
);
84 /* hide the separator widget if there are no toolbar items showing for the plugin */
85 ui_auto_separator_add_ref(autosep
, GTK_WIDGET(item
));
89 /** Ensures that a plugin's module (*.so) will never be unloaded.
90 * This is necessary if you register new GTypes in your plugin, e.g. when using own classes
91 * using the GObject system.
93 * @param plugin Must be @ref geany_plugin.
98 void plugin_module_make_resident(GeanyPlugin
*plugin
)
100 g_return_if_fail(plugin
);
101 plugin_make_resident(plugin
->priv
);
105 /** Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
106 * @param plugin Must be @ref geany_plugin.
107 * @param object Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink.
108 * @param signal_name The name of the signal. For a list of available
109 * signals, please see the @link pluginsignals.c Signal documentation @endlink.
110 * @param after Set to @c TRUE to call your handler after the main signal handlers have been called
111 * (if supported by @a signal_name).
112 * @param callback The function to call when the signal is emitted.
113 * @param user_data The user data passed to the signal handler.
114 * @see plugin_callbacks.
116 * @warning Before version 1.25 (API < 218),
117 * this should only be used on objects that outlive the plugin, never on
118 * objects that will get destroyed before the plugin is unloaded. For objects
119 * created and destroyed by the plugin, you can simply use @c g_signal_connect(),
120 * since all handlers are disconnected when the object is destroyed anyway.
121 * For objects that may or may not outlive the plugin (like @link GeanyEditor.sci
122 * a document's @c ScintillaObject @endlink, which is destroyed when the document
123 * is closed), you currently have to manually handle both situations, when the
124 * plugin is unloaded before the object is destroyed (and then, you have to
125 * disconnect the signal on @c plugin_cleanup()), and when the object is destroyed
126 * during the plugin's lifetime (in which case you cannot and should not disconnect
127 * manually in @c plugin_cleanup() since it already has been disconnected and the
128 * object has been destroyed), and disconnect yourself or not as appropriate.
129 * @note Since version 1.25 (API >= 218), the object lifetime is watched and so the above
130 * restriction does not apply. However, for objects destroyed by the plugin,
131 * @c g_signal_connect() is safe and has lower overhead. */
133 void plugin_signal_connect(GeanyPlugin
*plugin
,
134 GObject
*object
, const gchar
*signal_name
, gboolean after
,
135 GCallback callback
, gpointer user_data
)
140 g_return_if_fail(plugin
!= NULL
);
141 g_return_if_fail(object
== NULL
|| G_IS_OBJECT(object
));
144 object
= geany_object
;
147 g_signal_connect_after(object
, signal_name
, callback
, user_data
) :
148 g_signal_connect(object
, signal_name
, callback
, user_data
);
150 if (!plugin
->priv
->signal_ids
)
151 plugin
->priv
->signal_ids
= g_array_new(FALSE
, FALSE
, sizeof(SignalConnection
));
155 g_array_append_val(plugin
->priv
->signal_ids
, sc
);
157 /* watch the object lifetime to nuke our pointers to it */
158 plugin_watch_object(plugin
->priv
, object
);
162 typedef struct PluginSourceData
165 GList list_link
; /* element of plugin->sources cointaining this GSource */
166 GSourceFunc function
;
171 /* prepend psd->list_link to psd->plugin->sources */
172 static void psd_register(PluginSourceData
*psd
, GSource
*source
)
174 psd
->list_link
.data
= source
;
175 psd
->list_link
.prev
= NULL
;
176 psd
->list_link
.next
= psd
->plugin
->sources
;
177 if (psd
->list_link
.next
)
178 psd
->list_link
.next
->prev
= &psd
->list_link
;
179 psd
->plugin
->sources
= &psd
->list_link
;
183 /* removes psd->list_link from psd->plugin->sources */
184 static void psd_unregister(PluginSourceData
*psd
)
186 if (psd
->list_link
.next
)
187 psd
->list_link
.next
->prev
= psd
->list_link
.prev
;
188 if (psd
->list_link
.prev
)
189 psd
->list_link
.prev
->next
= psd
->list_link
.next
;
190 else /* we were the first of the list, update the plugin->sources pointer */
191 psd
->plugin
->sources
= psd
->list_link
.next
;
195 static void on_plugin_source_destroy(gpointer data
)
197 PluginSourceData
*psd
= data
;
200 g_slice_free1(sizeof *psd
, psd
);
204 static gboolean
on_plugin_source_callback(gpointer data
)
206 PluginSourceData
*psd
= data
;
208 return psd
->function(psd
->user_data
);
212 /* adds the given source to the default GMainContext and to the list of sources to remove at plugin
214 static guint
plugin_source_add(GeanyPlugin
*plugin
, GSource
*source
, GSourceFunc func
, gpointer data
)
217 PluginSourceData
*psd
= g_slice_alloc(sizeof *psd
);
219 psd
->plugin
= plugin
->priv
;
220 psd
->function
= func
;
221 psd
->user_data
= data
;
223 g_source_set_callback(source
, on_plugin_source_callback
, psd
, on_plugin_source_destroy
);
224 psd_register(psd
, source
);
225 id
= g_source_attach(source
, NULL
);
226 g_source_unref(source
);
232 /** Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
233 * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
235 * @param plugin Must be @ref geany_plugin.
236 * @param interval The time between calls to the function, in milliseconds.
237 * @param function The function to call after the given timeout.
238 * @param data The user data passed to the function.
239 * @return the ID of the event source (you generally won't need it, or better use g_timeout_add()
240 * directly if you want to manage this event source manually).
242 * @see g_timeout_add()
243 * @since 0.21, plugin API 205.
246 guint
plugin_timeout_add(GeanyPlugin
*plugin
, guint interval
, GSourceFunc function
, gpointer data
)
248 return plugin_source_add(plugin
, g_timeout_source_new(interval
), function
, data
);
252 /** Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
253 * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
255 * @param plugin Must be @ref geany_plugin.
256 * @param interval The time between calls to the function, in seconds.
257 * @param function The function to call after the given timeout.
258 * @param data The user data passed to the function.
259 * @return the ID of the event source (you generally won't need it, or better use
260 * g_timeout_add_seconds() directly if you want to manage this event source manually).
262 * @see g_timeout_add_seconds()
263 * @since 0.21, plugin API 205.
266 guint
plugin_timeout_add_seconds(GeanyPlugin
*plugin
, guint interval
, GSourceFunc function
,
269 return plugin_source_add(plugin
, g_timeout_source_new_seconds(interval
), function
, data
);
273 /** Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing
274 * it to run after the plugin has been unloaded (which may lead to a segfault).
276 * @param plugin Must be @ref geany_plugin.
277 * @param function The function to call in IDLE time.
278 * @param data The user data passed to the function.
279 * @return the ID of the event source (you generally won't need it, or better use g_idle_add()
280 * directly if you want to manage this event source manually).
283 * @since 0.21, plugin API 205.
286 guint
plugin_idle_add(GeanyPlugin
*plugin
, GSourceFunc function
, gpointer data
)
288 return plugin_source_add(plugin
, g_idle_source_new(), function
, data
);
292 /** Sets up or resizes a keybinding group for the plugin.
293 * You should then call keybindings_set_item() for each keybinding in the group.
294 * @param plugin Must be @ref geany_plugin.
295 * @param section_name Name used in the configuration file, such as @c "html_chars".
296 * @param count Number of keybindings for the group.
297 * @param callback Group callback, or @c NULL if you only want individual keybinding callbacks.
298 * @return The plugin's keybinding group.
301 GeanyKeyGroup
*plugin_set_key_group(GeanyPlugin
*plugin
,
302 const gchar
*section_name
, gsize count
, GeanyKeyGroupCallback callback
)
304 Plugin
*priv
= plugin
->priv
;
306 priv
->key_group
= keybindings_set_group(priv
->key_group
, section_name
,
307 priv
->info
.name
, count
, callback
);
308 return priv
->key_group
;
311 /** Sets up or resizes a keybinding group for the plugin
313 * You should then call keybindings_set_item() or keybindings_set_item_full() for each
314 * keybinding in the group.
315 * @param plugin Must be @ref geany_plugin.
316 * @param section_name Name used in the configuration file, such as @c "html_chars".
317 * @param count Number of keybindings for the group.
318 * @param cb New-style group callback, or @c NULL if you only want individual keybinding callbacks.
319 * @param pdata Plugin specific data, passed to the group callback.
320 * @param destroy_notify Function that is invoked to free the plugin data when not needed anymore.
321 * @return The plugin's keybinding group.
323 * @since 1.26 (API 226)
324 * @see See keybindings_set_item
325 * @see See keybindings_set_item_full
328 GeanyKeyGroup
*plugin_set_key_group_full(GeanyPlugin
*plugin
,
329 const gchar
*section_name
, gsize count
,
330 GeanyKeyGroupFunc cb
, gpointer pdata
, GDestroyNotify destroy_notify
)
332 GeanyKeyGroup
*group
;
334 group
= plugin_set_key_group(plugin
, section_name
, count
, NULL
);
336 group
->cb_data
= pdata
;
337 group
->cb_data_destroy
= destroy_notify
;
343 static void on_pref_btn_clicked(gpointer btn
, Plugin
*p
)
345 p
->configure_single(main_widgets
.window
);
349 static GtkWidget
*create_pref_page(Plugin
*p
, GtkWidget
*dialog
)
351 GtkWidget
*page
= NULL
; /* some plugins don't have prefs */
353 if (p
->cbs
.configure
)
355 page
= p
->cbs
.configure(&p
->public, GTK_DIALOG(dialog
), p
->cb_data
);
356 if (! GTK_IS_WIDGET(page
))
358 geany_debug("Invalid widget returned from plugin_configure() in plugin \"%s\"!",
364 GtkWidget
*align
= gtk_alignment_new(0.5, 0.5, 1, 1);
366 gtk_alignment_set_padding(GTK_ALIGNMENT(align
), 6, 6, 6, 6);
367 gtk_container_add(GTK_CONTAINER(align
), page
);
368 page
= gtk_vbox_new(FALSE
, 0);
369 gtk_box_pack_start(GTK_BOX(page
), align
, TRUE
, TRUE
, 0);
372 else if (p
->configure_single
)
374 GtkWidget
*align
= gtk_alignment_new(0.5, 0.5, 0, 0);
377 gtk_alignment_set_padding(GTK_ALIGNMENT(align
), 6, 6, 6, 6);
379 btn
= gtk_button_new_from_stock(GTK_STOCK_PREFERENCES
);
380 g_signal_connect(btn
, "clicked", G_CALLBACK(on_pref_btn_clicked
), p
);
381 gtk_container_add(GTK_CONTAINER(align
), btn
);
388 /* multiple plugin configure dialog
389 * current_plugin can be NULL */
390 static void configure_plugins(Plugin
*current_plugin
)
392 GtkWidget
*dialog
, *vbox
, *nb
;
396 dialog
= gtk_dialog_new_with_buttons(_("Configure Plugins"),
397 GTK_WINDOW(main_widgets
.window
), GTK_DIALOG_DESTROY_WITH_PARENT
,
398 GTK_STOCK_APPLY
, GTK_RESPONSE_APPLY
,
399 GTK_STOCK_CANCEL
, GTK_RESPONSE_CANCEL
,
400 GTK_STOCK_OK
, GTK_RESPONSE_OK
, NULL
);
401 gtk_widget_set_name(dialog
, "GeanyDialog");
403 vbox
= ui_dialog_vbox_new(GTK_DIALOG(dialog
));
404 nb
= gtk_notebook_new();
405 gtk_notebook_set_scrollable(GTK_NOTEBOOK(nb
), TRUE
);
406 gtk_box_pack_start(GTK_BOX(vbox
), nb
, TRUE
, TRUE
, 0);
408 foreach_list(node
, active_plugin_list
)
410 Plugin
*p
= node
->data
;
411 GtkWidget
*page
= create_pref_page(p
, dialog
);
415 GtkWidget
*label
= gtk_label_new(p
->info
.name
);
416 gint n
= gtk_notebook_append_page(GTK_NOTEBOOK(nb
), page
, label
);
418 if (p
== current_plugin
)
422 if (gtk_notebook_get_n_pages(GTK_NOTEBOOK(nb
)))
424 gtk_widget_show_all(vbox
);
426 gtk_notebook_set_current_page(GTK_NOTEBOOK(nb
), cur_page
);
429 while (gtk_dialog_run(GTK_DIALOG(dialog
)) == GTK_RESPONSE_APPLY
);
434 gtk_widget_destroy(dialog
);
438 /** Shows the plugin's configure dialog.
439 * The plugin must implement one of the plugin_configure() or plugin_configure_single() symbols.
440 * @param plugin Must be @ref geany_plugin.
442 /* if NULL, show all plugins */
444 void plugin_show_configure(GeanyPlugin
*plugin
)
450 configure_plugins(NULL
);
455 if (p
->cbs
.configure
)
456 configure_plugins(p
);
459 g_return_if_fail(p
->configure_single
);
460 p
->configure_single(main_widgets
.window
);
465 struct BuilderConnectData
472 static void connect_plugin_signals(GtkBuilder
*builder
, GObject
*object
,
473 const gchar
*signal_name
, const gchar
*handler_name
,
474 GObject
*connect_object
, GConnectFlags flags
, gpointer user_data
)
476 gpointer symbol
= NULL
;
477 struct BuilderConnectData
*data
= user_data
;
479 symbol
= plugin_get_module_symbol(data
->plugin
->priv
, handler_name
);
481 plugin_signal_connect(data
->plugin
, object
, signal_name
, FALSE
,
482 G_CALLBACK(symbol
) /*ub?*/, data
->user_data
);
487 * Allows auto-connecting Glade/GtkBuilder signals in plugins.
489 * When a plugin uses GtkBuilder to load some UI from file/string,
490 * the gtk_builder_connect_signals() function is unable to automatically
491 * connect to the plugin's signal handlers. A plugin could itself use
492 * the gtk_builder_connect_signals_full() function to automatically
493 * connect to the signal handler functions by loading it's GModule
494 * and retrieving pointers to the handler functions, but rather than
495 * each plugin having to do that, this function handles it automatically.
499 * GeanyPlugin *geany_plugin;
501 * G_MODULE_EXPORT void
502 * myplugin_button_clicked(GtkButton *button, gpointer user_data)
504 * g_print("Button pressed\n");
507 * void plugin_init(GeanyData *data)
509 * GtkBuilder *builder = gtk_builder_new();
510 * gtk_builder_add_from_file(builder, "gui.glade", NULL);
511 * plugin_builder_connect_signals(geany_plugin, builder, NULL);
516 * @note It's important that you prefix your callback handlers with
517 * a plugin-specific prefix to avoid clashing with other plugins since
518 * the function symbols will be exported process-wide.
520 * @param plugin Must be @ref geany_plugin.
521 * @param builder The GtkBuilder to connect signals with.
522 * @param user_data User data to pass to the connected signal handlers.
524 * @since 1.24, plugin API 217.
527 void plugin_builder_connect_signals(GeanyPlugin
*plugin
,
528 GtkBuilder
*builder
, gpointer user_data
)
530 struct BuilderConnectData data
= { NULL
};
532 g_return_if_fail(plugin
!= NULL
&& plugin
->priv
!= NULL
);
533 g_return_if_fail(GTK_IS_BUILDER(builder
));
535 data
.user_data
= user_data
;
536 data
.plugin
= plugin
;
538 gtk_builder_connect_signals_full(builder
, connect_plugin_signals
, &data
);
542 /** Add additional data that corresponds to the plugin.
544 * @p pdata is the pointer going to be passed to the individual plugin callbacks
545 * of GeanyPlugin::funcs. When the plugin is cleaned up, @p free_func is invoked for the data,
546 * which connects the data to the time the plugin is enabled.
548 * One intended use case is to set GObjects as data and have them destroyed automatically
549 * by passing g_object_unref() as @a free_func, so that member functions can be used
550 * for the @ref GeanyPluginFuncs (via wrappers) but you can set completely custom data.
552 * Be aware that this can only be called once and only by plugins registered via
553 * @ref geany_plugin_register(). So-called legacy plugins cannot use this function.
555 * @note This function must not be called if the plugin was registered with
556 * geany_plugin_register_full().
558 * @param plugin The plugin provided by Geany
559 * @param pdata The plugin's data to associate, must not be @c NULL
560 * @param free_func The destroy notify
562 * @since 1.26 (API 225)
565 void geany_plugin_set_data(GeanyPlugin
*plugin
, gpointer pdata
, GDestroyNotify free_func
)
567 Plugin
*p
= plugin
->priv
;
569 g_return_if_fail(PLUGIN_LOADED_OK(p
));
570 /* Do not allow calling this only to set a notify. */
571 g_return_if_fail(pdata
!= NULL
);
572 /* The rationale to allow only setting the data once is the following:
573 * In the future we want to support proxy plugins (which bind non-C plugins to
574 * Geany's plugin api). These proxy plugins might need to own the data pointer
575 * on behalf of the proxied plugin. However, if not, then the plugin should be
576 * free to use it. This way we can make sure the plugin doesn't accidently trash
579 * Better a more limited API now that can be opened up later than a potentially
580 * wrong one that can only be replaced by another one. */
581 if (p
->cb_data
!= NULL
|| p
->cb_data_destroy
!= NULL
)
583 if (PLUGIN_HAS_LOAD_DATA(p
))
584 g_warning("Invalid call to %s(), geany_plugin_register_full() was used. Ignored!\n", G_STRFUNC
);
586 g_warning("Double call to %s(), ignored!", G_STRFUNC
);
591 p
->cb_data_destroy
= free_func
;