|  |  |  | Libbonobo Reference Manual |  | 
|---|---|---|---|---|
BonoboObject* (*BonoboFactoryCallback) (BonoboGenericFactory *factory, const char *component_id, gpointer closure); BonoboGenericFactory* bonobo_generic_factory_new (const char *act_iid, BonoboFactoryCallback factory_cb, gpointer user_data); BonoboGenericFactory* bonobo_generic_factory_new_closure (const char *act_iid, GClosure *factory_closure); BonoboGenericFactory* bonobo_generic_factory_construct (BonoboGenericFactory *factory, const char *act_iid, GClosure *factory_closure); void bonobo_generic_factory_construct_noreg (BonoboGenericFactory *factory, const char *act_iid, GClosure *factory_closure); int bonobo_generic_factory_main (const char *act_iid, BonoboFactoryCallback factory_cb, gpointer user_data); int bonobo_generic_factory_main_timeout (const char *act_iid, BonoboFactoryCallback factory_cb, gpointer user_data, guint quit_timeout); #define BONOBO_FACTORY_INIT (descr, version, argcp, argv) #define BONOBO_OAF_FACTORY (oafiid, descr, version, callback, data) #define BONOBO_OAF_FACTORY_MULTI (oafiid, descr, version, callback, data) #define BONOBO_ACTIVATION_FACTORY (oafiid, descr, version, callback, data) #define BONOBO_ACTIVATION_FACTORY_TIMEOUT(oafiid, descr, version, callback, data, quit_timeout)
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 (
	"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.
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_ACTIVATION_FACTORY.
BonoboObject* (*BonoboFactoryCallback) (BonoboGenericFactory *factory, const char *component_id, gpointer closure);
Type of function that is called when it's time for the factory to create a new instance.
| factory: | the factory that invoked this callback | 
| component_id: | OAFIID of the component that should be activated | 
| closure: | user data | 
| Returns : | the newly created BonoboObject | 
BonoboGenericFactory* bonobo_generic_factory_new
                                            (const char *act_iid,
                                             BonoboFactoryCallback factory_cb,
                                             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.
| act_iid: | The GOAD id that this factory implements | 
| factory_cb: | A callback which is used to create new BonoboObject instances. | 
| user_data: | The closure data to be passed to the factorycallback routine. | 
| Returns : | A BonoboGenericFactory object that has an activated Bonobo::GenericFactory object that has registered with the GNOME name server. | 
BonoboGenericFactory* bonobo_generic_factory_new_closure
                                            (const char *act_iid,
                                             GClosure *factory_closure);
This is a helper routine that simplifies the creation of factory
objects for GNOME objects.  The factory_closure closure 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.
| act_iid: | The GOAD id that this factory implements | 
| factory_closure: | A closure which is used to create new BonoboObject instances. | 
| Returns : | A BonoboGenericFactory object that has an activated Bonobo::GenericFactory object that has registered with the GNOME name server. | 
BonoboGenericFactory* bonobo_generic_factory_construct
                                            (BonoboGenericFactory *factory,
                                             const char *act_iid,
                                             GClosure *factory_closure);
Initializes c_factory with and registers the new factory with
the name server.
| factory: | The object to be initialized. | 
| act_iid: | The Bonobo activation id that the new factory will implement. Bonobo::GenericFactory interface and which will be used to construct this BonoboGenericFactory Gtk object. | 
| factory_closure: | A Multi object factory closure. | 
| Returns : | The initialized BonoboGenericFactory object or NULL if already registered. | 
void        bonobo_generic_factory_construct_noreg
                                            (BonoboGenericFactory *factory,
                                             const char *act_iid,
                                             GClosure *factory_closure);
Initializes c_factory with the supplied closure and iid.
| factory: | The object to be initialized. | 
| act_iid: | The GOAD id that the new factory will implement. | 
| factory_closure: | A Multi object factory closure. | 
int         bonobo_generic_factory_main     (const char *act_iid,
                                             BonoboFactoryCallback factory_cb,
                                             gpointer user_data);
A Generic 'main' routine so we don't stick a load of code
inside a public macro. See also bonobo_generic_factory_main_timeout().
| act_iid: | the oaf iid of the factory | 
| factory_cb: | the factory callback | 
| user_data: | a user data pointer | 
| Returns : | 0 on success, 1 on failure. | 
int         bonobo_generic_factory_main_timeout
                                            (const char *act_iid,
                                             BonoboFactoryCallback factory_cb,
                                             gpointer user_data,
                                             guint quit_timeout);
A Generic 'main' routine so we don't stick a load of code inside a public macro.
| act_iid: | the oaf iid of the factory | 
| factory_cb: | the factory callback | 
| user_data: | a user data pointer | 
| quit_timeout: | ammount of time to wait (miliseconds) after all objects have been released before quitting the main loop. | 
| Returns : | 0 on success, 1 on failure. | 
#define BONOBO_FACTORY_INIT(descr, version, argcp, argv)
Macro that expands to the code need to initialize an exe factory.  Should be placed at the beginning of the main() function.
| descr: | factory description string | 
| version: | version string | 
| argcp: | pointer to main()'s argc | 
| argv: | main()'s argv | 
#define BONOBO_OAF_FACTORY(oafiid, descr, version, callback, data)
Deprecated; see BONOBO_ACTIVATION_FACTORY().
| oafiid: | |
| descr: | |
| version: | |
| callback: | |
| data: | 
#define BONOBO_OAF_FACTORY_MULTI(oafiid, descr, version, callback, data)
Deprecated; see BONOBO_ACTIVATION_FACTORY().
| oafiid: | |
| descr: | |
| version: | |
| callback: | |
| data: | 
#define BONOBO_ACTIVATION_FACTORY(oafiid, descr, version, callback, data)
    Macro that includes all boiler-plate code necessary to create an exe
    type factory, including a main() function and a generic factory.
| oafiid: | The factory's OAFIID | 
| descr: | Description of the factory | 
| version: | Version string of the factory program | 
| callback: | Function (BonoboFactoryCallback) responsible for intantiating components | 
| data: | Additional data to be passed to the callback | 
#define BONOBO_ACTIVATION_FACTORY_TIMEOUT(oafiid, descr, version, callback, data, quit_timeout)
    Like BONOBO_ACTIVATION_FACTORY(), but has an extra quit_timeout argument.
| oafiid: | The factory's OAFIID | 
| descr: | Description of the factory | 
| version: | Version string of the factory program | 
| callback: | Function (BonoboFactoryCallback) responsible for intantiating components | 
| data: | Additional data to be passed to the callback | 
| quit_timeout: | Ammount of time to wait (in milliseconds) before deciding to quit the factory. A larger value prevents frequent respawning of a new factory process when there are many consecutive one-time requests, so that your factory appears to start faster after the first time. |