<refentry id="PanelApplet">
<refmeta>
<refentrytitle>PanelApplet</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANEL-APPLET Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>PanelApplet</refname><refpurpose>The PanelApplet object.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;panel-applet.h&gt;


struct      <link linkend="PanelApplet-struct">PanelApplet</link>;
typedef     <link linkend="PanelAppletOrient">PanelAppletOrient</link>;
#define     <link linkend="PANEL-APPLET-ORIENT-UP-CAPS">PANEL_APPLET_ORIENT_UP</link>
#define     <link linkend="PANEL-APPLET-ORIENT-DOWN-CAPS">PANEL_APPLET_ORIENT_DOWN</link>
#define     <link linkend="PANEL-APPLET-ORIENT-LEFT-CAPS">PANEL_APPLET_ORIENT_LEFT</link>
#define     <link linkend="PANEL-APPLET-ORIENT-RIGHT-CAPS">PANEL_APPLET_ORIENT_RIGHT</link>
enum        <link linkend="PanelAppletBackgroundType">PanelAppletBackgroundType</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="panel-applet-new">panel_applet_new</link>                (void);
<link linkend="guint">guint</link>       <link linkend="panel-applet-get-size">panel_applet_get_size</link>           (<link linkend="PanelApplet">PanelApplet</link> *applet);
<link linkend="PanelAppletOrient">PanelAppletOrient</link> <link linkend="panel-applet-get-orient">panel_applet_get_orient</link>   (<link linkend="PanelApplet">PanelApplet</link> *applet);
<link linkend="BonoboControl">BonoboControl</link>* <link linkend="panel-applet-get-control">panel_applet_get_control</link>     (<link linkend="PanelApplet">PanelApplet</link> *applet);
<link linkend="BonoboUIComponent">BonoboUIComponent</link>* <link linkend="panel-applet-get-popup-component">panel_applet_get_popup_component</link>
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet);
void        <link linkend="panel-applet-setup-menu">panel_applet_setup_menu</link>         (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *xml,
                                             const <link linkend="BonoboUIVerb">BonoboUIVerb</link> *verb_list,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="panel-applet-setup-menu-from-file">panel_applet_setup_menu_from_file</link>
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *opt_datadir,
                                             const <link linkend="gchar">gchar</link> *file,
                                             const <link linkend="gchar">gchar</link> *opt_app_name,
                                             const <link linkend="BonoboUIVerb">BonoboUIVerb</link> *verb_list,
                                             <link linkend="gpointer">gpointer</link> user_data);
int         <link linkend="panel-applet-factory-main">panel_applet_factory_main</link>       (const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PanelAppletFactoryCallback">PanelAppletFactoryCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);
#define     <link linkend="PANEL-APPLET-BONOBO-FACTORY-CAPS">PANEL_APPLET_BONOBO_FACTORY</link>     (iid, type, name, version, callback, data)

</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GObject">GObject</link>
   +----<link linkend="GtkObject">GtkObject</link>
         +----<link linkend="GtkWidget">GtkWidget</link>
               +----<link linkend="GtkContainer">GtkContainer</link>
                     +----<link linkend="GtkBin">GtkBin</link>
                           +----<link linkend="GtkEventBox">GtkEventBox</link>
                                 +----PanelApplet
</synopsis>

</refsect1>


<refsect1>
<title>Signal Prototypes</title>
<synopsis>

&quot;<link linkend="PanelApplet-change-background">change-background</link>&quot;
            void        user_function      (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="PanelAppletBackgroundType">PanelAppletBackgroundType</link> arg1,
                                            <link linkend="gpointer">gpointer</link> arg2,
                                            <link linkend="GdkPixmap">GdkPixmap</link> *arg3,
                                            <link linkend="gpointer">gpointer</link> user_data);
&quot;<link linkend="PanelApplet-change-orient">change-orient</link>&quot;
            void        user_function      (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);
&quot;<link linkend="PanelApplet-change-size">change-size</link>&quot;
            void        user_function      (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsect1>


<refsect1>
<title>Description</title>
<para>
The <link linkend="PanelApplet">PanelApplet</link> object is an object which encapsulates an applet. It
is a <link linkend="GtkContainer">GtkContainer</link> which may contain a single widget. This widget, in
turn, should contain all widgets exposed by the applet.
</para>

<para>
A <link linkend="PanelApplet">PanelApplet</link> is associated with a <link linkend="BonoboControl">BonoboControl</link>. The control makes
the cross process UI emmbedding required by applets possible.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="PanelApplet-struct">struct PanelApplet</title>
<programlisting>struct PanelApplet;</programlisting>
<para>
The <link linkend="PanelApplet">PanelApplet</link> struct contains private data only.
</para></refsect2>
<refsect2>
<title><anchor id="PanelAppletOrient">PanelAppletOrient</title>
<programlisting>typedef GNOME_Vertigo_PanelOrient PanelAppletOrient;
</programlisting>
<para>
The <link linkend="PanelAppletOrient">PanelAppletOrient</link> type specifies the orientation of a panel. 

</para></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-ORIENT-UP-CAPS">PANEL_APPLET_ORIENT_UP</title>
<programlisting>#define PANEL_APPLET_ORIENT_UP    GNOME_Vertigo_PANEL_ORIENT_UP
</programlisting>
<para>
A panel at the top of the screen.
</para></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-ORIENT-DOWN-CAPS">PANEL_APPLET_ORIENT_DOWN</title>
<programlisting>#define PANEL_APPLET_ORIENT_DOWN  GNOME_Vertigo_PANEL_ORIENT_DOWN
</programlisting>
<para>
A panel at the bottom of the screen.
</para></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-ORIENT-LEFT-CAPS">PANEL_APPLET_ORIENT_LEFT</title>
<programlisting>#define PANEL_APPLET_ORIENT_LEFT  GNOME_Vertigo_PANEL_ORIENT_LEFT
</programlisting>
<para>
A panel at the left-hand side of the screen.
</para></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-ORIENT-RIGHT-CAPS">PANEL_APPLET_ORIENT_RIGHT</title>
<programlisting>#define PANEL_APPLET_ORIENT_RIGHT GNOME_Vertigo_PANEL_ORIENT_RIGHT
</programlisting>
<para>
A panel at the right-hand side of the screen.
</para></refsect2>
<refsect2>
<title><anchor id="PanelAppletBackgroundType">enum PanelAppletBackgroundType</title>
<programlisting>typedef enum {
	PANEL_NO_BACKGROUND,
	PANEL_COLOR_BACKGROUND,
	PANEL_PIXMAP_BACKGROUND
} PanelAppletBackgroundType;
</programlisting>
<para>
The <link linkend="PanelAppletOrient">PanelAppletOrient</link> enumerated type specifies the type of background
of a panel.

</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>PANEL_NO_BACKGROUND</literal></entry>
<entry>The panel has no backround, the default is used.
</entry>
</row>
<row>
<entry><literal>PANEL_COLOR_BACKGROUND</literal></entry>
<entry>The panel has a color, i.e rgb value,
background.
</entry>
</row>
<row>
<entry><literal>PANEL_PIXMAP_BACKGROUND</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-new">panel_applet_new ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  panel_applet_new                (void);</programlisting>
<para>
Creates a new <link linkend="PanelApplet">PanelApplet</link> which exposes <parameter>widget</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GtkWidget">GtkWidget</link> on success, <literal>NULL</literal> on failure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-size">panel_applet_get_size ()</title>
<programlisting><link linkend="guint">guint</link>       panel_applet_get_size           (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Returns the current size of the panel which
the applet is contained in.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a <link linkend="guint">guint</link> value.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-orient">panel_applet_get_orient ()</title>
<programlisting><link linkend="PanelAppletOrient">PanelAppletOrient</link> panel_applet_get_orient   (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Returns the current orientation of the panel which
the applet is contained in.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a <link linkend="PanelAppletOrient">PanelAppletOrient</link> value.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-control">panel_applet_get_control ()</title>
<programlisting><link linkend="BonoboControl">BonoboControl</link>* panel_applet_get_control     (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Retrieves the <link linkend="BonoboControl">BonoboControl</link> associated with <parameter>applet</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="BonobControl">BonobControl</link> on success, <literal>NULL</literal> on failure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-popup-component">panel_applet_get_popup_component ()</title>
<programlisting><link linkend="BonoboUIComponent">BonoboUIComponent</link>* panel_applet_get_popup_component
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Retrieves the <link linkend="BonoboUIComponent">BonoboUIComponent</link> used for popup menus associated
with <parameter>applet</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="BonoboUIComponent">BonoboUIComponent</link> on success, or <literal>NULL</literal> on failure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-setup-menu">panel_applet_setup_menu ()</title>
<programlisting>void        panel_applet_setup_menu         (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *xml,
                                             const <link linkend="BonoboUIVerb">BonoboUIVerb</link> *verb_list,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Sets up a popup menu for <parameter>applet</parameter> described by the xml 
string, <parameter>xml</parameter>. See &lt;link linkend="applet-writing"&gt;Applet Writing
&lt;/link&gt; section for a description of the format of the xml.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><parameter>xml</parameter>&nbsp;:</entry>
<entry> The xml character string describing the popup menu.
</entry></row>
<row><entry align="right"><parameter>verb_list</parameter>&nbsp;:</entry>
<entry> The list of <link linkend="BonoboUIVerbs">BonoboUIVerbs</link> for the menu.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> The user data pointer for the menu.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-setup-menu-from-file">panel_applet_setup_menu_from_file ()</title>
<programlisting>void        panel_applet_setup_menu_from_file
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *opt_datadir,
                                             const <link linkend="gchar">gchar</link> *file,
                                             const <link linkend="gchar">gchar</link> *opt_app_name,
                                             const <link linkend="BonoboUIVerb">BonoboUIVerb</link> *verb_list,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Sets up a popup menu for <parameter>applet</parameter> described by the xml 
file, <parameter>file</parameter>. See &amp;applet-writing for a description of
the format of the xml.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>applet</parameter>&nbsp;:</entry>
<entry> A <link linkend="PanelApplet">PanelApplet</link>.
</entry></row>
<row><entry align="right"><parameter>opt_datadir</parameter>&nbsp;:</entry>
<entry> The data directory - i.e. ${prefix}/share (optional).
</entry></row>
<row><entry align="right"><parameter>file</parameter>&nbsp;:</entry>
<entry> The file's name.
</entry></row>
<row><entry align="right"><parameter>opt_app_name</parameter>&nbsp;:</entry>
<entry> The application's name (optional).
</entry></row>
<row><entry align="right"><parameter>verb_list</parameter>&nbsp;:</entry>
<entry> The list of <link linkend="BonoboUIVerbs">BonoboUIVerbs</link> for the menu.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> The user data pointer for the menu.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="panel-applet-factory-main">panel_applet_factory_main ()</title>
<programlisting>int         panel_applet_factory_main       (const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PanelAppletFactoryCallback">PanelAppletFactoryCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
A generic 'main' routine for applets. This should not normally be
used directly because it is invoked by <link linkend="PANEL-APPLET-BONOBO-FACTORY-CAPS">PANEL_APPLET_BONOBO_FACTORY</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iid</parameter>&nbsp;:</entry>
<entry> The bonobo-activation iid of the factory.
</entry></row>
<row><entry align="right"><parameter>applet_type</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry> The factory callback.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry> The factory user data pointer.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 0 on success, 1 on failure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-BONOBO-FACTORY-CAPS">PANEL_APPLET_BONOBO_FACTORY()</title>
<programlisting>#define     PANEL_APPLET_BONOBO_FACTORY(iid, type, name, version, callback, data)</programlisting>
<para>
Defines a 'main' routine for the applet factory.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iid</parameter>&nbsp;:</entry>
<entry>The bonobo-activation iid of the factory.
</entry></row>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>The applet ID string.
</entry></row>
<row><entry align="right"><parameter>version</parameter>&nbsp;:</entry>
<entry>The applet version string.
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>The factory callback.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>he factory user data pointer.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>

<refsect1>
<title>Signals</title>
<refsect2><title><anchor id="PanelApplet-change-background">The &quot;change-background&quot; signal</title>
<programlisting>void        user_function                  (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="PanelAppletBackgroundType">PanelAppletBackgroundType</link> arg1,
                                            <link linkend="gpointer">gpointer</link> arg2,
                                            <link linkend="GdkPixmap">GdkPixmap</link> *arg3,
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Emitted when the background of the panel changes. Use <parameter>type</parameter> to
determine which, if any, of <parameter>color</parameter> and <parameter>pimxap</parameter> is valid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>panelapplet</parameter>&nbsp;:</entry>
<entry>The object which received the signal.
</entry></row>
<row><entry align="right"><parameter>arg1</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>arg2</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>arg3</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data set when the signal handler was connected.</entry></row>
</tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="PanelApplet-change-orient">The &quot;change-orient&quot; signal</title>
<programlisting>void        user_function                  (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Emitted when the orientation of the panel changes.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>panelapplet</parameter>&nbsp;:</entry>
<entry>The object which received the signal.
</entry></row>
<row><entry align="right"><parameter>arg1</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data set when the signal handler was connected.</entry></row>
</tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="PanelApplet-change-size">The &quot;change-size&quot; signal</title>
<programlisting>void        user_function                  (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="gint">gint</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Emitted when the size of the panel changes.
</para>

<para>
Note: this is different for size negotiation which is handled by
<link linkend="size-request">size_request</link>() and <link linkend="size-allocate">size_allocate</link>() as usual. This signal should
be used to determine what font size or widget layout to use 
depending on the size of the panel.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>panelapplet</parameter>&nbsp;:</entry>
<entry>The object which received the signal.
</entry></row>
<row><entry align="right"><parameter>arg1</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data set when the signal handler was connected.</entry></row>
</tbody></tgroup></informaltable></refsect2>
</refsect1>



</refentry>
