Clarisse 5.0 SP10 SDK 5.0.5.10.0
Loading...
Searching...
No Matches
EventObject Class Reference

Base class for all objects wanting to send or receive events. More...

#include <event_object.h>

Inherits CoreCustomData.

Inherited by AppBase, AppMainMenu, AppObjectClassPreference, AppPreferences, AppSelection, AppUnits, CacheRules, ColorIO, FCurve, GroupManager, GuiAction, GuiAppMainMenu, GuiGraphItem, GuiIcon, GuiImage, GuiImageHistory, GuiNodalItem, GuiSpreadsheetCellObjectSelector, GuiToolHandler, GuiWidget, OfChannelManager, OfClassFactory, OfCommandManager, OfItem, OfNodalPositionManager, OfObjectFactory, OfOverrides, OfProxyListener< T >, OfTime, OfVars, ResourceData, ResourceUser, and ShadingLayerListener.

Classes

class  EventInfo
 Class used to give custom data through events calls. The receiver must have knowledge how to interpret the data, depending on what it registered on. More...
 

Public Types

typedef void(* EventInfoFunction) (EventObject &, const EventInfo &, void *)
 event callback signature for free functions / static methods.
 
typedef void(EventObject::* EventInfoMethod) (EventObject &, const EventInfo &, void *)
 event callback signature for methods.
 
typedef void(* EventFunction) (EventObject &, const CoreString &, void *)
 
typedef void(EventObject::* EventMethod) (EventObject &, const CoreString &, void *)
 

Public Member Functions

 EventObject ()
 Constructor.
 
 EventObject (const EventObject &src)
 Copy Constructor.
 
virtual ~EventObject () override
 Destructor.
 
void connect (EventObject &sender, const CoreString &event_id, EventInfoMethod event_cb, void *data=0)
 Connects this to an object to listen to a specific event. More...
 
void connect (EventObject &sender, EventInfoMethod event_cb, void *data=0)
 Connects this to an object to listen any of its events. More...
 
bool disconnect (EventObject &sender, const CoreString &event_id, EventInfoMethod event_cb, void *data=0)
 
bool disconnect_all (EventObject &sender)
 Disconnects from all objects sender was listening on. More...
 
void disconnect_all ()
 Disconnects from all objects we were listening on.
 
void remove_all_connection ()
 Disconnects object from other objects it is listening to, and also disconnects all objects listening to it.
 
void raise_event (const CoreString &event_id) const
 sends an event More...
 
void raise_event (const EventInfo &event_info) const
 sends an event More...
 
bool is_connected (EventObject &sender, const CoreString &event_id, void *data)
 
void set_mute (const bool &mute)
 Asks for object muting. This will increase or decrease the muting counter. Unmuting may not be immediat since it will happen only when counter reaches 0.
 
bool is_mute () const
 Returns if object is muted.
 
CoreArray< EventObject * > get_senders () const
 
unsigned int get_sender_count () const
 
unsigned int get_receiver_count () const
 
virtual size_t get_memory_size () const override
 
- Public Member Functions inherited from CoreCustomData
 CoreCustomData (const CoreCustomData &src)
 
void add_custom_data (void *key, const bool &data)
 
void add_custom_data (void *key, const int &data)
 
void add_custom_data (void *key, const unsigned int &data)
 
void add_custom_data (void *key, const char *data)
 
void add_custom_data (void *key, const CoreString &data)
 
void add_custom_data (void *key, const double &data)
 
void add_custom_data (void *key, void *data)
 
void remove_custom_data (void *key)
 
void remove_all_custom_data ()
 
void set_custom_data (void *key, const bool &data)
 
void set_custom_data (void *key, const int &data)
 
void set_custom_data (void *key, const unsigned int &data)
 
void set_custom_data (void *key, const double &data)
 
void set_custom_data (void *key, const char *data)
 
void set_custom_data (void *key, const CoreString &data)
 
void set_custom_data (void *key, void *data)
 
void get_custom_data (void *key, bool &data) const
 
void get_custom_data (void *key, int &data) const
 
void get_custom_data (void *key, unsigned int &data) const
 
void get_custom_data (void *key, double &data) const
 
void get_custom_data (void *key, CoreString &data) const
 
void get_custom_data (void *key, void *&data) const
 
virtual size_t get_memory_size () const override
 
- Public Member Functions inherited from CoreBaseObject
bool is_kindof (const CoreBaseObject &object) const
 
virtual size_t get_memory_size () const
 
CoreString get_class_info_name () const
 
const unsigned long & get_class_info_id () const
 
virtual bool is_kindof (const CoreClassInfo &cinfo) const
 
virtual const CoreClassInfoget_class_info () const
 
template<class T >
T * cast ()
 
template<class T >
const T * cast () const
 
- Public Member Functions inherited from CoreBaseType
bool is_kindof (const CoreClassInfo &cinfo) const
 

Static Public Member Functions

static void connect (EventObject &sender, const CoreString &event_id, EventObject &receiver, EventInfoMethod event_cb, void *data=0)
 Static version of the above function.
 
static void connect (EventObject &sender, EventObject &receiver, EventInfoMethod event_cb, void *data=0)
 Static version of the above function.
 
static void connect (EventObject &sender, const CoreString &event_id, EventInfoFunction event_cb, void *data=0)
 Connects to an object to listen to a specific event. More...
 
static void connect (EventObject &sender, EventInfoFunction event_cb, void *data=0)
 Connects to an object to listen any of its events. More...
 
static bool disconnect (EventObject &sender, const CoreString &event_id, EventInfoFunction event_cb, void *data=0)
 
static void raise_event (EventObject &sender, const CoreString &event_id)
 Sends an event. More...
 
static void raise_event (EventObject &sender, const EventInfo &event_info)
 Sends an event. More...
 
- Static Public Member Functions inherited from CoreCustomData
static void * get_custom_data_key (const CoreString &key)
 
- Static Public Member Functions inherited from CoreBaseObject
static const CoreClassInfoclass_info ()
 
template<class T >
static T * cast (CoreBaseObject *object)
 
template<class T >
static const T * cast (const CoreBaseObject *object)
 
- Static Public Member Functions inherited from CoreBaseType
static const CoreClassInfoclass_info ()
 Get the type descriptor of this instance.
 
void connect (EventObject &sender, const CoreString &event_id, EventMethod event_cb, void *data=0)
 Connects this to an object to listen to a specific event. More...
 
void connect (EventObject &sender, EventMethod event_cb, void *data=0)
 Connects this to an object to listen any of its events. More...
 
bool disconnect (EventObject &sender, const CoreString &event_id, EventMethod event_cb, void *data=0)
 Disconnects this from an object for a specific event. More...
 
static void connect (EventObject &sender, const CoreString &event_id, EventFunction event_cb, void *data=0)
 Connects to an object to listen to a specific event. More...
 
static void connect (EventObject &sender, EventFunction event_cb, void *data=0)
 Connects to an object to listen any of its events. More...
 
static void connect (EventObject &sender, const CoreString &event_id, EventObject &receiver, EventMethod event_cb, void *data=0)
 Static version of the above function.
 
static void connect (EventObject &sender, EventObject &receiver, EventMethod event_cb, void *data=0)
 Static version of the above function.
 
static bool disconnect (EventObject &sender, const CoreString &event_id, EventFunction event_cb, void *data=0)
 Disconnects this from an object for a specific event. More...
 

Detailed Description

Base class for all objects wanting to send or receive events.

The basic philosophy is that it's the receiver that connects to a sender. Various callback signatures are supported: free functions (or static methods) or methods, both of them with 2 different signatures, one "legacy" and a more recent (and recommended) one.

Here is a very crude example of how to connect things. Note that this example contains some things that you should avoid. Please read the explanations after it, and check the last paragraph for a better (as in good practice) example:

// example receiver
class Receiver
: public EventObject
{
// constructor
EventObject(EventObject& some_other_object);
// static methods (can also be c-style functions)
static void on_event_static (EventObject& sender, const EventObject::EventInfo& event_info, void *data) { /* ... */ }
static void on_event_static_deprecated(EventObject& sender, const CoreString& event_id, void *data) { /* ... */ }
// methods
void on_event (EventObject& sender, const EventObject::EventInfo& event_info, void *data) { /* ... */ }
void on_event_deprecated(EventObject& sender, const CoreString& event_id, void *data) { /* ... */ }
};
Receiver::Receiver(EventObject& some_other_object)
{
// connect our 4 callbacks. Pay attention to the macro used on which signature
connect(some_other_object, EVENT_INFO_FUNCTION(Receiver::on_event_static), nullptr);
connect(some_other_object, EVENT_INFO_METHOD (Receiver::on_event), nullptr);
connect(some_other_object, EVENT_FUNCTION (Receiver::on_event_static_deprecated), nullptr);
connect(some_other_object, EVENT_METHOD (Receiver::on_event_deprecated), nullptr);
}
Definition: core_string.h:18
Class used to give custom data through events calls. The receiver must have knowledge how to interpre...
Definition: event_object.h:189
Base class for all objects wanting to send or receive events.
Definition: event_object.h:171
void connect(EventObject &sender, const CoreString &event_id, EventInfoMethod event_cb, void *data=0)
Connects this to an object to listen to a specific event.
Definition: event_object.cc:384

It's important to note that the signature of the callback method / function must match the EVENT_* macro used in the connect call, otherwise you'll get compilation errors. Also note that the callback signatures with a CoreString instead of a EventObject::EventInfo are legacy and deprecated (a warning is issued whenever they are used, and their support will be removed in the future)

A second important thing to note is that when we connect to a sender, we can either connect to all event it will send (which is the case of the previous example) or to a specific event (in this case the connect call takes an additional argument which is the event id to listen to) Whenever possible, connecting to a single event is recommended.

Another important thing to know is that when you connect a free function or a static method, you need to manually disconnect from the sender when you no longer need to receive events! For instance in the previous example, the 2 connections to the static methods will stay alive indefinitely. In some cases it's ok, in some other it's not. Also note that creating 2 Receiver instance in the example would connect the static methods twice.

And finally, connect is a bit flexible in the signatures it accepts as its callback: if you know the final type of the sender object, you can use this type instead of EventObject as the type of the first argument of the callbacks. For instance if you connect to a class Foo, you could have a callback signature like void (Foo& foo, const EventObject::EventInfo&, void *)

So, with all that being said, let's take back the example and fix it to show good practice:

// example receiver
class Receiver
: public EventObject
{
EventObject(EventObject& some_other_object);
EventObject(void);
static void on_event_static(EventObject& sender, const EventObject::EventInfo& event_info, void *data) { /* ... */ }
void on_event (EventObject& sender, const EventObject::EventInfo& event_info, void *data) { /* ... */ }
};
Receiver::Receiver(EventObject& some_other_object)
{
// connect our method. Will be automatically disconnected, and since we're in the constructor, we know the connection doesn't already exist.
connect(some_other_object, EVT_ID_SOME_EVENT, EVENT_INFO_METHOD(Receiver::on_event), nullptr);
// connect our static method, and attach the pointer to the receiver as its blind data: this will make the connection
// unique for each receiver, and will be passed as the last argument of the callback
connect(some_other_object, EVT_ID_SOME_OTHER_EVENT, EVENT_INFO_FUNCTION(Receiver::on_event_static), this);
}
Receiver::~Receiver(void)
{
// here, we need to disconnect the static callback, otherwise it would still live indefinitely in the sender instance!
// and this is why connecting free functions should be avoided, and connecting methods should be preferred instead.
disconnect(some_other_object, EVT_ID_SOME_OTHER_EVENT, EVENT_INFO_FUNCTION(Receiver::on_event_static), this);
}

Member Function Documentation

◆ connect() [1/8]

void EventObject::connect ( EventObject sender,
const CoreString event_id,
EventFunction  event_cb,
void *  data = 0 
)
static

Connects to an object to listen to a specific event.

@group OfEventDeprecated Deprecated Stuff.

All methods in EventObject come in 2 versions: one where the event is a simple CoreString, the other where the event is a EventInfo instance. All CoreString version are deprecated and should be ported to the ones using EventInfo instead. It's fairly easy though, you just need to replace the CoreString by EventInfo in the callbacks signature, and on connection use the correct macro (EVENT_INFO_* macros)

Parameters
[in]senderobject to connect on to listen to event
[in]event_idevent to listen to
[in]event_cbcallback to call when object send the event (static or c function)
[in]datauser data given to callback when its called

◆ connect() [2/8]

void EventObject::connect ( EventObject sender,
const CoreString event_id,
EventInfoFunction  event_cb,
void *  data = 0 
)
static

Connects to an object to listen to a specific event.

Parameters
[in]senderobject to connect on to listen to event
[in]event_idevent to listen to
[in]event_cbcallback to call when object send the event (static or c function)
[in]datauser data given to callback when its called

◆ connect() [3/8]

void EventObject::connect ( EventObject sender,
const CoreString event_id,
EventInfoMethod  event_cb,
void *  data = 0 
)

Connects this to an object to listen to a specific event.

Parameters
[in]senderobject to connect on to listen to event
[in]event_infoevent info (contains event id and custom data)
[in]event_cbcallback to call when object send the event (receiver object method)
[in]datauser data given to callback when its called

◆ connect() [4/8]

void EventObject::connect ( EventObject sender,
const CoreString event_id,
EventMethod  event_cb,
void *  data = 0 
)

Connects this to an object to listen to a specific event.

Parameters
[in]senderobject to connect on to listen to event
[in]event_idevent to listen to
[in]event_cbcallback to call when object send the event (receiver object method)
[in]datauser data given to callback when its called

◆ connect() [5/8]

void EventObject::connect ( EventObject sender,
EventFunction  event_cb,
void *  data = 0 
)
static

Connects to an object to listen any of its events.

Parameters
[in]senderobject to connect on to listen to event
[in]event_cbcallback to call when object send any event (receiver object method)
[in]datauser data given to callback when its called

◆ connect() [6/8]

void EventObject::connect ( EventObject sender,
EventInfoFunction  event_cb,
void *  data = 0 
)
static

Connects to an object to listen any of its events.

Parameters
[in]senderobject to connect on to listen to event
[in]event_cbcallback to call when object send any event (receiver object method)
[in]datauser data given to callback when its called

◆ connect() [7/8]

void EventObject::connect ( EventObject sender,
EventInfoMethod  event_cb,
void *  data = 0 
)

Connects this to an object to listen any of its events.

Parameters
[in]senderobject to connect on to listen to event
[in]event_cbcallback to call when object send any event (receiver object method)
[in]datauser data given to callback when its called

◆ connect() [8/8]

void EventObject::connect ( EventObject sender,
EventMethod  event_cb,
void *  data = 0 
)

Connects this to an object to listen any of its events.

Parameters
[in]senderobject to connect on to listen to event
[in]event_cbcallback to call when object send any event (receiver object method)
[in]datauser data given to callback when its called

◆ disconnect() [1/2]

bool EventObject::disconnect ( EventObject sender,
const CoreString event_id,
EventFunction  event_cb,
void *  data = 0 
)
static

Disconnects this from an object for a specific event.

Parameters
[in]senderobject to connect on to listen to event
[in]event_idevent to listen to
[in]event_cbcallback to call when object send the event (static or c function)
[in]datauser data given to callback when its called
Returns
true if connection was successful, false otherwise

◆ disconnect() [2/2]

bool EventObject::disconnect ( EventObject sender,
const CoreString event_id,
EventMethod  event_cb,
void *  data = 0 
)

Disconnects this from an object for a specific event.

Parameters
[in]senderobject to connect on to listen to event
[in]event_idevent to listen to
[in]event_cbcallback to call when object send the event (static or c function)
[in]datauser data given to callback when its called
Returns
true if connection was successful, false otherwise

◆ disconnect_all()

bool EventObject::disconnect_all ( EventObject sender)

Disconnects from all objects sender was listening on.

Parameters
[in]senderobject to be disconnected
Returns
true if disconnection was successful, false otherwise

◆ get_memory_size()

◆ raise_event() [1/4]

void EventObject::raise_event ( const CoreString event_id) const

sends an event

Parameters
[in]event_idevent to be sent

◆ raise_event() [2/4]

void EventObject::raise_event ( const EventInfo event_info) const

sends an event

Parameters
[in]event_infoevent id and custom data to be sent

◆ raise_event() [3/4]

void EventObject::raise_event ( EventObject sender,
const CoreString event_id 
)
static

Sends an event.

Parameters
[in]senderobject sending the event
[in]event_idevent to be sent

◆ raise_event() [4/4]

void EventObject::raise_event ( EventObject sender,
const EventInfo event_info 
)
static

Sends an event.

Parameters
[in]senderobject sending the event
[in]event_infoevent id and custom data to be sent