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.

One final thing worth thinking about is activation. When a control is embedded inside a BonoboControlFrame, it is initialy inactive. In order for the control to recieve interactive input it is neccessary to use bonobo_control_frame_activate. This signals to the control that it is activated, at which point the Control should merge any UI elements it has with the associated BonoboUIComponent. This needs to be done every time the control is activated.

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.


bonobo_control_get_widget ()

GtkWidget*  bonobo_control_get_widget       (BonoboControl *control);

Returns the GtkWidget associated with a BonoboControl.


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.


bonobo_control_get_automerge ()

gboolean    bonobo_control_get_automerge    (BonoboControl *control);


bonobo_control_set_property ()

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


bonobo_control_get_property ()

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


bonobo_control_construct ()

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


bonobo_control_get_ui_component ()

BonoboUIComponent* bonobo_control_get_ui_component
                                            (BonoboControl *control);


bonobo_control_set_ui_component ()

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


bonobo_control_get_remote_ui_container ()

Bonobo_UIContainer bonobo_control_get_remote_ui_container
                                            (BonoboControl *control);


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.


bonobo_control_get_control_frame ()

Bonobo_ControlFrame bonobo_control_get_control_frame
                                            (BonoboControl *control);


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.


bonobo_control_get_properties ()

BonoboPropertyBag* bonobo_control_get_properties
                                            (BonoboControl *control);


bonobo_control_get_ambient_properties ()

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


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.


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: ..."

See Also

BonoboWidget, bonobo_widget_new()