MateComponentControlFrame

## MateComponentControlFrame MateComponentControlFrame — An implementation of the container's frame containing a Control |

## Synopsis

    struct              MateComponentControlFrame;
                        MateComponentControlFramePrivate;
                        MateComponentControlFrameClass;
    #define             MATECOMPONENT_CONTROL_FRAME_TOPLEVEL_PROP
    MateComponentControlFrame * matecomponent_control_frame_construct     (MateComponentControlFrame *control_frame,
                                                             MateComponent_UIContainer ui_container,
                                                             CORBA_Environment *ev);
    MateComponentControlFrame * matecomponent_control_frame_new           (MateComponent_UIContainer ui_container);
    GtkWidget *         matecomponent_control_frame_get_widget     (MateComponentControlFrame *frame);
    void                matecomponent_control_frame_set_ui_container
                                                            (MateComponentControlFrame *control_frame,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);
    void                matecomponent_control_frame_control_activate
                                                            (MateComponentControlFrame *control_frame);
    void                matecomponent_control_frame_control_deactivate
                                                            (MateComponentControlFrame *control_frame);
    void                matecomponent_control_frame_set_autoactivate
                                                            (MateComponentControlFrame *control_frame,
                                                             gboolean autoactivate);
    gboolean            matecomponent_control_frame_get_autoactivate
                                                            (MateComponentControlFrame *control_frame);
    MateComponent_PropertyBag  matecomponent_control_frame_get_control_property_bag
                                                            (MateComponentControlFrame *control_frame,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_control_frame_set_propbag    (MateComponentControlFrame *control_frame,
                                                             MateComponentPropertyBag *propbag);
    MateComponentPropertyBag * matecomponent_control_frame_get_propbag    (MateComponentControlFrame *control_frame);
    void                matecomponent_control_frame_control_set_state
                                                            (MateComponentControlFrame *control_frame,
                                                             GtkStateType state);
    void                matecomponent_control_frame_set_autostate  (MateComponentControlFrame *control_frame,
                                                             gboolean autostate);
    gboolean            matecomponent_control_frame_get_autostate  (MateComponentControlFrame *control_frame);
    void                matecomponent_control_frame_bind_to_control
                                                            (MateComponentControlFrame *control_frame,
                                                             MateComponent_Control control,
                                                             CORBA_Environment *opt_ev);
    MateComponent_Control      matecomponent_control_frame_get_control    (MateComponentControlFrame *control_frame);
    MateComponent_UIContainer  matecomponent_control_frame_get_ui_container
                                                            (MateComponentControlFrame *control_frame);
    MateComponentUIComponent * matecomponent_control_frame_get_popup_component
                                                            (MateComponentControlFrame *control_frame,
                                                             CORBA_Environment *opt_ev);

## Object Hierarchy

      GObject
       +----MateComponentObject
             +----MateComponentControlFrame

## Signals

      "activate-uri"                                   : Run Last
      "activated"                                      : Run Last

## Description

The MateComponentControlFrame object is used to embed a Control. Most people will want to use MateComponentWidget instead of the control frame since it provides lots of nice auxiliary features to make embedding easy.

Figure 2. The MateComponent::ControlFrame interface

The control frame is coupled to an embedded control and is used to allow the Control to communicate with its environment, particuarly getting the MateComponentUIContainer for merging its menu / toolbar UI elements.

Example 3. A nice use of a MateComponentControlFrame

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    MateComponentWidget *
    matecomponent_widget_construct_control_from_objref (MateComponentWidget      *bw,
                                                 MateComponent_Control     control,
                                                 MateComponent_UIContainer uic)
    {
            GtkWidget    *control_frame_widget;
            /*
             * Create a local ControlFrame for it.
             */
            bw->priv->control_frame = matecomponent_control_frame_new (uic);
            matecomponent_control_frame_bind_to_control (bw->priv->control_frame, control);
            ...
            matecomponent_control_frame_set_autoactivate (bw->priv->control_frame, TRUE);
            /*
             * Grab the actual widget which visually contains the remote
             * Control.  This is a GtkSocket, in reality.
             */
            control_frame_widget = matecomponent_control_frame_get_widget (bw->priv->control_frame);
            /*
             * Now stick it into this MateComponentWidget.
             */
            gtk_container_add (GTK_CONTAINER (bw),
                               control_frame_widget);
            /*
             * Always remember to show the widget before reporting bugs.
             */
            gtk_widget_show (control_frame_widget);
            if (uic != CORBA_OBJECT_NIL)
                    bw->priv->uic = matecomponent_object_dup_ref (uic, NULL);
            return bw;
    }

## Details

### struct MateComponentControlFrame

    struct MateComponentControlFrame;

### MateComponentControlFramePrivate

    typedef struct _MateComponentControlFramePrivate MateComponentControlFramePrivate;

### MateComponentControlFrameClass

    typedef struct {
    	MateComponentObjectClass parent_class;

    	POA_MateComponent_ControlFrame__epv epv;

    	gpointer dummy[4];

    	/* Signals. */
    	void (*activated)           (MateComponentControlFrame *control_frame, gboolean state);
    	void (*activate_uri)        (MateComponentControlFrame *control_frame, const char *uri, gboolean relative);
    } MateComponentControlFrameClass;

### MATECOMPONENT_CONTROL_FRAME_TOPLEVEL_PROP

    #define MATECOMPONENT_CONTROL_FRAME_TOPLEVEL_PROP "matecomponent:toplevel"

### matecomponent_control_frame_construct ()

    MateComponentControlFrame * matecomponent_control_frame_construct     (MateComponentControlFrame *control_frame,
                                                             MateComponent_UIContainer ui_container,
                                                             CORBA_Environment *ev);

Initializes `control_frame` with the parameters.

`control_frame` : | The MateComponentControlFrame object to be initialized.
`ui_container` : | A CORBA object for the UIContainer for the container application.
`ev` : |
Returns : | the initialized MateComponentControlFrame object `control_frame` that implements the MateComponent::ControlFrame CORBA service.

### matecomponent_control_frame_new ()

    MateComponentControlFrame * matecomponent_control_frame_new           (MateComponent_UIContainer ui_container);

`ui_container` : | The MateComponent_UIContainer for the container application.
Returns : | MateComponentControlFrame object that implements the MateComponent::ControlFrame CORBA service.

### matecomponent_control_frame_get_widget ()

    GtkWidget *         matecomponent_control_frame_get_widget     (MateComponentControlFrame *frame);

Use this function when you want to embed a MateComponentControl into your container's widget hierarchy. Once you have bound the MateComponentControlFrame to a remote MateComponentControl, place the widget returned by `matecomponent_control_frame_get_widget()` into your widget hierarchy and the control will appear in your application.

`frame` : | The MateComponentControlFrame whose widget is being requested.a
Returns : | A GtkWidget which has the remote MateComponentControl physically inside it.

### matecomponent_control_frame_set_ui_container ()

    void                matecomponent_control_frame_set_ui_container
                                                            (MateComponentControlFrame *control_frame,
                                                             MateComponent_UIContainer uic,
                                                             CORBA_Environment *ev);

Associates a new `MateComponent_UIContainer` object with this ControlFrame. This is only allowed while the Control is deactivated.

`control_frame` : |
`uic` : | A MateComponent_UIContainer object reference.
`ev` : |

### matecomponent_control_frame_control_activate ()

    void                matecomponent_control_frame_control_activate
                                                            (MateComponentControlFrame *control_frame);

Activates the MateComponentControl embedded in `control_frame` by calling the `activate()` MateComponent_Control interface method on it.

`control_frame` : | The MateComponentControlFrame object whose control should be activated.

### matecomponent_control_frame_control_deactivate ()

    void                matecomponent_control_frame_control_deactivate
                                                            (MateComponentControlFrame *control_frame);

Deactivates the MateComponentControl embedded in `frame` by calling the `activate()` CORBA method on it with the parameter `FALSE`.

`control_frame` : | The MateComponentControlFrame object whose control should be deactivated.

### matecomponent_control_frame_set_autoactivate ()

    void                matecomponent_control_frame_set_autoactivate
                                                            (MateComponentControlFrame *control_frame,
                                                             gboolean autoactivate);

Modifies the autoactivate behavior of `frame`. If `frame` is set to autoactivate, then it will automatically send an "activate" message to the Control to which it is bound when it gets a focus-in event, and a "deactivate" message when it gets a focus-out event. Autoactivation is off by default.

`control_frame` : |
`autoactivate` : | A flag which indicates whether or not the ControlFrame should automatically perform activation on the Control to which it is bound.

### matecomponent_control_frame_get_autoactivate ()

    gboolean            matecomponent_control_frame_get_autoactivate
                                                            (MateComponentControlFrame *control_frame);

`control_frame` : |
Returns : | A boolean which indicates whether or not `frame` is set to automatically activate its Control. See `matecomponent_control_frame_set_autoactivate()`.

### matecomponent_control_frame_get_control_property_bag ()

    MateComponent_PropertyBag  matecomponent_control_frame_get_control_property_bag
                                                            (MateComponentControlFrame *control_frame,
                                                             CORBA_Environment *opt_ev);

This retrives a MateComponent_PropertyBag reference from its associated MateComponent Control

`control_frame` : |
`opt_ev` : |
Returns : | CORBA property bag reference or CORBA_OBJECT_NIL

### matecomponent_control_frame_set_propbag ()

    void                matecomponent_control_frame_set_propbag    (MateComponentControlFrame *control_frame,
                                                             MateComponentPropertyBag *propbag);

Makes `frame` use `propbag` for its ambient properties. When `frame`'s Control requests the ambient properties, it will get them from `propbag`.

`control_frame` : |
`propbag` : | A MateComponentPropertyBag which will hold `frame`'s ambient properties.

### matecomponent_control_frame_get_propbag ()

    MateComponentPropertyBag * matecomponent_control_frame_get_propbag    (MateComponentControlFrame *control_frame);

`control_frame` : |
Returns : | The MateComponentPropertyBag object which has been associated with `frame`.

### matecomponent_control_frame_control_set_state ()

    void                matecomponent_control_frame_control_set_state
                                                            (MateComponentControlFrame *control_frame,
                                                             GtkStateType state);

Proxies `state` to the control bound to `frame`.

`control_frame` : |
`state` : | A GtkStateType value, specifying the widget state to apply to the remote control.

### matecomponent_control_frame_set_autostate ()

    void                matecomponent_control_frame_set_autostate  (MateComponentControlFrame *control_frame,
                                                             gboolean autostate);

Changes whether or not `frame` automatically proxies state changes to its associated control. The default mode is for the control frame to autopropagate.

`control_frame` : |
`autostate` : | Whether or not GtkWidget state changes should be automatically propagated down to the Control.

### matecomponent_control_frame_get_autostate ()

    gboolean            matecomponent_control_frame_get_autostate  (MateComponentControlFrame *control_frame);

`control_frame` : |
Returns : | Whether or not this control frame will automatically proxy GtkState changes to its associated Control.

### matecomponent_control_frame_bind_to_control ()

    void                matecomponent_control_frame_bind_to_control
                                                            (MateComponentControlFrame *control_frame,
                                                             MateComponent_Control control,
                                                             CORBA_Environment *opt_ev);

Associates `control` with this `frame`.

`control_frame` : |
`control` : | The CORBA object for the MateComponentControl embedded in this MateComponentControlFrame.
`opt_ev` : | Optional exception environment

### matecomponent_control_frame_get_control ()

    MateComponent_Control      matecomponent_control_frame_get_control    (MateComponentControlFrame *control_frame);

`control_frame` : |
Returns : | The MateComponent_Control CORBA interface for the remote Control which is bound to `frame`. See also `matecomponent_control_frame_bind_to_control()`.

### matecomponent_control_frame_get_ui_container ()

    MateComponent_UIContainer  matecomponent_control_frame_get_ui_container
                                                            (MateComponentControlFrame *control_frame);

`control_frame` : |
Returns : | The MateComponent_UIContainer object reference associated with this ControlFrame. This ui_container is specified when the ControlFrame is created. See `matecomponent_control_frame_new()`.

### matecomponent_control_frame_get_popup_component ()

    MateComponentUIComponent * matecomponent_control_frame_get_popup_component
                                                            (MateComponentControlFrame *control_frame,
                                                             CORBA_Environment *opt_ev);

`control_frame` : |
`opt_ev` : |
Returns : |

## Signal Details

### The `"activate-uri"` signal

    void                user_function                      (MateComponentControlFrame *matecomponentcontrolframe,
                                                            gchar              *arg1,
                                                            gboolean            arg2,
                                                            gpointer            user_data)               : Run Last

`matecomponentcontrolframe` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"activated"` signal

    void                user_function                      (MateComponentControlFrame *matecomponentcontrolframe,
                                                            gboolean            arg1,
                                                            gpointer            user_data)               : Run Last

`matecomponentcontrolframe` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

MateComponentWidget, `matecomponent_widget_new()`