Events in OMGUI

Index

Signals & Slots

The event system in OMGUI is a signals & slots based system. The signals are identified by omgui::event_id and associated with an omgui::object_id. Slots are connected to the signals using the omgui::Widget::connect function by specifying the event_id of the signal and the slot being connected. The object_id is taken from the widget. The slot will be invoked whenever that event_id is signalled for that object_id. The omgui::EventManager object tracks what slots are connected to what signals, and is also used to send events, signalling the appropriate slots.

The signature of a slot function

All slots are functions with a similar signature. At minimum the signature of a slot must be:

 bool slotname(const omgui::Event &event);

Note:: If the slot is a member function, it may optionally be a const member function.

The event parameter: The event argument is used to pass information to the slot about what kind of event occured, and any data associated with that event. Here, the base omgui::Event class was used as the type of the function argument, but if the signal you are connecting to sends a specific kind of event object, you should use that as the type of the function argument instead.

Return value: The return value is used to indicate whether this slot processed the event when it was signaled. For some events, the processed state influences how the system should react. For example, a PAINT event may have default processing that occurs to paint the background of the widget if no slots processed the PAINT event. If the signal in question does not behave differently depending on the return value, either true of false can be returned, but returning true is preferred in case functionality is added in a future version that depends on the return value of the slot.

Connecting a slot

Slots are connected using the omgui::Widget::connect function (which in turn calls the omgui::EventManager::connect function). The slot itself is created by using the omgui::make_slot function. This template function has several overloads for creating several kinds of slots, using either plain function pointers, member function pointers, or function objects (such as that returned by boost::bind). The connect function returns a omgui::Connection object which can be used to manage the connection by temporarily blocking it, preventing it from being signaled, or disconnecting it. It is safe to disconnect a slot at any time, even while that slot is being signalled.

For the example slot function definition given previously, make_slot would be used as follows:

 make_slot<Event>(&slotname)

For connecting a slot that is a member function from within a class:

 make_slot<Event>(&MyClass::slotname, *this)

Additional references

See also:: omgui::EventManager, omgui::EventManager::send_event, omgui::Widget::connect, omgui::make_slot, omgui::Connection