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

# BonoboControl

## Name

BonoboControl -- An implementation of the control interface for GtkWidgets

## Synopsis

    typedef     BonoboControl;
    typedef     BonoboControlClass;
    BonoboControl* bonobo_control_new           (GtkWidget *widget);
    GtkWidget*  bonobo_control_get_widget       (BonoboControl *control);
    void        bonobo_control_set_automerge    (BonoboControl *control,
                                                 gboolean automerge);
    gboolean    bonobo_control_get_automerge    (BonoboControl *control);
    void        bonobo_control_set_property     (BonoboControl *control,
                                                 const char *first_prop,
                                                 ...);
    void        bonobo_control_get_property     (BonoboControl *control,
                                                 const char *first_prop,
                                                 ...);
    BonoboControl* bonobo_control_construct     (BonoboControl *control,
                                                 GtkWidget *widget);
    BonoboUIComponent* bonobo_control_get_ui_component
                                                (BonoboControl *control);
    void        bonobo_control_set_ui_component (BonoboControl *control,
                                                 BonoboUIComponent *component);
    Bonobo_UIContainer bonobo_control_get_remote_ui_container
                                                (BonoboControl *control);
    void        bonobo_control_set_control_frame
                                                (BonoboControl *control,
                                                 Bonobo_ControlFrame control_frame);
    Bonobo_ControlFrame bonobo_control_get_control_frame
                                                (BonoboControl *control);
    void        bonobo_control_set_properties   (BonoboControl *control,
                                                 BonoboPropertyBag *pb);
    BonoboPropertyBag* bonobo_control_get_properties
                                                (BonoboControl *control);
    Bonobo_PropertyBag bonobo_control_get_ambient_properties
                                                (BonoboControl *control,
                                                 CORBA_Environment *ev);
    void        bonobo_control_activate_notify  (BonoboControl *control,
                                                 gboolean activated);
    Bonobo_Control_windowId bonobo_control_windowid_from_x11
                                                (guint32 x11_id);

## Description

The BonoboControl object implements the CORBA interface for handling remote embeddable components. A Control is a light weight, single view, arbitrarily complex 'widget'. Controls typicaly expose much of their functionality through a property bag.

A BonoboControl provides the server ( or component ) side implementation of a Control. The client that uses this control will probably use a BonoboWidget to use the control in their program.

If you want to expose your widget as a control it is very simple

Example 1. CORBA-ifying your GtkWidget

    BonoboControl *control;
    GtkWidget     *widget;
    Bonobo_Unknown corba_object;

    widget = make_my_widget();
    gtk_widget_show (widget);

    control = bonobo_control_new (widget);
    corba_object = BONOBO_OBJREF (control);

The corba_object can then be passed off down the wire to anyone and the control popped into a BonoboWidget or BonoboControlFrame at the other end. Here is an even less useful example

Example 2. A pretty useless Control

    GtkWidget *widget;

    widget = gtk_button_new_with_label ("My Control");
    gtk_widget_show (widget);

    return bonobo_control_new (widget);

If you learn only one thing from this example, it should be that you need to do a gtk_widget_show on your control. It is not sufficient to do a gtk_widget_show_all on the top level of the client side, since this will not ( and should not ) propagate over to the Control.

## Details

### BonoboControl

    typedef struct {
    	BonoboXObject base;

    	BonoboControlPrivate *priv;
    } BonoboControl;

### BonoboControlClass

    typedef struct {
    	BonoboXObjectClass      parent_class;

    	POA_Bonobo_Control__epv epv;

    	/* Signals. */
    	void (*set_frame)      (BonoboControl *control);
    	void (*activate)       (BonoboControl *control, gboolean state);
    } BonoboControlClass;

### bonobo_control_new ()

    BonoboControl* bonobo_control_new           (GtkWidget *widget);

This function creates a new BonoboControl object for `widget`.

`widget` : | a GTK widget that contains the control and will be passed to the container process.
Returns : | a BonoboControl object that implements the Bonobo::Control CORBA service that will transfer the `widget` to the container process.

### bonobo_control_get_widget ()

    GtkWidget*  bonobo_control_get_widget       (BonoboControl *control);

Returns the GtkWidget associated with a BonoboControl.

`control` : | a BonoboControl
Returns : | the BonoboControl's widget

### bonobo_control_set_automerge ()

    void        bonobo_control_set_automerge    (BonoboControl *control,
                                                 gboolean automerge);

Sets whether or not the control handles menu/toolbar merging automatically. If automerge is on, the control will automatically register its BonoboUIComponent with the remote BonoboUIContainer when it is activated.

`control` : | A BonoboControl.
`automerge` : | Whether or not menus and toolbars should be automatically merged when the control is activated.

### bonobo_control_get_automerge ()

    gboolean    bonobo_control_get_automerge    (BonoboControl *control);

`control` : | A BonoboControl.
Returns : | Whether or not the control is set to automerge its menus/toolbars. See bonobo_control_set_automerge().

### bonobo_control_set_property ()

    void        bonobo_control_set_property     (BonoboControl *control,
                                                 const char *first_prop,
                                                 ...);

`control` : |
`first_prop` : |
`...` : |

### bonobo_control_get_property ()

    void        bonobo_control_get_property     (BonoboControl *control,
                                                 const char *first_prop,
                                                 ...);

`control` : |
`first_prop` : |
`...` : |

### bonobo_control_construct ()

    BonoboControl* bonobo_control_construct     (BonoboControl *control,
                                                 GtkWidget *widget);

`control` : |
`widget` : |
Returns : |

### bonobo_control_get_ui_component ()

    BonoboUIComponent* bonobo_control_get_ui_component
                                                (BonoboControl *control);

`control` : | The control
Returns : | the associated UI component

### bonobo_control_set_ui_component ()

    void        bonobo_control_set_ui_component (BonoboControl *control,
                                                 BonoboUIComponent *component);

`control` : |
`component` : |

### bonobo_control_get_remote_ui_container ()

    Bonobo_UIContainer bonobo_control_get_remote_ui_container
                                                (BonoboControl *control);

`control` : | A BonoboControl object which is associated with a remote ControlFrame.
Returns : | The Bonobo_UIContainer CORBA server for the remote BonoboControlFrame.

### bonobo_control_set_control_frame ()

    void        bonobo_control_set_control_frame
                                                (BonoboControl *control,
                                                 Bonobo_ControlFrame control_frame);

Sets the ControlFrame for `control` to `control_frame`.

`control` : | A BonoboControl object.
`control_frame` : | A CORBA interface for the ControlFrame which contains this Controo.

### bonobo_control_get_control_frame ()

    Bonobo_ControlFrame bonobo_control_get_control_frame
                                                (BonoboControl *control);

`control` : | A BonoboControl object whose Bonobo_ControlFrame CORBA interface is being retrieved.
Returns : | The Bonobo_ControlFrame CORBA object associated with `control`, this is a CORBA_object_duplicated object. You need to CORBA_free it when you are done with it.

### bonobo_control_set_properties ()

    void        bonobo_control_set_properties   (BonoboControl *control,
                                                 BonoboPropertyBag *pb);

Binds `pb` to `control`. When a remote object queries `control` for its property bag, `pb` will be used in the responses.

`control` : | A BonoboControl object.
`pb` : | A BonoboPropertyBag.

### bonobo_control_get_properties ()

    BonoboPropertyBag* bonobo_control_get_properties
                                                (BonoboControl *control);

`control` : | A BonoboControl whose PropertyBag has already been set.
Returns : | The BonoboPropertyBag bound to `control`.

### bonobo_control_get_ambient_properties ()

    Bonobo_PropertyBag bonobo_control_get_ambient_properties
                                                (BonoboControl *control,
                                                 CORBA_Environment *ev);

`control` : | A BonoboControl which is bound to a remote BonoboControlFrame.
`ev` : | CORBA exception environment.
Returns : | A Bonobo_PropertyBag bound to the bag of ambient properties associated with this Control's ControlFrame.

### bonobo_control_activate_notify ()

    void        bonobo_control_activate_notify  (BonoboControl *control,
                                                 gboolean activated);

Notifies the remote ControlFrame which is associated with `control` that `control` has been activated/deactivated.

`control` : | A BonoboControl object which is bound to a remote ControlFrame.
`activated` : | Whether or not `control` has been activated.

### bonobo_control_windowid_from_x11 ()

    Bonobo_Control_windowId bonobo_control_windowid_from_x11
                                                (guint32 x11_id);

This mangles the X11 name into the ':' delimited string format "X-id: ..."

`x11_id` : | the x11 window id.
Returns : | the string; free after use.

## See Also

BonoboWidget, bonobo_widget_new()

<<< Previous Page | Home | Up | Next Page >>>
Controls | BonoboControlFrame