BonoboGenericFactory

BonoboGenericFactory — The basic, generic Bonobo object factory implementation

Functions

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

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.

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.

 

Types and Values