<!-- ##### SECTION Title ##### -->
matecomponent-event-source

<!-- ##### SECTION Short_Description ##### -->
An Event Source where clients can connect to listen to events.

<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>

<para>
To notify a listener, you need to construct a textual string,
this is done by the <function>matecomponent_event</function> functions
( see #MateComponentListener ) ':' 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 matecomponent property bag notification code
uses the IDL path "MateComponent/Property" the "change" kind and sets the
sub-type to the property name:
  <example>
    <title>An example event source notification</title>
    <programlisting>
static void
notify_listeners (MateComponentPropertyBag *pb,
		  MateComponentProperty    *prop,
		  const MateComponentArg   *new_value,
		  CORBA_Environment *opt_ev)
{
	if (prop->flags &amp; MATECOMPONENT_PROPERTY_NO_LISTENING)
		return;
	
	matecomponent_event_source_notify_listeners_full (pb->es,
						   "MateComponent/Property",
						   "change", prop->name,
						   new_value, opt_ev);
}
    </programlisting>
  </example>
  Of course, you need to notify the listener with a valid
MateComponentArg containing the event data, this could easily contain
a structure. eg.
  <example>
     <title>Passing a structure in an event</title>
     <programlisting>
module MATE {
	module Foo {
		struct BaaEvent {
			double a;
			string b;
			long   c;
		};
	};
};
     </programlisting>
     <programlisting>
static void
fire_event (MateComponentEventSource *on_source,
            double             a_double,
	    char              *a_string,
	    long               a_float,
	    CORBA_Environment *opt_ev)
{
	CORBA_any any;
	MATE_Foo_BaaEvent e;

	e.a = a_double;
	e.b = a_string;
	e.c = a_float;

	any->_type = TC_MATE_Foo_BaaEvent;
	any->_data = &amp;e;

	matecomponent_event_source_notify_listeners_full (
	   on_source, "MATE/Foo", "event", NULL,
	   &amp;any, opt_ev);
}
     </programlisting>
  </example>
  NB. it is reccommended that you make it clear that the event
structure is intended for use with the #MateComponentEventSource /
#MateComponentListener by naming it XYZEvent, ie. with the 'Event'
suffix.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
  #MateComponentListener #MateComponentArg
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### FUNCTION matecomponent_event_source_new ##### -->
<para>

</para>

@void: 
@Returns: 


<!-- ##### FUNCTION matecomponent_event_source_notify_listeners ##### -->
<para>

</para>

@event_source: 
@event_name: 
@opt_value: 
@opt_ev: 


<!-- ##### FUNCTION matecomponent_event_source_notify_listeners_full ##### -->
<para>

</para>

@event_source: 
@path: 
@type: 
@subtype: 
@opt_value: 
@opt_ev: 


<!-- ##### FUNCTION matecomponent_event_source_client_remove_listener ##### -->
<para>

</para>

@object: 
@listener: 
@opt_ev: 


<!-- ##### FUNCTION matecomponent_event_source_client_add_listener ##### -->
<para>

</para>

@object: 
@event_callback: 
@opt_mask: 
@opt_ev: 
@user_data: 


<!-- ##### FUNCTION matecomponent_event_source_has_listener ##### -->
<para>

</para>

@event_source: 
@event_name: 
@Returns: 


<!-- ##### FUNCTION matecomponent_event_source_client_add_listener_closure ##### -->
<para>

</para>

@object: 
@callback: 
@opt_mask: 
@opt_ev: 


<!-- ##### FUNCTION matecomponent_event_source_client_add_listener_full ##### -->
<para>

</para>

@object: 
@callback: 
@opt_mask: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_event_source_ignore_listeners ##### -->
<para>

</para>

@event_source: 


