Add geanyplugin.h single include for plugin API; update all core

plugins to use it.
Add sci_set_font() to API.
Update plugin howto.



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3966 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -15,6 +15,15 @@
    Add documents_foreach() API macro that skips invalid docs.
    Make filetypes[], documents[] part of the API again.
    Add GEANY() macro for sharing geany symbols between API and core.
+ * src/plugindata.h, src/plugins.c, doc/plugins.dox,
+   plugins/saveactions.c, plugins/export.c, plugins/geanyfunctions.h,
+   plugins/demoplugin.c, plugins/filebrowser.c, plugins/splitwindow.c,
+   plugins/htmlchars.c, plugins/geanyplugin.h, plugins/Makefile.am,
+   plugins/classbuilder.c, wscript:
+   Add geanyplugin.h single include for plugin API; update all core
+   plugins to use it.
+   Add sci_set_font() to API.
+   Update plugin howto.
 
 
 2009-07-13  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>

doc/Doxyfile.in

@@ -94,7 +94,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../src/ ./ ../plugins/pluginmacros.h \
+INPUT                  = ../src/ ./ ../plugins/pluginmacros.h ../plugins/geanyplugin.h \
                          ../tagmanager/tm_source_file.c ../tagmanager/include/tm_source_file.h \
                          ../tagmanager/tm_work_object.c ../tagmanager/include/tm_work_object.h \
                          ../tagmanager/tm_workspace.c ../tagmanager/include/tm_workspace.h

doc/plugins.dox

@@ -365,22 +365,15 @@ PluginCallback plugin_callbacks[] =
  *
  *  Let's start with the very basic headers and add more later if necessary.
  *  @code
-#include "geany.h"
-#include "plugindata.h"
-#include "geanyfunctions.h"
+#include "geanyplugin.h"
  *  @endcode
  *
- *  @a geany.h will include the necessary GTK header files, so there is no need to include
- *  @a gtk/gtk.h yourself.
+ *  @a geanyplugin.h includes all of the Geany API and also the necessary GTK header files,
+ *  so there is no need to include @a gtk/gtk.h yourself.
  *
+ *  @note
  *  @a plugindata.h contains the biggest part of the plugin API and provides some basic macros.
- *
- *  @a geanyfunctions.h provide some macros for convenient access to the plugin API.
- *
- *  Later, you will note that by adding more functionality more header file includes will be
- *  necessary. Best practice for including header files is to always include @a geany.h at first,
- *  then include other necessary header files and at last include plugindata.h and @a
- *  geanyfunctions.h.
+ *  @a geanyfunctions.h provides some macros for convenient access to plugin API functions.
  *
  *  The you should define three basic variables which will give access to data fields and
  *  functions provided by the plugin API.
@@ -400,14 +393,14 @@ GeanyFunctions		*geany_functions;
  *  Nevertheless when setting this value, you should choose the lowest possible version here to
  *  make the plugin compatible with a bigger number of versions of Geany.
  *
- *  As the next step, you will need to tell Geany a couple of basic information of your plugin,
- *  so it is able to show them e.g. on the plugin manager dialog.
+ *  For the next step, you will need to tell Geany some basic information about your plugin
+ *  which will be shown in the plugin manager dialog.
  *
  *  For doing this, you should use PLUGIN_SET_INFO() which expects 4 values:
- *  - Plugin name that should appear on the plugin manager dialog
- *  - Short plugin description
- *  - Plugin version
- *  - Author.
+ *  - Plugin name
+ *  - Short description
+ *  - Version
+ *  - Author
  *
  *  Based on this, the line could look like:
  *  @code
@@ -421,7 +414,7 @@ PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
  *  need to implement the function that is called when your plugin is unloaded.
  *  These functions are called plugin_init() and plugin_cleanup(). Let's see how it could look like:
  *  @code
-PLUGIN_VERSION_CHECK(130)
+PLUGIN_VERSION_CHECK(147)
 
 PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
 				"1.0", "Joe Doe <joe.doe@example.org>");
@@ -435,15 +428,15 @@ void plugin_cleanup(void)
 }
  *  @endcode
  *
- *  If you think this plugin seems to doesn't implement any function right now and only waste
- *  some memory, you are right. At least, it should compile and load/unload on in Geany nicely.
+ *  If you think this plugin seems not to implement any functionality right now and only wastes
+ *  some memory, you are right. But it should compile and load/unload in Geany nicely.
  *  Now you have the very basic layout of a new plugin. Great, isn't it?
  *
  *  Let's go on and implement some real functionality.
  *
  *  As mentioned before, plugin_init() will be called when the plugin is loaded in Geany.
- *  So it should implement everything that needs to be done during startup. In this example case,
- *  we like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World".
+ *  So it should implement everything that needs to be done during startup. In this case,
+ *  we'd like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World".
  *  @code
 void plugin_init(GeanyData *data)
 {
@@ -467,15 +460,11 @@ void plugin_init(GeanyData *data)
  *  This will add an item to the Tools menu and connect this item to a function which implements
  *  what should be done when the menu item is activated by the user.
  *  This is done by g_signal_connect(). The Tools menu can be accessed with
- *  geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to some
- *  main GUI elements in Geany. To be able to use it, you must include ui_utils.h. This can
- *  be done by adding the following line to the include section of your code.
- *  @code
-#include "ui_utils.h"
- *  @endcode
+ *  geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to the
+ *  main GUI elements in Geany.
  *
- *  Geany is offering a simple API for showing message dialogs. So the function contains
- *  only a few lines like:
+ *  Geany has a simple API for showing message dialogs. So our function contains
+ *  only a few lines:
  *  @code
 void item_activate_cb(GtkMenuItem *menuitem, gpointer user_data)
 {
@@ -485,8 +474,7 @@ void item_activate_cb(GtkMenuItem *menuitem, gpointer user_data)
  *
  *  For the moment you don't need to worry about the parameters of that function.
  *
- *  Do you remember, you need to clean up when unloading the plugin? Because of this,
- *  some more action is required.
+ *  Now we need to clean up properly when the plugin is unloaded.
  *
  *  To remove the menu item from the Tools menu, you can use gtk_widget_destroy().
  *  gtk_widget_destroy() expects a pointer to a GtkWidget object.
@@ -513,22 +501,19 @@ void plugin_cleanup(void)
 }
  *  @endcode
  *
- *  This will ensure, your menu item will be removed from the Tools menu as well as from
- *  memory once your plugin is unloaded and you don't leave any memory leaks back.
+ *  This will ensure your menu item is removed from the Tools menu as well as from
+ *  memory once your plugin is unloaded, so you don't leave any memory leaks.
  *  Once this is done, your first plugin is ready. Congratulations!
  *
  *  The complete listing (without comments):
  *  @code
-#include "geany.h"
-#include "ui_utils.h"
-#include "plugindata.h"
-#include "geanyfunctions.h"
+#include "geanyplugin.h"
 
 GeanyPlugin		*geany_plugin;
 GeanyData		*geany_data;
 GeanyFunctions	*geany_functions;
 
-PLUGIN_VERSION_CHECK(130)
+PLUGIN_VERSION_CHECK(147)
 
 PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
 				"1.0", "John Doe <john.doe@example.org>");
@@ -557,4 +542,7 @@ void plugin_cleanup(void)
 }
  *  @endcode
  *
+ *
+ * Now you might like to look at Geany's source code for core plugins such as
+ * @a plugins/demoplugin.c.
  **/

plugins/Makefile.am

@@ -2,8 +2,6 @@
 
 EXTRA_DIST = \
 	makefile.win32 \
-	pluginmacros.h \
-	geanyfunctions.h \
 	genapi.py
 
 plugindir = $(libdir)/geany
@@ -11,6 +9,7 @@ plugindir = $(libdir)/geany
 plugins_includedir = $(includedir)/geany
 plugins_include_HEADERS = \
 	pluginmacros.h \
+	geanyplugin.h \
 	geanyfunctions.h
 
 # systems without python should continue to build OK

plugins/classbuilder.c

@@ -25,14 +25,7 @@
 
 /* Class Builder - creates source files containing a new class interface and definition. */
 
-#include "geany.h"
-#include "plugindata.h"
-#include "support.h"
-#include "filetypes.h"
-#include "document.h"
-#include "editor.h"
-#include "ui_utils.h"
-#include "geanyfunctions.h"
+#include "geanyplugin.h"
 
 
 GeanyData		*geany_data;
@@ -197,7 +190,7 @@ static void cc_dlg_on_create_class(CreateClassDialog *cc_dlg);
 
 /* The list must be ended with NULL as an extra check that arg_count is correct. */
 static void
-utils_free_pointers(gsize arg_count, ...)
+free_pointers(gsize arg_count, ...)
 {
 	va_list a;
 	gsize i;
@@ -716,7 +709,7 @@ static void cc_dlg_on_create_class(CreateClassDialog *cc_dlg)
 		g_free(text);
 	}
 
-	utils_free_pointers(17, tmp, class_info->class_name, class_info->class_name_up,
+	free_pointers(17, tmp, class_info->class_name, class_info->class_name_up,
 		class_info->base_name, class_info->class_name_low, class_info->base_include,
 		class_info->header, class_info->header_guard, class_info->source, class_info->base_decl,
 		class_info->constructor_decl, class_info->constructor_impl,

plugins/demoplugin.c

@@ -35,18 +35,9 @@
  */
 
 
-#include "geany.h"		/* for the GeanyApp data type */
-#include "support.h"	/* for the _() translation macro (see also po/POTFILES.in) */
-#include "editor.h"		/* for the declaration of the GeanyEditor struct, not strictly necessary
-						   as it will be also included by plugindata.h */
-#include "document.h"	/* for the declaration of the GeanyDocument struct */
-#include "ui_utils.h"
+#include "geanyplugin.h"	/* plugin API, always comes first */
 #include "Scintilla.h"	/* for the SCNotification struct */
 
-#include "plugindata.h"		/* this defines the plugin API */
-#include "geanyfunctions.h"	/* this wraps geany_functions function pointers */
-
-
 
 /* These items are set by Geany before plugin_init() is called. */
 GeanyPlugin		*geany_plugin;
@@ -54,9 +45,9 @@ GeanyData		*geany_data;
 GeanyFunctions	*geany_functions;
 
 
-/* Check that the running Geany supports the plugin API used below, and check
+/* Check that the running Geany supports the plugin API version used below, and check
  * for binary compatibility. */
-PLUGIN_VERSION_CHECK(112)
+PLUGIN_VERSION_CHECK(147)
 
 /* All plugins must set name, description, version and author. */
 PLUGIN_SET_INFO(_("Demo"), _("Example plugin."), VERSION, _("The Geany developer team"))

plugins/export.c

@@ -27,15 +27,7 @@
 #include <ctype.h>
 #include <math.h>
 
-#include "geany.h"
-#include "support.h"
-#include "plugindata.h"
-#include "editor.h"
-#include "document.h"
-#include "prefs.h"
-#include "utils.h"
-#include "ui_utils.h"
-#include "geanyfunctions.h"
+#include "geanyplugin.h"
 
 
 GeanyData		*geany_data;

plugins/filebrowser.c

@@ -24,22 +24,11 @@
 
 /* Sidebar file browser plugin. */
 
-#include "geany.h"
+#include "geanyplugin.h"
 #include <string.h>
 
 #include <gdk/gdkkeysyms.h>
 
-#include "support.h"
-#include "prefs.h"
-#include "document.h"
-#include "utils.h"
-#include "keybindings.h"
-#include "project.h"
-#include "ui_utils.h"
-
-#include "plugindata.h"
-#include "geanyfunctions.h"
-
 
 GeanyData		*geany_data;
 GeanyFunctions	*geany_functions;

plugins/geanyfunctions.h

@@ -148,6 +148,8 @@
 	geany_functions->p_sci->get_contents_range
 #define sci_get_selection_contents \
 	geany_functions->p_sci->get_selection_contents
+#define sci_set_font \
+	geany_functions->p_sci->set_font
 #define templates_get_template_fileheader \
 	geany_functions->p_templates->get_template_fileheader
 #define utils_str_equal \

plugins/geanyplugin.h

+/*
+ *      geanyplugin.h - this file is part of Geany, a fast and lightweight IDE
+ *
+ *      Copyright 2009 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
+ *      Copyright 2009 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
+ *
+ *      This program is free software; you can redistribute it and/or modify
+ *      it under the terms of the GNU General Public License as published by
+ *      the Free Software Foundation; either version 2 of the License, or
+ *      (at your option) any later version.
+ *
+ *      This program is distributed in the hope that it will be useful,
+ *      but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *      GNU General Public License for more details.
+ *
+ *      You should have received a copy of the GNU General Public License
+ *      along with this program; if not, write to the Free Software
+ *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ *      MA 02110-1301, USA.
+ *
+ * $Id$
+ */
+
+/**
+ *  @file geanyplugin.h
+ *  Single include for plugins.
+ **/
+
+
+#ifndef GEANY_PLUGIN_H
+#define GEANY_PLUGIN_H 1
+
+#include "geany.h"
+#include "plugindata.h"
+
+#include "dialogs.h"
+#include "document.h"
+#include "editor.h"
+#include "encodings.h"
+#include "filetypes.h"
+#include "highlighting.h"
+#include "keybindings.h"
+#include "main.h"
+#include "msgwindow.h"
+#include "plugins.h"
+#include "prefs.h"
+#include "project.h"
+#include "sciwrappers.h"
+#include "search.h"
+#include "support.h"
+#include "templates.h"
+#include "toolbar.h"
+#include "ui_utils.h"
+#include "utils.h"
+
+#include "geanyfunctions.h"
+
+#endif

plugins/htmlchars.c

@@ -25,18 +25,9 @@
 
 /* HTML Characters plugin (Inserts HTML character entities like '&') */
 
-#include "geany.h"
+#include "geanyplugin.h"
 #include <string.h>
 
-#include "support.h"
-#include "plugindata.h"
-#include "document.h"
-#include "editor.h"
-#include "keybindings.h"
-#include "ui_utils.h"
-#include "utils.h"
-#include "geanyfunctions.h"
-
 
 GeanyData		*geany_data;
 GeanyFunctions	*geany_functions;

plugins/saveactions.c

@@ -23,15 +23,7 @@
  */
 
 
-#include "geany.h"
-#include "support.h"
-#include "document.h"
-#include "utils.h"
-#include "ui_utils.h"
-#include "filetypes.h"
-
-#include "plugindata.h"
-#include "geanyfunctions.h"
+#include "geanyplugin.h"
 
 #include <unistd.h>
 #include <errno.h>
@@ -353,7 +345,7 @@ void plugin_init(GeanyData *data)
 		config, "saveactions", "enable_backupcopy", FALSE);
 
 	instantsave_default_ft = utils_get_setting_string(config, "instantsave", "default_ft",
-		filetypes_index(GEANY_FILETYPES_NONE)->name);
+		filetypes[GEANY_FILETYPES_NONE]->name);
 
 	autosave_src_id = G_MAXUINT; /* mark as invalid */
 	autosave_interval = utils_get_setting_integer(config, "autosave", "interval", 300);

plugins/splitwindow.c

@@ -24,23 +24,13 @@
 
 /* Split Window plugin. */
 
-#include "geany.h"
+#include "geanyplugin.h"
 #include <string.h>
 
-#include "support.h"
 #include "Scintilla.h"
 #include "ScintillaWidget.h"
 #include "SciLexer.h"
 
-#include "ui_utils.h"
-#include "document.h"
-#include "editor.h"
-#include "plugindata.h"
-#include "keybindings.h"
-#include "utils.h"
-
-#include "geanyfunctions.h"
-
 
 PLUGIN_VERSION_CHECK(GEANY_API_VERSION)
 PLUGIN_SET_INFO(_("Split Window"), _("Splits the editor view into two windows."),
@@ -124,14 +114,6 @@ static void set_styles(ScintillaObject *oldsci, ScintillaObject *newsci)
 }
 
 
-static void sci_set_font(ScintillaObject *sci, gint style, const gchar *font,
-	gint size)
-{
-	scintilla_send_message(sci, SCI_STYLESETFONT, style, (sptr_t) font);
-	scintilla_send_message(sci, SCI_STYLESETSIZE, style, size);
-}
-
-
 static void update_font(ScintillaObject *current, ScintillaObject *sci)
 {
 	gint style_id;

src/plugindata.h

@@ -50,7 +50,7 @@
 enum {
 	/** The Application Programming Interface (API) version, incremented
 	 * whenever any plugin data types are modified or appended to. */
-	GEANY_API_VERSION = 146,
+	GEANY_API_VERSION = 147,
 
 	/** The Application Binary Interface (ABI) version, incremented whenever
 	 * existing fields in the plugin data types have to be changed or reordered. */
@@ -326,6 +326,7 @@ typedef struct SciFuncs
 	gchar*	(*get_contents) (struct _ScintillaObject *sci, gint len);
 	gchar*	(*get_contents_range) (struct _ScintillaObject *sci, gint start, gint end);
 	gchar*	(*get_selection_contents) (struct _ScintillaObject *sci);
+	void	(*set_font) (struct _ScintillaObject *sci, gint style, const gchar *font, gint size);
 }
 SciFuncs;
 

src/plugins.c

@@ -195,7 +195,8 @@ static SciFuncs sci_funcs = {
 	&sci_indicator_set,
 	&sci_get_contents,
 	&sci_get_contents_range,
-	&sci_get_selection_contents
+	&sci_get_selection_contents,
+	&sci_set_font
 };
 
 static TemplateFuncs template_funcs = {

wscript

@@ -453,7 +453,7 @@ def build(bld):
 			src/highlighting.h src/keybindings.h src/main.h src/msgwindow.h src/plugindata.h
 			src/plugins.h src/prefs.h src/project.h src/sciwrappers.h src/search.h src/support.h
 			src/templates.h src/toolbar.h src/ui_utils.h src/utils.h plugins/pluginmacros.h
-			plugins/geanyfunctions.h ''')
+			plugins/geanyplugin.h plugins/geanyfunctions.h ''')
 		bld.install_files('${PREFIX}/include/geany/scintilla', '''
 			scintilla/include/SciLexer.h scintilla/include/Scintilla.h
 			scintilla/include/Scintilla.iface scintilla/include/ScintillaWidget.h ''')