Using Interfaces

Table of Contents

• About
• Reference Objects
• ClassInterface
• Object Class
• Further Reading

About

The functionality presented by an interface is used by creating an instance of the reference class. The definition of that reference class is created automatically based on the interface class by the Source Processor and is stored in the automatically generated .hxx files.

A reference object gives access to a component or just contains a maxon::NullValue. Reference objects are typically reference counted (depending on the Reference Type).

Reference Objects

A simple interface can be defined like this:

// This example shows the declaration of a simple interface.
 
// ---------------------------------------------------------------------
// Simple class that stores a maxon::Int number.
// ---------------------------------------------------------------------
class SimpleClassInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
  MAXON_INTERFACE(SimpleClassInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.simpleclass");
 
public:
  // ---------------------------------------------------------------------
  // Sets the number to store.
  // ---------------------------------------------------------------------
  MAXON_METHOD void SetNumber(maxon::Int number);
 
  // ---------------------------------------------------------------------
  // Returns the stored number.
  // ---------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetNumber() const;
};
 
// This interface is declared in a file named "simpleclass.h". The automatically
// generated files are therefore named "simpleclass1.hxx" and "simpleclass2.hxx"
 
// The .hxx header files define the reference class "SimpleClassRef".
 
#include "simpleclass1.hxx"
 
// declare the published objects "SomeSimpleClass" and "OtherSimpleClass"
// that give access to implementations of SimpleClassInterface
 
// the declaration must be placed between the two hxx files since "SimpleClassRef" is defined in the first hxx file
 
MAXON_DECLARATION(maxon::Class<SimpleClassRef>, SomeSimpleClass, "net.maxonexample.somesimpleclass");
MAXON_DECLARATION(SimpleClassRef, OtherSimpleClass, "net.maxonexample.othersimpleclass");
 
#include "simpleclass2.hxx"
 

There are multiple ways to create a reference object. One way is to access the component class of the desired implementation. This component class is identified with a maxon::Id.

The direct way to obtain the component class is to get it from the global registry maxon::Classes with maxon::Classes::Get().

  // This example creates an instance of an interface
  // and uses the created instance.
 
  // define the ID of the component to use
  const maxon::Id id { "net.maxonexample.class.somesimpleclass" };
 
  // get component class of the given ID from the global maxon::Classes registry
  const maxon::Class<SimpleClassRef>& componentClass = maxon::Classes::Get<SimpleClassRef>(id);
 
  // create reference
  const SimpleClassRef simpleClass = componentClass.Create() iferr_return;
 
  // use reference
  simpleClass.SetNumber(123);
  const maxon::Int number = simpleClass.GetNumber();
 
  DiagnosticOutput("Number: @", number);

Alternatively a reference object can be created from an implementation that is exposed as a published object with MAXON_DECLARATION. See also Published Objects.

  // This example creates a reference class from a component
  // registered at the given declaration.
 
  // create reference
  // The "SomeSimpleClass" published object is declared in a header file.
  // The obtained component is used to create a new instance using Create().
  const SimpleClassRef simpleClass = SomeSimpleClass().Create() iferr_return;
 
  // use reference
  simpleClass.SetNumber(456);
  const maxon::Int number = simpleClass.GetNumber();
 
  DiagnosticOutput("Number: @", number);

It is also possible to obtain components from a registry. See Registry Usage.

  // This example creates a reference object from the registry with the given ID.
 
  // get the class with the given Id from the registry "ColorClasses"
  const maxon::Id redID { "net.maxonexample.class.colors.red" };
  const maxon::Class<ColorRef>* const componentClass = ColorClasses::Find(redID);
 
  if (componentClass == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not get color."_s);
 
  // create reference object
  const ColorRef color = componentClass->Create() iferr_return;
 
  // use reference object
 
  const maxon::String  colorName = color.GetName();
  const maxon::Color32 colorRGB  = color.GetRGB();
 
  DiagnosticOutput("Color Name: @", colorName);
  DiagnosticOutput("Color RGB: @", colorRGB);

ClassInterface

Component classes are based on maxon::ClassInterface. This base class provides basic functionality to create instances.

Functions for instance creation (behaviour depends on the Reference Types):

• maxon::ClassInterface::Create(): Returns a newly constructed instance of this class.
• maxon::ClassInterface::CreatePointer(): Returns a pointer to a newly constructed instance of this class.

Information on the component class can be obtained with:

• maxon::ClassInterface::GetId(): Returns the maxon::Id of the class.
• maxon::ClassInterface::GetKind(): Returns the kind of the class. See maxon::ClassInterface::KIND.
• maxon::ClassInterface::GetImplementedInterfaces(): Returns an array of all interfaces which this class implements.
• maxon::ClassInterface::Implements(): Returns true if the class implements the given interface.
• maxon::ClassInterface::IsSubclassOf(): Returns true if the class is a subclass of the given class.

The components of the class are accessed with these functions. It is typically not needed to use these functions:

• maxon::ClassInterface::GetComponents(): Returns a list of all class components.
• maxon::ClassInterface::AddComponent(): Adds a component to this class.
• maxon::ClassInterface::AddComponents(): Adds all components of the given class to this class.
• maxon::ClassInterface::Finalize(): Finalizes this class so that it can be used afterwards.
• maxon::ClassInterface::IsFinalized(): Returns true if the class has been finalized successfully before.

Object Class

Most interfaces (and objects) are based on the maxon::ObjectInterface interface. For details see Object Interface.

Further Reading

• Interface Basics
• Interface Declaration
• Interface Inheritance
• Object Interface
• Interface Annotations
• Reference Types