Name
bonobo-event-source -- An Event Source where clients can connect to listen to events.
Synopsis
typedef BonoboEventSource;
typedef BonoboEventSourceClass;
BonoboEventSource* bonobo_event_source_new (void);
void bonobo_event_source_notify_listeners
(BonoboEventSource *event_source,
const char *event_name,
const CORBA_any *value,
CORBA_Environment *opt_ev);
void bonobo_event_source_notify_listeners_full
(BonoboEventSource *event_source,
const char *path,
const char *type,
const char *subtype,
const CORBA_any *value,
CORBA_Environment *opt_ev);
Bonobo_EventSource_ListenerId bonobo_event_source_client_add_listener
(Bonobo_Unknown object,
BonoboListenerCallbackFn event_callback,
const char *opt_mask,
CORBA_Environment *opt_ev,
gpointer user_data);
void bonobo_event_source_client_remove_listener
(Bonobo_Unknown object,
Bonobo_EventSource_ListenerId id,
CORBA_Environment *opt_ev);
void bonobo_event_source_ignore_listeners
(BonoboEventSource *event_source);
|
Description
An event source object is responsible for channeling the emission
of signals on an object to the appropriate attached listeners.
The API is extremely simple and allows implementations to notify
their listeners of a new event occuring.
To notify a listener, you need to construct a textual string,
this is done by the bonobo_event functions
( see BonoboListener ) ':' delimiting the fields. It is reccommended
that the IDL module path of the interface be used as the first
part of the string. This is because many interfaces can be aggregated
together and need to share the same event namespace without conflicts.
So for example the bonobo property bag notification code
uses the IDL path "Bonobo/Property" the "change" kind and sets the
sub-type to the property name:
Example 1. An example event source notification
static void
notify_listeners (BonoboPropertyBag *pb,
BonoboProperty *prop,
const BonoboArg *new_value,
CORBA_Environment *opt_ev)
{
if (prop->flags & BONOBO_PROPERTY_NO_LISTENING)
return;
bonobo_event_source_notify_listeners_full (pb->es,
"Bonobo/Property",
"change", prop->name,
new_value, opt_ev);
}
|
Of course, you need to notify the listener with a valid
BonoboArg containing the event data, this could easily contain
a structure. eg.
Example 2. Passing a structure in an event
module GNOME {
module Foo {
struct BaaEvent {
double a;
string b;
long c;
};
};
};
|
static void
fire_event (BonoboEventSource *on_source,
double a_double,
char *a_string,
long a_float,
CORBA_Environment *opt_ev)
{
CORBA_any any;
GNOME_Foo_BaaEvent e;
e.a = a_double;
e.b = a_string;
e.c = a_float;
any->_type = TC_GNOME_Foo_BaaEvent;
any->_data = &e;
bonobo_event_source_notify_listeners_full (
on_source, "GNOME/Foo", "event", NULL,
&any, opt_ev);
}
|
NB. it is reccommended that you make it clear that the event
structure is intended for use with the
BonoboEventSource /
BonoboListener by naming it XYZEvent, ie. with the 'Event'
suffix.
Details
BonoboEventSource
typedef struct {
BonoboXObject parent;
BonoboEventSourcePrivate *priv;
} BonoboEventSource; |
BonoboEventSourceClass
typedef struct {
BonoboXObjectClass parent_class;
POA_Bonobo_EventSource__epv epv;
} BonoboEventSourceClass; |
bonobo_event_source_new ()
Creates a new BonoboEventSource object. Typically this
object will be exposed to clients through CORBA and they
will register and unregister functions to be notified
of events that this EventSource generates.
To notify clients of an event, use the bonobo_event_source_notify_listeners()
function.
bonobo_event_source_notify_listeners ()
void bonobo_event_source_notify_listeners
(BonoboEventSource *event_source,
const char *event_name,
const CORBA_any *value,
CORBA_Environment *opt_ev); |
This will notify all clients that have registered with this EventSource
(through the addListener or addListenerWithMask methods) of the availability
of the event named event_name. The value CORBA::any value is passed to
all listeners.
event_name can not contain comma separators, as commas are used to
separate the various event names.
bonobo_event_source_notify_listeners_full ()
void bonobo_event_source_notify_listeners_full
(BonoboEventSource *event_source,
const char *path,
const char *type,
const char *subtype,
const CORBA_any *value,
CORBA_Environment *opt_ev); |
bonobo_event_source_client_add_listener ()
Bonobo_EventSource_ListenerId bonobo_event_source_client_add_listener
(Bonobo_Unknown object,
BonoboListenerCallbackFn event_callback,
const char *opt_mask,
CORBA_Environment *opt_ev,
gpointer user_data); |
bonobo_event_source_client_remove_listener ()
void bonobo_event_source_client_remove_listener
(Bonobo_Unknown object,
Bonobo_EventSource_ListenerId id,
CORBA_Environment *opt_ev); |
bonobo_event_source_ignore_listeners ()
Instructs the event source to de-register any listeners
that are added from the global running context.