Interface Methods

Table of Contents

• About
• MAXON_METHOD
• MAXON_FUNCTION
• Plain Functions
• Reference Class Attributes
• Further Reading

About

An interface declares various methods. These methods must either be defined in an implementation of that interface or in the interface itself. Depending on the type of function, a method will also be part of the generated reference class.

MAXON_METHOD

The attribute MAXON_METHOD declares a function that must be defined in an implementation of the given interface.

A declaration of a MAXON_METHOD looks like this:

// This example shows an interface that declares a MAXON_METHOD function
// that can be defined in any implementation of this interface.
 
// ---------------------------------------------------------------------
// Primitive automobile class.
// ---------------------------------------------------------------------
class AutomobileInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(AutomobileInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.automobile1");
 
public:
  //----------------------------------------------------------------------------------------
  // Returns the number of wheels.
  //----------------------------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetWheelCount() const;
};

The implementation of this MAXON_METHOD is defined as:

// This example implements an interface and the MAXON_METHOD declared in the interface.
 
// implementation of AutomobileInterface
class TruckImplementation : public maxon::Component<TruckImplementation, AutomobileInterface>
{
  MAXON_COMPONENT();
 
public:
  MAXON_METHOD maxon::Int GetWheelCount() const
  {
    return 6;
  }
};

Finally this method can be used with the generated reference class:

  // This example creates an object of the given implementation and calls the implemented function.
 
  // access component class
  const maxon::Class<AutomobileRef> componentClass = maxon::Classes::Get<AutomobileRef>(id);
 
  // create new object
  const AutomobileRef truck = componentClass.Create() iferr_return;
 
  // use object
  const maxon::Int wheels = truck.GetWheelCount();
  DiagnosticOutput("Wheels: @", wheels);

If a MAXON_METHOD marked function is private or protected, it can still be defined in an implementation. But it will not be added to the reference class.

MAXON_FUNCTION

The attribute MAXON_FUNCTION defines a method that cannot be defined in a component. Instead it must be defined in the interface declaration. The method is added to the generated reference class.

Note

A MAXON_FUNCTION can be a function template.

// This example shows an interface that declares a MAXON_FUNCTION function.
// This function must be implemented in the interface and is available in the reference class.
 
// ---------------------------------------------------------------------
// Primitive automobile class.
// ---------------------------------------------------------------------
class AutomobileInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(AutomobileInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.automobile2");
 
public:
  //----------------------------------------------------------------------------------------
  // Returns the number of wheels.
  //----------------------------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetWheelCount() const;
 
  //----------------------------------------------------------------------------------------
  // Returns the number of wheels as a maxon::Float value.
  //----------------------------------------------------------------------------------------
  MAXON_FUNCTION maxon::Float GetWheelCountFloat()
  {
    return maxon::Float(GetWheelCount());
  }
};

The method can be used with the reference class.

  // This example creates an object of the given implementation and calls a function implemented in the interface itself.
 
  // access component class
  const maxon::Id id { "net.maxonexample.class.automobiles.functions" };
  const maxon::Class<AutomobileRef> componentClass = maxon::Classes::Get<AutomobileRef>(id);
 
  // create new object
  const AutomobileRef truck = componentClass.Create() iferr_return;
 
  // use object
  const maxon::Float wheels = truck.GetWheelCountFloat();
  DiagnosticOutput("Wheels: @", wheels);

Plain Functions

A function that is added to an interface without any attribute cannot be defined in a component and will not be part of the generated reference class. It can only act as an (internal) utility function that is used within other functions.

// This example shows an interface that declares a MAXON_METHOD function and some plain function.
// The plain function must be implemented in the interface and can only be used in implementations of the interface,
// not in reference classes.
 
// ---------------------------------------------------------------------
// Primitive automobile class.
// ---------------------------------------------------------------------
class AutomobileInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(AutomobileInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.automobile3");
 
public:
  //----------------------------------------------------------------------------------------
  // Returns the number of wheels.
  //----------------------------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetWheelCount() const;
 
  //----------------------------------------------------------------------------------------
  // Returns half the number of wheels. For internal use.
  //----------------------------------------------------------------------------------------
  maxon::Int GetHalfWheelCount() const;
};

// This example implements a plain function declared in the interface.
 
maxon::Int AutomobileInterface::GetHalfWheelCount() const
{
  return GetWheelCount() / 2;
}

Reference Class Attributes

With these attributes it is possible to add any additional code (e.g. simple functions) to the generated reference class.

• MAXON_ADD_TO_REFERENCE_CLASS: Adds the given code to the reference class.
• MAXON_ADD_TO_CONST_REFERENCE_CLASS: Adds the given code to the const reference class.
• MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS: Adds the given code to the copy-on-write reference class.

Note

The code marked with these attributes is simply copied into the .hxx files. It can also be used for typedefs, using, etc.

In most cases it is recommended to rather use MAXON_FUNCTION.

// This example shows an interface that declares a MAXON_METHOD function.
// An additional function is added to the reference class using the specific macro.
 
// ---------------------------------------------------------------------
// Primitive automobile class.
// ---------------------------------------------------------------------
class AutomobileInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(AutomobileInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.automobile4");
 
public:
  //----------------------------------------------------------------------------------------
  // Returns the number of wheels.
  //----------------------------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetWheelCount() const;
 
  MAXON_ADD_TO_REFERENCE_CLASS(
    //----------------------------------------------------------------------------------------
    // Returns half the number of wheels.
    //----------------------------------------------------------------------------------------
    maxon::Int GetHalfWheelCount() const
    {
      return this->GetWheelCount() / 2;
    };
    );
};

The function that was defined this way is simply used with the reference class:

  // This example creates a reference to the given implementation and
  // calls a function that was added to the reference class.
 
  // access component class
  const maxon::Id id { "net.maxonexample.class.automobiles.const" };
  const maxon::Class<AutomobileRef> componentClass = maxon::Classes::Get<AutomobileRef>(id);
 
  // create new object
  const AutomobileRef truck = componentClass.Create() iferr_return;
 
  // use object
  const maxon::Int wheels = truck.GetHalfWheelCount();
  DiagnosticOutput("Wheels: @", wheels);

Often interfaces contain both const and non-const functions to access internal data. This can easily be implemented with MAXON_NONCONST_COUNTERPART. See Generic Macros.

Further Reading

• Interface Basics
• Interface Declaration
• Interface Implementation
• Object Interface