<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>;
enum        <link linkend="PanelAppletFlags">PanelAppletFlags</link>;
<link linkend="gboolean">gboolean</link>    (<link linkend="PanelAppletFactoryCallback">*PanelAppletFactoryCallback</link>)   (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="panel-applet-new">panel_applet_new</link>                (void);
<link linkend="PanelAppletOrient">PanelAppletOrient</link> <link linkend="panel-applet-get-orient">panel_applet_get_orient</link>   (<link linkend="PanelApplet">PanelApplet</link> *applet);
<link linkend="guint">guint</link>       <link linkend="panel-applet-get-size">panel_applet_get_size</link>           (<link linkend="PanelApplet">PanelApplet</link> *applet);
<link linkend="PanelAppletBackgroundType">PanelAppletBackgroundType</link> <link linkend="panel-applet-get-background">panel_applet_get_background</link>
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             <link linkend="GdkColor">GdkColor</link> *color,
                                             <link linkend="GdkPixmap">GdkPixmap</link> **pixmap);
<link linkend="gchar">gchar</link>*      <link linkend="panel-applet-get-preferences-key">panel_applet_get_preferences_key</link>
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet);
void        <link linkend="panel-applet-add-preferences">panel_applet_add_preferences</link>    (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *schema_dir,
                                             <link linkend="GError">GError</link> **opt_error);
<link linkend="PanelAppletFlags">PanelAppletFlags</link> <link linkend="panel-applet-get-flags">panel_applet_get_flags</link>     (<link linkend="PanelApplet">PanelApplet</link> *applet);
void        <link linkend="panel-applet-set-flags">panel_applet_set_flags</link>          (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             <link linkend="PanelAppletFlags">PanelAppletFlags</link> flags);
void        <link linkend="panel-applet-set-size-hints">panel_applet_set_size_hints</link>     (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const int *size_hints,
                                             int n_elements,
                                             int base_size);
<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);
int         <link linkend="panel-applet-factory-main-closure">panel_applet_factory_main_closure</link>
                                            (const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="GClosure">GClosure</link> *closure);
#define     <link linkend="PANEL-APPLET-BONOBO-FACTORY-CAPS">PANEL_APPLET_BONOBO_FACTORY</link>     (iid, type, name, version, callback, data)
<link linkend="Bonobo-Unknown">Bonobo_Unknown</link> <link linkend="panel-applet-shlib-factory">panel_applet_shlib_factory</link>   (const char *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PortableServer-POA">PortableServer_POA</link> poa,
                                             <link linkend="gpointer">gpointer</link> impl_ptr,
                                             <link linkend="PanelAppletFactoryCallback">PanelAppletFactoryCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *ev);
<link linkend="Bonobo-Unknown">Bonobo_Unknown</link> <link linkend="panel-applet-shlib-factory-closure">panel_applet_shlib_factory_closure</link>
                                            (const char *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PortableServer-POA">PortableServer_POA</link> poa,
                                             <link linkend="gpointer">gpointer</link> impl_ptr,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *ev);
#define     <link linkend="PANEL-APPLET-BONOBO-SHLIB-FACTORY-CAPS">PANEL_APPLET_BONOBO_SHLIB_FACTORY</link>(iid, type, descr, 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>Implemented Interfaces</title>
<para>
PanelApplet implements <link linkend="AtkImplementorIface">AtkImplementorIface</link>.
</para>
</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);
&quot;<link linkend="PanelApplet-move-focus-out-of-applet">move-focus-out-of-applet</link>&quot;
            void        user_function      (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="GtkDirectionType">GtkDirectionType</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 the applet. The
values may seem backward (e.g. <literal>PANEL_APPLET_ORIENT_LEFT</literal> means the panel
is on the right hand side), but this is because the value is representative
of the applet's <emphasis>orientation</emphasis>, not the panel's position.
</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>
The applet is orientated up (i.e. the panel is at the bottom 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>
The applet is orientated down (i.e. the panel is at the top 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>
The applet is orientated left (i.e. the panel is at the right 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>
The applet is orientated right (i.e. the panel is at the left 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="PanelAppletBackgroundType">PanelAppletBackgroundType</link> enumerated type specifies the type of
background of a panel.
</para><variablelist role="enum">
<varlistentry>
<term><literal>PANEL_NO_BACKGROUND</literal></term>
<listitem><simpara>The panel has no background, the default is used.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>PANEL_COLOR_BACKGROUND</literal></term>
<listitem><simpara>The panel has a color, i.e rgb value,
background.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>PANEL_PIXMAP_BACKGROUND</literal></term>
<listitem><simpara> The panel has either an image background
or is translucent.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PanelAppletFlags">enum PanelAppletFlags</title>
<programlisting>typedef enum {
	PANEL_APPLET_FLAGS_NONE   = 0,
	PANEL_APPLET_EXPAND_MAJOR = 1 &lt;&lt; 0,
	PANEL_APPLET_EXPAND_MINOR = 1 &lt;&lt; 1,
	PANEL_APPLET_HAS_HANDLE   = 1 &lt;&lt; 2
} PanelAppletFlags;
</programlisting>
<para>
The <link linkend="PanelAppletFlags">PanelAppletFlags</link> associated with the applet are boolean flags which
the panel may read in order to figure out how to handle the applet.
</para><variablelist role="enum">
<varlistentry>
<term><literal>PANEL_APPLET_FLAGS_NONE</literal></term>
<listitem><simpara>No flags are to be associated with the applet.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>PANEL_APPLET_EXPAND_MAJOR</literal></term>
<listitem><simpara>The applet should expand horizontally on an
horizontal panel and vertically on a vertical panel - e.g. the behaviour
of the Window List applet.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>PANEL_APPLET_EXPAND_MINOR</literal></term>
<listitem><simpara>The applet should expand vertically on an
horizontal panel and horizontally on a vertical panel. Most applets should
set this flag in order to utilise the full panel width and allow the applet
to be Fitt's Law compliant.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>PANEL_APPLET_HAS_HANDLE</literal></term>
<listitem><simpara>The panel should draw a grab handle around the
applet - e.g. the Window List and Notification Area applets both set this
flag.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PanelAppletFactoryCallback">PanelAppletFactoryCallback ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    (*PanelAppletFactoryCallback)   (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
This callback is invoked when the applet is loaded onto the panel. Typically
the callback will check that <parameter>iid</parameter> matches and fill the <parameter>applet</parameter> with the
widgets which make up the applet.
</para>

<para>
Prior to the callback being invoked the <link linkend="PanelApplet">PanelApplet</link> (or an instance of the
sub-class specified by the <link linkend="GType">GType</link> passed to the factory macros) is instantiated
and initialized.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The Bonobo IID of the applet requested.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>The data passed to the factory macros.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> on success, <literal>FALSE</literal> on failure.


</simpara></listitem></varlistentry>
</variablelist></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>. This function is typically not
useful as the applet is created before the <link linkend="PanelAppletFactoryCallback">PanelAppletFactoryCallback</link>
is invoked.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.


</simpara></listitem></varlistentry>
</variablelist></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>
Get the current orientation of the applet.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The orientation of the applet.


</simpara></listitem></varlistentry>
</variablelist></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>
Get the current size hint for the panel. The size hint is
not useful for most applets.
</para>

<para>
Note: The return value is <emphasis>not an integer value
specifying the pixel size of the panel.</emphasis> Do not
use this value to calculate the size of the applet. Use it
only as a hint by which to decide the applet's layout.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The panel's size hint.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-background">panel_applet_get_background ()</title>
<programlisting><link linkend="PanelAppletBackgroundType">PanelAppletBackgroundType</link> panel_applet_get_background
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             <link linkend="GdkColor">GdkColor</link> *color,
                                             <link linkend="GdkPixmap">GdkPixmap</link> **pixmap);</programlisting>
<para>
Returns the current background type. If the background
type is <literal>PANEL_NO_BACKGROUND</literal> both <parameter>color</parameter> and <parameter>pixmap</parameter> will
be unaffected. If the background type is <literal>PANEL_COLOR_BACKGROUND</literal>
then <parameter>color</parameter> will contain the current panel background colour.
If the background type is <literal>PANEL_PIXMAP_BACKGROUND</literal>, <parameter>pixmap</parameter> will
contain a pointer to a <link linkend="GdkPixmap">GdkPixmap</link> which is a copy of the applet's
portion of the panel's background pixmap.
</para>

<!-- FIXME: give an example of how to use this --><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>A <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>color</parameter>&nbsp;:</term>
<listitem><simpara>A <link linkend="GdkColor">GdkColor</link> to be filled in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pixmap</parameter>&nbsp;:</term>
<listitem><simpara>Returned <link linkend="GdkPixmap">GdkPixmap</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The background type.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-preferences-key">panel_applet_get_preferences_key ()</title>
<programlisting><link linkend="gchar">gchar</link>*      panel_applet_get_preferences_key
                                            (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Returns the GConf path to the directory containing the applet's
per-instance preference keys. Using this you may construct the
full path for the applet's preference keys. See 
<xref linkend="panel-applet-Panel-Applet-GConf-Utilities"> for
more information.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>A GConf path.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-add-preferences">panel_applet_add_preferences ()</title>
<programlisting>void        panel_applet_add_preferences    (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const <link linkend="gchar">gchar</link> *schema_dir,
                                             <link linkend="GError">GError</link> **opt_error);</programlisting>
<para>
Associates each schema in <parameter>schema_dir</parameter> with a key in the applet's
preferences directory (i.e. the directory returned by
<link linkend="panel-applet-get-preferences-key">panel_applet_get_preferences_key</link>()). Each applet preference
should have an associated schema to ensure that the key has
a defined type, sane default and documentation.
</para>

<para>
If you pass <literal>NULL</literal> for <parameter>opt_error</parameter>, this function will print
a warning message from any <link linkend="GError">GError</link> which GConf may return.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>schema_dir</parameter>&nbsp;:</term>
<listitem><simpara>The GConf path where the applet's schemas are installed
e.g. /schemas/apps/my_applet
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>opt_error</parameter>&nbsp;:</term>
<listitem><simpara>Optional <link linkend="GError">GError</link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-get-flags">panel_applet_get_flags ()</title>
<programlisting><link linkend="PanelAppletFlags">PanelAppletFlags</link> panel_applet_get_flags     (<link linkend="PanelApplet">PanelApplet</link> *applet);</programlisting>
<para>
Retrieve the <link linkend="PanelAppletFlags">PanelAppletFlags</link> associated with the applet.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The <link linkend="PanelAppletFlags">PanelAppletFlags</link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-set-flags">panel_applet_set_flags ()</title>
<programlisting>void        panel_applet_set_flags          (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             <link linkend="PanelAppletFlags">PanelAppletFlags</link> flags);</programlisting>
<para>
Set the <link linkend="PanelAppletFlags">PanelAppletFlags</link> associated with the applet. See
<link linkend="PanelAppletFlags">PanelAppletFlags</link> for more details on the possible uses of
these flags.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelAppletFlags">PanelAppletFlags</link> to associate.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-set-size-hints">panel_applet_set_size_hints ()</title>
<programlisting>void        panel_applet_set_size_hints     (<link linkend="PanelApplet">PanelApplet</link> *applet,
                                             const int *size_hints,
                                             int n_elements,
                                             int base_size);</programlisting>
<para>
Set a list of desired size ranges for an applet with the
<link linkend="PANEL-APPLET-EXPAND-MAJOR-CAPS">PANEL_APPLET_EXPAND_MAJOR</link> flags set. <parameter>size_hints</parameter> is an
array of (max, min) pairs where min(i) > max(i + 1).
</para>

<para>
The panel will endeavour to allocate the applet a size
in one of the (<parameter>base</parameter> + max, <parameter>base</parameter> + min) ranges.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size_hints</parameter>&nbsp;:</term>
<listitem><simpara>Array of size_hints.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_elements</parameter>&nbsp;:</term>
<listitem><simpara>Number of elements in the array. <emphasis>
Not</emphasis> the number of pairs.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>base_size</parameter>&nbsp;:</term>
<listitem><simpara>The base size of the applet.


</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>A <link linkend="BonoboControl">BonoboControl</link>.


</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>A <link linkend="BonoboUIComponent">BonoboUIComponent</link>.


</simpara></listitem></varlistentry>
</variablelist></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 <xref linkend="applet-writing"> section
for a description of the format of the xml.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>A <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xml</parameter>&nbsp;:</term>
<listitem><simpara>The xml character string describing the popup menu.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>verb_list</parameter>&nbsp;:</term>
<listitem><simpara>The list of <link linkend="BonoboUIVerbs">BonoboUIVerbs</link> for the menu.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>The user data pointer for the menu.


</simpara></listitem></varlistentry>
</variablelist></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 <xref linkend="applet-writing"> for a description of
the format of the xml.
</para><variablelist role="params">
<varlistentry><term><parameter>applet</parameter>&nbsp;:</term>
<listitem><simpara>A <link linkend="PanelApplet">PanelApplet</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>opt_datadir</parameter>&nbsp;:</term>
<listitem><simpara>The data directory - i.e. ${prefix}/share (optional).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>file</parameter>&nbsp;:</term>
<listitem><simpara>The file's name.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>opt_app_name</parameter>&nbsp;:</term>
<listitem><simpara>The application's name (optional).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>verb_list</parameter>&nbsp;:</term>
<listitem><simpara>The list of <link linkend="BonoboUIVerbs">BonoboUIVerbs</link> for the menu.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>The user data pointer for the menu.


</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>applet_type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara>The factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>The factory user data pointer.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>0 on success, 1 on failure.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-factory-main-closure">panel_applet_factory_main_closure ()</title>
<programlisting>int         panel_applet_factory_main_closure
                                            (const <link linkend="gchar">gchar</link> *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="GClosure">GClosure</link> *closure);</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><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>applet_type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>closure</parameter>&nbsp;:</term>
<listitem><simpara>The factory callback closure.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>0 on success, 1 on failure.


</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara>The applet ID string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>version</parameter>&nbsp;:</term>
<listitem><simpara>The applet version string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara>The factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>The factory user data pointer.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-shlib-factory">panel_applet_shlib_factory ()</title>
<programlisting><link linkend="Bonobo-Unknown">Bonobo_Unknown</link> panel_applet_shlib_factory   (const char *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PortableServer-POA">PortableServer_POA</link> poa,
                                             <link linkend="gpointer">gpointer</link> impl_ptr,
                                             <link linkend="PanelAppletFactoryCallback">PanelAppletFactoryCallback</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *ev);</programlisting>
<para>
A generic shared library factory routine for applets. This should not
normally be used directly as it is invoked by <link linkend="PANEL-APPLET-BONOBO-SHLIB-FACTORY-CAPS">PANEL_APPLET_BONOBO_SHLIB_FACTORY</link>.
</para><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>applet_type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>poa</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PortableServer-POA">PortableServer_POA</link> passed to the shlib factory
callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>impl_ptr</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="gpointer">gpointer</link> passed to the shlib factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara>The applet factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>The factory user data pointer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ev</parameter>&nbsp;:</term>
<listitem><simpara>The $CORBA_Environment passed to the shlib factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>A <link linkend="Bonobo-Unknown">Bonobo_Unknown</link> to return from the shlib factory
callback.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="panel-applet-shlib-factory-closure">panel_applet_shlib_factory_closure ()</title>
<programlisting><link linkend="Bonobo-Unknown">Bonobo_Unknown</link> panel_applet_shlib_factory_closure
                                            (const char *iid,
                                             <link linkend="GType">GType</link> applet_type,
                                             <link linkend="PortableServer-POA">PortableServer_POA</link> poa,
                                             <link linkend="gpointer">gpointer</link> impl_ptr,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *ev);</programlisting>
<para>
A generic shared library factory routine for applets. This should not
normally be used directly as it is invoked by <link linkend="PANEL-APPLET-BONOBO-SHLIB-FACTORY-CAPS">PANEL_APPLET_BONOBO_SHLIB_FACTORY</link>.
</para><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>applet_type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>poa</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="PortableServer-POA">PortableServer_POA</link> passed to the shlib factory
callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>impl_ptr</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="gpointer">gpointer</link> passed to the shlib factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>closure</parameter>&nbsp;:</term>
<listitem><simpara>The applet factory closure.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ev</parameter>&nbsp;:</term>
<listitem><simpara>The $CORBA_Environment passed to the shlib factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>A <link linkend="Bonobo-Unknown">Bonobo_Unknown</link> to return from the shlib factory
callback.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PANEL-APPLET-BONOBO-SHLIB-FACTORY-CAPS">PANEL_APPLET_BONOBO_SHLIB_FACTORY()</title>
<programlisting>#define     PANEL_APPLET_BONOBO_SHLIB_FACTORY(iid, type, descr, callback, data)</programlisting>
<para>
Defines a Bonobo Activation shared library plugin and associated
factory callback.
</para><variablelist role="params">
<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
<listitem><simpara>The bonobo-activation iid of the factory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara>The <link linkend="GType">GType</link> to instantiate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>descr</parameter>&nbsp;:</term>
<listitem><simpara>A description of the applet.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara>The factory callback.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>The factory user data pointer.


</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>panelapplet</parameter>&nbsp;:</term>
<listitem><simpara>The object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>arg1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>arg2</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>arg3</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></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><variablelist role="params">
<varlistentry><term><parameter>panelapplet</parameter>&nbsp;:</term>
<listitem><simpara>The object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>orient</parameter>&nbsp;:</term>
<listitem><simpara>The new <link linkend="PanelAppletOrient">PanelAppletOrient</link> of the applet.

</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></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. See <link linkend="panel-applet-get-size">panel_applet_get_size</link>().
</para><variablelist role="params">
<varlistentry><term><parameter>panelapplet</parameter>&nbsp;:</term>
<listitem><simpara>The object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara>The size hint of the panel.

</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2><refsect2><title><anchor id="PanelApplet-move-focus-out-of-applet">The &quot;move-focus-out-of-applet&quot; signal</title>
<programlisting>void        user_function                  (<link linkend="PanelApplet">PanelApplet</link> *panelapplet,
                                            <link linkend="GtkDirectionType">GtkDirectionType</link> arg1,
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>panelapplet</parameter>&nbsp;:</term>
<listitem><simpara>the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>arg1</parameter>&nbsp;:</term>
<listitem><simpara>

</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>



</refentry>
