<!-- ##### SECTION ./tmpl/matecomponent-canvas-component.sgml:Long_Description ##### -->
<para>
  The MateComponentCanvasComponent objects are used to wrap MateCanvasItems
  and export them to container applications.  Typically the
  matecomponent_component_canvas_new() function will be invoked in a callback
  from a MateComponentEmbeddable object.
</para>

<para>
  Here is an example of how to export Mate Canvas Items in a simple
  way.  
  <example>
    <title>Wrapping a Mate Canvas Item</title>
    <programlisting>

/*
 * Here is where the MateCanvasItem (in this case an ellipse)
 * is created and wrapped in a MateComponentCanvasComponent.
 *
 * This function is invoked on demand on the embeddable
 * argument.  Embeddables are the document model, and the
 * items returned are the views.  
 */
MateComponentCanvasComponent *
my_item_creator (MateComponentEmbeddable *embeddable,
                 MateCanvas      *canvas,
                 void             *data)
{
        MateCanvasItem *item = mate_canvas_item_new (
		mate_canvas_root (canvas),
                mate_canvas_ellipse_get_type (),
                "x1", 5.0,  "y1", 5.0,
                "x2", 95.0, "y2", 95.0,
                "fill_color", "white",
                "outline_color", "black",
                NULL);

        return matecomponent_canvas_component_new (item);
}

/*
 * This is a routine that creates a MateComponentEmbeddable that
 * uses CanvasItems.
 */
MateComponentEmbeddable *make_embeddable (void)
{
       return matecomponent_embeddable_new_canvas_item (my_item_creator, NULL);
}
    </programlisting>
  </example>
</para>

<para>
  Applications that do not use the base #MateComponentEmbeddable class, but
  use their own types derived from the #MateComponentEmbeddable can use the
  matecomponent_embeddable_construct() during their construction phase. 
</para>

<para>
  On the client side (the application that will embed this component)
  an object of the type #MateComponentCanvasItem is used.
</para>


<!-- ##### SECTION ./tmpl/matecomponent-canvas-component.sgml:See_Also ##### -->
<para>
  #MateComponentEmbeddable, #MateComponentCanvasItem
</para>


<!-- ##### SECTION ./tmpl/matecomponent-canvas-component.sgml:Short_Description ##### -->
Class for exporting MateComponentCanvasItems through MateComponentEmbeddables to
other applications.


<!-- ##### SECTION ./tmpl/matecomponent-canvas-component.sgml:Title ##### -->
MateComponentCanvasComponent


<!-- ##### SECTION ./tmpl/matecomponent-canvas-item.sgml:Long_Description ##### -->
<para>
   The MateComponent Canvas Item is a Canvas item that will allow you to
   embed an arbitrary Canvas Item that lives in in a remote
   Embeddable.  On the remote end, the #MateComponentCanvasComponent class is
   used to wrap an arbitrary #MateCanvasItem and export it. 
</para>

<para>
   This allows arbitrarily shaped components to be inserted into an
   application.  Both Xlib and AA canvas items are supported.
</para>


<!-- ##### SECTION ./tmpl/matecomponent-canvas-item.sgml:See_Also ##### -->
<para>
   #MateComponentCanvasComponent, #MateComponentEmbeddable, #MateComponentObjectClient.
</para>


<!-- ##### SECTION ./tmpl/matecomponent-canvas-item.sgml:Short_Description ##### -->
A MATE Canvas Item that can be used to embed remote MateComponent MATE
Canvas Items.


<!-- ##### SECTION ./tmpl/matecomponent-canvas-item.sgml:Title ##### -->
MateComponentCanvasItem


<!-- ##### SECTION ./tmpl/matecomponent-client-site.sgml:Long_Description ##### -->
<para>
   The <classname>MateComponentClientSite</classname> implements the
   <classname>MateComponent::ClientSite</classname> CORBA interface.  It acts
   as the container-side contact for
   <classname>MateComponentEmbeddable</classname> objects.
</para>

<para>
   For each object embedded in your application, you should create a
   <classname>MateComponentClientSite</classname> object.  
</para>

<para>
   Once you have a handle on a remote object that implements the
   <classname>MateComponent::Embeddable</classname> interface (typically
   returned by matecomponent_object_activate() or
   matecomponent_get_object () or wrapper with
   matecomponent_object_client_from_corba ()) of type
   <classname>MateComponentObjectClient</classname>), you will have to bind
   this object to the <classname>MateComponentClientSite</classname> using the
   matecomponent_client_site_bind_embeddable ().  Once this is done, you will
   be able to request a #MateComponentView on the #MateComponentClientSite.  
</para>

<para>
   The #MateComponentClientSite object also provides access to the remote
   MateComponentEmbeddable object's verb list.  
</para>

<example>
   <title>Sample usage</title>

   <para>
      This demostrates the use of the #MateComponentClientSite object.  This
      launches the object specified, creates a #MateComponentClientSite,
      then requests a new #MateComponentViewFrame and finally it returns the
      widget that represents that component.
   </para>
      
   <programlisting>
GtkWidget *
create_widget_from_component (MateComponentContainer *container, const char *id)
{
	MateComponentObjectClient *server;
	MateComponentClientSite   *client_site;
	MateComponentViewFrame    *view_frame;

	/*
	 * Launch the requested component
	 */
	server = matecomponent_object_activate (id, 0);
	if (!server){
		printf ("Could not activate the server");
		return NULL;
	}

	client_site = matecomponent_client_site_new (app->container);

	/*
	 * Add this client site to the container
	 */
	matecomponent_container_add (container, MATECOMPONENT_OBJECT (client_site));

	/*
	 * Bind the component to the client site
	 */
	matecomponent_client_site_bind_embeddable (client_site, server);

	/*
	 * Create a new MateComponentView, and then get a GtkWidget
	 */
	view_frame = matecomponent_client_site_embeddable_new_view (client_site);

	/*
	 * Get the widget for this view.
	 */

	 return matecomponent_view_frame_get_wrapper (view_frame);
}

   </programlisting>
</example>


<!-- ##### SECTION ./tmpl/matecomponent-client-site.sgml:See_Also ##### -->
<para>
  #MateComponentEmbeddable, #MateComponentContainer, #MateComponentObjectClient, #MateComponentViewFrame
</para>


<!-- ##### SECTION ./tmpl/matecomponent-client-site.sgml:Short_Description ##### -->
Container side object embedding server.


<!-- ##### SECTION ./tmpl/matecomponent-client-site.sgml:Title ##### -->
MateComponentClientSite


<!-- ##### SECTION ./tmpl/matecomponent-transient.sgml:Long_Description ##### -->
<para>
   The <classname>MateComponentTransient</classname> is used to create
   transient objects.  These objects only exist during the lifetime of
   the method execution of the interface they implement: they are
   created on demand and destroyed after the method invocation
   finishes. 
</para>

<para>
   Transient objects are an optimization useful when it is possible
   for a very large set of object to exist but there is no need to
   have implementations of the servers running all the time, as they
   can be created on the demand to satisfy the requests of client
   applications. 
</para>

<para>
   For example, consider the case in which a large list of objects
   needs to be returned to a client application.  For example, an
   object reference could be returned for every file on a directory.
   But it would be wasteful to keep one server running for each file.
   And given that the program has all the information available to
   create the servers on demand, you want to use this system.
</para>

<para>
   This can be used for implementations of the IDL:MateComponent/PropertyBag
   interface, as there are in theories thousands of keys that could be
   returned, but the method invocations on each object is short-lived,
   so it is efficient to just create servers to satisfy an object
   request on demand, and destroy them when the request is done.
</para>

<para>
   To create such object, you first need to create a
   <classname>MateComponentTransient</classname> object, and then for every
   virtual object that you want to expose to the world, you invoke the
   matecomponent_transient_create_objref() function to create a new CORBA
   object reference. 
</para>

<para>
   matecomponent_transient_new() will create a new POA inside the POA you
   specify (you can use CORBA_OBJECT_NIL to get the POA to be created
   in the default MateComponent POA).  All object references created with
   matecomponent_transient_create_objref() will live in this new POA. 
</para>

<para>
   The matecomponent_transient_new() function takes an argument that
   specifies the function that will be used to create the temporary
   CORBA servant that will satisfy an incoming request.  And a
   function that will be used to destroy the servant when the request
   processing is done. 
</para>

<para>
   The matecomponent_transient_create_objref() function takes a number of
   arguments:
</para>

<itemizedlist>
  <listitem>
    <para>
      The name of the object you want to create.  This name will be
      passed to the servant creation routine when an incoming request
      for that object comes in.  Your servant creation routine should
      be able to create a servant from the data you expose as the
      name (it can be a stringified representation of an in-process
      pointer for all that we care).
    </para>
  </listitem>

  <listitem>
    <para>
      The interface name implemented by the object named before.  This
      is the CORBA interface name that your object implements, for
      example "IDL:Echo/echo:1.0".
    </para>
  </listitem>
</itemizedlist>

<para>
   Here is an example of how to use MateComponentTransient:
   <example>
     <title>Using MateComponentTransient</title>
     <programlisting>
MateComponentTransient *my_transient = NULL;

static PortableServer_Servant
create_servant (PortableServer_POA  poa,
                MateComponentTransient    *bt,
                char               *name,
                void               *my_callback_data)
{
        MyServant *servant;

	if (!my_validate_name (name))
        	return NULL;

        servant = g_new0 (MyServant, 1);
        servant->vepv = my_servant_get_epv ();
        servant->my_data = g_strdup ("Hello world!");
        POA_My_Iface__init ((PortableServer_Servant) servant, &amp;ev);
        return servant;
}

void
destroy_servant (PortableServer_Servant servant, void *my_callback_data)
{
        CORBA_Environment ev;

        g_free (servant->my_data);
        CORBA_exception_init (&amp;ev);
        POA_My_Iface__fini (servant, &amp;ev);
        CORBA_exception_free (&amp;ev);
}

CORBA_Object
impl_Some_Iface (PortableServer_Servant servant, CORBA_Environment *ev)
{
	return matecomponent_transient_create_objref (
        	my_transient, "IDL:My/Iface:1.0",
                "hello",
                ev);
}

void
init_transient ()
{
	my_transient = matecomponent_transient_new (
		CORBA_OBJECT_NIL,
                create_servant,
                destroy_servant,
                NULL);
}


     </programlisting>
   </example>
</para>
 
<para>
   The previous example shows: how the
   <parameter>my_transient</parameter> object is first created, and what
   the implementations for the create_servant and destroy_servant look
   like.  It does not make use of the user pointer, so it passes
   NULL.  However, in practice, applications will most likely want to
   pass data here to the new_servant and destroy_servant methods.  
</para>

<para>
   The impl_Some_Iface is a method that we assume in the example will
   be part of the implementation of a CORBA server.  This method will
   be invoked at some time to get an object reference to one of the
   transient objects (in this case, we have called our object "hello"
   and it implements the interface IDL:My/Iface:1.0).
</para>


<!-- ##### SECTION ./tmpl/matecomponent-transient.sgml:See_Also ##### -->
<para>
  <classname>MateComponentPropertyBag</classname>
</para>


<!-- ##### SECTION ./tmpl/matecomponent-transient.sgml:Short_Description ##### -->
Creates a server that will handle transient objects.


<!-- ##### SECTION ./tmpl/matecomponent-transient.sgml:Title ##### -->
MateComponentTransient


<!-- ##### SECTION ./tmpl/matecomponent-ui-config-widget.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/matecomponent-ui-config-widget.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/matecomponent-ui-config-widget.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/matecomponent-ui-config-widget.sgml:Title ##### -->
matecomponent-ui-config-widget


<!-- ##### STRUCT MateComponentCanvasComponent ##### -->
<para>

</para>


<!-- ##### SIGNAL MateComponentCanvasComponent::event ##### -->
<para>

</para>

@matecomponentcanvascomponent: the object which received the signal.
@arg1: 
@Returns: 

<!-- ##### SIGNAL MateComponentCanvasComponent::set-bounds ##### -->
<para>

</para>

@matecomponentcanvascomponent: the object which received the signal.
@arg1: 
@arg2: 
@bbox: The bounding box.
@ev: CORBA Environment to return errors on.

<!-- ##### TYPEDEF MateComponentCanvasComponentClass ##### -->
<para>
  
</para>


<!-- ##### STRUCT MateComponentCanvasComponentPrivate ##### -->
<para>

</para>


<!-- ##### STRUCT MateComponentCanvasItem ##### -->
<para>

</para>


<!-- ##### TYPEDEF MateComponentCanvasItemClass ##### -->
<para>

</para>


<!-- ##### STRUCT MateComponentCanvasItemPrivate ##### -->
<para>

</para>


<!-- ##### STRUCT MateComponentClientSite ##### -->
<para>

</para>


<!-- ##### SIGNAL MateComponentClientSite::save-object ##### -->
<para>

</para>

@matecomponentclientsite: the object which received the signal.
@arg1: 

<!-- ##### SIGNAL MateComponentClientSite::show-window ##### -->
<para>

</para>

@matecomponentclientsite: the object which received the signal.
@arg1: 

<!-- ##### TYPEDEF MateComponentClientSiteClass ##### -->
<para>

</para>


<!-- ##### TYPEDEF MateComponentTransient ##### -->
<para>

</para>


<!-- ##### TYPEDEF MateComponentTransientClass ##### -->
<para>

</para>


<!-- ##### USER_FUNCTION MateComponentTransientServantDestroy ##### -->
<para>

</para>

@servant: 
@data: 

<!-- ##### USER_FUNCTION MateComponentTransientServantNew ##### -->
<para>

</para>

@Param1: 
@Param2: 
@name: 
@data: 
@Returns: 

<!-- ##### FUNCTION matecomponent_canvas_component_construct ##### -->
<para>

</para>

@comp: 
@item: 
@Returns: 
@corba_canvas_comp: 
@ccomp: 

<!-- ##### FUNCTION matecomponent_canvas_component_get_item ##### -->
<para>

</para>

@comp: 
@Returns: 

<!-- ##### FUNCTION matecomponent_canvas_component_get_ui_container ##### -->
<para>

</para>

@comp: 
@opt_ev: 
@Returns: 

<!-- ##### FUNCTION matecomponent_canvas_component_grab ##### -->
<para>

</para>

@comp: 
@mask: 
@cursor: 
@time: 
@opt_ev: 

<!-- ##### FUNCTION matecomponent_canvas_component_new ##### -->
<para>

</para>

@item: 
@Returns: 

<!-- ##### FUNCTION matecomponent_canvas_component_ungrab ##### -->
<para>

</para>

@comp: 
@time: 
@opt_ev: 

<!-- ##### FUNCTION matecomponent_canvas_item_set_bounds ##### -->
<para>

</para>

@item: 
@x1: 
@y1: 
@x2: 
@y2: 

<!-- ##### FUNCTION matecomponent_canvas_new ##### -->
<para>

</para>

@is_aa: 
@proxy: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_bind_embeddable ##### -->
<para>

</para>

@client_site: 
@object: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_construct ##### -->
<para>

</para>

@client_site: 
@container: 
@Returns: 
@corba_client_site: 

<!-- ##### FUNCTION matecomponent_client_site_free_verbs ##### -->
<para>

</para>

@verb_list: 

<!-- ##### FUNCTION matecomponent_client_site_get_container ##### -->
<para>

</para>

@client_site: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_get_embeddable ##### -->
<para>

</para>

@client_site: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_get_verbs ##### -->
<para>

</para>

@client_site: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_new ##### -->
<para>

</para>

@container: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_new_item ##### -->
<para>

</para>

@client_site: 
@uic: 
@group: 
@Returns: 

<!-- ##### FUNCTION matecomponent_client_site_new_view ##### -->
<para>

</para>

@client_site: 
@uic: 
@Returns: 
@uih: 

<!-- ##### FUNCTION matecomponent_client_site_new_view_full ##### -->
<para>

</para>

@client_site: 
@uic: 
@visible_cover: 
@active_view: 
@Returns: 
@uih: 

<!-- ##### FUNCTION matecomponent_transient_construct ##### -->
<para>

</para>

@transient: 
@poa: 
@new_servant: 
@destroy_servant: 
@data: 
@Returns: 

<!-- ##### FUNCTION matecomponent_transient_create_objref ##### -->
<para>
</para>

@transient: 
@iface_name: 
@name: 
@ev: 
@Returns: 

<!-- ##### FUNCTION matecomponent_transient_new ##### -->
<para>

</para>

@poa: 
@new_servant: 
@destroy_servant: 
@data: 
@Returns: 

