IEvent#

Fully qualified name: carb::events::IEvent

Defined in carb/events/IEvents.h

class IEvent : public carb::IObject#

Event object which is sent and received.

Lifetime is managed by carb::IObject refcounting.

Public Functions

template<typename ValueT>
inline void setValues(
const std::pair<const char*, ValueT> &param,
)#

Helper function to build a carb.dictionary of values.

Parameters:

param – The key/value pair to include in the carb.dictionary.

template<typename ValueT, typename ...ValuesT>
inline void setValues(
const std::pair<const char*, ValueT> &param,
ValuesT&&... params,
)#

Helper function to build a carb.dictionary of values.

Parameters:

  • param – The key/value pair to include in the carb.dictionary.

  • params – Additional key/value pairs.

virtual void consume() = 0#

Stops propagation of an event during dispatch.

inline carb::ObjectPtr<carb::IObject> retrieveObject(
cpp::unbounded_string name,
)#

Retrieves a previously-stored carb::IObject from this event by name.

The object was previously set with attachObject(). The object remains attached to *this until *this is destroyed or it is overwritten with a different object (or nullptr) by calling attachObject() again.

Thread Safety

This function is thread safe: retrieveObject() can be called concurrently and will serialize calls to attachObject().

Parameters:

name – The name of the object to retrieve. Must not be nullptr. This parameter is case-sensitive.

Returns:

The object previously passed to attachObject(). May be nullptr

virtual void getObjectNames(omni::vector<RString> &out) const = 0#

Retrieves the names of all objects attached to this event.

Thread Safety

This function is thread-safe with respect to attachObject() and retrieveObject(). However, the list may be modified by another thread after the output vector is filled.

Parameters:

out – Receives the names of all objects attached to this event. The vector is not cleared; the names are appended to existing entries.

template<typename ValueT>
inline void setValue(
cpp::string_view name,
ValueT &&value,
)#

Helper function to build a carb.dictionary of values using string_view.

Parameters:
virtual void attachObject(
carb::cpp::string_view name,
carb::IObject *ptr,
) = 0#

Attaches a carb::IObject to this event by name and holds a reference to the object.

The object can be retrieved with retrieveObject(). If an object is already stored under the given name, the stored object is released and ptr is stored instead. References to stored objects are released when *this is destroyed. To clear the current reference for a given name, pass ptr as nullptr.

Thread Safety

This function is thread safe: all attachObject() calls are serialized with each other and all calls with retrieveObject().

Parameters:

  • name – The name of the object to attach. The same name must be passed to retrieveObject() in order to retrieve the pointer. This parameter is case-sensitive.

  • ptr – The pointer to attach to *this with the given name.

inline void attachObject(
cpp::unbounded_string name,
carb::IObject *ptr,
)#

Attaches a carb::IObject to this event by name (deprecated template version).

Deprecated:

Use attachObject() with string_view instead

Parameters:

  • name – The name of the object to attach.

  • ptr – The pointer to attach to *this with the given name.

inline carb::ObjectPtr<carb::IObject> retrieveObject(
carb::cpp::string_view name,
)#

Retrieves a previously-stored carb::IObject from this event by name using string_view.

The object was previously set with attachObject(). The object remains attached to *this until *this is destroyed or it is overwritten with a different object (or nullptr) by calling attachObject() again.

Thread Safety

This function is thread safe: retrieveObject() can be called concurrently and will serialize calls to attachObject().

Parameters:

name – The name of the object to retrieve. This parameter is case-sensitive.

Returns:

The object previously passed to attachObject(). May be nullptr

virtual bool isConsumed() const noexcept = 0#

Returns whether the event has been consumed.

Returns:

true if consume() was called on the event; false otherwise.

virtual size_t addRef() = 0#

Atomically add one to the reference count.

Returns:

The current reference count after one was added, though this value may change before read if other threads are also modifying the reference count. The return value is guaranteed to be non-zero.

virtual size_t release() = 0#

Atomically subtracts one from the reference count.

If the result is zero, carb::deleteHandler() is called for this.

Returns:

The current reference count after one was subtracted. If zero is returned, carb::deleteHandler() was called for this.

Public Members

EventType type#

Event type.

SenderId sender#

The sender of the event, or carb::events::kGlobalSenderId.

dictionary::Item *payload#

Event payload is dictionary Item. Any data can be put into.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc(
) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc(
) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about the latest version of this interface.