![]() | ![]() | ![]() | Libbonobo Reference Manual | ![]() |
---|
BonoboGenericFactory — The basic, generic Bonobo object factory implementation
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 factory callback 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. |
<< BonoboObject | bonobo-shlib-factory >> |