QGlib Namespace Reference

Classes
class	Error
class	Interface
class	Object
class	ObjectBase
class	ParamSpec
class	Quark
class	RefCountedObject
class	RefPointer
class	Signal
class	Type
class	Value
struct	ValueImpl
struct	ValueVTable

Typedefs
typedef RefPointer< ParamSpec >	ParamSpecPtr
typedef RefPointer< Object >	ObjectPtr

Enumerations
enum	ConnectFlag { ConnectAfter = 1, PassSender = 2 }

Functions
template<typename T , typename R , typename... Args>
bool	connect (void *instance, const char *detailedSignal, T *receiver, R(T::*slot)(Args...), ConnectFlags flags=0)
template<typename T , typename R , typename... Args>
bool	disconnect (void *instance, const char *detailedSignal=0, T *receiver=0, R(T::*slot)(Args...)=0)
template<typename R , typename... Args>
R	emit (void *instance, const char *detailedSignal, const Args &...args)
template<typename R , typename... Args>
R	emitWithDetail (void *instance, const char *signal, Quark detail, const Args &...args)
QDebug	operator<< (QDebug dbg, const Error &error)
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::RunFirst)==static_cast< int >(G_SIGNAL_RUN_FIRST))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::RunLast)==static_cast< int >(G_SIGNAL_RUN_LAST))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::RunCleanup)==static_cast< int >(G_SIGNAL_RUN_CLEANUP))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::NoRecurse)==static_cast< int >(G_SIGNAL_NO_RECURSE))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::Detailed)==static_cast< int >(G_SIGNAL_DETAILED))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::Action)==static_cast< int >(G_SIGNAL_ACTION))
	BOOST_STATIC_ASSERT (static_cast< int >(Signal::NoHooks)==static_cast< int >(G_SIGNAL_NO_HOOKS))
QGlib::RefCountedObject *	ParamSpec_new (void *instance)
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::Readable)==static_cast< int >(G_PARAM_READABLE))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::Writable)==static_cast< int >(G_PARAM_WRITABLE))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::ReadWrite)==static_cast< int >(G_PARAM_READWRITE))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::Construct)==static_cast< int >(G_PARAM_CONSTRUCT))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::ConstructOnly)==static_cast< int >(G_PARAM_CONSTRUCT_ONLY))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::LaxValidation)==static_cast< int >(G_PARAM_LAX_VALIDATION))
	BOOST_STATIC_ASSERT (static_cast< int >(ParamSpec::Deprecated)==static_cast< int >(G_PARAM_DEPRECATED))
QGlib::RefCountedObject *	Object_new (void *instance)
QGlib::RefCountedObject *	Interface_new (void *instance)
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Invalid)==static_cast< int >(G_TYPE_INVALID))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::None)==static_cast< int >(G_TYPE_NONE))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Interface)==static_cast< int >(G_TYPE_INTERFACE))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Char)==static_cast< int >(G_TYPE_CHAR))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Uchar)==static_cast< int >(G_TYPE_UCHAR))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Boolean)==static_cast< int >(G_TYPE_BOOLEAN))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Int)==static_cast< int >(G_TYPE_INT))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Uint)==static_cast< int >(G_TYPE_UINT))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Long)==static_cast< int >(G_TYPE_LONG))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Ulong)==static_cast< int >(G_TYPE_ULONG))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Int64)==static_cast< int >(G_TYPE_INT64))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Uint64)==static_cast< int >(G_TYPE_UINT64))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Enum)==static_cast< int >(G_TYPE_ENUM))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Flags)==static_cast< int >(G_TYPE_FLAGS))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Float)==static_cast< int >(G_TYPE_FLOAT))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Double)==static_cast< int >(G_TYPE_DOUBLE))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::String)==static_cast< int >(G_TYPE_STRING))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Pointer)==static_cast< int >(G_TYPE_POINTER))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Boxed)==static_cast< int >(G_TYPE_BOXED))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Param)==static_cast< int >(G_TYPE_PARAM))
	BOOST_STATIC_ASSERT (static_cast< int >(Type::Object)==static_cast< int >(G_TYPE_OBJECT))
void	init ()
template<class T >
Type	GetType ()
QDebug	operator<< (QDebug debug, const Value &value)
RefCountedObject *	constructWrapper (Type instanceType, void *instance)

Detailed Description

Wrappers for Glib and GObject classes.

This namespace provides wrapper classes for objects from the Glib and GObject libraries, plus some helper classes that provide the foundations for building C++/Qt bindings for GObject-based libraries.

Note

This namespace is contained in the QtGLib library.

Enumeration Type Documentation

enum QGlib::ConnectFlag

These flags define options that can be passed to connect() to modify its behaviour.

Enumerator
ConnectAfter	If ConnectAfter is specified, the slot passed to connect() will be invoked after the default signal handler of this signal has been called. See the Glib signals documentation for more details on this parameter.
PassSender	If PassSender is specified, the slot passed to connect() will receive as the first argument a pointer to the sender of the signal. Thus, your slot should be defined like this: void mySlot(const QGlib::ObjectPtr & sender, const Foo & firstArgument, ...);

Definition at line 36 of file connect.h.

Function Documentation

template<typename T , typename R , typename... Args>

bool QGlib::connect	(	void *	instance,
		const char *	detailedSignal,
		T *	receiver,
		R(T::*)(Args...)	slot,
		ConnectFlags	flags = 0
	)

Connects detailedSignal of instance to the specified slot of receiver.

This method provides a way of connecting GObject signals to C++ slots, in a Qt-like fashion.

instance needs to be a pointer to a GLib instantiatable type, such as a GObject. You can pass a RefPointer as an argument here without any problems; it will automatically cast to void*.

detailedSignal should be the name of the signal that you want to conenct to - with an optional detail, if the signal supports details. The signal must not use the Qt SIGNAL() macro; it should use the signal canonical form specified in GLib, i.e. it should be a string containing only lowercase letters and dashes. For example, "my-signal" is a valid signal name. The detail may be specified by appending "::" to the signal name and the detail after that. For example, "my-signal::detail".

receiver should be the instance of the class on which slot will be invoked. Currently, the receiver needs to inherit QObject. If you use another class that doesn't inherit QObject, a compilation error will occur.

slot should be a C++ member function pointer that points to the method that you want to be invoked on the receiver once the signal is emitted. Note that it must not use the Qt SLOT() macro.

Special care must be taken with the arguments that slot takes. Consider the following example. The C API documentation mentions a signal that takes these parameters:

void user_function (GObject *object, GParamSpec *pspec, gpointer user_data);

The first argument is always a pointer to the sender object, the second argument is the real signal argument and the third argument is a user defined pointer that is usually used in C as a substitute for the receiver. In general, the first argument is always the sender, the 2nd to Nth-1 arguments are the real signal arguments and the Nth argument is a user defined pointer. Now in C++, the following rules apply:

• You must use the C++ equivalent types of the arguments that the signal sends. So, in the above example, GParamSpec* is translated to QGlib::ParamSpecPtr.
• You must not have the user_data argument at the end.
• You must not have the sender argument at the beginning, unless QGlib::PassSender is used in flags.
• You may use const references in the arguments to avoid unecessary copying of objects, as the C++ marshaller that will call your slot will always hold a copy of the converted C++ objects.

So, the C++ signature should eventually be:

void MyClass::mySlot(const QGlib::ParamSpecPtr & pspec);
...
//Connected with:
QGlib::connect(element, "notify::name", myClassInstance, &MyClass::mySlot);

or

void MyClass::mySlot(const QGlib::ObjectPtr & sender, const QGlib::ParamSpecPtr & pspec);
...
//Connected with:
QGlib::connect(element, "notify::name", myClassInstance, &MyClass::mySlot, QGlib::PassSender);

Internally, the signal provides GValues that are converted to the C++ types that your slot specifies using Value::get(), so all rules that apply there also apply to the slot arguments. That means that you may actually use different types of arguments than the ones that the documentation specifies, given that Value is able to transform them (see Value::canTransformTo) to the type that you have requested. Obviously, if you specify non-compatible arguments on the slot, the conversion will fail, and in this case a warning is printed at the time of the signal emission and the slot is not invoked.

Note

• Include <QGlib/Connect> to use this function
• Unlike Qt, in GObject some signals are able to return values back to the sender. In this case, your slot should specify a compatible return type instead of void.
• This method makes use of C++0x features (namely, variadic templates and rvalue references). If your compiler does not support them, a hacky implementation using boost's preprocessor, function and bind libraries will be compiled instead. That version has a limit of 9 slot arguments.
• This function is thread-safe.

Returns

whether the connection was successfully made or not

See also

disconnect(), ConnectFlag, Connect Design

Examples:

examples/appsink-src/main.cpp, examples/player/main.cpp, examples/qmlplayer/main.cpp, examples/recorder/main.cpp, and examples/voip/main.cpp.

Definition at line 186 of file connectimpl.h.

template<typename T , typename R , typename... Args>

bool QGlib::disconnect	(	void *	instance,
		const char *	detailedSignal = 0,
		T *	receiver = 0,
		R(T::*)(Args...)	slot = 0
	)

Disconnects detailedSignal of instance from the slot of receiver.

A signal-slot connection typically is broken when either of the objects involved are destroyed. However, there are cases in which you might want to break that connection manually using this method.

disconnect() can be used in the following ways:

• Disconnect everything connected to an object's signals:

  disconnect(myGObject);

• Disconnect everything connected to a specific signal:

  disconnect(myGObject, "some-signal");

• Disconnect a specific receiver:

  disconnect(myGObject, 0, myReceiver);

• Disconnect a specific slot (note that the receiver must also be specified):

  disconnect(myGObject, 0, myReceiver, &MyReceiver::mySlot);

0 can be used as a wildcard, meaning "any signal", "any receiver" or "any slot". instance can never be 0.

If detailedSignal is 0, it disconnects receiver and slot from any signal. Otherwise, only detailedSignal is disconnected. A signal detail may or may not be specified. If it is not specified, it acts as a wildcard for all details, meaning it disconnects all the connections that have been made with a specific detail.

If receiver is 0, it disconnects anything connected to detailedSignal. If not, only slots in receiver are disconnected.

If slot is 0, it disconnects anything that is connected to receiver. If not, only the specified slot will be disconnected. Note that slot must be 0 if receiver is left out.

Note

• Include <QGlib/Connect> to use this function
• This function is thread-safe.

Returns

true if the connection was successfully broken, or false otherwise

See also

connect()

template<typename R , typename... Args>

R QGlib::emit	(	void *	instance,
		const char *	detailedSignal,
		const Args &...	args
	)

Emits a signal on a specified instance with the specified arguments.

This method will convert all the specified arguments to GValues using Value::set() and will then emit the signal using g_signal_emitv(). The returned value from the signal (if the signal returns a value) will be converted from GValue to the type R using Value::get() and will be returned. If some argument is not of the type that the signal expects and a conversion is not possible, a warning will be printed to stderr at runtime and the signal will not be emitted. On the contrary, if the return value is not of the type that the signal returns and a conversion is not possible, the signal will be emitted, but a default-constructed value for the type R will be returned and a warning will be printed to stderr.

Note that since the implementation uses Value::set() to convert the GValues into the specified types, the same rules that apply to Value::set() apply here (i.e. you should only use the types of the bindings and not the C types, which means QGst::ObjectPtr instead of GstObject*, etc...).

Emitting a signal is useful for the so-called Action signals. These are meant to be emitted from the application and not connected to. They are more like dynamic methods that can be identified with a string.

Note

• This method makes use of C++0x features (namely, variadic templates and rvalue references). If your compiler does not support them, a hacky implementation using boost's preprocessor, function and bind libraries will be compiled instead. That version has a limit of 9 arguments by default. Define QGLIB_SIGNAL_MAX_ARGS to a greater value before including QGlib/Signal if you want to support more arguments.
• This function's name clashes with Qt's emit keyword. To compile it successfully, the headers will undefine Qt's emit and print a warning at compile time. It is recommended that you compile your project with QT_NO_KEYWORDS to avoid this, however note that this means that the "signals", "slots" and "foreach" keywords will also be unavailable under these names (you can use "Q_SIGNALS", "Q_SLOTS" and "Q_FOREACH" respectively). If you do not wish to do that, you can also define QT_NO_EMIT or QGLIB_NO_EMIT_WARNING. The first one undefines Qt's emit completely and the second one supresses the warning and undefines Qt's emit in all the code files that include the QGlib/Signal header. In all cases, to emit Qt signals you will have to use "Q_EMIT" instead of "emit".

Parameters

instance	The instance of the object on which the signal will be emitted. You can pass a RefPointer as an instance without any problems; it will automatically cast to void*.
detailedSignal	The name of the signal that you want to emit, with an optional detail if the signal is detailed. The detail may be specified with the following syntax: "signal::detail".
args	The arguments that will be passed to the signal.

Returns

The return value of the signal.

Definition at line 111 of file emitimpl.h.

template<typename R , typename... Args>

R QGlib::emitWithDetail	(	void *	instance,
		const char *	signal,
		Quark	detail,
		const Args &...	args
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This method takes the detail argument as a quark, separated from the signal name. It may be useful if you already have the quark of the detail that you want to specify.

Definition at line 117 of file emitimpl.h.

void QGlib::init

(

)

Initializes the type system. You must call this function before using any QtGLib API.

Note

You need to include <QGlib/Init> to use this function.

Definition at line 27 of file init.cpp.

RefCountedObject * QGlib::constructWrapper	(	Type	instanceType,
		void *	instance
	)

This function constructs a RefCountedObject that wraps the given instance, which is of type instanceType. It returns a C++ wrapper class that inherits RefCountedObject and wraps instanceType objects in the best possible way.

This function is provided for implementing bindings that use QtGLib. It is only needed if those bindings have some reference counted instance type that is not an Object or Interface or ParamSpec (like QGst::MiniObject and QGst::Caps). You should not otherwise call this function directly.

Definition at line 24 of file wrap.cpp.