Using Interfaces

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):

Information on the component class can be obtained with:

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

Object Class

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

Further Reading