Event Handling Callbacks

void ThisClass::callback_function(NodePtr, int) {
	/* .. */
}
// create a callback with no predefined parameters
CallbackBase2<NodePtr, int> *callback = MakeCallback(this, &ThisClass::callback_function);

// create a callback with predefined parameters
CallbackBase2<NodePtr, int> *callback2 = MakeCallback(this, &ThisClass::callback_function, NodeDummy::create()->getNode(), 1);

// create a callback with parameters from lambda
CallbackBase2<NodePtr, int> *callback = MakeCallback([](NodePtr node, int value) { /* .. */ });

// create a callback with parameters from generic lambda
CallbackBase2<NodePtr, int> *callback = MakeCallback([](auto node, auto value) { /* .. */ });

To use overloaded functions and methods as callbacks, provide the template parameters:
MakeCallback< Class, ReturnType, Callback Parameters Types >

Source code (C++)

void ThisClass::callback_method()
{
	/* .. */
}

void ThisClass::callback_method(WidgetPtr w, WidgetPtr w2, int i)
{
	/* .. */
}

CallbackBase *callback = MakeCallback<ThisClass, void, WidgetPtr, WidgetPtr, int>(this, &ThisClass::callback_method);

To raise a custom callback the run() function of the CallbackBase.. class is used.

Source code (C++)

// run the callback with no parameters or with default predefined parameters
callback->run();

// run the callback with the specified parameters
callback->run(node, 2);

You can also use lambda expressions for callbacks:

Source code (C++)

// create a callback from lambda
int value = 5;
CallbackBase* callback = MakeCallback([value](){ /* .. */ });

// or std function
std::function<void()> callable_obj = [value]() { /* .. */ };
CallbackBase* callback = MakeCallback(callable_obj);

// or any other type of callable
struct Callable
{
void operator()() const { /* .. */ }
int value;
} callable_obj = { /* .. */ };

CallbackBase* callback = MakeCallback(callable_obj);

Usage Example#

The following section contains the complete source code of a simple callback usage example.

AppWorldLogic.h

Source code (C++)

#include <UnigineLogic.h>
#include <UnigineStreams.>
#include <UnigineCallback.h>

using namespace Unigine;

class AppWorldLogic : public WorldLogic {
	
public:
	AppWorldLogic();
	virtual ~AppWorldLogic();
	
	virtual int init();
	
	virtual int update();
	virtual int postUpdate();
	virtual int updatePhysics();
	
	virtual int shutdown();
}

#endif // __APP_WORLD_LOGIC_H__

AppWorldLogic.cpp

Source code (C++)

#include "AppWorldLogic.h"

AppWorldLogic::AppWorldLogic()
{
}

AppWorldLogic::~AppWorldLogic()
{
}

int AppWorldLogic::update()
{
	return 1;
}

class SomeClass
{
public:
	// a member function to be called on action
	void callback_method(int a, int b)
	{
		Log::message("\tcallback_method has been called %d %d\n", a, b);
	}
	
	void create_callbacks()
	{
		Log::message("create a callback with no predefined parameters\n");
		CallbackBase * callback = MakeCallback(this, &SomeClass::callback_method);

		// run the callback with two parameters
		callback->run(73, 37);
		// run the callback with no parameters.
		// if the callback function has arguments like in this case, this will lead to unsafe behaviour
		callback->run();
		
		Log::message("create a callback with predefined parameters\n");
		CallbackBase * callback2 = MakeCallback(this, &SomeClass::callback_method, 1, 2);
		
		// run the callback with no parameters. In this case the predefined parameters will be used
		callback2->run();
		// run the callback with new parameters. The predefined ones will be ignored
		callback2->run(351, 153);
		// run the callback with only one first parameter.
		// the second predefined parameter will be used as the second argument
		callback2->run(118);
	}
};

// a callback function to be called on action
void callback_function(int a, int b)
{
	Log::message("\tcallback_function has been called %d %d\n", a, b);
}

int AppWorldLogic::init()
{
	SomeClass * some = new SomeClass();
	
	a->create_callbacks();
	
	Log::message("create a callback in other instance\n");
	// use a member function of another class to create a callback
	CallbackBase * callback3 = MakeCallback(some, &SomeClass::callback_method, 5, 25);
	callback3->run();
	
	Log::message("create callback functions\n");
	CallbackBase * callback4 = MakeCallback(&callback_function);
	callback4->run(20,70);
	CallbackBase * callback5 = MakeCallback(&callback_function , 50, 25);
	callback5->run();

	return 1;
}

int AppWorldLogic::postUpdate()
{
	return 1;
}

int AppWorldLogic::updatePhysics()
{
	return 1;
}

int AppWorldLogic::shutdown()
{
	return 1;

Practical Use#

Callbacks are widely used in event handling. A number of Unigine API members have several predefined events which can be handled by using callbacks in certain cases.

Triggers#

Triggers are used to detect changes in nodes position or state. Unigine offers three types of built-in triggers:

NodeTrigger fires callbacks when the trigger node is enabled or the trigger node position has changed.
WorldTrigger fires callbacks when any node (collider or not) gets inside or outside of it.
PhysicalTrigger fires callbacks when physical objects get inside or outside of it.

Here is a simple WorldTrigger usage example:

Source code (C++)

WorldTriggerPtr trigger;
int enter_callback_id;
				
// implement the enter callback
void AppWorldLogic::enter_callback(NodePtr node){
	Log::message("\nA node named %s has entered the trigger\n", node->getName());
}
				
// implement the leave callback
void AppWorldLogic::leave_callback(NodePtr node){
	Log::message("\nA node named %s has left the trigger\n", node->getName());
}
				
int AppWorldLogic::init() {
	// create a world trigger node
	trigger = WorldTrigger::create(Math::vec3(3.0f));
				
	// add the enter callback to be fired when a node enters the world trigger
	//and keep its id to be used to remove the callback when necessary
	enter_callback_id = trigger->addEnterCallback(MakeCallback(this, &AppWorldLogic::enter_callback));
	// add the leave callback to be fired when a node leaves the world trigger
	trigger->addLeaveCallback(MakeCallback(this, &AppWorldLogic::leave_callback));

	return 1;
}

To remove the callbacks use the following code:

Source code (C++)

// remove the callback by using its id
trigger->removeEnterCallback(enter_callback_id);
// clear all leave callbacks
trigger->clearLeaveCallbacks();

Widgets#

The widgets base class Widget allows registering callbacks for events defined in the GUI class. The following example shows how to create a WidgetButton and register a callback function for the CLICKED event:

Source code (C++)

/* .. */

// event handler function
int onButtonClicked()
{
	/* .. */
	
	return 1;
}

/* .. */

// getting a pointer to the system GUI
GuiPtr gui = Gui::get();

// creating a button widget and setting its caption
WidgetButtonPtr widget_button = WidgetButton::create(gui, "Press me");

// setting a tooltip
widget_button->setToolTip("Click this button");

// rearranging button size
widget_button->arrange();

// setting button position
widget_button->setPosition(10, 10);

// setting onButtonClicked function to handle CLICKED event
widget_button->addCallback(Gui::CLICKED, MakeCallback(onButtonClicked));

// adding the created button widget to the system GUI
gui->addChild(widget_button, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

Physics#

You can track certain events of the physics-related Bodies and Joints:

Body::addFrozenCallback() to track an event when a body freezes.
Body::addPositionCallback() to track an event when a body changes its position.
Body::addContactEnterCallback() to track an event when a contact emerges (body starts touching another body or collidable surface).
Body::addContactLeaveCallback() to track an event when a contact ends (body stops touching another body or collidable surface).
Body::addContactsCallback() to get all contacts of the body including new ones (enter) and the ending ones (leave). Leave contacts are removed after the callback execution stage, so this is the only point where you can still get them.
Joint::addBrokenCallback() to track an event when a joint breaks.

The following sample shows the way of registering callbacks for a BodyRigid and change the color of a mesh depending on its state:

Source code (C++)

/* .. */

// set the node's albedo color to red on freezing event
int AppWorldLogic::frozen_callback(BodyPtr body)
{
	body->getObject()->setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0);
	return 1;
}

// set the node's albedo color to blue on position change event
int AppWorldLogic::position_callback(BodyPtr body)
{
	body->getObject()->setMaterialParameterFloat4("albedo_color", vec4(0.0f, 0.0f, 1.0f, 1.0f), 0);
	return 1;
}

// set the node's albedo color to yellow on each contact
int AppWorldLogic::contact_enter_callback(BodyPtr body, int num)
{
	body->getObject()->setMaterialParameterFloat4("albedo_color", vec4(1.0f, 1.0f, 0.0f, 1.0f), 0);
	return 1;
}

int AppWorldLogic::init() {
	// create a box
	MeshPtr mesh = Mesh::create();
	mesh->addBoxSurface("box", vec3(1.0f));
	ObjectMeshStaticPtr node = ObjectMeshStatic::create(mesh);
	node->setPosition(Vec3(0, 0, 5.0f));
	// add a rigid body to the box
	BodyRigidPtr body = BodyRigid::create(node);
	// register callbacks for events
	body->addFrozenCallback(MakeCallback(this, &AppWorldLogic::frozen_callback));
	body->addPositionCallback(MakeCallback(this, &AppWorldLogic::position_callback));
	body->addContactEnterCallback(MakeCallback(this, &AppWorldLogic::contact_enter_callback));
	// add a shape to the body
	ShapeBoxPtr shape = ShapeBox::create(body, vec3(1.0f));

	return 1;
}
/* .. */

NoticePhysics-based callbacks are executed in the main tread, as they are mainly used for creation, destruction or modification of other objects.

Properties#

Callback functions can be used to determine actions to be performed when adding or removing node and surface properties as well as when swapping node properties. Here is an example demonstrating how to track adding a node property via callbacks:

Source code (C++)

NodePtr node;

void node_property_added(NodePtr node, PropertyPtr property)
{
	Log::message("Property \"%s\" was added to the node named \"%s\".\n", property->getName(), node->getName());
    // ...
}

// somewhere in the code

// inheriting a new property named "my_prop" from the base property "node_base"
Properties::findManualProperty("node_base")->inherit("my_prop");

// setting our callback function on adding a node property
node->addCallback(Node::CALLBACK_PROPERTY_NODE_ADD, MakeCallback(node_property_added));

// adding the property named "my_prop" to the node
node->addProperty("my_prop");

You can add callbacks to track any changes made to a property and its parameters and perform certain actions.

The example below shows how to add a callback to track changes of property parameters and report the name of the property and the changed parameter (suppose we have a manual property named my_prop with an integer parameter named my_int_param).

Source code (C++)

void parameter_changed(PropertyPtr property, int num)
{
	Log::message("Parameter \"%s\" of the property \"%s\" has changed its value.\n", property->getParameterName(num), property->getName());
    // ...
}

// somewhere in the code

// getting a manual property named "my_prop" via the Property Manager
PropertyPtr property = Properties::findManualProperty("my_prop");

// setting our callback function on parameter change
property->addCallback(Property::CALLBACK_PARAMETER_CHANGED, MakeCallback(parameter_changed));

// changing the value of the "my_int_param" parameter
property->setParameterInt(property->findParameter("my_int_param"), 3);

You can also add callbacks to the Properties manager to track any changes made to any property and perform certain actions:

Source code (C++)

void property_removed(PropertyPtr property)
{
	Log::message("Property \"%s\" was removed.\n", property->getName());
    // ...
}

// somewhere in the code

// inheriting a new property named "my_prop" from the base property "surface_base"
PropertyPtr property = Properties::findManualProperty("surface_base")->inherit("my_prop");

// setting our callback function on property removal
Properties::addCallback(Property::CALLBACK_REMOVED, MakeCallback(property_removed));

// removing the property named "my_prop"
Properties::removeProperty(Properties::findProperty("my_prop")->getGUID());

Event Handling Callbacks

In This Article:

Usage Example#

Practical Use#

Triggers#

See Also

Widgets#

See Also

Physics#

See Also

Properties#

See Also#