BonoboEmbeddable

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

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);

`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