Libbonobo Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Synopsis
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)
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 7. How to register a factory with OAF
1 2 3 4 5 |
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 8. A simple factory
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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.
Details
BonoboFactoryCallback ()
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.
|
the factory that invoked this callback |
|
OAFIID of the component that should be activated |
|
user data |
Returns : |
the newly created BonoboObject |
bonobo_generic_factory_new ()
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.
|
The GOAD id that this factory implements |
|
A callback which is used to create new BonoboObject instances. |
|
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. |
bonobo_generic_factory_new_closure ()
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.
|
The GOAD id that this factory implements |
|
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. |
bonobo_generic_factory_construct ()
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.
|
The object to be initialized. |
|
The Bonobo activation id that the new factory will implement. Bonobo::GenericFactory interface and which will be used to construct this BonoboGenericFactory Gtk object. |
|
A Multi object factory closure. |
Returns : |
The initialized BonoboGenericFactory object or NULL if already registered. |
bonobo_generic_factory_construct_noreg ()
void bonobo_generic_factory_construct_noreg (BonoboGenericFactory *factory
,const char *act_iid
,GClosure *factory_closure
);
Initializes c_factory
with the supplied closure and iid.
|
The object to be initialized. |
|
The GOAD id that the new factory will implement. |
|
A Multi object factory closure. |
bonobo_generic_factory_main ()
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()
.
|
the oaf iid of the factory |
|
the factory callback |
|
a user data pointer |
Returns : |
0 on success, 1 on failure. |
bonobo_generic_factory_main_timeout ()
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.
|
the oaf iid of the factory |
|
the factory callback |
|
a user data pointer |
|
ammount of time to wait (miliseconds) after all objects have been released before quitting the main loop. |
Returns : |
0 on success, 1 on failure. |
BONOBO_FACTORY_INIT()
#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.
|
factory description string |
|
version string |
|
pointer to main() 's argc
|
|
main()'s argv |
BONOBO_OAF_FACTORY()
#define BONOBO_OAF_FACTORY(oafiid, descr, version, callback, data)
Deprecated; see BONOBO_ACTIVATION_FACTORY()
.
|
|
|
|
|
|
|
|
|
BONOBO_OAF_FACTORY_MULTI()
#define BONOBO_OAF_FACTORY_MULTI(oafiid, descr, version, callback, data)
Deprecated; see BONOBO_ACTIVATION_FACTORY()
.
|
|
|
|
|
|
|
|
|
BONOBO_ACTIVATION_FACTORY()
#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.
|
The factory's OAFIID |
|
Description of the factory |
|
Version string of the factory program |
|
Function (BonoboFactoryCallback) responsible for intantiating components |
|
Additional data to be passed to the callback |
BONOBO_ACTIVATION_FACTORY_TIMEOUT()
#define BONOBO_ACTIVATION_FACTORY_TIMEOUT(oafiid, descr, version, callback, data, quit_timeout)
Like BONOBO_ACTIVATION_FACTORY()
, but has an extra quit_timeout
argument.
|
The factory's OAFIID |
|
Description of the factory |
|
Version string of the factory program |
|
Function (BonoboFactoryCallback) responsible for intantiating components |
|
Additional data to be passed to the callback |
|
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. |