BonoboItemHandler

## BonoboItemHandler BonoboItemHandler — Simple Moniker Arguments |

## Synopsis

                BonoboItemHandler;
                BonoboItemHandlerClass;
    BonoboItemHandler* bonobo_item_handler_new  (BonoboItemHandlerEnumObjectsFn enum_objects,
                                                 BonoboItemHandlerGetObjectFn get_object,
                                                 gpointer user_data);
    BonoboItemHandler* bonobo_item_handler_new_closure
                                                (GClosure *enum_objects,
                                                 GClosure *get_object);
    BonoboItemHandler* bonobo_item_handler_construct
                                                (BonoboItemHandler *handler,
                                                 GClosure *enum_objects,
                                                 GClosure *get_object);
                BonoboItemOption;
    GSList*     bonobo_item_option_parse        (const char *option_string);
    void        bonobo_item_options_free        (GSList *options);

## Object Hierarchy

      GObject
       +----BonoboObject
             +----BonoboItemHandler

## Description

Sometimes you want to pass "arguments" to a component. Consider the component with the following OAFIID:

`OAFIID:GNOME_FileSelector`

You might want to be able to set configuration options from its moniker name, without having to ever use the property bag API. For example:

`OAFIID:GNOME_FileSelector!AcceptMimeTypes=image/*`

### Implementing it

Create a BonoboItemHandler. This component will let you do argument parsing of any kind.

You have to provide two functions: `enumObjects` (this can be empty) and `getObject`.

The getObject function will be called when the moniker mechanism is trying to resolve a set of arguments to your function.

Like this:

    Bonobo_Unknown
    getObject (BonoboItemHandler *h, const char *item_name,
               gboolean only_if_exists, gpointer data,
               CORBA_Environment *ev)
    {
            MyData *m = data;

            if (strcmp (item_name, "friendly") == 0){
                    m->friendly = true;
            }

            /* we just return ourselves */
            return bonobo_object_dup_ref (bonobo_object_corba_objref (h), NULL);
    }

So basically during the `getObject' operation you will be given a chance to process the `item_name' string which is basically like a command line argument (for the sake of explaining this) and based on this information you can customize your component.

### Sample functions

Sometimes you will want to specify a bunch of options to configure your component, like this:

`OAFIID:MyComponent!visible=true;image=blah.png`

So we are separating the various options with semi-colons here. To simplify your code, we have provided a couple of functions that given the following string:

`visible=true;image=blah.png`

Will return a GList split with BonoboItemOptions:

    GSList *l, *x;

    x = bonobo_item_option_parse ("visible=true;image=blah.png");

    for (l = x; l != NULL; l++){
    	BonoboItemOption *io = l->data;

    	printf ("Key=s, Value=s\n", io->key, io->value);
    }
    bonobo_item_option_free (x);

## Details

### BonoboItemHandler

    typedef struct _BonoboItemHandler BonoboItemHandler;

Bonobo::ItemHandler implementation

### BonoboItemHandlerClass

    typedef struct {
    	BonoboObjectClass parent_class;

    	POA_Bonobo_ItemContainer__epv epv;
    } BonoboItemHandlerClass;

BonoboItemHandler class

### bonobo_item_handler_new ()

    BonoboItemHandler* bonobo_item_handler_new  (BonoboItemHandlerEnumObjectsFn enum_objects,
                                                 BonoboItemHandlerGetObjectFn get_object,
                                                 gpointer user_data);

Creates a new BonoboItemHandler object. These are used to hold client sites.

`enum_objects` : | callback invoked for Bonobo::ItemContainer::enum_objects
`get_object` : | callback invoked for Bonobo::ItemContainer::get_objects
`user_data` : | extra data passed on the callbacks
Returns : | The newly created BonoboItemHandler object

### bonobo_item_handler_new_closure ()

    BonoboItemHandler* bonobo_item_handler_new_closure
                                                (GClosure *enum_objects,
                                                 GClosure *get_object);

Creates a new BonoboItemHandler object. These are used to hold client sites.

`enum_objects` : | closure invoked for Bonobo::ItemContainer::enum_objects
`get_object` : | closure invoked for Bonobo::ItemContainer::get_objects
Returns : | The newly created BonoboItemHandler object

### bonobo_item_handler_construct ()

    BonoboItemHandler* bonobo_item_handler_construct
                                                (BonoboItemHandler *handler,
                                                 GClosure *enum_objects,
                                                 GClosure *get_object);

Constructs the `container` BonoboObject using the provided closures for the actual implementation.

`handler` : | The handler object to construct
`enum_objects` : | The closure implementing enumObjects
`get_object` : | The closure implementing getObject
Returns : | The constructed BonoboItemContainer object.

### BonoboItemOption

    typedef struct {
    	char *key;
    	char *value;
    } BonoboItemOption;

A key-value pair.

### bonobo_item_option_parse ()

    GSList*     bonobo_item_option_parse        (const char *option_string);

`option_string` : |
Returns : |

### bonobo_item_options_free ()

    void        bonobo_item_options_free        (GSList *options);

Use this to release a list returned by `bonobo_item_option_parse()`

`options` : | a GSList of BonoboItemOption structures that was returned by `bonobo_item_option_parse()`

## See Also

A simplistic implementation exists in BonoboItemContainer.