The MetaObject class provides access to meta-data of types at run-time. More...

#include <metaobject.hpp>

Inheritance diagram for Nuria::MetaObject:

Public Types
enum	GateMethod { ClassName = 0, MetaTypeId = 1, PointerMetaTypeId = 2, BaseClasses = 3, AnnotationCount = 4, MethodCount = 5, FieldCount = 6, EnumCount = 7, AnnotationName = 10, AnnotationValue = 11, MethodName = 20, MethodType = 21, MethodReturnType = 22, MethodArgumentNames = 23, MethodArgumentTypes = 24, MethodCallback = 25, MethodUnsafeCallback = 26, MethodArgumentTest = 27, FieldName = 30, FieldType = 31, FieldRead = 32, FieldWrite = 33, FieldAccess = 34, EnumName = 40, EnumElementCount = 41, EnumElementKey = 42, EnumElementValue = 43, DestroyInstance = 50 }

Public Member Functions
	MetaObject ()

virtual	~MetaObject ()

MetaAnnotation	annotation (int idx) const

int	annotationCount ()

int	annotationLowerBound (const QByteArray &name) const

int	annotationUpperBound (const QByteArray &name) const

QByteArray	className ()

void	destroyInstance (void *instance)

MetaEnum	enumAt (int idx)

MetaEnum	enumByName (const QByteArray &name)

int	enumCount ()

MetaField	field (int idx)

MetaField	fieldByName (const QByteArray &name)

int	fieldCount ()

int	metaTypeId ()

MetaMethod	method (int idx)

MetaMethod	method (const QVector< QByteArray > &prototype)

int	methodCount ()

int	methodLowerBound (const QByteArray &name)

int	methodUpperBound (const QByteArray &name)

QVector< QByteArray >	parents ()

int	pointerMetaTypeId ()

Static Public Member Functions
static MetaObjectMap	allTypes ()

static MetaObject *	byName (const QByteArray &type)

static MetaObject *	byTypeId (int typeId)

template<typename T >
static MetaObject *	of ()

static void	registerMetaObject (MetaObject *object)
	Registers object to the global meta system. More...

static MetaObjectMap	typesInheriting (const QByteArray &typeName)

static MetaObjectMap	typesWithAnnotation (const QByteArray &name)

Protected Member Functions
virtual void	gateCall (GateMethod method, int category, int index, int nth, void result, void additional=0)=0

Friends
class	MetaAnnotation

class	MetaEnum

class	MetaField

class	MetaMethod

Detailed Description

The MetaObject class provides access to meta-data of types at run-time.

Instances of this class are usually generated by Tria, the code-generator of the Nuria Framework. While this is the primary use-case, you're free to sub-class this class yourself to create types at run-time.

Using Tria you're able to "expose" arbitary structures to be used dynamically at run-time.

How to use Tria: Tria is a code-generator comparable to Qt's meta object compiler (moc). And like moc, Tria will be run on all header files in a project. All you need to do for this is to include the Nuria Framework in your project using the known mechanism:

CONFIG += nuria

NURIA += core

If you want to use tria without qmake, please see the nuria.prf file and tria itself for information (Calling it with "-h" as argument).

Preparing structures for Tria: To tell Tria you want to a structure to be exported you'll use the NURIA_INTROSPECT annotation. Keep in mind that attributes of any kind go after the terminal for structs/classes and enums and go before methods and fields:

// structs/classes and enums expect annotations *after* the terminal.
struct NURIA_INTROSPECT NURIA_ANNOTATE(IsAClass, true) {
  enum NURIA_ANNOTATE(IsAEnum, 2 / 2) Foo { };
  // Methods and fields expect annotations in front.
  NURIA_ANNOTATE(IsAMethod, "yes")
  QVariant iAmAMethod ();
  
  NURIA_ANNOTATE(IsAField, true)
  int field;
};

That already covers the basics. You should probably Q_DECLARE_METATYPE your types. Tria will automatically do this in the generated code for all needed types though.

Automatically exported things: Tria will export public methods (member methods, static methods and constructors), enums (Including elements) and fields ("raw fields" and user-defined ones with accessor methods). Everything else, including private and protected elements, is ignored. To explicitly ignore a element, annotate it with NURIA_SKIP.

Annotations in overview: There are currently multiple annotations available.

NURIA_INTROSPECT will mark a struct or a class to be exported. It's ignored on anything else.

NURIA_SKIP can be used to explicitly mark elements (methods, enums, fields) to be ignored by Tria.

NURIA_READ and NURIA_WRITE mark a method to be used as getter or setter method for the field whose name is passed as only argument. Methods with this annotation will not be exposed as methods themselves. Please refer to MetaField for further information.

NURIA_REQUIRE is a powerful mechanism which lets you write a requirement which needs to be fulfilled for the operation to succeed. Can be applied to fields and methods (Of all kind). The macro itself takes a C++ condition as check. The condition can call methods as well as use fields directly, as long the method/field the macro is applied to requires a instance of the object itself (E.g., it's a member method). These conditions are embedded into the generated source by Tria, thus there's no notable overhead introduced here.

Detection of conversions in Tria

Tria will automatically detect methods supporting conversions. These are:

Constructors taking only one argument
Static methods beginning with "from" taking one argument
Member methods beginning with "to" taking one argument
C++ conversion operators

Except for the conversion operators, all methods are still exposed as normal methods. Methods may take additional optional arguments.

Note: The conversion is registered in the QVariant conversion feature introduced in Qt5.2; This is a feature of Tria, not of MetaObject. Thus, custom sub-classes of MetaObject won't have this feature.

Order of elements: All elements, that is, parent-class names, annotations, methods, fields and enums are sorted by name by the MetaObject. Annotations of enums, fields and methods are sorted too, as are enum keys.

This means that all elements are sorted in ascending order, which allows you to use binary search algorithms.

Creating types at run-time: You can sub-class MetaObject yourself if you need to create types at run-time, e.g. when embedding a scripting language. You'll need to implement the protected gateCall method. While it may look strange to only have a single virtual method for everything, this method was chosen as it reduces the size of a MetaObject significantly while offering marginal run-time overhead. On top of that it ensures that MetaObject can be extended in the future without breaking ABI or API compatibility.

Please refer to the GateMethod enum class. You can also read the source code of MetaObject or open a file generated by Tria.

See also: Nuria::MetaObject::GateMethod

Member Enumeration Documentation

enum Nuria::MetaObject::GateMethod

strong

Methods for gateCall. You only need to know about this if you intend to sub-class MetaObject yourself.

Constructor & Destructor Documentation

Nuria::MetaObject::MetaObject ( )

inline

Constructor, does nothing.

virtual Nuria::MetaObject::~MetaObject ( )

inlinevirtual

Destructor, does nothing.

Member Function Documentation

static MetaObjectMap Nuria::MetaObject::allTypes ( )

static

Returns a map of all known types.

MetaAnnotation Nuria::MetaObject::annotation ( int idx ) const

Returns the MetaAnnotation instance for the annotation at idx.

See also: annotationCount

int Nuria::MetaObject::annotationCount ( )

Returns the number of known annotations.

See also: annotation

int Nuria::MetaObject::annotationLowerBound ( const QByteArray & name ) const

Returns the index of the first annotation name. Returns -1 if there's no annotation called like that.

int Nuria::MetaObject::annotationUpperBound ( const QByteArray & name ) const

Returns the index of the last annotation name. Returns -1 if there's no annotation called like that.

static MetaObject* Nuria::MetaObject::byName ( const QByteArray & type )

static

Returns the corresponding MetaObject instance for type. If type is not known, nullptr is returned.

static MetaObject* Nuria::MetaObject::byTypeId ( int typeId )

static

Returns the MetaObject for the type typeId. If typeId may be the Qt type id for T* or T. If no matching meta object is found nullptr is returned.

QByteArray Nuria::MetaObject::className ( )

Returns the class name of the represented type.

void Nuria::MetaObject::destroyInstance ( void * instance )

Destroys instance.

Warning: instance must be of the type the MetaObject represents, else the behaviour is undefined!

MetaEnum Nuria::MetaObject::enumAt ( int idx )

Returns the MetaEnum instance for the enum at idx.

See also: enumCount

MetaEnum Nuria::MetaObject::enumByName ( const QByteArray & name )

Tries to find the enum name. Returns a valid MetaEnum instance on success, else the instance is invalid.

See also: MetaEnum::isValid

int Nuria::MetaObject::enumCount ( )

Returns the number of known enums.

See also: enumAt

MetaField Nuria::MetaObject::field ( int idx )

Returns the MetaField instance for the field at idx.

See also: fieldCount

MetaField Nuria::MetaObject::fieldByName ( const QByteArray & name )

Tries to find the field name. Returns a valid MetaField instance on success, else the instance is invalid.

See also: MetaField::isValid

int Nuria::MetaObject::fieldCount ( )

Returns the number of known fields.

See also: field

virtual void Nuria::MetaObject::gateCall	(	GateMethod	method,
		int	category,
		int	index,
		int	nth,
		void *	result,
		void *	additional = `0`
	)

protectedpure virtual

Calls the back-end. method will be called, passing category, target and index, the result will be written to result.

Implemented in Nuria::RuntimeMetaObject.

int Nuria::MetaObject::metaTypeId ( )

Returns the Qt meta-type id of this type. Returns 0 if this type doesn't have value-semantics.

MetaMethod Nuria::MetaObject::method ( int idx )

Returns the MetaMethod instance for the method at idx.

See also: methodCount

MetaMethod Nuria::MetaObject::method ( const QVector< QByteArray > & prototype )

Tries to find the method prototype. The first item in prototype is the method name, all latter items are typenames of the arguments in the correct order.

The method name of a constructor is "" (Empty). If the method can't be found, the returned method is invalid.

int Nuria::MetaObject::methodCount ( )

Returns the number of known methods.

See also: method

int Nuria::MetaObject::methodLowerBound ( const QByteArray & name )

Returns the index of the first overload of method name. Returns -1 if there's no method called like that.

int Nuria::MetaObject::methodUpperBound ( const QByteArray & name )

Returns the index of the last overload of method name. Returns -1 if there's no method called like that.

template<typename T >

static MetaObject* Nuria::MetaObject::of ( )

inlinestatic

Returns the MetaObject of T. For this to work, T* has to be registered to the Qt meta system using Q_DECLARE_METATYPE(T*)

QVector< QByteArray > Nuria::MetaObject::parents ( )

Returns a list of types this type inherits.

int Nuria::MetaObject::pointerMetaTypeId ( )

Returns the Qt meta-type id of this type as pointer.

static void Nuria::MetaObject::registerMetaObject ( MetaObject * object )

static

Registers object to the global meta system.

This method will not take ownership of object, you'll need to make sure that it'll survive until the application quits. Please note that you rarely need to do this by hand.

Warning: The class-name of object must be unique application-wide, else you'll override a already existing type.

static MetaObjectMap Nuria::MetaObject::typesInheriting ( const QByteArray & typeName )

static

Returns all types which inherit typeName.

Note: A type does not inherit itself.

static MetaObjectMap Nuria::MetaObject::typesWithAnnotation ( const QByteArray & name )

static

Returns all types which have a annotation called name stored in the type. This method does not search through methods, etc.

The documentation for this class was generated from the following file:

metaobject.hpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation