Re-enable SIGTERM handling
[geany-mirror.git] / src / pluginutils.c
blob1e431cfb801ce65d0279fae858c2b57acf2ebf7b
1 /*
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. */
26 #ifdef HAVE_CONFIG_H
27 # include "config.h"
28 #endif
30 #ifdef HAVE_PLUGINS
32 #include "pluginutils.h"
34 #include "app.h"
35 #include "geanyobject.h"
36 #include "keybindings.h"
37 #include "keybindingsprivate.h"
38 #include "plugindata.h"
39 #include "pluginprivate.h"
40 #include "plugins.h"
41 #include "support.h"
42 #include "toolbar.h"
43 #include "ui_utils.h"
44 #include "utils.h"
47 typedef struct
49 gpointer data;
50 GDestroyNotify free_func;
52 PluginDocDataProxy;
55 /** Returns the runtime API version Geany was compiled with.
57 * Unlike @ref GEANY_API_VERSION this version is the value of that
58 * define at the time when Geany itself was compiled. This allows to
59 * establish soft dependencies which are resolved at runtime depending
60 * on Geany's API version.
62 * @return Geany's API version
63 * @since 1.30 (API 231)
64 **/
65 GEANY_API_SYMBOL
66 gint geany_api_version(void)
68 return GEANY_API_VERSION;
71 /** Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item.
72 * A separator is added on the first call to this function, and will be shown when @a item is
73 * shown; hidden when @a item is hidden.
74 * @note You should still destroy @a item yourself, usually in @ref plugin_cleanup().
75 * @param plugin Must be @ref geany_plugin.
76 * @param item The item to add. */
77 GEANY_API_SYMBOL
78 void plugin_add_toolbar_item(GeanyPlugin *plugin, GtkToolItem *item)
80 GtkToolbar *toolbar = GTK_TOOLBAR(main_widgets.toolbar);
81 gint pos;
82 GeanyAutoSeparator *autosep;
84 g_return_if_fail(plugin);
85 autosep = &plugin->priv->toolbar_separator;
87 if (!autosep->widget)
89 GtkToolItem *sep;
91 pos = toolbar_get_insert_position();
93 sep = gtk_separator_tool_item_new();
94 gtk_toolbar_insert(toolbar, sep, pos);
95 autosep->widget = GTK_WIDGET(sep);
97 toolbar_item_ref(sep);
99 else
101 pos = gtk_toolbar_get_item_index(toolbar, GTK_TOOL_ITEM(autosep->widget));
102 g_return_if_fail(pos >= 0);
105 gtk_toolbar_insert(toolbar, item, pos + autosep->item_count + 1);
106 toolbar_item_ref(item);
108 /* hide the separator widget if there are no toolbar items showing for the plugin */
109 ui_auto_separator_add_ref(autosep, GTK_WIDGET(item));
113 /** Ensures that a plugin's module (*.so) will never be unloaded.
114 * This is necessary if you register new GTypes in your plugin, e.g. when using own classes
115 * using the GObject system.
117 * @param plugin Must be @ref geany_plugin.
119 * @since 0.16
121 GEANY_API_SYMBOL
122 void plugin_module_make_resident(GeanyPlugin *plugin)
124 g_return_if_fail(plugin);
125 plugin_make_resident(plugin->priv);
129 /** @girskip
130 * Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
131 * @param plugin Must be @ref geany_plugin.
132 * @param object @nullable Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink.
133 * @param signal_name The name of the signal. For a list of available
134 * signals, please see the @link pluginsignals.c Signal documentation @endlink.
135 * @param after Set to @c TRUE to call your handler after the main signal handlers have been called
136 * (if supported by @a signal_name).
137 * @param callback The function to call when the signal is emitted.
138 * @param user_data The user data passed to the signal handler.
139 * @see plugin_callbacks.
141 * @warning Before version 1.25 (API < 218),
142 * this should only be used on objects that outlive the plugin, never on
143 * objects that will get destroyed before the plugin is unloaded. For objects
144 * created and destroyed by the plugin, you can simply use @c g_signal_connect(),
145 * since all handlers are disconnected when the object is destroyed anyway.
146 * For objects that may or may not outlive the plugin (like @link GeanyEditor.sci
147 * a document's @c ScintillaObject @endlink, which is destroyed when the document
148 * is closed), you currently have to manually handle both situations, when the
149 * plugin is unloaded before the object is destroyed (and then, you have to
150 * disconnect the signal on @c plugin_cleanup()), and when the object is destroyed
151 * during the plugin's lifetime (in which case you cannot and should not disconnect
152 * manually in @c plugin_cleanup() since it already has been disconnected and the
153 * object has been destroyed), and disconnect yourself or not as appropriate.
154 * @note Since version 1.25 (API >= 218), the object lifetime is watched and so the above
155 * restriction does not apply. However, for objects destroyed by the plugin,
156 * @c g_signal_connect() is safe and has lower overhead.
158 GEANY_API_SYMBOL
159 void plugin_signal_connect(GeanyPlugin *plugin,
160 GObject *object, const gchar *signal_name, gboolean after,
161 GCallback callback, gpointer user_data)
163 gulong id;
164 SignalConnection sc;
166 g_return_if_fail(plugin != NULL);
167 g_return_if_fail(object == NULL || G_IS_OBJECT(object));
169 if (!object)
170 object = geany_object;
172 id = after ?
173 g_signal_connect_after(object, signal_name, callback, user_data) :
174 g_signal_connect(object, signal_name, callback, user_data);
176 if (!plugin->priv->signal_ids)
177 plugin->priv->signal_ids = g_array_new(FALSE, FALSE, sizeof(SignalConnection));
179 sc.object = object;
180 sc.handler_id = id;
181 g_array_append_val(plugin->priv->signal_ids, sc);
183 /* watch the object lifetime to nuke our pointers to it */
184 plugin_watch_object(plugin->priv, object);
188 typedef struct PluginSourceData
190 Plugin *plugin;
191 GList list_link; /* element of plugin->sources cointaining this GSource */
192 GSourceFunc function;
193 gpointer user_data;
194 } PluginSourceData;
197 /* prepend psd->list_link to psd->plugin->sources */
198 static void psd_register(PluginSourceData *psd, GSource *source)
200 psd->list_link.data = source;
201 psd->list_link.prev = NULL;
202 psd->list_link.next = psd->plugin->sources;
203 if (psd->list_link.next)
204 psd->list_link.next->prev = &psd->list_link;
205 psd->plugin->sources = &psd->list_link;
209 /* removes psd->list_link from psd->plugin->sources */
210 static void psd_unregister(PluginSourceData *psd)
212 if (psd->list_link.next)
213 psd->list_link.next->prev = psd->list_link.prev;
214 if (psd->list_link.prev)
215 psd->list_link.prev->next = psd->list_link.next;
216 else /* we were the first of the list, update the plugin->sources pointer */
217 psd->plugin->sources = psd->list_link.next;
221 static void on_plugin_source_destroy(gpointer data)
223 PluginSourceData *psd = data;
225 psd_unregister(psd);
226 g_slice_free1(sizeof *psd, psd);
230 static gboolean on_plugin_source_callback(gpointer data)
232 PluginSourceData *psd = data;
234 return psd->function(psd->user_data);
238 /* adds the given source to the default GMainContext and to the list of sources to remove at plugin
239 * unloading time */
240 static guint plugin_source_add(GeanyPlugin *plugin, GSource *source, GSourceFunc func, gpointer data)
242 guint id;
243 PluginSourceData *psd = g_slice_alloc(sizeof *psd);
245 psd->plugin = plugin->priv;
246 psd->function = func;
247 psd->user_data = data;
249 g_source_set_callback(source, on_plugin_source_callback, psd, on_plugin_source_destroy);
250 psd_register(psd, source);
251 id = g_source_attach(source, NULL);
252 g_source_unref(source);
254 return id;
258 /** @girskip
259 * Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
260 * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
262 * @param plugin Must be @ref geany_plugin.
263 * @param interval The time between calls to the function, in milliseconds.
264 * @param function The function to call after the given timeout.
265 * @param data The user data passed to the function.
266 * @return the ID of the event source (you generally won't need it, or better use g_timeout_add()
267 * directly if you want to manage this event source manually).
269 * @see g_timeout_add()
270 * @since 0.21, plugin API 205.
272 GEANY_API_SYMBOL
273 guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc function, gpointer data)
275 return plugin_source_add(plugin, g_timeout_source_new(interval), function, data);
279 /** @girskip
280 * Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
281 * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
283 * @param plugin Must be @ref geany_plugin.
284 * @param interval The time between calls to the function, in seconds.
285 * @param function The function to call after the given timeout.
286 * @param data The user data passed to the function.
287 * @return the ID of the event source (you generally won't need it, or better use
288 * g_timeout_add_seconds() directly if you want to manage this event source manually).
290 * @see g_timeout_add_seconds()
291 * @since 0.21, plugin API 205.
293 GEANY_API_SYMBOL
294 guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFunc function,
295 gpointer data)
297 return plugin_source_add(plugin, g_timeout_source_new_seconds(interval), function, data);
301 /** @girskip
302 * Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing
303 * it to run after the plugin has been unloaded (which may lead to a segfault).
305 * @param plugin Must be @ref geany_plugin.
306 * @param function The function to call in IDLE time.
307 * @param data The user data passed to the function.
308 * @return the ID of the event source (you generally won't need it, or better use g_idle_add()
309 * directly if you want to manage this event source manually).
311 * @see g_idle_add()
312 * @since 0.21, plugin API 205.
314 GEANY_API_SYMBOL
315 guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
317 return plugin_source_add(plugin, g_idle_source_new(), function, data);
321 /** @girskip
322 * Sets up or resizes a keybinding group for the plugin.
323 * You should then call keybindings_set_item() for each keybinding in the group.
324 * @param plugin Must be @ref geany_plugin.
325 * @param section_name Name of the section used for this group in the keybindings configuration file, i.e. @c "html_chars".
326 * @param count Number of keybindings for the group.
327 * @param callback @nullable Group callback, or @c NULL if you only want individual keybinding callbacks.
328 * @return The plugin's keybinding group.
329 * @since 0.19.
331 GEANY_API_SYMBOL
332 GeanyKeyGroup *plugin_set_key_group(GeanyPlugin *plugin,
333 const gchar *section_name, gsize count, GeanyKeyGroupCallback callback)
335 Plugin *priv = plugin->priv;
337 priv->key_group = keybindings_set_group(priv->key_group, section_name,
338 priv->info.name, count, callback);
339 return priv->key_group;
342 /** Sets up or resizes a keybinding group for the plugin
344 * You should then call keybindings_set_item() or keybindings_set_item_full() for each
345 * keybinding in the group.
346 * @param plugin Must be @ref geany_plugin.
347 * @param section_name Name of the section used for this group in the keybindings configuration file, i.e. @c "html_chars".
348 * @param count Number of keybindings for the group.
349 * @param cb @nullable New-style group callback, or @c NULL if you only want individual keybinding callbacks.
350 * @param pdata Plugin specific data, passed to the group callback @a cb.
351 * @param destroy_notify Function that is invoked to free the plugin data when not needed anymore.
352 * @return @transfer{none} The plugin's keybinding group.
354 * @since 1.26 (API 226)
355 * @see See keybindings_set_item
356 * @see See keybindings_set_item_full
358 GEANY_API_SYMBOL
359 GeanyKeyGroup *plugin_set_key_group_full(GeanyPlugin *plugin,
360 const gchar *section_name, gsize count,
361 GeanyKeyGroupFunc cb, gpointer pdata, GDestroyNotify destroy_notify)
363 GeanyKeyGroup *group;
365 group = plugin_set_key_group(plugin, section_name, count, NULL);
366 group->cb_func = cb;
367 group->cb_data = pdata;
368 group->cb_data_destroy = destroy_notify;
370 return group;
374 static void on_pref_btn_clicked(gpointer btn, Plugin *p)
376 p->configure_single(main_widgets.window);
380 static GtkWidget *create_pref_page(Plugin *p, GtkWidget *dialog)
382 GtkWidget *page = NULL; /* some plugins don't have prefs */
384 if (p->cbs.configure)
386 page = p->cbs.configure(&p->public, GTK_DIALOG(dialog), p->cb_data);
387 if (! GTK_IS_WIDGET(page))
389 geany_debug("Invalid widget returned from plugin_configure() in plugin \"%s\"!",
390 p->info.name);
391 return NULL;
393 else
395 GtkWidget *align = gtk_alignment_new(0.5, 0.5, 1, 1);
397 gtk_alignment_set_padding(GTK_ALIGNMENT(align), 6, 6, 6, 6);
398 gtk_container_add(GTK_CONTAINER(align), page);
399 page = gtk_vbox_new(FALSE, 0);
400 gtk_box_pack_start(GTK_BOX(page), align, TRUE, TRUE, 0);
403 else if (p->configure_single)
405 GtkWidget *align = gtk_alignment_new(0.5, 0.5, 0, 0);
406 GtkWidget *btn;
408 gtk_alignment_set_padding(GTK_ALIGNMENT(align), 6, 6, 6, 6);
410 btn = gtk_button_new_from_stock(GTK_STOCK_PREFERENCES);
411 g_signal_connect(btn, "clicked", G_CALLBACK(on_pref_btn_clicked), p);
412 gtk_container_add(GTK_CONTAINER(align), btn);
413 page = align;
415 return page;
419 /* multiple plugin configure dialog
420 * current_plugin can be NULL */
421 static void configure_plugins(Plugin *current_plugin)
423 GtkWidget *dialog, *vbox, *nb;
424 GList *node;
425 gint cur_page = -1;
427 dialog = gtk_dialog_new_with_buttons(_("Configure Plugins"),
428 GTK_WINDOW(main_widgets.window), GTK_DIALOG_DESTROY_WITH_PARENT,
429 GTK_STOCK_APPLY, GTK_RESPONSE_APPLY,
430 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
431 GTK_STOCK_OK, GTK_RESPONSE_OK, NULL);
432 gtk_widget_set_name(dialog, "GeanyDialog");
434 vbox = ui_dialog_vbox_new(GTK_DIALOG(dialog));
435 nb = gtk_notebook_new();
436 gtk_notebook_set_scrollable(GTK_NOTEBOOK(nb), TRUE);
437 gtk_box_pack_start(GTK_BOX(vbox), nb, TRUE, TRUE, 0);
439 foreach_list(node, active_plugin_list)
441 Plugin *p = node->data;
442 GtkWidget *page = create_pref_page(p, dialog);
444 if (page)
446 GtkWidget *label = gtk_label_new(p->info.name);
447 gint n = gtk_notebook_append_page(GTK_NOTEBOOK(nb), page, label);
449 if (p == current_plugin)
450 cur_page = n;
453 if (gtk_notebook_get_n_pages(GTK_NOTEBOOK(nb)))
455 gtk_widget_show_all(vbox);
456 if (cur_page >= 0)
457 gtk_notebook_set_current_page(GTK_NOTEBOOK(nb), cur_page);
459 /* run the dialog */
460 while (gtk_dialog_run(GTK_DIALOG(dialog)) == GTK_RESPONSE_APPLY);
462 else
463 utils_beep();
465 gtk_widget_destroy(dialog);
469 /** Shows the plugin's configure dialog.
470 * The plugin must implement one of the plugin_configure() or plugin_configure_single() symbols.
471 * @param plugin Must be @ref geany_plugin.
472 * @since 0.19. */
473 /* if NULL, show all plugins */
474 GEANY_API_SYMBOL
475 void plugin_show_configure(GeanyPlugin *plugin)
477 Plugin *p;
479 if (!plugin)
481 configure_plugins(NULL);
482 return;
484 p = plugin->priv;
486 if (p->cbs.configure)
487 configure_plugins(p);
488 else
490 g_return_if_fail(p->configure_single);
491 p->configure_single(main_widgets.window);
496 struct BuilderConnectData
498 gpointer user_data;
499 GeanyPlugin *plugin;
503 static void connect_plugin_signals(GtkBuilder *builder, GObject *object,
504 const gchar *signal_name, const gchar *handler_name,
505 GObject *connect_object, GConnectFlags flags, gpointer user_data)
507 gpointer symbol = NULL;
508 struct BuilderConnectData *data = user_data;
510 symbol = plugin_get_module_symbol(data->plugin->priv, handler_name);
512 plugin_signal_connect(data->plugin, object, signal_name, FALSE,
513 G_CALLBACK(symbol) /*ub?*/, data->user_data);
518 * Allows auto-connecting Glade/GtkBuilder signals in plugins.
520 * When a plugin uses GtkBuilder to load some UI from file/string,
521 * the gtk_builder_connect_signals() function is unable to automatically
522 * connect to the plugin's signal handlers. A plugin could itself use
523 * the gtk_builder_connect_signals_full() function to automatically
524 * connect to the signal handler functions by loading it's GModule
525 * and retrieving pointers to the handler functions, but rather than
526 * each plugin having to do that, this function handles it automatically.
528 * @code
529 * ...
530 * GeanyPlugin *geany_plugin;
532 * G_MODULE_EXPORT void
533 * myplugin_button_clicked(GtkButton *button, gpointer user_data)
535 * g_print("Button pressed\n");
538 * void plugin_init(GeanyData *data)
540 * GtkBuilder *builder = gtk_builder_new();
541 * gtk_builder_add_from_file(builder, "gui.glade", NULL);
542 * plugin_builder_connect_signals(geany_plugin, builder, NULL);
543 * ...
545 * @endcode
547 * @note It's important that you prefix your callback handlers with
548 * a plugin-specific prefix to avoid clashing with other plugins since
549 * the function symbols will be exported process-wide.
551 * @param plugin Must be @ref geany_plugin.
552 * @param builder The GtkBuilder to connect signals with.
553 * @param user_data User data to pass to the connected signal handlers.
555 * @since 1.24, plugin API 217.
557 GEANY_API_SYMBOL
558 void plugin_builder_connect_signals(GeanyPlugin *plugin,
559 GtkBuilder *builder, gpointer user_data)
561 struct BuilderConnectData data = { NULL };
563 g_return_if_fail(plugin != NULL && plugin->priv != NULL);
564 g_return_if_fail(GTK_IS_BUILDER(builder));
566 data.user_data = user_data;
567 data.plugin = plugin;
569 gtk_builder_connect_signals_full(builder, connect_plugin_signals, &data);
573 /** Add additional data that corresponds to the plugin.
575 * @p pdata is the pointer going to be passed to the individual plugin callbacks
576 * of GeanyPlugin::funcs. When the plugin is cleaned up, @p free_func is invoked for the data,
577 * which connects the data to the time the plugin is enabled.
579 * One intended use case is to set GObjects as data and have them destroyed automatically
580 * by passing g_object_unref() as @a free_func, so that member functions can be used
581 * for the @ref GeanyPluginFuncs (via wrappers) but you can set completely custom data.
583 * Be aware that this can only be called once and only by plugins registered via
584 * @ref geany_plugin_register(). So-called legacy plugins cannot use this function.
586 * @note This function must not be called if the plugin was registered with
587 * geany_plugin_register_full().
589 * @param plugin The plugin provided by Geany
590 * @param pdata The plugin's data to associate, must not be @c NULL
591 * @param free_func The destroy notify
593 * @since 1.26 (API 225)
595 GEANY_API_SYMBOL
596 void geany_plugin_set_data(GeanyPlugin *plugin, gpointer pdata, GDestroyNotify free_func)
598 Plugin *p = plugin->priv;
600 g_return_if_fail(PLUGIN_LOADED_OK(p));
601 /* Do not allow calling this only to set a notify. */
602 g_return_if_fail(pdata != NULL);
603 /* The rationale to allow only setting the data once is the following:
604 * In the future we want to support proxy plugins (which bind non-C plugins to
605 * Geany's plugin api). These proxy plugins might need to own the data pointer
606 * on behalf of the proxied plugin. However, if not, then the plugin should be
607 * free to use it. This way we can make sure the plugin doesn't accidentally
608 * trash its proxy.
610 * Better a more limited API now that can be opened up later than a potentially
611 * wrong one that can only be replaced by another one. */
612 if (p->cb_data != NULL || p->cb_data_destroy != NULL)
614 if (PLUGIN_HAS_LOAD_DATA(p))
615 g_warning("Invalid call to %s(), geany_plugin_register_full() was used. Ignored!\n", G_STRFUNC);
616 else
617 g_warning("Double call to %s(), ignored!", G_STRFUNC);
618 return;
621 p->cb_data = pdata;
622 p->cb_data_destroy = free_func;
626 static void plugin_doc_data_proxy_free(gpointer pdata)
628 PluginDocDataProxy *prox = pdata;
629 if (prox != NULL)
631 if (prox->free_func)
632 prox->free_func(prox->data);
633 g_slice_free(PluginDocDataProxy, prox);
639 * Retrieve plugin-specific data attached to a document.
641 * @param plugin The plugin who attached the data.
642 * @param doc The document which the data was attached to.
643 * @param key The key name of the attached data.
645 * @return The attached data pointer or `NULL` if the key is not found
646 * for the given plugin.
648 * @since 1.29 (Plugin API 228)
649 * @see plugin_set_document_data plugin_set_document_data_full
651 GEANY_API_SYMBOL
652 gpointer plugin_get_document_data(struct GeanyPlugin *plugin,
653 struct GeanyDocument *doc, const gchar *key)
655 gchar *real_key;
656 PluginDocDataProxy *data;
658 g_return_val_if_fail(plugin != NULL, NULL);
659 g_return_val_if_fail(doc != NULL, NULL);
660 g_return_val_if_fail(key != NULL && *key != '\0', NULL);
662 real_key = g_strdup_printf("geany/plugins/%s/%s", plugin->info->name, key);
663 data = document_get_data(doc, real_key);
664 g_free(real_key);
666 return (data != NULL) ? data->data : NULL;
671 * Attach plugin-specific data to a document.
673 * @param plugin The plugin attaching data to the document.
674 * @param doc The document to attach the data to.
675 * @param key The key name for the data.
676 * @param data The pointer to attach to the document.
678 * @since 1.29 (Plugin API 228)
679 * @see plugin_get_document_data plugin_set_document_data_full
681 GEANY_API_SYMBOL
682 void plugin_set_document_data(struct GeanyPlugin *plugin, struct GeanyDocument *doc,
683 const gchar *key, gpointer data)
685 plugin_set_document_data_full(plugin, doc, key, data, NULL);
690 * Attach plugin-specific data and a free function to a document.
692 * This is useful for plugins who want to keep some additional data with
693 * the document and even have it auto-released appropriately (see below).
695 * This is a simple example showing how a plugin might use this to
696 * attach a string to each document and print it when the document is
697 * saved:
699 * @code
700 * void on_document_open(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
702 * plugin_set_document_data_full(plugin, doc, "my-data",
703 * g_strdup("some-data"), g_free);
706 * void on_document_save(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
708 * const gchar *some_data = plugin_get_document_data(plugin, doc, "my-data");
709 * g_print("my-data: %s", some_data);
712 * gboolean plugin_init(GeanyPlugin *plugin, gpointer unused)
714 * plugin_signal_connect(plugin, NULL, "document-open", TRUE,
715 * G_CALLBACK(on_document_open), plugin);
716 * plugin_signal_connect(plugin, NULL, "document-new", TRUE,
717 * G_CALLBACK(on_document_open), plugin);
718 * plugin_signal_connect(plugin, NULL, "document-save", TRUE,
719 * G_CALLBACK(on_document_save), plugin);
720 * return TRUE;
723 * void geany_load_module(GeanyPlugin *plugin)
725 * // ...
726 * plugin->funcs->init = plugin_init;
727 * // ...
729 * @endcode
731 * The @a free_func can be used to tie the lifetime of the data to that
732 * of the @a doc and/or the @a plugin. The @a free_func will be called
733 * in any of the following cases:
735 * - When a document is closed.
736 * - When the plugin is unloaded.
737 * - When the document data is set again using the same key.
739 * @param plugin The plugin attaching data to the document.
740 * @param doc The document to attach the data to.
741 * @param key The key name for the data.
742 * @param data The pointer to attach to the document.
743 * @param free_func The function to call with data when removed.
745 * @since 1.29 (Plugin API 228)
746 * @see plugin_get_document_data plugin_set_document_data
748 GEANY_API_SYMBOL
749 void plugin_set_document_data_full(struct GeanyPlugin *plugin,
750 struct GeanyDocument *doc, const gchar *key, gpointer data,
751 GDestroyNotify free_func)
753 PluginDocDataProxy *prox;
755 g_return_if_fail(plugin != NULL);
756 g_return_if_fail(doc != NULL);
757 g_return_if_fail(key != NULL);
759 prox = g_slice_new(PluginDocDataProxy);
760 if (prox != NULL)
762 gchar *real_key = g_strdup_printf("geany/plugins/%s/%s", plugin->info->name, key);
763 prox->data = data;
764 prox->free_func = free_func;
765 document_set_data_full(doc, real_key, prox, plugin_doc_data_proxy_free);
766 g_free(real_key);
771 #endif