atk/atkversion.h.in: Add Version/Deprecation Macros

This adds version macros, like what is now done in GLib, GTK+ and Clutter,
so that these macros can be used in public headers to:

-Prepare for using a visibility-based (or __declspec(dllexport)method to
 export the public APIs during the build.  These macros are marked for 2.x
 stable releases as ATK_AVAILABLE_IN_X_Y, and ATK_AVAILABLE_IN_ALL for APIs
 introduced on or before the ATK-2.0.0 release.

-Add ATK_DEPRECATED_IN_X_Y macros for use on APIs that are deprecated
 in 2.x, and ATK_DEPRECATED for those deprecated earlier.  This
 is also used to export the deprecated APIs using the visibility-based/
 __declspec(dllexport) method.

https://bugzilla.gnome.org/show_bug.cgi?id=728031

1 files changed, 279 insertions, 0 deletions

diff --git a/atk/atkversion.h.in b/atk/atkversion.h.in
index 65c9ece..eefa775 100644
--- a/atk/atkversion.h.in
+++ b/atk/atkversion.h.in
@@ -1,6 +1,7 @@
 /* ATK -  Accessibility Toolkit
  *
  * Copyright (C) 2012 Igalia, S.L.
+ * Copyright (C) 2014 Chun-wei Fan
  *
  * Author: Alejandro Piņeiro Iglesias <apinheiro@igalia.com>
  *
@@ -27,6 +28,8 @@
 #ifndef __ATK_VERSION_H__
 #define __ATK_VERSION_H__
 
+#include <glib.h>
+
 /**
  * ATK_MAJOR_VERSION:
  *
@@ -99,11 +102,287 @@
      (ATK_MAJOR_VERSION == (major) && ATK_MINOR_VERSION == (minor) && \
       ATK_MICRO_VERSION >= (micro)))
 
+#ifndef _ATK_EXTERN
+#define _ATK_EXTERN extern
+#endif
+
+/**
+ * ATK_VERSION_2_2:
+ *
+ * A macro that evaluates to the 2.2 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_2       (G_ENCODE_VERSION (2, 2))
+
+/**
+ * ATK_VERSION_2_4:
+ *
+ * A macro that evaluates to the 2.4 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_4       (G_ENCODE_VERSION (2, 4))
+
+/**
+ * ATK_VERSION_2_6:
+ *
+ * A macro that evaluates to the 2.6 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_6       (G_ENCODE_VERSION (2, 6))
+
+/**
+ * ATK_VERSION_2_8:
+ *
+ * A macro that evaluates to the 2.8 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_8       (G_ENCODE_VERSION (2, 8))
+
+/**
+ * ATK_VERSION_2_10:
+ *
+ * A macro that evaluates to the 2.10 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+
+#define ATK_VERSION_2_10       (G_ENCODE_VERSION (2, 10))
+/**
+ * ATK_VERSION_2_12:
+ *
+ * A macro that evaluates to the 2.12 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_12       (G_ENCODE_VERSION (2, 12))
+
+/**
+ * ATK_VERSION_2_14:
+ *
+ * A macro that evaluates to the 2.14 version of ATK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.14
+ */
+#define ATK_VERSION_2_14       (G_ENCODE_VERSION (2, 14))
+
+/* evaluates to the current stable version; for development cycles,
+ * this means the next stable target
+ */
+#if (ATK_MINOR_VERSION % 2)
+#define ATK_VERSION_CUR_STABLE         (G_ENCODE_VERSION (ATK_MAJOR_VERSION, ATK_MINOR_VERSION + 1))
+#else
+#define ATK_VERSION_CUR_STABLE         (G_ENCODE_VERSION (ATK_MAJOR_VERSION, ATK_MINOR_VERSION))
+#endif
+
+/* evaluates to the previous stable version */
+#if (ATK_MINOR_VERSION % 2)
+#define ATK_VERSION_PREV_STABLE        (G_ENCODE_VERSION (ATK_MAJOR_VERSION, ATK_MINOR_VERSION - 1))
+#else
+#define ATK_VERSION_PREV_STABLE        (G_ENCODE_VERSION (ATK_MAJOR_VERSION, ATK_MINOR_VERSION - 2))
+#endif
+
+/**
+ * ATK_VERSION_MIN_REQUIRED:
+ *
+ * A macro that should be defined by the user prior to including
+ * the atk/atk.h header.
+ * The definition should be one of the predefined ATK version
+ * macros: %ATK_VERSION_2_12, %ATK_VERSION_2_14,...
+ *
+ * This macro defines the earliest version of ATK that the package is
+ * required to be able to compile against.
+ *
+ * If the compiler is configured to warn about the use of deprecated
+ * functions, then using functions that were deprecated in version
+ * %ATK_VERSION_MIN_REQUIRED or earlier will cause warnings (but
+ * using functions deprecated in later releases will not).
+ *
+ * Since: 2.14
+ */
+/* If the package sets ATK_VERSION_MIN_REQUIRED to some future
+ * ATK_VERSION_X_Y value that we don't know about, it will compare as
+ * 0 in preprocessor tests.
+ */
+#ifndef ATK_VERSION_MIN_REQUIRED
+# define ATK_VERSION_MIN_REQUIRED      (ATK_VERSION_CUR_STABLE)
+#elif ATK_VERSION_MIN_REQUIRED == 0
+# undef  ATK_VERSION_MIN_REQUIRED
+# define ATK_VERSION_MIN_REQUIRED      (ATK_VERSION_CUR_STABLE + 2)
+#endif
+
+/**
+ * ATK_VERSION_MAX_ALLOWED:
+ *
+ * A macro that should be defined by the user prior to including
+ * the atk/atk.h header.
+ * The definition should be one of the predefined ATK version
+ * macros: %ATK_VERSION_2_12, %ATK_VERSION_2_14,...
+ *
+ * This macro defines the latest version of the ATK API that the
+ * package is allowed to make use of.
+ *
+ * If the compiler is configured to warn about the use of deprecated
+ * functions, then using functions added after version
+ * %ATK_VERSION_MAX_ALLOWED will cause warnings.
+ *
+ * Unless you are using ATK_CHECK_VERSION() or the like to compile
+ * different code depending on the ATK version, then this should be
+ * set to the same value as %ATK_VERSION_MIN_REQUIRED.
+ *
+ * Since: 2.14
+ */
+#if !defined (ATK_VERSION_MAX_ALLOWED) || (ATK_VERSION_MAX_ALLOWED == 0)
+# undef ATK_VERSION_MAX_ALLOWED
+# define ATK_VERSION_MAX_ALLOWED      (ATK_VERSION_CUR_STABLE)
+#endif
+
+/* sanity checks */
+#if ATK_VERSION_MIN_REQUIRED > ATK_VERSION_CUR_STABLE
+#error "ATK_VERSION_MIN_REQUIRED must be <= ATK_VERSION_CUR_STABLE"
+#endif
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_MIN_REQUIRED
+#error "ATK_VERSION_MAX_ALLOWED must be >= ATK_VERSION_MIN_REQUIRED"
+#endif
+#if ATK_VERSION_MIN_REQUIRED < ATK_VERSION_2_2
+#error "ATK_VERSION_MIN_REQUIRED must be >= ATK_VERSION_2_2"
+#endif
+
+/* these macros are used to mark deprecated functions, and thus have to be
+ * exposed in a public header.
+ *
+ * do *not* use them in other libraries depending on Atk: use G_DEPRECATED
+ * and G_DEPRECATED_FOR, or use your own wrappers around them.
+ */
+#ifdef ATK_DISABLE_DEPRECATION_WARNINGS
+#define ATK_DEPRECATED _ATK_EXTERN
+#define ATK_DEPRECATED_FOR(f) _ATK_EXTERN
+#else
+#define ATK_DEPRECATED G_DEPRECATED _ATK_EXTERN
+#define ATK_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f) _ATK_EXTERN
+#endif
+
+#define ATK_AVAILABLE_IN_ALL _ATK_EXTERN
+
+/* XXX: Every new stable minor release should add a set of macros here */
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_2
+# define ATK_DEPRECATED_IN_2_2                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_2_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_2                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_2_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_2
+# define ATK_AVAILABLE_IN_2_2                 ATK_UNAVAILABLE(2, 2)
+#else
+# define ATK_AVAILABLE_IN_2_2                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_4
+# define ATK_DEPRECATED_IN_2_4                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_4_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_4                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_4_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_4
+# define ATK_AVAILABLE_IN_2_4                 ATK_UNAVAILABLE(2, 4)
+#else
+# define ATK_AVAILABLE_IN_2_4                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_6
+# define ATK_DEPRECATED_IN_2_6                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_6_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_6                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_6_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_6
+# define ATK_AVAILABLE_IN_2_6                 ATK_UNAVAILABLE(2, 6)
+#else
+# define ATK_AVAILABLE_IN_2_6                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_8
+# define ATK_DEPRECATED_IN_2_8                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_8_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_8                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_8_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_8
+# define ATK_AVAILABLE_IN_2_8                 ATK_UNAVAILABLE(2, 8)
+#else
+# define ATK_AVAILABLE_IN_2_8                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_10
+# define ATK_DEPRECATED_IN_2_10                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_10_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_10                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_10_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_10
+# define ATK_AVAILABLE_IN_2_10                 ATK_UNAVAILABLE(2, 10)
+#else
+# define ATK_AVAILABLE_IN_2_10                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_12
+# define ATK_DEPRECATED_IN_2_12                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_12_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_12                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_12_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_12
+# define ATK_AVAILABLE_IN_2_12                 ATK_UNAVAILABLE(2, 12)
+#else
+# define ATK_AVAILABLE_IN_2_12                 _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_14
+# define ATK_DEPRECATED_IN_2_14                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_14_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_14                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_14_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_14
+# define ATK_AVAILABLE_IN_2_14                 ATK_UNAVAILABLE(2, 14)
+#else
+# define ATK_AVAILABLE_IN_2_14                 _ATK_EXTERN
+#endif
 
+ATK_AVAILABLE_IN_2_8
 guint atk_get_major_version (void) G_GNUC_CONST;
+ATK_AVAILABLE_IN_2_8
 guint atk_get_minor_version (void) G_GNUC_CONST;
+ATK_AVAILABLE_IN_2_8
 guint atk_get_micro_version (void) G_GNUC_CONST;
+ATK_AVAILABLE_IN_2_8
 guint atk_get_binary_age    (void) G_GNUC_CONST;
+ATK_AVAILABLE_IN_2_8
 guint atk_get_interface_age (void) G_GNUC_CONST;
 
 #define atk_major_version atk_get_major_version ()