Libbonobo Reference Manual: BonoboGenericFactory

BonoboGenericFactory

BonoboGenericFactory — The basic, generic Bonobo object factory implementation

Functions

BonoboObject *	(*BonoboFactoryCallback) ()
BonoboGenericFactory *	bonobo_generic_factory_new ()
BonoboGenericFactory *	bonobo_generic_factory_new_closure ()
BonoboGenericFactory *	bonobo_generic_factory_construct ()
void	bonobo_generic_factory_construct_noreg ()
int	bonobo_generic_factory_main ()
int	bonobo_generic_factory_main_timeout ()
#define	BONOBO_FACTORY_INIT()
#define	BONOBO_OAF_FACTORY()
#define	BONOBO_OAF_FACTORY_MULTI()
#define	BONOBO_ACTIVATION_FACTORY()
#define	BONOBO_ACTIVATION_FACTORY_TIMEOUT()

Object Hierarchy

    GObject
    ╰── BonoboObject
        ╰── BonoboGenericFactory
            ╰── BonoboShlibFactory

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

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

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.

Functions

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.

Parameters

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

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.

Parameters

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.

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.

Parameters

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.

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.

Parameters

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.

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.

Parameters

factory	The object to be initialized.
act_iid	The GOAD id that the new factory will implement.
factory_closure	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().

Parameters

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.

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.

Parameters

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.

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.

Parameters

descr	factory description string
version	version string
argcp	pointer to `main()`'s argc
argv	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.

Parameters

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

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.

Parameters

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.

BonoboGenericFactory

Functions

Object Hierarchy

Description

Functions

BonoboFactoryCallback ()

Parameters

Returns

bonobo_generic_factory_new ()

Parameters

Returns

bonobo_generic_factory_new_closure ()

Parameters

Returns

bonobo_generic_factory_construct ()

Parameters

Returns

bonobo_generic_factory_construct_noreg ()

Parameters

bonobo_generic_factory_main ()

Parameters

Returns

bonobo_generic_factory_main_timeout ()

Parameters

Returns

BONOBO_FACTORY_INIT()

Parameters

BONOBO_OAF_FACTORY()

BONOBO_OAF_FACTORY_MULTI()

BONOBO_ACTIVATION_FACTORY()

Parameters

BONOBO_ACTIVATION_FACTORY_TIMEOUT()

Parameters

Types and Values