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

# BonoboClientSite

## Name

BonoboClientSite -- Container side object embedding server.

## Synopsis

    struct      BonoboClientSite;
    typedef     BonoboClientSiteClass;
    BonoboClientSite* bonobo_client_site_new    (BonoboItemContainer *container);
    BonoboClientSite* bonobo_client_site_construct
                                                (BonoboClientSite *client_site,
                                                 BonoboItemContainer *container);
    gboolean    bonobo_client_site_bind_embeddable
                                                (BonoboClientSite *client_site,
                                                 BonoboObjectClient *object);
    BonoboObjectClient* bonobo_client_site_get_embeddable
                                                (BonoboClientSite *client_site);
    BonoboItemContainer* bonobo_client_site_get_container
                                                (BonoboClientSite *client_site);
    BonoboViewFrame* bonobo_client_site_new_view_full
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic,
                                                 gboolean visible_cover,
                                                 gboolean active_view);
    BonoboViewFrame* bonobo_client_site_new_view
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic);
    GnomeCanvasItem* bonobo_client_site_new_item
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic,
                                                 GnomeCanvasGroup *group);
    GList*      bonobo_client_site_get_verbs    (BonoboClientSite *client_site);
    void        bonobo_client_site_free_verbs   (GList *verb_list);

## Object Hierarchy

      GtkObject
       +----BonoboObject
             +----BonoboXObject
                   +----BonoboClientSite

## Signal Prototypes

    "show-window"
                void        user_function      (BonoboClientSite *bonoboclientsite,
                                                gint arg1,
                                                gpointer user_data);
    "save-object"
                void        user_function      (BonoboClientSite *bonoboclientsite,
                                                gpointer arg1,
                                                gpointer user_data);

## Description

The `BonoboClientSite` implements the `Bonobo::ClientSite` CORBA interface. It acts as the container-side contact for `BonoboEmbeddable` objects.

For each object embedded in your application, you should create a `BonoboClientSite` object.

Once you have a handle on a remote object that implements the `Bonobo::Embeddable` interface (typically returned by bonobo_object_activate() or bonobo_get_object() or wrapper with bonobo_object_client_from_corba()) of type `BonoboObjectClient`), you will have to bind this object to the `BonoboClientSite` using the bonobo_client_site_bind_embeddable(). Once this is done, you will be able to request a BonoboView on the BonoboClientSite.

The BonoboClientSite object also provides access to the remote BonoboEmbeddable object's verb list.

Example 1. Sample usage

This demostrates the use of the BonoboClientSite object. This launches the object specified, creates a BonoboClientSite, then requests a new BonoboViewFrame and finally it returns the widget that represents that component.

    GtkWidget *
    create_widget_from_component (BonoboContainer *container, const char *id)
    {
    	BonoboObjectClient *server;
    	BonoboClientSite   *client_site;
    	BonoboViewFrame    *view_frame;

    	/*
    	 * Launch the requested component
    	 */
    	server = bonobo_object_activate (id, 0);
    	if (!server){
    		printf ("Could not activate the server");
    		return NULL;
    	}

    	client_site = bonobo_client_site_new (app->container);

    	/*
    	 * Add this client site to the container
    	 */
    	bonobo_container_add (container, BONOBO_OBJECT (client_site));

    	/*
    	 * Bind the component to the client site
    	 */
    	bonobo_client_site_bind_embeddable (client_site, server);

    	/*
    	 * Create a new BonoboView, and then get a GtkWidget
    	 */
    	view_frame = bonobo_client_site_embeddable_new_view (client_site);

    	/*
    	 * Get the widget for this view.
    	 */

    	 return bonobo_view_frame_get_wrapper (view_frame);
    }

## Details

### struct BonoboClientSite

    struct BonoboClientSite;

### BonoboClientSiteClass

    typedef struct {
    	BonoboXObjectClass parent_class;

    	POA_Bonobo_ClientSite__epv epv;

    	void (*show_window)  (BonoboClientSite *, CORBA_boolean shown);
    	void (*queue_resize) (BonoboClientSite *);
    	void (*save_object)  (BonoboClientSite *, Bonobo_Persist_Status *status);
    } BonoboClientSiteClass;

### bonobo_client_site_new ()

    BonoboClientSite* bonobo_client_site_new    (BonoboItemContainer *container);

Container programs should provide a BonoboClientSite GTK object (ie, a Bonobo::ClientSite CORBA server) for each Embeddable which they embed. This is the contact end point for the remote Bonobo::Embeddable object.

This routine creates a new BonoboClientSite.

`container` : | The container to which this client_site belongs.
Returns : | The activated BonoboClientSite object bound to the `container` container.

### bonobo_client_site_construct ()

    BonoboClientSite* bonobo_client_site_construct
                                                (BonoboClientSite *client_site,
                                                 BonoboItemContainer *container);

This initializes an object of type BonoboClientSite. See the description for bonobo_client_site_new() for more details.

`client_site` : | The BonoboClientSite object to initialize
`container` : | a BonoboContainer to bind to.
Returns : | the constructed BonoboClientSite `client_site`.

### bonobo_client_site_bind_embeddable ()

    gboolean    bonobo_client_site_bind_embeddable
                                                (BonoboClientSite *client_site,
                                                 BonoboObjectClient *object);

This routine binds a remote Embeddable object to a local BonoboClientSite object. The idea is that there is always a one-to-one mapping between BonoboClientSites and BonoboEmbeddables. The Embeddable uses its BonoboClientSite to communicate with the container in which it is embedded.

`client_site` : | the client site to which the remote Embeddable object will be bound.
`object` : | The remote object which supports the Bonobo::Embeddable interface.
Returns : | `TRUE` if `object` was successfully bound to `client_site` `client_site`.

### bonobo_client_site_get_embeddable ()

    BonoboObjectClient* bonobo_client_site_get_embeddable
                                                (BonoboClientSite *client_site);

`client_site` : | A BonoboClientSite object which is bound to a remote BonoboObject server.
Returns : | The BonoboObjectClient object which corresponds to the remote BonoboObject to which `client_site` is bound.

### bonobo_client_site_get_container ()

    BonoboItemContainer* bonobo_client_site_get_container
                                                (BonoboClientSite *client_site);

`client_site` : | A BonoboClientSite object which is bound to a remote BonoboObject server.
Returns : | The BonoboObjectClient object which corresponds to the remote BonoboObject to which `client_site` is bound.

### bonobo_client_site_new_view_full ()

    BonoboViewFrame* bonobo_client_site_new_view_full
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic,
                                                 gboolean visible_cover,
                                                 gboolean active_view);

Creates a ViewFrame and asks the remote `server_object` (which must support the Bonobo::Embeddable interface) to provide a new view of its data. The remote `server_object` will construct a BonoboView object which corresponds to the new BonoboViewFrame returned by this function.

`client_site` : | the client site that contains a remote Embeddable object.
`uic` : | The CORBA object for the container's UIContainer server.
`visible_cover` : | `TRUE` if the cover should draw a border when it is active.
`active_view` : | `TRUE` if the view should be uncovered when it is created.
Returns : | A BonoboViewFrame object that contains the view frame for the new view of `server_object`.

### bonobo_client_site_new_view ()

    BonoboViewFrame* bonobo_client_site_new_view
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic);

The same as bonobo_client_site_new_view_full() with an inactive, visible cover.

`client_site` : | the client site that contains a remote Embeddable object.
`uic` : | The UIContainer object.
Returns : | A BonoboViewFrame object that contains the view frame for the new view of `server_object`.

### bonobo_client_site_new_item ()

    GnomeCanvasItem* bonobo_client_site_new_item
                                                (BonoboClientSite *client_site,
                                                 Bonobo_UIContainer uic,
                                                 GnomeCanvasGroup *group);

`client_site` : | The client site that contains a remote Embeddable object
`uic` : | The UI container for the item.
`group` : | The Canvas group that will be the parent for the new item.
Returns : | A GnomeCanvasItem that wraps the remote Canvas Item.

### bonobo_client_site_get_verbs ()

    GList*      bonobo_client_site_get_verbs    (BonoboClientSite *client_site);

`client_site` : |
Returns : |

### bonobo_client_site_free_verbs ()

    void        bonobo_client_site_free_verbs   (GList *verb_list);

`verb_list` : |

## Signals

### The "show-window" signal

    void        user_function                  (BonoboClientSite *bonoboclientsite,
                                                gint arg1,
                                                gpointer user_data);

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

### The "save-object" signal

    void        user_function                  (BonoboClientSite *bonoboclientsite,
                                                gpointer arg1,
                                                gpointer user_data);

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

## See Also

BonoboEmbeddable, BonoboContainer, BonoboObjectClient, BonoboViewFrame

<<< Previous Page | Home | Up | Next Page >>>
Bonobo Compound Documents | BonoboEmbeddable