The pcb-rnd event system is a very simple callback system: a list of function pointers registered by different parts of the code (e.g. plugins), to be called back on certain events. Different events have different number and type of arguments, which are passed as an argc/argv pair. An event may be bound to any number of functions.
Upon the occurrence of the event, all event handler functions bound to it are called, in no particular order.
An event handler function can be bound to one or more events, and it can be bound and unbound runtime.
For more details, please read the API in src/event.h.
Create an event handler function of type pcb_event_handler_t.
static void ev_my_event_handler_name(void *user_data, int argc, pcb_event_arg_t argv[])
{
}
Call pcb_event_bind(), typically in the init callback of the plugin:
pcb_event_bind(PCB_EVENT_BOARD_CHANGED, ev_my_event_handler_name, NULL, pluginname_cookie);
The registration requires a standard plugin cookie.
The 3rd argument is an arbitrary user data pointer that will get passed to each call of the event handler. It can be used to communicate between the code that registers the event and the event handler code. The event system only stores and passes it on, never dereferences, allocates or frees it. Should be NULL if not used.
Events are normally unbound in the plugin's uninit callback, using pcb_event_unbind_cookie(), which unregisters all events registered with the same cookie. The typical call is:
pcb_event_unbind_allcookie(pluginname_cookie);
Events can be unbound one by one, on an event_id/callback_function basis, using pcb_event_unbind(). This is useful if an event needs to be installed and uninstalled temporarily.