matecomponent-listener

## matecomponent-listener matecomponent-listener — An Event Listener (an implementation of MateComponent::Listener) |

## Synopsis

                        MateComponentListener;
                        MateComponentListenerClass;
    void                (*MateComponentListenerCallbackFn)         (MateComponentListener *listener,
                                                             const char *event_name,
                                                             const CORBA_any *any,
                                                             CORBA_Environment *ev,
                                                             gpointer user_data);
    MateComponentListener *    matecomponent_listener_new                 (MateComponentListenerCallbackFn event_cb,
                                                             gpointer user_data);
    MateComponentListener *    matecomponent_listener_new_closure         (GClosure *event_closure);
    char *              matecomponent_event_make_name              (const char *idl_path,
                                                             const char *kind,
                                                             const char *subtype);
    char *              matecomponent_event_type                   (const char *event_name);
    char *              matecomponent_event_subtype                (const char *event_name);
    char *              matecomponent_event_kind                   (const char *event_name);
    char *              matecomponent_event_idl_path               (const char *event_name);

## Object Hierarchy

      GObject
       +----MateComponentObject
             +----MateComponentListener

## Signals

      "event-notify"                                   : Run Last

## Description

The MateComponentListener object is a CORBA server used to receive events emitted by a remote MateComponent::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 MateComponentListener object needs to be attached to a remote IDL:MateComponent/EventSource:1.0 server. This is done by passing the CORBA Object reference of the MateComponentListener to the addListener method in the IDL:MateComponent/EventSource:1.0.

The MateComponentListener object allows the user to specify a callback function to be invoked when an event is emitted by the IDL:MateComponent/EventSource:1.0 server. The MateComponentListener 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
    MateComponentListener *keyboard_listener;
    my_listener_function (MateComponentListener *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 (MateComponent_EventSource *keyboard)
    {
            MateComponent_Unknown reference;
            /*
             * First, create the listener MateComponent server.
             */
        keyboard_listener = matecomponent_listener_new (my_listener_function, NULL);
            /*
             * Now, register our listener with the EventSource
             */
            reference = matecomponent_object_corba_objref (keyboard_listener);
            MateComponent_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.

## Details

### MateComponentListener

    typedef struct _MateComponentListener MateComponentListener;

Implementents MateComponent::Listener.

### MateComponentListenerClass

    typedef struct {
    	MateComponentObjectClass     parent_class;

    	POA_MateComponent_Listener__epv epv;

    	/* Signals */
    	void (* event_notify) (MateComponentListener    *listener,
    			       char              *event_name,
    			       MateComponentArg         *event_data,
    			       CORBA_Environment *ev);
    } MateComponentListenerClass;

MateComponentListener's class

### MateComponentListenerCallbackFn ()

    void                (*MateComponentListenerCallbackFn)         (MateComponentListener *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 MateComponentListener object.

`listener` : | a pointer to the MateComponentListener.
`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 matecomponent_listener_new

### matecomponent_listener_new ()

    MateComponentListener *    matecomponent_listener_new                 (MateComponentListenerCallbackFn 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 (MateComponentListener *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).

`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 MateComponentListener object.

### matecomponent_listener_new_closure ()

    MateComponentListener *    matecomponent_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 (MateComponentListener *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).

`event_closure` : | closure to be invoked when an event is emitted by the EventSource.
Returns : | A MateComponentListener object.

### matecomponent_event_make_name ()

    char *              matecomponent_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 "MateComponent/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. "MateComponent/Property:change" or "MateComponent/Property:change:autosave" are examples of valid event names.

`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.

### matecomponent_event_type ()

    char *              matecomponent_event_type                   (const char *event_name);

`event_name` : | the event name
Returns : | The event subtype, or NULL on error.

### matecomponent_event_subtype ()

    char *              matecomponent_event_subtype                (const char *event_name);

`event_name` : |
Returns : |

### matecomponent_event_kind ()

    char *              matecomponent_event_kind                   (const char *event_name);

`event_name` : | the event name
Returns : | The event kind, or NULL on error.

### matecomponent_event_idl_path ()

    char *              matecomponent_event_idl_path               (const char *event_name);

`event_name` : | the event name
Returns : | The event idl path, or NULL on error.

## Signal Details

### The `"event-notify"` signal

    void                user_function                      (MateComponentListener       *matecomponentlistener,
                                                            gchar                *arg1,
                                                            MateComponentCorbaAny       *arg2,
                                                            MateComponentCorbaException *arg3,
                                                            gpointer              user_data)           : Run Last

`matecomponentlistener` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

MateComponentEventSource MateComponentArg