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

# BonoboGenericFactory

## Name

BonoboGenericFactory -- The basic, generic Bonobo object factory implementation

## Synopsis

    struct      BonoboGenericFactory;
    BonoboObject* (*BonoboGenericFactoryFn)     (BonoboGenericFactory *Factory,
                                                 void *closure);
    BonoboObject* (*GnomeFactoryCallback)       (BonoboGenericFactory *factory,
                                                 const char *component_id,
                                                 gpointer closure);
    typedef     BonoboGenericFactoryClass;
    BonoboGenericFactory* bonobo_generic_factory_new
                                                (const char *oaf_iid,
                                                 BonoboGenericFactoryFn factory,
                                                 gpointer user_data);
    BonoboGenericFactory* bonobo_generic_factory_new_multi
                                                (const char *oaf_iid,
                                                 GnomeFactoryCallback factory_cb,
                                                 gpointer data);
    BonoboGenericFactory* bonobo_generic_factory_construct
                                                (const char *oaf_iid,
                                                 BonoboGenericFactory *c_factory,
                                                 CORBA_Object corba_factory,
                                                 BonoboGenericFactoryFn factory,
                                                 GnomeFactoryCallback factory_cb,
                                                 gpointer user_data);
    void        bonobo_generic_factory_set      (BonoboGenericFactory *c_factory,
                                                 BonoboGenericFactoryFn factory,
                                                 void *data);
    POA_GNOME_ObjectFactory__epv* bonobo_generic_factory_get_epv
                                                (void);
    CORBA_Object bonobo_generic_factory_corba_object_create
                                                (BonoboObject *object,
                                                 gpointer shlib_id);
    #define     BONOBO_OAF_FACTORY              (oafiid, descr, version, fn, data)
    #define     BONOBO_OAF_FACTORY_MULTI        (oafiid, descr, version, fn, data)

## Description

The vast majority of Bonobo objects are created by the BonoboGenericFactory implementation. This provides a very simple C sugar wrapper of the GNOME::ObjectFactory IDL interface, used by OAF to instantiate new objects.

Most applications when they start up will register their Bonobo object factory with OAF, this can be done like this:

Example 1. How to register a factory with OAF

    BonoboGenericFactory *factory;

    factory = bonobo_generic_factory_new_multi (
    	"OAFIID:GNOME_MyApp_myId",
    	my_factory_function, NULL);
    bonobo_running_context_auto_exit_unref (BONOBO_OBJECT (factory));

This registers the factory with OAF, associated with your factory's OAFIID ( as specified in the installed .oaf file ). The running_context_auto_exit_unref function is used to ensure that the program exits the gtk main loop when all of the factory's ( or any derived ) objects are destroyed.

When an object that is created by your factory is demanded from OAF the my_factory_function will be called:

Example 2. A simple factory

    static BonoboObject *
    my_factory_fn (BonoboGenericFactory *this,
                   const char           *object_id,
                   void                 *data)
    {
    	BonoboObject *object = NULL;

    	g_return_val_if_fail (object_id != NULL, NULL);

    	if (!strcmp (object_id, "OAFIID:Bonobo_Sample_Clock"))
    		object = bonobo_clock_control_new();
    	else
    		g_warning ("Unknown OAFIID 's'", object_id);

    	return object;
    }

This will return the newly constructed object via OAF to the Object requestor.

The generic factory works in two modes, multi and plain, it is recommended that the multi mode be used. Also, there is a macro that can be used for simple components to remove the burden of writing the main function and getting the initialization correct, see BONOBO_OAF_FACTORY_MULTI.

## Details

### struct BonoboGenericFactory

    struct BonoboGenericFactory;

### BonoboGenericFactoryFn ()

    BonoboObject* (*BonoboGenericFactoryFn)     (BonoboGenericFactory *Factory,
                                                 void *closure);

`Factory` : |
`closure` : |
Returns : |

### GnomeFactoryCallback ()

    BonoboObject* (*GnomeFactoryCallback)       (BonoboGenericFactory *factory,
                                                 const char *component_id,
                                                 gpointer closure);

`factory` : |
`component_id` : |
`closure` : |
Returns : |

### BonoboGenericFactoryClass

    typedef struct {
    	BonoboObjectClass parent_class;

    	/* Virtual methods */
    	BonoboObject *(*new_generic) (BonoboGenericFactory *c_factory,
    				      const char           *component_id);
    } BonoboGenericFactoryClass;

### bonobo_generic_factory_new ()

    BonoboGenericFactory* bonobo_generic_factory_new
                                                (const char *oaf_iid,
                                                 BonoboGenericFactoryFn factory,
                                                 gpointer user_data);

This is a helper routine that simplifies the creation of factory objects for GNOME objects. The `factory` function will be invoked by the CORBA server when a request arrives to create a new instance of an object supporting the Bonobo::Generic interface. The factory callback routine is passed the `data` pointer to provide the creation function with some state information.

`oaf_iid` : | The GOAD id that this factory implements
`factory` : |
`user_data` : |
Returns : | A BonoboGenericFactory object that has an activated Bonobo::GenericFactory object that has registered with the GNOME name server.

### bonobo_generic_factory_new_multi ()

    BonoboGenericFactory* bonobo_generic_factory_new_multi
                                                (const char *oaf_iid,
                                                 GnomeFactoryCallback factory_cb,
                                                 gpointer data);

`oaf_iid` : |
`factory_cb` : |
`data` : |
Returns : |

### bonobo_generic_factory_construct ()

    BonoboGenericFactory* bonobo_generic_factory_construct
                                                (const char *oaf_iid,
                                                 BonoboGenericFactory *c_factory,
                                                 CORBA_Object corba_factory,
                                                 BonoboGenericFactoryFn factory,
                                                 GnomeFactoryCallback factory_cb,
                                                 gpointer user_data);

Initializes `c_factory` with the command-line arguments and registers the new factory in the name server.

`oaf_iid` : | The GOAD id that the new factory will implement.
`c_factory` : | The object to be initialized.
`corba_factory` : | The CORBA object which supports the Bonobo::GenericFactory interface and which will be used to construct this BonoboGenericFactory Gtk object.
`factory` : | A callback which is used to create new GnomeGeneric object instances.
`factory_cb` : | A Multi object factory callback.
`user_data` : | The closure data to be passed to the `factory` callback routine.
Returns : | The initialized BonoboGenericFactory object.

### bonobo_generic_factory_set ()

    void        bonobo_generic_factory_set      (BonoboGenericFactory *c_factory,
                                                 BonoboGenericFactoryFn factory,
                                                 void *data);

Sets the callback and callback closure for `c_factory` to `factory` and `data`, respectively.

`c_factory` : | The BonoboGenericFactory object whose callback will be set.
`factory` : | A callback routine which is used to create new object instances.
`data` : | The closure data to be passed to the `factory` callback.

### bonobo_generic_factory_get_epv ()

    POA_GNOME_ObjectFactory__epv* bonobo_generic_factory_get_epv
                                                (void);

Returns : | The EPV for the default BonoboGenericFactory implementation.

### bonobo_generic_factory_corba_object_create ()

    CORBA_Object bonobo_generic_factory_corba_object_create
                                                (BonoboObject *object,
                                                 gpointer shlib_id);

`object` : |
`shlib_id` : |
Returns : |

### BONOBO_OAF_FACTORY()

    #define     BONOBO_OAF_FACTORY(oafiid, descr, version, fn, data)

`oafiid` : |
`descr` : |
`version` : |
`fn` : |
`data` : |

### BONOBO_OAF_FACTORY_MULTI()

    #define     BONOBO_OAF_FACTORY_MULTI(oafiid, descr, version, fn, data)

`oafiid` : |
`descr` : |
`version` : |
`fn` : |
`data` : |

<<< Previous Page | Home | Up | Next Page >>>
BonoboObjectClient | bonobo-exception