Macros
#define	K_GLOBAL_STATIC(TYPE, NAME) K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ())

#define	K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ARGS)

#define	KDE_BF_ENUM(a) a

#define	KDE_CAST_BF_ENUM(a, b) b

#define	KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED

#define	KDE_DUMMY_COMPARISON_OPERATOR(C)

#define	KDE_DUMMY_QHASH_FUNCTION(C)

#define	KDE_EXPORT __attribute__ ((visibility("default")))

#define	KDE_IMPORT __attribute__ ((visibility("default")))

#define	KDE_IS_VERSION(a, b, c) ( KDE_VERSION >= KDE_MAKE_VERSION(a,b,c) )

#define	KDE_ISLIKELY(x) ( x )

#define	KDE_ISUNLIKELY(x) ( x )

#define	KDE_MAKE_VERSION(a, b, c) (((a) << 16) \| ((b) << 8) \| (c))

#define	KDE_MUST_USE_RESULT

#define	KDE_NO_DEPRECATED

#define	KDE_NO_EXPORT __attribute__ ((visibility("hidden")))

#define	KDE_PACKED

#define	KDE_VERSION KDE_MAKE_VERSION(KDE_VERSION_MAJOR,KDE_VERSION_MINOR,KDE_VERSION_RELEASE)

#define	KDE_VERSION_MAJOR ${KDE_VERSION_MAJOR}

#define	KDE_VERSION_MINOR ${KDE_VERSION_MINOR}

#define	KDE_VERSION_RELEASE ${KDE_VERSION_RELEASE}

#define	KDE_VERSION_STRING "${KDE_VERSION_STRING}"

#define	KDE_WEAK_SYMBOL

#define	RESERVE_VIRTUAL_1 virtual void reservedVirtual1() {}

#define	RESERVE_VIRTUAL_2

#define	RESERVE_VIRTUAL_3

#define	RESERVE_VIRTUAL_4

#define	RESERVE_VIRTUAL_5

#define	RESERVE_VIRTUAL_6

#define	RESERVE_VIRTUAL_7

#define	RESERVE_VIRTUAL_8

#define	RESERVE_VIRTUAL_9

Detailed Description

Macro Definition Documentation

#define K_GLOBAL_STATIC	(	TYPE,
		NAME
	)	K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ())

This macro makes it easy to use non-POD types as global statics.

The object is created on first use and creation is threadsafe.

The object is destructed on library unload or application exit. Be careful with calling other objects in the destructor of the class as you have to be sure that they (or objects they depend on) are not already destructed.

Parameters

TYPE	The type of the global static object. Do not add a *.
NAME	The name of the function to get a pointer to the global static object.

If you have code that might be called after the global object has been destroyed you can check for that using the isDestroyed() function.

If needed (If the destructor of the global object calls other functions that depend on other global statics (e.g. KConfig::sync) your destructor has to be called before those global statics are destroyed. A Qt post routine does that.) you can also install a post routine (qAddPostRoutine) to clean up the object using the destroy() method. If you registered a post routine and the object is destroyed because of a lib unload you have to call qRemovePostRoutine!

Example:

class A {
public:
    ~A();
    ...
};
K_GLOBAL_STATIC(A, globalA)
// The above creates a new globally static variable named 'globalA' which you
// can use as a pointer to an instance of A.
void doSomething()
{
    //  The first time you access globalA a new instance of A will be created automatically.
    A *a = globalA;
    ...
}
void doSomethingElse()
{
    if (globalA.isDestroyed()) {
        return;
    }
    A *a = globalA;
    ...
}
void installPostRoutine()
{
    // A post routine can be used to delete the object when QCoreApplication destructs,
    // not adding such a post routine will delete the object normally at program unload
    qAddPostRoutine(globalA.destroy);
}
A::~A()
{
    // When you install a post routine you have to remove the post routine from the destructor of
    // the class used as global static!
    qRemovePostRoutine(globalA.destroy);
}

A common case for the need of deletion on lib unload/app shutdown are Singleton classes. Here's an example how to do it:

class MySingletonPrivate;
class EXPORT_MACRO MySingleton
{
friend class MySingletonPrivate;
public:
    static MySingleton *self();
    QString someFunction();
private:
    MySingleton();
    ~MySingleton();
};

in the .cpp file:

// This class will be instantiated and referenced as a singleton in this example
class MySingletonPrivate
{
public:
    QString foo;
    MySingleton instance;
};
K_GLOBAL_STATIC(MySingletonPrivate, mySingletonPrivate)
MySingleton *MySingleton::self()
{
    // returns the singleton; automatically creates a new instance if that has not happened yet.
    return &mySingletonPrivate->instance;
}
QString MySingleton::someFunction()
{
    // Refencing the singleton directly is possible for your convenience
    return mySingletonPrivate->foo;
}

Instead of the above you can use also the following pattern (ignore the name of the namespace):

namespace MySingleton
{
    EXPORT_MACRO QString someFunction();
}

in the .cpp file:

class MySingletonPrivate
{
public:
    QString foo;
};
K_GLOBAL_STATIC(MySingletonPrivate, mySingletonPrivate)
QString MySingleton::someFunction()
{
    return mySingletonPrivate->foo;
}

Now code that wants to call someFunction() doesn't have to do

MySingleton::self()->someFunction();

anymore but instead:

MySingleton::someFunction();

Definition at line 221 of file kglobal.h.

#define K_GLOBAL_STATIC_WITH_ARGS	(	TYPE,
		NAME,
		ARGS
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This is the same as K_GLOBAL_STATIC, but can take arguments that are passed to the object's constructor.

Parameters

TYPE	The type of the global static object. Do not add a *.
NAME	The name of the function to get a pointer to the global static object.
ARGS	the list of arguments, between brackets

Example:

class A
{
public:
    A(const char *s, int i);
    ...
};
K_GLOBAL_STATIC_WITH_ARGS(A, globalA, ("foo", 0))
// The above creates a new globally static variable named 'globalA' which you
// can use as a pointer to an instance of A.
void doSomething()
{
    //  The first time you access globalA a new instance of A will be created automatically.
    A *a = globalA;
    ...
}

Definition at line 255 of file kglobal.h.

#define KDE_BF_ENUM ( a ) a

The KDE_BF_ENUM is used when storing an enum in a bitfield, to ensure correct conversion by all compilers.

See also: KDE_CAST_BF_ENUM

Definition at line 438 of file kdemacros.h.cmake.

#define KDE_CAST_BF_ENUM	(	a,
		b
	)	b

The KDE_CAST_BF_ENUM is used when retrieving an enum from a bitfield, to ensure correct conversion by all compilers.

See also: KDE_BF_ENUM

Definition at line 439 of file kdemacros.h.cmake.

#define KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED

The KDE_CONSTRUCTOR_DEPRECATED macro can be used to trigger compile-time warnings with newer compilers when deprecated constructors are used.

For non-inline constructors, the macro gets inserted at front of the constructor declaration, right before the return type:

KDE_CONSTRUCTOR_DEPRECATED classA();

For constructors which are implemented inline, the KDE_CONSTRUCTOR_DEPRECATED macro is inserted at the front, but after the "inline" keyword:

KDE_CONSTRUCTOR_DEPRECATED classA() { .. }

Note: Do not forget that inlined constructors are not allowed in public headers for KDE.

Definition at line 207 of file kdemacros.h.cmake.

#define KDE_DUMMY_COMPARISON_OPERATOR ( C )

The KDE_DUMMY_COMPARISON_OPERATOR defines a simple compare operator for classes.

See also: KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION; KDE_DUMMY_QHASH_FUNCTION

Definition at line 408 of file kdemacros.h.cmake.

#define KDE_DUMMY_QHASH_FUNCTION ( C )

The KDE_DUMMY_QHASH_FUNCTION defines a simple hash-function for classes.

See also: KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION; KDE_DUMMY_COMPARISON_OPERATOR

Definition at line 409 of file kdemacros.h.cmake.

#define KDE_EXPORT __attribute__ ((visibility("default")))

The KDE_EXPORT macro marks the symbol of the given variable to be visible, so it can be used from outside the resulting library.

int KDE_NO_EXPORT foo;

int KDE_EXPORT bar;

See also: KDE_NO_EXPORT

Definition at line 74 of file kdemacros.h.cmake.

#define KDE_IMPORT __attribute__ ((visibility("default")))

Definition at line 75 of file kdemacros.h.cmake.

#define KDE_IS_VERSION	(	a,
		b,
		c
	)	( KDE_VERSION >= KDE_MAKE_VERSION(a,b,c) )

Check if the KDE version matches a certain version or is higher.

This macro is typically used to compile conditionally a part of code:

#if KDE_IS_VERSION(4,0,90)
// Code for KDE 4.1
#else
// Code for KDE 4.0
#endif

Warning: Especially during development phases of KDE, be careful when choosing the version number that you are checking against. Otherwise you might risk to break the next KDE release. Therefore be careful that development version have a version number lower than the released version, so do not check e.g. for KDE 4.1 with KDE_IS_VERSION(4,1,0) but with the actual version number at a time a needed feature was introduced.

Definition at line 109 of file kdeversion.h.cmake.

#define KDE_ISLIKELY ( x ) ( x )

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.

Example:

if ( KDE_ISLIKELY( testsomething() ) )

abort(); // assume its likely that the application aborts

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 ).; Do NOT use ( !KDE_ISLIKELY(foo) ) as an replacement for KDE_ISUNLIKELY() !

See also: KDE_ISUNLIKELY

Definition at line 284 of file kdemacros.h.cmake.

#define KDE_ISUNLIKELY ( x ) ( x )

The KDE_ISUNLIKELY macro tags a boolean expression as likely to evaluate to false.

When used in an if ( ) statement, it gives a hint to the compiler that the following codeblock is unlikely 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.

Example:

if ( KDE_ISUNLIKELY( testsomething() ) )

abort(); // assume its unlikely that the application aborts

Note: Providing wrong information ( like marking a condition that almost never passes as 'unlikely' ) 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 ).; Do NOT use ( !KDE_ISUNLIKELY(foo) ) as an replacement for KDE_ISLIKELY() !

See also: KDE_ISLIKELY

Definition at line 285 of file kdemacros.h.cmake.

#define KDE_MAKE_VERSION	(	a,
		b,
		c
	)	(((a) << 16) \| ((b) << 8) \| (c))

Make a number from the major, minor and release number of a KDE version.

This function can be used for preprocessing when KDE_IS_VERSION is not appropriate.

Definition at line 75 of file kdeversion.h.cmake.

#define KDE_MUST_USE_RESULT

The KDE_MUST_USE_RESULT macro can be used to tell the compiler that a particular functions return value must be checked.

Definition at line 469 of file kdemacros.h.cmake.

#define KDE_NO_DEPRECATED

The KDE_NO_DEPRECATED indicates if the deprecated symbols of the platform have been compiled out.

Definition at line 218 of file kdemacros.h.cmake.

#define KDE_NO_EXPORT __attribute__ ((visibility("hidden")))

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.

int KDE_NO_EXPORT foo;

int KDE_EXPORT bar;

See also: KDE_EXPORT

Definition at line 73 of file kdemacros.h.cmake.

#define KDE_PACKED

The KDE_PACKED macro can be used to hint the compiler that a particular structure or class should not contain unnecessary paddings.

Definition at line 97 of file kdemacros.h.cmake.

#define KDE_VERSION KDE_MAKE_VERSION(KDE_VERSION_MAJOR,KDE_VERSION_MINOR,KDE_VERSION_RELEASE)

Version of KDE as number, at compile time.

This macro contains the KDE version in number form. As it is a macro, it contains the version at compile time. See version() if you need the KDE version used at runtime.

Definition at line 85 of file kdeversion.h.cmake.

#define KDE_VERSION_MAJOR ${KDE_VERSION_MAJOR}

Major version of KDE, at compile time.

Definition at line 54 of file kdeversion.h.cmake.

#define KDE_VERSION_MINOR ${KDE_VERSION_MINOR}

Minor version of KDE, at compile time.

Definition at line 60 of file kdeversion.h.cmake.

#define KDE_VERSION_RELEASE ${KDE_VERSION_RELEASE}

Release version of KDE, at compile time.

Definition at line 66 of file kdeversion.h.cmake.

#define KDE_VERSION_STRING "${KDE_VERSION_STRING}"

Version of KDE as string, at compile time.

This macro contains the KDE version in string form. As it is a macro, it contains the version at compile time. See versionString() if you need the KDE version used at runtime.

Note: The version string might contain a section in parentheses, especially for development versions of KDE. If you use that macro directly for a file format (e.g. OASIS Open Document) or for a protocol (e.g. http) be careful that it is appropriate. (Fictional) example: "4.0.90 (>=20070101)"

Definition at line 47 of file kdeversion.h.cmake.

#define KDE_WEAK_SYMBOL

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 overridden in another library, -Bdirect will not bind this symbol directly)

Definition at line 454 of file kdemacros.h.cmake.

#define RESERVE_VIRTUAL_1 virtual void reservedVirtual1() {}

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.

Definition at line 301 of file kdemacros.h.cmake.

#define RESERVE_VIRTUAL_2

Value:

virtual void reservedVirtual2() {} \

RESERVE_VIRTUAL_1

#define RESERVE_VIRTUAL_1

This macro, and it's friends going up to 10 reserve a fixed number of virtual functions in a class...

Definition: kdemacros.h.cmake:301

Definition at line 306 of file kdemacros.h.cmake.

#define RESERVE_VIRTUAL_3

Value:

virtual void reservedVirtual3() {} \