Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboEmbeddable

## Name

BonoboEmbeddable -- A compound document element's model

## Synopsis

    struct      BonoboEmbeddable;
    #define     BONOBO_VIEW_FACTORY             (fn)
    BonoboView* (*BonoboViewFactory)            (BonoboEmbeddable *embeddable,
                                                 const Bonobo_ViewFrame view_frame,
                                                 void *closure);
    BonoboCanvasComponent* (*GnomeItemCreator)  (BonoboEmbeddable *embeddable,
                                                 GnomeCanvas *canvas,
                                                 void *user_data);
    void        (*BonoboEmbeddableForeachViewFn)
                                                (BonoboView *view,
                                                 void *data);
    void        (*BonoboEmbeddableForeachItemFn)
                                                (BonoboCanvasComponent *comp,
                                                 void *data);
    struct      BonoboEmbeddableClass;
    BonoboEmbeddable* bonobo_embeddable_new     (BonoboViewFactory factory,
                                                 void *data);
    BonoboEmbeddable* bonobo_embeddable_new_canvas_item
                                                (GnomeItemCreator item_factory,
                                                 void *data);
    BonoboEmbeddable* bonobo_embeddable_construct
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *data);
    BonoboEmbeddable* bonobo_embeddable_construct_full
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *factory_data,
                                                 GnomeItemCreator item_factory,
                                                 void *item_factory_data);
    void        bonobo_embeddable_set_view_factory
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *data);
    const char* bonobo_embeddable_get_uri       (BonoboEmbeddable *embeddable);
    void        bonobo_embeddable_set_uri       (BonoboEmbeddable *embeddable,
                                                 const char *uri);
    void        bonobo_embeddable_foreach_view  (BonoboEmbeddable *embeddable,
                                                 BonoboEmbeddableForeachViewFn fn,
                                                 void *data);
    void        bonobo_embeddable_foreach_item  (BonoboEmbeddable *embeddable,
                                                 BonoboEmbeddableForeachItemFn fn,
                                                 void *data);

## Object Hierarchy

      GtkObject
       +----BonoboObject
             +----BonoboXObject
                   +----BonoboEmbeddable

## Signal Prototypes

    "host-name-changed"
                void        user_function      (BonoboEmbeddable *bonoboembeddable,
                                                gchar *arg1,
                                                gpointer user_data);
    "uri-changed"
                void        user_function      (BonoboEmbeddable *bonoboembeddable,
                                                gchar *arg1,
                                                gpointer user_data);

## Description

A BonoboEmbeddable is a component that is an element of a compound document. There is an implicit contract that anything implimenting the embeddable interface will also implement the following interfaces:

- BonoboPrint

- BonoboPersistStream

An embeddable is not a Control - by this I mean that it does not control its own sizing, rendering or layout. It is entirely a slave to the parent with respect to this. An Embeddable should never render scroll bars into itself ( unless, exceptionaly if it is activated, and allows the user to pan around a larger area ). Essentialy a non-activated embeddable view should only show things that it will print, and should render WYSIWYG as much as possible. Embeddable's views scale linearly to obey the zoom level they are given.

If you think your embeddable should have scroll bars, or other widgets inside it's view, you need to implement a BonoboControl first. Many applications will export a BonoboControl and several BonoboEmbeddable. eg. to embed a complete gnumeric application you would use the BonoboControl, to embed a cell range you would use a BonoboEmbeddable.

Embeddables are model / view, that is the BonoboEmbeddable should be derived from and becomes the model, several BonoboView or BonoboCanvasComponent views can be produced to render this information.

Here is an example of how to create a BonoboEmbeddable interface:

Example 1. An embeddable interface

    static BonoboView *
    simple_view_factory (BonoboEmbeddable      *embeddable,
                         const Bonobo_ViewFrame view_frame,
    		     void                  *closure)
    {
    	BonoboView *view = bonobo_view_new (
    		gtk_drawing_area_new());

    	bonobo_view_set_view_frame (view, view_frame);

    	return view;
    }

    BonoboObject *
    create_embeddable()
    {
    	BonoboEmbeddable *embeddable;

    	embeddable = bonobo_embeddable_new (simple_view_factory, NULL);

    	... aggregate other interfaces ...

    	return BONOBO_OBJECT (embeddable);
    }

Note, that this example returns a GtkDrawingArea with nothing in it - simply a white box. This is better than returning a widget - no widget can be a correct Embeddable view, since it cannot zoom.

## Details

### struct BonoboEmbeddable

    struct BonoboEmbeddable;

### BONOBO_VIEW_FACTORY()

    #define BONOBO_VIEW_FACTORY(fn) ((BonoboViewFactory)(fn))

`fn` : |

### BonoboViewFactory ()

    BonoboView* (*BonoboViewFactory)            (BonoboEmbeddable *embeddable,
                                                 const Bonobo_ViewFrame view_frame,
                                                 void *closure);

`embeddable` : |
`view_frame` : |
`closure` : |
Returns : |

### GnomeItemCreator ()

    BonoboCanvasComponent* (*GnomeItemCreator)  (BonoboEmbeddable *embeddable,
                                                 GnomeCanvas *canvas,
                                                 void *user_data);

`embeddable` : |
`canvas` : |
`user_data` : |
Returns : |

### BonoboEmbeddableForeachViewFn ()

    void        (*BonoboEmbeddableForeachViewFn)
                                                (BonoboView *view,
                                                 void *data);

`view` : |
`data` : |

### BonoboEmbeddableForeachItemFn ()

    void        (*BonoboEmbeddableForeachItemFn)
                                                (BonoboCanvasComponent *comp,
                                                 void *data);

`comp` : |
`data` : |

### struct BonoboEmbeddableClass

    struct BonoboEmbeddableClass {
    	BonoboXObjectClass parent_class;

    	POA_Bonobo_Embeddable__epv epv;

    	/* Signals */
    	void (*host_name_changed)  (BonoboEmbeddable *comp, const char *hostname);
    	void (*uri_changed)        (BonoboEmbeddable *comp, const char *uri);
    };

### bonobo_embeddable_new ()

    BonoboEmbeddable* bonobo_embeddable_new     (BonoboViewFactory factory,
                                                 void *data);

This routine creates a Bonobo::Embeddable CORBA server and activates it. The `factory` routine will be invoked by this CORBA server when a request arrives to get a new view of the embeddable (embeddable should be able to provide multiple views of themselves upon demand). The `data` pointer is passed to this factory routine untouched to allow the factory to get some context on what it should create.

`factory` : | Factory routine that provides new views of the embeddable on demand
`data` : | pointer passed to the `factory` routine to provide context.
Returns : | a BonoboEmbeddable that contains an activated Bonobo::Embeddable CORBA server.

### bonobo_embeddable_new_canvas_item ()

    BonoboEmbeddable* bonobo_embeddable_new_canvas_item
                                                (GnomeItemCreator item_factory,
                                                 void *data);

This routine creates a Bonobo::Embeddable CORBA server and activates it. The `factory` routine will be invoked by this CORBA server when a request arrives to get a new view of the embeddable (embeddable should be able to provide multiple views of themselves upon demand). The `data` pointer is passed to this factory routine untouched to allow the factory to get some context on what it should create.

`item_factory` : | Factory routine that provides new canvas items of the embeddable on demand
`data` : | pointer passed to the `factory` routine to provide context.
Returns : | a BonoboEmbeddable that contains an activated Bonobo::Embeddable CORBA server.

### bonobo_embeddable_construct ()

    BonoboEmbeddable* bonobo_embeddable_construct
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *data);

This routine constructs a Bonobo::Embeddable CORBA server and activates it. The `factory` routine will be invoked by this CORBA server when a request arrives to get a new view of the embeddable (embeddable should be able to provide multiple views of themselves upon demand). The `data` pointer is passed to this factory routine untouched to allow the factory to get some context on what it should create.

`embeddable` : | BonoboEmbeddable object to construct.
`factory` : | Factory routine that provides new views of the embeddable on demand
`data` : | pointer passed to the `factory` routine to provide context.
Returns : | The constructed object.

### bonobo_embeddable_construct_full ()

    BonoboEmbeddable* bonobo_embeddable_construct_full
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *factory_data,
                                                 GnomeItemCreator item_factory,
                                                 void *item_factory_data);

`embeddable` : |
`factory` : |
`factory_data` : |
`item_factory` : |
`item_factory_data` : |
Returns : |

### bonobo_embeddable_set_view_factory ()

    void        bonobo_embeddable_set_view_factory
                                                (BonoboEmbeddable *embeddable,
                                                 BonoboViewFactory factory,
                                                 void *data);

This routine defines the view factory for this embeddable component. When a container requires a view, the routine specified in `factory` will be invoked to create a new BonoboView object to satisfy this request.

`embeddable` : | The embeddable object to operate on.
`factory` : | A pointer to a function that can provide BonoboView objects on demand.
`data` : | data to pass to the `factory` function.

### bonobo_embeddable_get_uri ()

    const char* bonobo_embeddable_get_uri       (BonoboEmbeddable *embeddable);

`embeddable` : | The embeddable object to operate on.
Returns : | the URI that this object represents

### bonobo_embeddable_set_uri ()

    void        bonobo_embeddable_set_uri       (BonoboEmbeddable *embeddable,
                                                 const char *uri);

Sets the URI that this object represents.

`embeddable` : | The embeddable object to operate on.
`uri` : | the URI this embeddable represents.

### bonobo_embeddable_foreach_view ()

    void        bonobo_embeddable_foreach_view  (BonoboEmbeddable *embeddable,
                                                 BonoboEmbeddableForeachViewFn fn,
                                                 void *data);

Invokes the `fn` function for each existing view.

`embeddable` : | Embeddable on which we operate
`fn` : | function to be invoked for each existing BonoboView
`data` : | data to pass to function

### bonobo_embeddable_foreach_item ()

    void        bonobo_embeddable_foreach_item  (BonoboEmbeddable *embeddable,
                                                 BonoboEmbeddableForeachItemFn fn,
                                                 void *data);

Invokes the `fn` function for each existing item.

`embeddable` : | Embeddable on which we operate
`fn` : | function to be invoked for each existing GnomeItem
`data` : | data to pass to function

## Signals

### The "host-name-changed" signal

    void        user_function                  (BonoboEmbeddable *bonoboembeddable,
                                                gchar *arg1,
                                                gpointer user_data);

`bonoboembeddable` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "uri-changed" signal

    void        user_function                  (BonoboEmbeddable *bonoboembeddable,
                                                gchar *arg1,
                                                gpointer user_data);

`bonoboembeddable` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

BonoboView, BonoboCanvasComponent, BonoboWidget, BonoboControl, bonobo_widget_new()

<<< Previous Page | Home | Up | Next Page >>>
BonoboClientSite | BonoboItemContainer