Merge pull request #911 from b4n/deprecations

Deprecations cleanup and improvement

HACKING

@@ -176,6 +176,20 @@ libs (including GLib, GDK and Pango) has the advantages
 that you don't get confused by any newer API additions and you 
 don't have to take care about whether you can use them or not.
 
+You might want to pass the ``-DGLIB_VERSION_MAX_ALLOWED=GLIB_VERSION_2_28`` C
+preprocessor flag to get warnings about newer symbols from the GLib.
+
+On the contrary, you might also want to get deprecation warnings for symbols
+deprecated in newer versions, typically when preparing a dependency bump or
+trying to improve forward compatibility.
+To do so, use the ``-UGLIB_VERSION_MIN_REQUIRED`` flag for GLib deprecations,
+and ``-UGDK_DISABLE_DEPRECATION_WARNINGS`` for GTK and GDK ones.
+To change the lower deprecation bound for GLib (and then get warnings about
+symbols deprecated more recently) instead of simply removing it entirely, use
+``-UGLIB_VERSION_MIN_REQUIRED -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_X_YY``.
+
+See `Compiler options & warnings`_ for how to set such flags.
+
 Coding
 ------
 * Don't write long functions with a lot of variables and/or scopes - break

configure.ac

@@ -78,6 +78,13 @@ gtk_modules="$gtk_package >= $gtk_min_version glib-2.0 >= 2.28"
 gtk_modules_private="gio-2.0 >= 2.28 gmodule-no-export-2.0"
 PKG_CHECK_MODULES([GTK], [$gtk_modules $gtk_modules_private])
 AC_SUBST([DEPENDENCIES], [$gtk_modules])
+dnl Define minimum requirements to avoid warnings about symbols deprecated afterward.
+dnl Although GLIB_VERSION_2_28 is new in 2.32, older versions won't evaluate
+dnl GLIB_VERSION_MIN_REQUIRED so it won't be a problem.
+AS_VAR_APPEND([GTK_CFLAGS], [" -DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_28"])
+dnl Disable all GTK deprecations on 3.x so long as we want to keep 2.x support and only require 3.0.
+dnl No need on 2.x as we target the latest version.
+AM_COND_IF([GTK3], [AS_VAR_APPEND([GTK_CFLAGS], [" -DGDK_DISABLE_DEPRECATION_WARNINGS"])])
 AC_SUBST([GTK_CFLAGS])
 AC_SUBST([GTK_LIBS])
 GTK_VERSION=`$PKG_CONFIG --modversion $gtk_package`

doc/Doxyfile.in

@@ -2037,6 +2037,8 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = "G_GNUC_PRINTF(x,y)=" \
                          G_BEGIN_DECLS= \
                          G_END_DECLS= \
+                         GEANY_DEPRECATED= \
+                         GEANY_DEPRECATED_FOR(x)= \
                          HAVE_PLUGINS \
                          GEANY_API_SYMBOL= \
                          GEANY_FUNCTIONS_H

plugins/filebrowser.c

@@ -59,8 +59,6 @@ enum
 	KB_COUNT
 };
 
-PLUGIN_KEY_GROUP(file_browser, KB_COUNT)
-
 
 enum
 {
@@ -1122,6 +1120,7 @@ static void kb_activate(guint key_id)
 
 void plugin_init(GeanyData *data)
 {
+	GeanyKeyGroup *key_group;
 	GtkWidget *scrollwin, *toolbar, *filterbar;
 
 	filter = NULL;
@@ -1160,9 +1159,10 @@ void plugin_init(GeanyData *data)
 		file_view_vbox, gtk_label_new(_("Files")));
 
 	/* setup keybindings */
-	keybindings_set_item(plugin_key_group, KB_FOCUS_FILE_LIST, kb_activate,
+	key_group = plugin_set_key_group(geany_plugin, "file_browser", KB_COUNT, NULL);
+	keybindings_set_item(key_group, KB_FOCUS_FILE_LIST, kb_activate,
 		0, 0, "focus_file_list", _("Focus File List"), NULL);
-	keybindings_set_item(plugin_key_group, KB_FOCUS_PATH_ENTRY, kb_activate,
+	keybindings_set_item(key_group, KB_FOCUS_PATH_ENTRY, kb_activate,
 		0, 0, "focus_path_entry", _("Focus Path Entry"), NULL);
 
 	plugin_signal_connect(geany_plugin, NULL, "document-activate", TRUE,

plugins/htmlchars.c

@@ -31,6 +31,7 @@
 #include "SciLexer.h"
 
 
+GeanyPlugin		*geany_plugin;
 GeanyData		*geany_data;
 
 
@@ -49,8 +50,6 @@ enum
 	KB_COUNT
 };
 
-PLUGIN_KEY_GROUP(html_chars, KB_COUNT)
-
 
 enum
 {
@@ -734,6 +733,7 @@ static void init_configuration(void)
 /* Called by Geany to initialise the plugin */
 void plugin_init(GeanyData *data)
 {
+	GeanyKeyGroup *key_group;
 	GtkWidget *menu_item;
 	const gchar *menu_text = _("_Insert Special HTML Characters...");
 
@@ -779,13 +779,14 @@ void plugin_init(GeanyData *data)
 	main_menu_item = menu_item;
 
 	/* setup keybindings */
-	keybindings_set_item(plugin_key_group, KB_INSERT_HTML_CHARS,
+	key_group = plugin_set_key_group(geany_plugin, "html_chars", KB_COUNT, NULL);
+	keybindings_set_item(key_group, KB_INSERT_HTML_CHARS,
 		kb_activate, 0, 0, "insert_html_chars",
 		_("Insert Special HTML Characters"), menu_item);
-	keybindings_set_item(plugin_key_group, KB_REPLACE_HTML_ENTITIES,
+	keybindings_set_item(key_group, KB_REPLACE_HTML_ENTITIES,
 		kb_special_chars_replacement, 0, 0, "replace_special_characters",
 		_("Replace special characters"), NULL);
-	keybindings_set_item(plugin_key_group, KB_HTMLTOGGLE_ACTIVE,
+	keybindings_set_item(key_group, KB_HTMLTOGGLE_ACTIVE,
 		kbhtmltoggle_toggle, 0, 0, "htmltoogle_toggle_plugin_status",
 		_("Toggle plugin status"), menu_htmltoggle);
 }

src/geany.h

@@ -55,6 +55,14 @@ G_BEGIN_DECLS
 #define G_GNUC_WARN_UNUSED_RESULT
 #endif
 
+#if defined(GEANY_PRIVATE) || defined(GEANY_DISABLE_DEPRECATION_WARNINGS)
+#	define GEANY_DEPRECATED
+#	define GEANY_DEPRECATED_FOR(x)
+#else
+#	define GEANY_DEPRECATED			G_GNUC_DEPRECATED
+#	define GEANY_DEPRECATED_FOR(x)	G_GNUC_DEPRECATED_FOR(x)
+#endif
+
 /* Re-defined by plugindata.h as something else */
 #ifndef GEANY
 # define GEANY(symbol_name) symbol_name

src/plugindata.h

@@ -32,6 +32,7 @@
 #ifndef GEANY_PLUGIN_DATA_H
 #define GEANY_PLUGIN_DATA_H 1
 
+#include "geany.h"  /* for GEANY_DEPRECATED */
 #include "build.h"  /* GeanyBuildGroup, GeanyBuildSource, GeanyBuildCmdEntries enums */
 #include "document.h" /* GeanyDocument */
 #include "editor.h"	/* GeanyEditor, GeanyIndentType */
@@ -146,35 +147,6 @@ PluginInfo;
 	}
 
 
-/** @deprecated - use plugin_set_key_group() instead.
- * @see PLUGIN_KEY_GROUP() macro. */
-typedef struct GeanyKeyGroupInfo
-{
-	const gchar *name;		/**< Group name used in the configuration file, such as @c "html_chars" */
-	gsize count;			/**< The number of keybindings the group will hold */
-}
-GeanyKeyGroupInfo;
-
-/** @deprecated - use plugin_set_key_group() instead.
- * Declare and initialise a keybinding group.
- * @code GeanyKeyGroup *plugin_key_group; @endcode
- * You must then set the @c plugin_key_group::keys[] entries for the group in plugin_init(),
- * normally using keybindings_set_item().
- * The @c plugin_key_group::label field is set by Geany after @c plugin_init()
- * is called, to the name of the plugin.
- * @param group_name A unique group name (without quotes) to be used in the
- * configuration file, such as @c html_chars.
- * @param key_count	The number of keybindings the group will hold. */
-#define PLUGIN_KEY_GROUP(group_name, key_count) \
-	/* We have to declare this as a single element array.
-	 * Declaring as a pointer to a struct doesn't work with g_module_symbol(). */ \
-	GeanyKeyGroupInfo plugin_key_group_info[1] = \
-	{ \
-		{G_STRINGIFY(group_name), key_count} \
-	};\
-	GeanyKeyGroup *plugin_key_group = NULL;
-
-
 /** Callback array entry type used with the @ref plugin_callbacks symbol. */
 typedef struct PluginCallback
 {
@@ -193,29 +165,6 @@ typedef struct PluginCallback
 PluginCallback;
 
 
-/** @deprecated Use @ref ui_add_document_sensitive() instead.
- * Flags to be set by plugins in PluginFields struct. */
-typedef enum
-{
-	/** Whether a plugin's menu item should be disabled when there are no open documents */
-	PLUGIN_IS_DOCUMENT_SENSITIVE	= 1 << 0
-}
-PluginFlags;
-
-/** @deprecated Use @ref ui_add_document_sensitive() instead.
- * Fields set and owned by the plugin. */
-typedef struct PluginFields
-{
-	/** Bitmask of @c PluginFlags. */
-	PluginFlags	flags;
-	/** Pointer to a plugin's menu item which will be automatically enabled/disabled when there
-	 *  are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set.
-	 *  This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
-	GtkWidget	*menu_item;
-}
-PluginFields;
-
-
 /** This contains pointers to global variables owned by Geany for plugins to use.
  * Core variable pointers can be appended when needed by plugin authors, if appropriate. */
 typedef struct GeanyData
@@ -406,7 +355,57 @@ gint geany_plugin_register_proxy(GeanyPlugin *plugin, const gchar **extensions);
 /* This remains so that older plugins that contain a `GeanyFunctions *geany_functions;`
  * variable in their plugin - as was previously required - will still compile
  * without changes.  */
-typedef struct GeanyFunctionsUndefined GeanyFunctions;
+typedef struct GeanyFunctionsUndefined GeanyFunctions GEANY_DEPRECATED;
+
+/** @deprecated - use plugin_set_key_group() instead.
+ * @see PLUGIN_KEY_GROUP() macro. */
+typedef struct GeanyKeyGroupInfo
+{
+	const gchar *name;		/**< Group name used in the configuration file, such as @c "html_chars" */
+	gsize count;			/**< The number of keybindings the group will hold */
+}
+GeanyKeyGroupInfo GEANY_DEPRECATED_FOR(plugin_set_key_group);
+
+/** @deprecated - use plugin_set_key_group() instead.
+ * Declare and initialise a keybinding group.
+ * @code GeanyKeyGroup *plugin_key_group; @endcode
+ * You must then set the @c plugin_key_group::keys[] entries for the group in plugin_init(),
+ * normally using keybindings_set_item().
+ * The @c plugin_key_group::label field is set by Geany after @c plugin_init()
+ * is called, to the name of the plugin.
+ * @param group_name A unique group name (without quotes) to be used in the
+ * configuration file, such as @c html_chars.
+ * @param key_count	The number of keybindings the group will hold. */
+#define PLUGIN_KEY_GROUP(group_name, key_count) \
+	/* We have to declare this as a single element array.
+	 * Declaring as a pointer to a struct doesn't work with g_module_symbol(). */ \
+	GeanyKeyGroupInfo plugin_key_group_info[1] = \
+	{ \
+		{G_STRINGIFY(group_name), key_count} \
+	};\
+	GeanyKeyGroup *plugin_key_group = NULL;
+
+/** @deprecated Use @ref ui_add_document_sensitive() instead.
+ * Flags to be set by plugins in PluginFields struct. */
+typedef enum
+{
+	/** Whether a plugin's menu item should be disabled when there are no open documents */
+	PLUGIN_IS_DOCUMENT_SENSITIVE	= 1 << 0
+}
+PluginFlags;
+
+/** @deprecated Use @ref ui_add_document_sensitive() instead.
+ * Fields set and owned by the plugin. */
+typedef struct PluginFields
+{
+	/** Bitmask of @c PluginFlags. */
+	PluginFlags	flags;
+	/** Pointer to a plugin's menu item which will be automatically enabled/disabled when there
+	 *  are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set.
+	 *  This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
+	GtkWidget	*menu_item;
+}
+PluginFields GEANY_DEPRECATED_FOR(ui_add_document_sensitive);
 
 #define document_reload_file document_reload_force
 

src/sciwrappers.h

@@ -22,6 +22,7 @@
 #ifndef GEANY_SCI_WRAPPERS_H
 #define GEANY_SCI_WRAPPERS_H 1
 
+#include "geany.h" /* for GEANY_DEPRECATED */
 #include "gtkcompat.h" /* Needed by ScintillaWidget.h */
 #include "Scintilla.h" /* Needed by ScintillaWidget.h */
 #include "ScintillaWidget.h" /* for ScintillaObject */
@@ -53,9 +54,7 @@ void 				sci_set_selection_start		(ScintillaObject *sci, gint position);
 void				sci_set_selection_end		(ScintillaObject *sci, gint position);
 
 gint				sci_get_length				(ScintillaObject *sci);
-void				sci_get_text				(ScintillaObject *sci, gint len, gchar *text);
 gchar*				sci_get_contents			(ScintillaObject *sci, gint buffer_len);
-void				sci_get_selected_text		(ScintillaObject *sci, gchar *text);
 gint				sci_get_selected_text_length(ScintillaObject *sci);
 gchar*				sci_get_selection_contents	(ScintillaObject *sci);
 gchar*				sci_get_line				(ScintillaObject *sci, gint line_num);
@@ -75,7 +74,6 @@ gint				sci_find_text				(ScintillaObject *sci, gint flags, struct Sci_TextToFin
 void				sci_set_font				(ScintillaObject *sci, gint style, const gchar *font, gint size);
 void				sci_goto_line				(ScintillaObject *sci, gint line, gboolean unfold);
 gint				sci_get_style_at			(ScintillaObject *sci, gint position);
-void				sci_get_text_range			(ScintillaObject *sci, gint start, gint end, gchar *text);
 gchar*				sci_get_contents_range		(ScintillaObject *sci, gint start, gint end);
 void				sci_insert_text				(ScintillaObject *sci, gint pos, const gchar *text);
 
@@ -95,6 +93,11 @@ void				sci_set_line_indentation	(ScintillaObject *sci, gint line, gint indent);
 gint				sci_get_line_indentation	(ScintillaObject *sci, gint line);
 gint				sci_find_matching_brace		(ScintillaObject *sci, gint pos);
 
+#ifndef GEANY_DISABLE_DEPRECATED
+void				sci_get_text				(ScintillaObject *sci, gint len, gchar *text) GEANY_DEPRECATED_FOR(sci_get_contents);
+void				sci_get_selected_text		(ScintillaObject *sci, gchar *text) GEANY_DEPRECATED_FOR(sci_get_selection_contents);
+void				sci_get_text_range			(ScintillaObject *sci, gint start, gint end, gchar *text) GEANY_DEPRECATED_FOR(sci_get_contents_range);
+#endif	/* GEANY_DISABLE_DEPRECATED */
 
 #ifdef GEANY_PRIVATE
 

src/ui_utils.h

@@ -22,6 +22,7 @@
 #ifndef GEANY_UI_UTILS_H
 #define GEANY_UI_UTILS_H 1
 
+#include "geany.h" /* for GEANY_DEPRECATED */
 #include "document.h"
 
 #include "gtkcompat.h"
@@ -112,8 +113,6 @@ GtkWidget *ui_button_new_with_image(const gchar *stock_id, const gchar *text);
 
 void ui_add_document_sensitive(GtkWidget *widget);
 
-void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text);
-
 GtkWidget *ui_image_menu_item_new(const gchar *stock_id, const gchar *label);
 
 GtkWidget *ui_lookup_widget(GtkWidget *widget, const gchar *widget_name);
@@ -143,6 +142,11 @@ const gchar *ui_lookup_stock_label(const gchar *stock_id);
 void ui_tree_view_set_tooltip_text_column(GtkTreeView *tree_view, gint column);
 
 
+#ifndef GEANY_DISABLE_DEPRECATED
+void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text) GEANY_DEPRECATED_FOR(gtk_widget_set_tooltip_text);
+#endif	/* GEANY_DISABLE_DEPRECATED */
+
+
 #ifdef GEANY_PRIVATE
 
 extern GeanyInterfacePrefs interface_prefs;

src/utils.h

@@ -49,15 +49,21 @@ G_BEGIN_DECLS
  * E.g. @code SETPTR(str, g_strndup(str, 5)); @endcode
  **/
 #define SETPTR(ptr, result) \
-	do setptr(ptr, result) while (0)
+	do {\
+		gpointer setptr_tmp = ptr;\
+		ptr = result;\
+		g_free(setptr_tmp);\
+	} while (0)
 
+#ifndef GEANY_DISABLE_DEPRECATED
 /** @deprecated 2011/11/15 - use SETPTR() instead. */
 #define setptr(ptr, result) \
 	{\
 		gpointer setptr_tmp = ptr;\
 		ptr = result;\
 		g_free(setptr_tmp);\
 	}
+#endif
 
 /** Duplicates a string on the stack using @c g_alloca().
  * Like glibc's @c strdupa(), but portable.