Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 220 insertions, 0 deletions

diff --git a/kdecore/kdemacros.h.in b/kdecore/kdemacros.h.in
new file mode 100644
index 000000000..00f49bbd7
--- /dev/null
+++ b/kdecore/kdemacros.h.in
@@ -0,0 +1,220 @@
+/* This file is part of the KDE libraries
+    Copyright (c) 2002-2003 KDE Team
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This library 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
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+*/
+
+#ifndef _KDE_MACROS_H_
+#define _KDE_MACROS_H_
+
+/* Set by configure */
+#undef __KDE_HAVE_GCC_VISIBILITY
+
+/**
+ * The KDE_NO_EXPORT macro marks the symbol of the given variable 
+ * to be hidden. A hidden symbol is stripped during the linking step, 
+ * so it can't be used from outside the resulting library, which is similar
+ * to static. However, static limits the visibility to the current 
+ * compilation unit. hidden symbols can still be used in multiple compilation
+ * units.
+ *
+ * \code
+ * int KDE_NO_EXPORT foo;
+ * int KDE_EXPORT bar;
+ * \end
+ */
+
+#ifdef __KDE_HAVE_GCC_VISIBILITY
+#define KDE_NO_EXPORT __attribute__ ((visibility("hidden")))
+#define KDE_EXPORT __attribute__ ((visibility("default")))
+#elif defined(Q_WS_WIN)
+#define KDE_NO_EXPORT
+#define KDE_EXPORT __declspec(dllexport)
+#else
+#define KDE_NO_EXPORT
+#define KDE_EXPORT
+#endif
+
+/**
+ * KDE_Q_EXPORT_PLUGIN is a workaround for Qt not being able to
+ * cope with symbol visibility.
+ */
+#define KDE_Q_EXPORT_PLUGIN(PLUGIN) \
+  Q_EXTERN_C KDE_EXPORT const char* qt_ucm_query_verification_data(); \
+  Q_EXTERN_C KDE_EXPORT QUnknownInterface* ucm_instantiate(); \
+  Q_EXPORT_PLUGIN(PLUGIN)
+
+/**
+ * The KDE_PACKED can be used to hint the compiler that a particular
+ * structure or class should not contain unnecessary paddings. 
+ */
+
+#ifdef __GNUC__
+#define KDE_PACKED __attribute__((__packed__))
+#else
+#define KDE_PACKED
+#endif
+
+/**
+ * The KDE_DEPRECATED macro can be used to trigger compile-time warnings
+ * with newer compilers when deprecated functions are used.
+ *
+ * For non-inline functions, the macro gets inserted at the very end of the
+ * function declaration, right before the semicolon:
+ *
+ * \code
+ * DeprecatedConstructor() KDE_DEPRECATED;
+ * void deprecatedFunctionA() KDE_DEPRECATED;
+ * int deprecatedFunctionB() const KDE_DEPRECATED;
+ * \endcode
+ *
+ * Functions which are implemented inline are handled differently: for them,
+ * the KDE_DEPRECATED macro is inserted at the front, right before the return
+ * type, but after "static" or "virtual":
+ *
+ * \code
+ * KDE_DEPRECATED void deprecatedInlineFunctionA() { .. }
+ * virtual KDE_DEPRECATED int deprecatedInlineFunctionB() { .. }
+ * static KDE_DEPRECATED bool deprecatedInlineFunctionC() { .. }
+ * \end
+ *
+ * You can also mark whole structs or classes as deprecated, by inserting the
+ * KDE_DEPRECATED macro after the struct/class keyword, but before the
+ * name of the struct/class:
+ *
+ * \code
+ * class KDE_DEPRECATED DeprecatedClass { };
+ * struct KDE_DEPRECATED DeprecatedStruct { };
+ * \endcode
+ *
+ * \note
+ * It does not make much sense to use the KDE_DEPRECATED keyword for a Qt signal;
+ * this is because usually get called by the class which they belong to,
+ * and one'd assume that a class author doesn't use deprecated methods of his
+ * own class. The only exception to this are signals which are connected to
+ * other signals; they get invoked from moc-generated code. In any case, 
+ * printing a warning message in either case is not useful.
+ * For slots, it can make sense (since slots can be invoked directly) but be
+ * aware that if the slots get triggered by a signal, the will get called from
+ * moc code as well and thus the warnings are useless.
+ *
+ * \par
+ * Also note that it is not possible to use KDE_DEPRECATED for classes which
+ * use the k_dcop keyword (to indicate a DCOP interface declaration); this is
+ * because the dcopidl program would choke on the unexpected declaration
+ * syntax.
+ */
+
+#ifndef KDE_DEPRECATED
+#if __GNUC__ - 0 > 3 || (__GNUC__ - 0 == 3 && __GNUC_MINOR__ - 0 >= 2)
+  /* gcc >= 3.2 */
+# define KDE_DEPRECATED __attribute__ ((deprecated))
+#elif defined(_MSC_VER) && (_MSC_VER >= 1300)
+  /* msvc >= 7 */
+# define KDE_DEPRECATED __declspec(deprecated)
+#else
+# define KDE_DEPRECATED
+#endif
+#endif
+
+/**
+ * The KDE_ISLIKELY macro tags a boolean expression as likely to evaluate to
+ * 'true'. When used in an if ( ) statement, it gives a hint to the compiler
+ * that the following codeblock is likely to get executed. Providing this
+ * information helps the compiler to optimize the code for better performance.
+ * Using the macro has an insignificant code size or runtime memory footprint impact.
+ * The code semantics is not affected.
+ *
+ * \note
+ * Providing wrong information ( like marking a condition that almost never
+ * passes as 'likely' ) will cause a significant runtime slowdown. Therefore only
+ * use it for cases where you can be sure about the odds of the expression to pass
+ * in all cases ( independent from e.g. user configuration ).
+ *
+ * \par
+ * The KDE_ISUNLIKELY macro tags an expression as unlikely evaluating to 'true'. 
+ *
+ * \note
+ * Do NOT use ( !KDE_ISLIKELY(foo) ) as an replacement for KDE_ISUNLIKELY !
+ *
+ * \code
+ * if ( KDE_ISUNLIKELY( testsomething() ) )
+ *     abort();     // assume its unlikely that the application aborts
+ * \endcode
+ */
+#if __GNUC__ - 0 >= 3
+# define KDE_ISLIKELY( x )    __builtin_expect(!!(x),1)
+# define KDE_ISUNLIKELY( x )  __builtin_expect(!!(x),0)
+#else
+# define KDE_ISLIKELY( x )   ( x )
+# define KDE_ISUNLIKELY( x )  ( x )
+#endif
+
+/**
+ * This macro, and it's friends going up to 10 reserve a fixed number of virtual
+ * functions in a class.  Because adding virtual functions to a class changes the
+ * size of the vtable, adding virtual functions to a class breaks binary
+ * compatibility.  However, by using this macro, and decrementing it as new
+ * virtual methods are added, binary compatibility can still be preserved.
+ *
+ * \note The added functions must be added to the header at the same location
+ * as the macro; changing the order of virtual functions in a header is also
+ * binary incompatible as it breaks the layout of the vtable.
+ */
+
+#define RESERVE_VIRTUAL_1 \
+    virtual void reservedVirtual1() {}
+#define RESERVE_VIRTUAL_2 \
+    virtual void reservedVirtual2() {} \
+    RESERVE_VIRTUAL_1
+#define RESERVE_VIRTUAL_3 \
+    virtual void reservedVirtual3() {} \
+    RESERVE_VIRTUAL_2
+#define RESERVE_VIRTUAL_4 \
+    virtual void reservedVirtual4() {} \
+    RESERVE_VIRTUAL_3
+#define RESERVE_VIRTUAL_5 \
+    virtual void reservedVirtual5() {} \
+    RESERVE_VIRTUAL_4
+#define RESERVE_VIRTUAL_6 \
+    virtual void reservedVirtual6() {} \
+    RESERVE_VIRTUAL_5
+#define RESERVE_VIRTUAL_7 \
+    virtual void reservedVirtual7() {} \
+    RESERVE_VIRTUAL_6
+#define RESERVE_VIRTUAL_8 \
+    virtual void reservedVirtual8() {} \
+    RESERVE_VIRTUAL_7
+#define RESERVE_VIRTUAL_9 \
+    virtual void reservedVirtual9() {} \
+    RESERVE_VIRTUAL_8
+#define RESERVE_VIRTUAL_10 \
+    virtual void reservedVirtual10() {} \
+    RESERVE_VIRTUAL_9
+
+/**
+ * The KDE_WEAK_SYMBOL macro can be used to tell the compiler that
+ * a particular function should be a weak symbol (that e.g. may be overriden
+ * in another library, -Bdirect will not bind this symbol directly)
+ */
+
+#ifdef __GNUC__
+#define KDE_WEAK_SYMBOL __attribute__((__weak__))
+#else
+#define KDE_WEAK_SYMBOL
+#endif
+
+#endif /* _KDE_MACROS_H_ */