manpagez: man pages & more
html files: libbonobo
Home | html | info | man

BonoboGenericFactory

BonoboGenericFactory — The basic, generic Bonobo object factory implementation

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.

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.

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.

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.

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.

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().

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.

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.

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().

oafiid :

descr :

version :

callback :

data :


BONOBO_OAF_FACTORY_MULTI()

#define             BONOBO_OAF_FACTORY_MULTI(oafiid, descr, version, callback, data)

Deprecated; see BONOBO_ACTIVATION_FACTORY().

oafiid :

descr :

version :

callback :

data :


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.

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.

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.
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.