bonobo-listener

bonobo-listener — An Event Listener (an implementation of Bonobo::Listener)

Functions

Signals

void event-notify Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── BonoboObject
        ╰── BonoboListener

Description

The BonoboListener object is a CORBA server used to receive events emitted by a remote Bonobo::EventSource server. The combination EventSource/Listener is used to notify one or more client applications of events that happen in a component. Think of the EventSource/Listener as a notification/callback system that allows multiple clients to be informed of events.

Once created, the BonoboListener object needs to be attached to a remote IDL:Bonobo/EventSource:1.0 server. This is done by passing the CORBA Object reference of the BonoboListener to the addListener method in the IDL:Bonobo/EventSource:1.0.

The BonoboListener object allows the user to specify a callback function to be invoked when an event is emitted by the IDL:Bonobo/EventSource:1.0 server. The BonoboListener object also emits the "event_notify" Gtk+ signal, which allows you to connect multiple code segments to the same event notification.

Here is a sample client application that registers interest in being notified of events from the fictional "Keyboard" event source:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
BonoboListener *keyboard_listener;
my_listener_function (BonoboListener *l, char *event_name,
                      CORBA_any value, CORBA_Environment *ev,
                      gpointer user_data)
{
	printf ("Received event named: %s\n", event_name);
}
connect_to_keyboard_source (Bonobo_EventSource *keyboard)
{
        Bonobo_Unknown reference;
        /*
         * First, create the listener Bonobo server.
         */
	keyboard_listener = bonobo_listener_new (my_listener_function, NULL);
        /*
         * Now, register our listener with the EventSource
         */
        reference = bonobo_object_corba_objref (keyboard_listener);
        Bonobo_EventSource_addListener (keyboard, reference);
}

The CORBA::any value passed to the listener function is defined by the contract between the EventSource's event you are using and you. To manipulate the value, you can use the CORBA DynamicAny interface to introspect the value and extract the information you need.

Functions

BonoboListenerCallbackFn ()

void
(*BonoboListenerCallbackFn) (BonoboListener *listener,
                             const char *event_name,
                             const CORBA_any *any,
                             CORBA_Environment *ev,
                             gpointer user_data);

The signature for the callback function invoked when an event is delivered to the BonoboListener object.

Parameters

listener

a pointer to the BonoboListener.

 

event_name

the event name that was emitted.

 

any

The value (A CORBA Any) that was passed by the EventSource.

 

ev

Environment for returning CORBA errors.

 

user_data

the data pointer specified when you called bonobo_listener_new

 

bonobo_listener_new ()

BonoboListener *
bonobo_listener_new (BonoboListenerCallbackFn event_cb,
                     gpointer user_data);

Creates a generic event listener. The listener calls the event_callback function and emits an "event_notify" signal when notified of an event. The signal callback should be of the form:

1
2
3
4
5
void some_callback (BonoboListener *listener,
                    char *event_name, 
		    CORBA_any *any,
		    CORBA_Environment *ev,
		    gpointer user_data);

You will typically pass the CORBA_Object reference in the return value to an EventSource (by invoking EventSource::addListener).

Parameters

event_cb

function to be invoked when an event is emitted by the EventSource.

 

user_data

data passed to the functioned pointed by event_call .

 

Returns

A BonoboListener object.


bonobo_listener_new_closure ()

BonoboListener *
bonobo_listener_new_closure (GClosure *event_closure);

Creates a generic event listener. The listener invokes the event_closure closure and emits an "event_notify" signal when notified of an event. The signal callback should be of the form:

1
2
3
4
5
void some_callback (BonoboListener *listener,
                    char *event_name, 
		    CORBA_any *any,
		    CORBA_Environment *ev,
		    gpointer user_data);

You will typically pass the CORBA_Object reference in the return value to an EventSource (by invoking EventSource::addListener).

Parameters

event_closure

closure to be invoked when an event is emitted by the EventSource.

 

Returns

A BonoboListener object.


bonobo_event_make_name ()

char *
bonobo_event_make_name (const char *idl_path,
                        const char *kind,
                        const char *subtype);

Creates an event name. Event names consist of three parts. The idl_path is mainly to create a unique namespace, and should identify the interface which triggered the event, for example "Bonobo/Property". The kind denotes what happened, for example "change". Finally you can use the optional subtype to make events more specific. All three parts of the name are joined together separated by colons. "Bonobo/Property:change" or "Bonobo/Property:change:autosave" are examples of valid event names.

Parameters

idl_path

the IDL part of the event name.

 

kind

the kind of the event

 

subtype

an optional subtype

 

Returns

A valid event_name, or NULL on error.


bonobo_event_type ()

char *
bonobo_event_type (const char *event_name);

Parameters

event_name

the event name

 

Returns

The event subtype, or NULL on error.


bonobo_event_subtype ()

char *
bonobo_event_subtype (const char *event_name);

Returns


bonobo_event_kind ()

char *
bonobo_event_kind (const char *event_name);

Parameters

event_name

the event name

 

Returns

The event kind, or NULL on error.


bonobo_event_idl_path ()

char *
bonobo_event_idl_path (const char *event_name);

Parameters

event_name

the event name

 

Returns

The event idl path, or NULL on error.

Types and Values

struct BonoboListener

struct BonoboListener;

Implementents Bonobo::Listener.


BonoboListenerClass

typedef struct {
	BonoboObjectClass     parent_class;

	POA_Bonobo_Listener__epv epv;

	/* Signals */
	void (* event_notify) (BonoboListener    *listener, 
			       char              *event_name,
			       BonoboArg         *event_data, 
			       CORBA_Environment *ev);
} BonoboListenerClass;

BonoboListener's class

Signal Details

The “event-notify” signal

void
user_function (BonoboListener       *bonobolistener,
               gchar                *arg1,
               BonoboCorbaAny       *arg2,
               BonoboCorbaException *arg3,
               gpointer              user_data)

Parameters

bonobolistener

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

BonoboEventSource BonoboArg