Interface Annotations


An interface defines a class that is the base for both the implementation and the automatically created reference class. It is possible to add annotations to the interface to change the behaviour of the Source Processor when creating the reference class.

Annotations are added as comments in this form:

// @MAXON_ANNOTATION{refclass=false}

Interface Annotations

Annotations can be added to the interface itself. These annotations define the overall creation of the reference class.

  • refclass: Defines how the reference class is created. Valid settings are:
    • false: No reference class is created.
  • refprefix: Defines a prefix that is added to the reference class name.

Method Annotations

Annotations can also be added to single functions of the interface.

  • refclass: If set to false the function is not added to the reference class.
  • default: Defines the default return value in case of an error (e.g. no implementation was found).
  • refclassParameter: Set to the name of a function template parameter that should be replaced with the actual reference class.

Special annotations for COW interfaces are:

  • cowName: Changes the name of the generated function of the COW reference class.


Annotations are used on the definition of the interface.

// This example shows an interface with additional annotations.
// ---------------------------------------------------------------------
// The reference class should be named GenericElementArrayRef
// @MAXON_ANNOTATION{refprefix=Generic}
// ---------------------------------------------------------------------
class ElementArrayInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
MAXON_INTERFACE(ElementArrayInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.elementarray");
// ---------------------------------------------------------------------
// If this function is not implemented it should return maxon::InvalidArrayIndex.
// @MAXON_ANNOTATION{default = maxon::InvalidArrayIndex}
// ---------------------------------------------------------------------
// ---------------------------------------------------------------------
// This function should not be added to the reference class.
// @MAXON_ANNOTATION{refclass=false}
// ---------------------------------------------------------------------
// ---------------------------------------------------------------------
// This function should be used instead.
// ---------------------------------------------------------------------
if (e == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, maxon::String("Invalid Index."));
return e;
// ---------------------------------------------------------------------
// This function returns a clone of the array and returns an object of
// the currently used reference class type.
// @MAXON_ANNOTATION{refclassParameter=REFCLASS}
// ---------------------------------------------------------------------
template <typename REFCLASS> MAXON_FUNCTION maxon::Result<REFCLASS> CloneArray() const
return REFCLASS(static_cast<typename REFCLASS::ReferencedType*>(o));
Definition: annotations.h:19
MAXON_FUNCTION maxon::Result< Element * > GetElementResult(maxon::Int index)
Definition: annotations.h:38
MAXON_METHOD Element * GetElement(maxon::Int index)
MAXON_METHOD maxon::Int FindIndex(Element *e) const
MAXON_INTERFACE(ElementArrayInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.elementarray")
MAXON_FUNCTION maxon::Result< REFCLASS > CloneArray() const
Definition: annotations.h:52
Definition: objectbase.h:1371
Definition: resultbase.h:766
Definition: string.h:1235
Py_ssize_t * index
Definition: abstract.h:374
PyObject * o
Definition: abstract.h:325
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:188
Definition: interfacebase.h:1022
Definition: interfacebase.h:1173
Definition: memoryallocationbase.h:67
Definition: interfacebase.h:1001
Definition: objectbase.h:1062
Py_ssize_t * e
Definition: longobject.h:89
#define iferr_scope
Definition: resultbase.h:1374
#define iferr_return
Definition: resultbase.h:1465
Definition: annotations.h:7

The behaviour of the created reference class is defined by the annotations.

// This example uses the reference class defined with various annotations.
// create a NullValue
GenericElementArrayRef nullValue;
// since FindIndex() is not implemented it should
// return the defined return value
const maxon::Int index = nullValue.FindIndex(nullptr);
DiagnosticOutput("Could not find element.");
// create proper instance
const maxon::Class<GenericElementArrayRef> componentClass = maxon::Classes::Get<GenericElementArrayRef>(id);
const GenericElementArrayRef elementArray = componentClass.Create() iferr_return;
// use some functions
GenericElementArrayRef elements = elementArray.CloneArray() iferr_return;
Element* const e = elementArray.GetElementResult(-1) iferr_return;
Definition: objectbase.h:709
static const Int InvalidArrayIndex
Invalid array index (e.g. returned for an array index out of bounds).
Definition: apibase.h:280
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176

Further Reading