Bonobo API Reference Manual
<<< Previous PageHomeUpNext Page >>>

BonoboWidget

Name

BonoboWidget -- Simplified embedding of widgets in Bonobo.

Synopsis



struct      BonoboWidget;
typedef     BonoboWidgetClass;
BonoboObjectClient* bonobo_widget_get_server
                                            (BonoboWidget *bw);
BonoboWidget* bonobo_widget_construct_control
                                            (BonoboWidget *bw,
                                             const char *moniker,
                                             Bonobo_UIContainer uic);
BonoboWidget* bonobo_widget_construct_control_from_objref
                                            (BonoboWidget *bw,
                                             Bonobo_Control control,
                                             Bonobo_UIContainer uic);
GtkWidget*  bonobo_widget_new_control       (const char *moniker,
                                             Bonobo_UIContainer uic);
GtkWidget*  bonobo_widget_new_control_from_objref
                                            (Bonobo_Control control,
                                             Bonobo_UIContainer uic);
BonoboControlFrame* bonobo_widget_get_control_frame
                                            (BonoboWidget *bw);
GtkWidget*  bonobo_widget_new_subdoc        (const char *moniker,
                                             Bonobo_UIContainer uic);
BonoboItemContainer* bonobo_widget_get_container
                                            (BonoboWidget *bw);
BonoboClientSite* bonobo_widget_get_client_site
                                            (BonoboWidget *bw);
BonoboViewFrame* bonobo_widget_get_view_frame
                                            (BonoboWidget *bw);
Bonobo_UIContainer bonobo_widget_get_uih    (BonoboWidget *bw);
Bonobo_Unknown bonobo_widget_get_objref     (BonoboWidget *bw);
void        bonobo_widget_set_property      (BonoboWidget *control,
                                             const char *first_prop,
                                             ...);
void        bonobo_widget_get_property      (BonoboWidget *control,
                                             const char *first_prop,
                                             ...);

Description

Bonobo component embedding for hydrocephalic imbeciles.

Pure cane sugar.

This purpose of BonoboWidget is to make container-side use of Bonobo as easy as pie. This widget has two functions:

  1. Provide a simple wrapper for embedding a single-view subdocument. In this case, BonoboWidget handles creating the embeddable, binding it to a local BonoboClientSite, creating a view for it, and displaying the view. You can use the accessor functions (bonobo_widget_get_view_frame, etc) to get at the actual Bonobo objects which underlie the whole process.

    In order to do this, just call: 

    	bw = bonobo_widget_new_subdoc ("id of subdoc embeddable", top_level_uihandler);

    And then insert the 'bw' widget into the widget tree of your application like so: 

    	gtk_container_add (some_container, bw);

    You are free to make the UIContainer argument to bonobo_widget_new_subdoc() be CORBA_OBJECT_NIL.

  2. Provide a simple wrapper for embedding Controls. Embedding controls is already really easy, but BonoboWidget reduces the work from about 5 lines to 1. To embed a given control, just do: 

           bw = bonobo_widget_new_control ("id for control");
       gtk_container_add (some_container, bw);

  3. To provide an extremely simple wrapper for using Monikers. In fact all BonoboWidget use uses the OAFIID: moniker to activate its sub-components. However monikers (bonobo-moniker-util) are far more powerful than this: 

    	         bw = bonobo_widget_new_control ("file:/demo/a.jpeg");

    will launch an application that can render a jpeg as a control, usualy the Eye Of Gnome (EOG), and embed it as a control.

There are also functions for fetching and setting values in the Control PropertyBag, but the use of these functions is discouraged.

Details

struct BonoboWidget

struct BonoboWidget;

BonoboWidgetClass

typedef struct {
	GtkBinClass	 bin_class;
} BonoboWidgetClass;

bonobo_widget_get_server ()

BonoboObjectClient* bonobo_widget_get_server
                                            (BonoboWidget *bw);

bw : 
Returns : The BonoboObjectClient (a wrapper for the CORBA object reference) to the object that this BonoboWidget is wrapping.

bonobo_widget_construct_control ()

BonoboWidget* bonobo_widget_construct_control
                                            (BonoboWidget *bw,
                                             const char *moniker,
                                             Bonobo_UIContainer uic);

This is a constructor function. Only usable for wrapping and derivation of new objects. For normal use, please refer to bonobo_widget_new_control.

This function will unref the passed in bw in case it cannot launch the component and return NULL in such a case. Otherwise it returns the bw itself.

bw : A BonoboWidget to construct
moniker : A Moniker describing the object to be activated
uic : Bonobo_UIContainer for the launched object.
Returns : A BonoboWidget or NULL

bonobo_widget_construct_control_from_objref ()

BonoboWidget* bonobo_widget_construct_control_from_objref
                                            (BonoboWidget *bw,
                                             Bonobo_Control control,
                                             Bonobo_UIContainer uic);

This is a constructor function. Only usable for wrapping and derivation of new objects. For normal use, please refer to bonobo_widget_new_control_from_objref.

bw : A BonoboWidget to construct
control : A CORBA Object reference to an IDL:Bonobo/Control:1.0
uic : Bonobo_UIContainer for the launched object.
Returns : A BonoboWidget (the bw)

bonobo_widget_new_control ()

GtkWidget*  bonobo_widget_new_control       (const char *moniker,
                                             Bonobo_UIContainer uic);

This function is a simple wrapper for easily embedding controls into applications. It will launch the component identified by id and will return it as a GtkWidget.

moniker : A Moniker describing the object to be activated
uic : Bonobo_UIContainer for the launched object.
Returns : A GtkWidget that is bound to the Bonobo Control.

bonobo_widget_new_control_from_objref ()

GtkWidget*  bonobo_widget_new_control_from_objref
                                            (Bonobo_Control control,
                                             Bonobo_UIContainer uic);

This function is a simple wrapper for easily embedding controls into applications. This function is used when you have already a CORBA object reference to an IDL:Bonobo/Control:1.0 (the control) argument.

control : A CORBA Object reference to an IDL:Bonobo/Control:1.0
uic : Bonobo_UIContainer for the launched object.
Returns : the control wrapped as a GtkWidget.

bonobo_widget_get_control_frame ()

BonoboControlFrame* bonobo_widget_get_control_frame
                                            (BonoboWidget *bw);

Every IDL:Bonobo/Control:1.0 needs to be placed inside an IDL:Bonobo/ControlFrame:1.0. This returns the BonoboControlFrame object that wraps the Control in the bonobo_widget.

bw : 
Returns : The BonoboControlFrame associated with the bonobo_widget

bonobo_widget_new_subdoc ()

GtkWidget*  bonobo_widget_new_subdoc        (const char *moniker,
                                             Bonobo_UIContainer uic);

This function is a simple wrapper for easily embedding documents into applications. It will launch the component identified by id and will return it as a GtkWidget.

This will launch a single view of the embeddable activated by moniker.

FIXME: this function should really be using bonobo_get_object() instead of bonobo_activate_object() to launch the object.

moniker : A moniker description of the Object to be activated.
uic : Bonobo_UIContainer for the launched object.
Returns : A GtkWidget that is bound to the Bonobo Control.

bonobo_widget_get_container ()

BonoboItemContainer* bonobo_widget_get_container
                                            (BonoboWidget *bw);

This operation is only valid for BonoboWidgets that were created by the bonobo_widget_new_subdoc().

bw : 
Returns : the BonoboItemContainer associated with this bonobo_widget

bonobo_widget_get_client_site ()

BonoboClientSite* bonobo_widget_get_client_site
                                            (BonoboWidget *bw);

This operation is only valid for BonoboWidgets that were created by the bonobo_widget_new_subdoc().

bw : 
Returns : the BonoboClientSite associated with this bonobo_widget

bonobo_widget_get_view_frame ()

BonoboViewFrame* bonobo_widget_get_view_frame
                                            (BonoboWidget *bw);

This operation is only valid for BonoboWidgets that were created by the bonobo_widget_new_subdoc().

bw : 
Returns : The BonoboViewFrame associated with this bonobo_widget.

bonobo_widget_get_uih ()

Bonobo_UIContainer bonobo_widget_get_uih    (BonoboWidget *bw);

bw : 
Returns : the CORBA object reference to the Bonobo_UIContainer associated with the bonobo_widget.

bonobo_widget_get_objref ()

Bonobo_Unknown bonobo_widget_get_objref     (BonoboWidget *bw);

bw : 
Returns : 

bonobo_widget_set_property ()

void        bonobo_widget_set_property      (BonoboWidget *control,
                                             const char *first_prop,
                                             ...);

This is a utility function used to set a number of properties in the Bonobo Control in control.

This function takes a variable list of arguments that must be NULL terminated. Arguments come in tuples: a string (for the argument name) and the data type that is to be transfered. The implementation of the actual setting of the PropertyBag values is done by the bonobo_property_bag_client_setv() function).

FIXME: This function is error prone because it depends on the client and the server to agree on the data types to be sent. If the server arguments change the data type, this routine will not be able to cope gracefully with this condition.

This only works for BonoboWidgets that represent controls (ie, that were returned by bonobo_widget_new_control_from_objref() or bonobo_widget_new_control().

control : A BonoboWidget that represents an IDL:Bonobo/Control:1.0
first_prop : first property name to set.
... : 

bonobo_widget_get_property ()

void        bonobo_widget_get_property      (BonoboWidget *control,
                                             const char *first_prop,
                                             ...);

This is a utility function used to get a number of properties in the Bonobo Control in control.

This function takes a variable list of arguments that must be NULL terminated. Arguments come in tuples: a string (for the argument name) and a pointer where the data will be stored. The implementation of the actual setting of the PropertyBag values is done by the bonobo_property_bag_client_setv() function).

FIXME: This function is error prone because it depends on the client and the server to agree on the data types to be sent. If the server arguments change the data type, this routine will not be able to cope gracefully with this condition.

This only works for BonoboWidgets that represent controls (ie, that were returned by bonobo_widget_new_control_from_objref() or bonobo_widget_new_control().

control : A BonoboWidget that represents an IDL:Bonobo/Control:1.0
first_prop : first property name to set.
... : 

See Also

Object activation happens with bonobo_get_object().

BonoboControl, BonoboControlFrame, BonoboObject, BonoboView, BonoboEmbeddable, BonoboUIContainer, BonoboItemContainer.



<<< Previous PageHomeUpNext Page >>>
Bonobo UIBonoboWindow