bonobo-event-source

Bonobo API Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

bonobo-event-source

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