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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    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:

    1
    2
    3
    4
    5
    6
    7
    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.