MateComponentWidget

## MateComponentWidget MateComponentWidget — Simplified embedding of widgets in MateComponent. |

## Synopsis

    struct              MateComponentWidget;
                        MateComponentWidgetPrivate;
                        MateComponentWidgetClass;
    MateComponent_Unknown      matecomponent_widget_get_objref            (MateComponentWidget *bw);
    GtkWidget *         matecomponent_widget_new_control           (const char *moniker,
                                                             MateComponent_UIContainer uic);
    GtkWidget *         matecomponent_widget_new_control_from_objref
                                                            (MateComponent_Control control,
                                                             MateComponent_UIContainer uic);
    MateComponentControlFrame * matecomponent_widget_get_control_frame    (MateComponentWidget *bw);
    MateComponent_UIContainer  matecomponent_widget_get_ui_container      (MateComponentWidget *bw);
    void                (*MateComponentWidgetAsyncFn)              (MateComponentWidget *widget,
                                                             CORBA_Environment *ev,
                                                             gpointer user_data);
    GtkWidget *         matecomponent_widget_new_control_async     (const char *moniker,
                                                             MateComponent_UIContainer uic,
                                                             MateComponentWidgetAsyncFn fn,
                                                             gpointer user_data);
    MateComponentWidget *      matecomponent_widget_construct_control_from_objref
                                                            (MateComponentWidget *bw,
                                                             MateComponent_Control control,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);
    MateComponentWidget *      matecomponent_widget_construct_control     (MateComponentWidget *bw,
                                                             const char *moniker,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);
    void                matecomponent_widget_set_property          (MateComponentWidget *control,
                                                             const char *first_prop,
                                                             ...);
    void                matecomponent_widget_get_property          (MateComponentWidget *control,
                                                             const char *first_prop,
                                                             ...);
    #define             matecomponent_widget_get_uih               (w)

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----MateComponentWidget

## Implemented Interfaces

MateComponentWidget implements AtkImplementorIface and GtkBuildable.

## Description

MateComponent component embedding for hydrocephalic imbeciles.

Pure cane sugar.

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

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

       1
       2
       bw = matecomponent_widget_new_control ("id for control", toplevel_ui_handler);
              gtk_container_add (some_container, bw);

   You are free to make the 2nd (UIContainer) argument to `matecomponent_widget_new_control()` be CORBA_OBJECT_NIL.

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

       1
       bw = matecomponent_widget_new_control ("file:/demo/a.jpeg", toplevel_ui_handler);

   will launch an application that can render a jpeg as a control, usualy the Eye Of Mate (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 MateComponentWidget

    struct MateComponentWidget;

### MateComponentWidgetPrivate

    typedef struct _MateComponentWidgetPrivate MateComponentWidgetPrivate;

### MateComponentWidgetClass

    typedef struct {
    	GtkBinClass	 bin_class;

    	gpointer dummy[4];
    } MateComponentWidgetClass;

### matecomponent_widget_get_objref ()

    MateComponent_Unknown      matecomponent_widget_get_objref            (MateComponentWidget *bw);

`bw` : |
Returns : |

### matecomponent_widget_new_control ()

    GtkWidget *         matecomponent_widget_new_control           (const char *moniker,
                                                             MateComponent_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` : | MateComponent_UIContainer for the launched object or CORBA_OBJECT_NIL if there is no need of menu / toolbar merging.
Returns : | A GtkWidget that is bound to the MateComponent Control.

### matecomponent_widget_new_control_from_objref ()

    GtkWidget *         matecomponent_widget_new_control_from_objref
                                                            (MateComponent_Control control,
                                                             MateComponent_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:MateComponent/Control:1.0 (the `control`) argument.

`control` : | A CORBA Object reference to an IDL:MateComponent/Control:1.0
`uic` : | MateComponent_UIContainer for the launched object or CORBA_OBJECT_NIL if there is no need of menu / toolbar merging.
Returns : | the `control` wrapped as a GtkWidget.

### matecomponent_widget_get_control_frame ()

    MateComponentControlFrame * matecomponent_widget_get_control_frame    (MateComponentWidget *bw);

Every IDL:MateComponent/Control:1.0 needs to be placed inside an IDL:MateComponent/ControlFrame:1.0. This returns the MateComponentControlFrame object that wraps the Control in the `matecomponent_widget`.

`bw` : |
Returns : | The MateComponentControlFrame associated with the `matecomponent_widget`

### matecomponent_widget_get_ui_container ()

    MateComponent_UIContainer  matecomponent_widget_get_ui_container      (MateComponentWidget *bw);

`bw` : |
Returns : | the CORBA object reference to the MateComponent_UIContainer associated with the `matecomponent_widget`.

### MateComponentWidgetAsyncFn ()

    void                (*MateComponentWidgetAsyncFn)              (MateComponentWidget *widget,
                                                             CORBA_Environment *ev,
                                                             gpointer user_data);

`widget` : |
`ev` : |
`user_data` : |

### matecomponent_widget_new_control_async ()

    GtkWidget *         matecomponent_widget_new_control_async     (const char *moniker,
                                                             MateComponent_UIContainer uic,
                                                             MateComponentWidgetAsyncFn fn,
                                                             gpointer user_data);

This method creates a widget, returns it to the user, and asynchronously activates a control to insert into the widget.

`moniker` : | A Moniker describing the object to be activated
`uic` : | MateComponent_UIContainer for the launched object or CORBA_OBJECT_NIL if there is no need of menu / toolbar merging.
`fn` : | a callback function called when the activation has happend
`user_data` : | user data to be passed back to the callback.
Returns : | a (temporarily) empty Widget to be filled with the control later

### matecomponent_widget_construct_control_from_objref ()

    MateComponentWidget *      matecomponent_widget_construct_control_from_objref
                                                            (MateComponentWidget *bw,
                                                             MateComponent_Control control,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);

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

`bw` : | A MateComponentWidget to construct
`control` : | A CORBA Object reference to an IDL:MateComponent/Control:1.0
`uic` : | MateComponent_UIContainer for the launched object or CORBA_OBJECT_NIL if there is no need of menu / toolbar merging.
`ev` : | a CORBA exception environment
Returns : | A MateComponentWidget (the `bw`)

### matecomponent_widget_construct_control ()

    MateComponentWidget *      matecomponent_widget_construct_control     (MateComponentWidget *bw,
                                                             const char *moniker,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);

This is a constructor function. Only usable for wrapping and derivation of new objects. For normal use, please refer to matecomponent_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 MateComponentWidget to construct
`moniker` : | A Moniker describing the object to be activated
`uic` : | MateComponent_UIContainer for the launched object or CORBA_OBJECT_NIL if there is no need of menu / toolbar merging.
`ev` : | a CORBA exception environment
Returns : | A MateComponentWidget or `NULL`

### matecomponent_widget_set_property ()

    void                matecomponent_widget_set_property          (MateComponentWidget *control,
                                                             const char *first_prop,
                                                             ...);

This is a utility function used to set a number of properties in the MateComponent 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 `matecomponent_property_bag_client_setv()` function).

This only works for MateComponentWidgets that represent controls (ie, that were returned by `matecomponent_widget_new_control_from_objref()` or `matecomponent_widget_new_control()`.

`control` : | A MateComponentWidget that represents an IDL:MateComponent/Control:1.0
`first_prop` : | first property name to set.
`...` : |

### matecomponent_widget_get_property ()

    void                matecomponent_widget_get_property          (MateComponentWidget *control,
                                                             const char *first_prop,
                                                             ...);

This is a utility function used to get a number of properties in the MateComponent 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 `matecomponent_property_bag_client_setv()` function).

This only works for MateComponentWidgets that represent controls (ie, that were returned by `matecomponent_widget_new_control_from_objref()` or `matecomponent_widget_new_control()`.

`control` : | A MateComponentWidget that represents an IDL:MateComponent/Control:1.0
`first_prop` : | first property name to set.
`...` : |

### matecomponent_widget_get_uih()

    #define matecomponent_widget_get_uih(w) matecomponent_widget_get_ui_container (w)

`w` : |
Returns : |

## See Also

Object activation happens with `matecomponent_get_object()`.

MateComponentControl, MateComponentControlFrame, MateComponentObject, MateComponentView, MateComponentEmbeddable, MateComponentUIContainer, MateComponentItemContainer.