Interface Annotations

Table of Contents

• About
• Interface Annotations
• Method Annotations
• Usage
• Further Reading

About

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.

Usage

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");
 
public:
  // ---------------------------------------------------------------------
  // If this function is not implemented it should return maxon::InvalidArrayIndex.
  // @MAXON_ANNOTATION{default = maxon::InvalidArrayIndex}
  // ---------------------------------------------------------------------
  MAXON_METHOD maxon::Int FindIndex(Element * e) const;
 
  // ---------------------------------------------------------------------
  // This function should not be added to the reference class.
  // @MAXON_ANNOTATION{refclass=false}
  // ---------------------------------------------------------------------
  MAXON_METHOD Element* GetElement(maxon::Int index);
 
  // ---------------------------------------------------------------------
  // This function should be used instead.
  // ---------------------------------------------------------------------
  MAXON_FUNCTION maxon::Result<Element*> GetElementResult(maxon::Int index)
  {
    Element* e = GetElement(index);
    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
  {
    iferr_scope;
 
    maxon::ObjectInterface* o = Clone() iferr_return;
    return REFCLASS(static_cast<typename REFCLASS::ReferencedType*>(o));
  }
};

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);
  if (index == maxon::InvalidArrayIndex)
    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;
 

Further Reading

• Interface Basics
• Interface Declaration
• Using Interfaces
• Reference Types