BonoboControl
3
LIBBONOBOUI Library

# BonoboControl

An implementation of the control interface for GtkWidgets

## Synopsis

                        BonoboControl;
                        BonoboControlPrivate;
                        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,
                                                             CORBA_Environment *opt_ev,
                                                             const char *first_prop,
                                                             ...);
    void                bonobo_control_get_property         (BonoboControl *control,
                                                             CORBA_Environment *opt_ev,
                                                             const char *first_prop,
                                                             ...);
    void                bonobo_control_set_transient_for    (BonoboControl *control,
                                                             GtkWindow *window,
                                                             CORBA_Environment *opt_ev);
    void                bonobo_control_unset_transient_for  (BonoboControl *control,
                                                             GtkWindow *window,
                                                             CORBA_Environment *opt_ev);
    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,
                                                             CORBA_Environment *opt_ev);
    void                bonobo_control_set_control_frame    (BonoboControl *control,
                                                             Bonobo_ControlFrame control_frame,
                                                             CORBA_Environment *opt_ev);
    Bonobo_ControlFrame  bonobo_control_get_control_frame   (BonoboControl *control,
                                                             CORBA_Environment *opt_ev);
    void                bonobo_control_set_properties       (BonoboControl *control,
                                                             Bonobo_PropertyBag pb,
                                                             CORBA_Environment *opt_ev);
    Bonobo_PropertyBag  bonobo_control_get_properties       (BonoboControl *control);
    Bonobo_PropertyBag  bonobo_control_get_ambient_properties
                                                            (BonoboControl *control,
                                                             CORBA_Environment *opt_ev);
    void                bonobo_control_activate_notify      (BonoboControl *control,
                                                             gboolean activated,
                                                             CORBA_Environment *opt_ev);
    Bonobo_Gdk_WindowId  bonobo_control_window_id_from_x11  (guint32 x11_id);
    guint32             bonobo_control_x11_from_window_id   (const CORBA_char *id);
    #define             bonobo_control_windowid_from_x11    (a)
    #define             BONOBO_CONTROL_POPUP_BUTTON1
    #define             BONOBO_CONTROL_POPUP_BUTTON2
    #define             BONOBO_CONTROL_POPUP_BUTTON3
    BonoboUIContainer * bonobo_control_get_popup_ui_container
                                                            (BonoboControl *control);
    BonoboUIComponent * bonobo_control_get_popup_ui_component
                                                            (BonoboControl *control);
    void                bonobo_control_set_popup_ui_container
                                                            (BonoboControl *control,
                                                             BonoboUIContainer *ui_container);
    gboolean            bonobo_control_do_popup             (BonoboControl *control,
                                                             guint button,
                                                             guint32 activate_time);
    gboolean            bonobo_control_do_popup_full        (BonoboControl *control,
                                                             GtkWidget *parent_menu_shell,
                                                             GtkWidget *parent_menu_item,
                                                             GtkMenuPositionFunc func,
                                                             gpointer data,
                                                             guint button,
                                                             guint32 activate_time);
    void                (*BonoboControlLifeCallback)        (void);
    void                bonobo_control_life_set_purge       (long ms );
    void                bonobo_control_life_set_callback    (BonoboControlLifeCallback all_dead_callback);
    void                bonobo_control_life_instrument      (BonoboControl *control);
    int                 bonobo_control_life_get_count       (void);

## Object Hierarchy

      GObject
       +----BonoboObject
             +----BonoboControl

## Signals

      "activate"                                       : Run Last
      "disconnected"                                   : Run Last
      "plug-created"                                   : Run Last
      "set-frame"                                      : Run Last

## 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.

### The Bonobo::Control interface

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

### 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

### 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 _BonoboControl BonoboControl;

### BonoboControlPrivate

    typedef struct _BonoboControlPrivate BonoboControlPrivate;

### BonoboControlClass

    typedef struct {
    	BonoboObjectClass      parent_class;

    	POA_Bonobo_Control__epv epv;

    	gpointer dummy[2];

    	/* Signals. */
    	void (*plug_created)   (BonoboControl *control);
    	void (*disconnected)   (BonoboControl *control);
    	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,
                                                             CORBA_Environment *opt_ev,
                                                             const char *first_prop,
                                                             ...);

This method takes a NULL terminated list of name, type, value triplicates, and sets the corresponding values on the control's associated property bag.

`control` :

  the control with associated property bag

`opt_ev` :

  optional corba exception environment

`first_prop` :

  the first property's name

`...` :

### bonobo_control_get_property ()

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

This method takes a NULL terminated list of name, type, value triplicates, and fetches the corresponding values on the control's associated property bag.

`control` :

  the control with associated property bag

`opt_ev` :

  optional corba exception environment

`first_prop` :

  the first property's name

`...` :

### bonobo_control_set_transient_for ()

    void                bonobo_control_set_transient_for    (BonoboControl *control,
                                                             GtkWindow *window,
                                                             CORBA_Environment *opt_ev);

Attempts to make the `window` transient for the toplevel of any associated controlframe the BonoboControl may have.

`control` :

  a control with associated control frame

`window` :

  a window upon which to set the transient window.

`opt_ev` :

### bonobo_control_unset_transient_for ()

    void                bonobo_control_unset_transient_for  (BonoboControl *control,
                                                             GtkWindow *window,
                                                             CORBA_Environment *opt_ev);

`control` :

  a control with associated control frame

`window` :

  a window upon which to unset the transient window.

`opt_ev` :

### 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,
                                                             CORBA_Environment *opt_ev);

`control` :

  A BonoboControl object which is associated with a remote ControlFrame.

`opt_ev` :

  an optional exception environment

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,
                                                             CORBA_Environment *opt_ev);

`control` :

`control_frame` :

`opt_ev` :

### bonobo_control_get_control_frame ()

    Bonobo_ControlFrame  bonobo_control_get_control_frame   (BonoboControl *control,
                                                             CORBA_Environment *opt_ev);

`control` :

  A BonoboControl object whose Bonobo_ControlFrame CORBA interface is being retrieved.

`opt_ev` :

  an optional exception environment

Returns :

  The Bonobo_ControlFrame CORBA object associated with `control`, this is a CORBA_Object_duplicated object. You need to CORBA_Object_release it when you are done with it.

### bonobo_control_set_properties ()

    void                bonobo_control_set_properties       (BonoboControl *control,
                                                             Bonobo_PropertyBag pb,
                                                             CORBA_Environment *opt_ev);

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 Bonobo_PropertyBag.

`opt_ev` :

  An optional exception environment

### bonobo_control_get_properties ()

    Bonobo_PropertyBag  bonobo_control_get_properties       (BonoboControl *control);

`control` :

  A BonoboControl whose PropertyBag has already been set.

Returns :

  The Bonobo_PropertyBag bound to `control`.

### bonobo_control_get_ambient_properties ()

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

`control` :

  A BonoboControl which is bound to a remote BonoboControlFrame.

`opt_ev` :

  an optional 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,
                                                             CORBA_Environment *opt_ev);

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.

`opt_ev` :

  An optional exception environment

### bonobo_control_window_id_from_x11 ()

    Bonobo_Gdk_WindowId  bonobo_control_window_id_from_x11  (guint32 x11_id);

`x11_id` :

  the x11 window id or Windows HWND.

Returns :

  the window id or handle as a string; free after use.

### bonobo_control_x11_from_window_id ()

    guint32             bonobo_control_x11_from_window_id   (const CORBA_char *id);

De-mangle a window id string, fields are separated by ':' character, currently only the first field is used.

`id` :

  CORBA_char *

Returns :

  the native window id.

### bonobo_control_windowid_from_x11()

    #define             bonobo_control_windowid_from_x11(a)

`a` :

Returns :

### BONOBO_CONTROL_POPUP_BUTTON1

    #define                     BONOBO_CONTROL_POPUP_BUTTON1           "/popups/button1"

### BONOBO_CONTROL_POPUP_BUTTON2

    #define                     BONOBO_CONTROL_POPUP_BUTTON2           "/popups/button2"

### BONOBO_CONTROL_POPUP_BUTTON3

    #define                     BONOBO_CONTROL_POPUP_BUTTON3           "/popups/button3"

### bonobo_control_get_popup_ui_container ()

    BonoboUIContainer * bonobo_control_get_popup_ui_container
                                                            (BonoboControl *control);

`control` :

Returns :

### bonobo_control_get_popup_ui_component ()

    BonoboUIComponent * bonobo_control_get_popup_ui_component
                                                            (BonoboControl *control);

`control` :

Returns :

### bonobo_control_set_popup_ui_container ()

    void                bonobo_control_set_popup_ui_container
                                                            (BonoboControl *control,
                                                             BonoboUIContainer *ui_container);

`control` :

`ui_container` :

### bonobo_control_do_popup ()

    gboolean            bonobo_control_do_popup             (BonoboControl *control,
                                                             guint button,
                                                             guint32 activate_time);

`control` :

`button` :

`activate_time` :

Returns :

### bonobo_control_do_popup_full ()

    gboolean            bonobo_control_do_popup_full        (BonoboControl *control,
                                                             GtkWidget *parent_menu_shell,
                                                             GtkWidget *parent_menu_item,
                                                             GtkMenuPositionFunc func,
                                                             gpointer data,
                                                             guint button,
                                                             guint32 activate_time);

`control` :

`parent_menu_shell` :

`parent_menu_item` :

`func` :

`data` :

`button` :

`activate_time` :

Returns :

### BonoboControlLifeCallback ()

    void                (*BonoboControlLifeCallback)        (void);

### bonobo_control_life_set_purge ()

    void                bonobo_control_life_set_purge       (long ms );

Set time we're prepared to wait without a ControlFrame before terminating the Control. This can happen if the panel activates us but crashes before the set_frame.

`Param1` :

### bonobo_control_life_set_callback ()

    void                bonobo_control_life_set_callback    (BonoboControlLifeCallback all_dead_callback);

See bonobo_control_life_instrument

`all_dead_callback` :

  method to call at idle when no controls remain

### bonobo_control_life_instrument ()

    void                bonobo_control_life_instrument      (BonoboControl *control);

Request that `control` is lifecycle managed by this code; when it (and all other registerees are dead, the all_dead_callback set by bonobo_control_life_set_callback will be called at idle.

`control` :

  control to manage.

### bonobo_control_life_get_count ()

    int                 bonobo_control_life_get_count       (void);

calculates the number of live controls under management.

Returns :

  the number of live controls.

## Signal Details

### The `"activate"` signal

    void                user_function                      (BonoboControl *bonobocontrol,
                                                            gboolean       arg1,
                                                            gpointer       user_data)          : Run Last

`bonobocontrol` :

  the object which received the signal.

`arg1` :

`user_data` :

  user data set when the signal handler was connected.

### The `"disconnected"` signal

    void                user_function                      (BonoboControl *bonobocontrol,
                                                            gpointer       user_data)          : Run Last

`bonobocontrol` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### The `"plug-created"` signal

    void                user_function                      (BonoboControl *bonobocontrol,
                                                            gpointer       user_data)          : Run Last

`bonobocontrol` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### The `"set-frame"` signal

    void                user_function                      (BonoboControl *bonobocontrol,
                                                            gpointer       user_data)          : Run Last

`bonobocontrol` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

## See Also

BonoboWidget, `bonobo_widget_new()`