<!-- ##### SECTION Title ##### -->
PanelApplet

<!-- ##### SECTION Short_Description ##### -->
The PanelApplet object.

<!-- ##### SECTION Long_Description ##### -->
<para>
The #PanelApplet object is an object which encapsulates an applet. It
is a #GtkContainer which may contain a single widget. This widget, in
turn, should contain all widgets exposed by the applet.
</para>

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

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT PanelApplet ##### -->
<para>
The #PanelApplet struct contains private data only.
</para>


<!-- ##### SIGNAL PanelApplet::change-background ##### -->
<para>
Emitted when the background of the panel changes. Use @type to
determine which, if any, of @color and @pimxap is valid.
</para>

@panelapplet: The object which received the signal.
@arg1: 
@arg2: 
@arg3: 
<!-- # Unused Parameters # -->
@type: The #PanelAppletBackgroundType.
@color: The #GdkColor if @type is #PANEL_COLOR_BACKGROUND.
@pixmap: The pixmap file name if @type is #PANEL_PIXMAP_BACKGROUND

<!-- ##### SIGNAL PanelApplet::change-orient ##### -->
<para>
Emitted when the orientation of the panel changes.
</para>

@panelapplet: The object which received the signal.
@orient: The new #PanelAppletOrient of the applet.

<!-- ##### SIGNAL PanelApplet::change-size ##### -->
<para>
Emitted when the size of the panel changes.
</para>

<para>
Note: this is different for size negotiation which is handled by
size_request() and size_allocate() 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 panel_applet_get_size().
</para>

@panelapplet: The object which received the signal.
@size: The size hint of the panel.

<!-- ##### SIGNAL PanelApplet::move-focus-out-of-applet ##### -->
<para>
Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves.
</para>

@panelapplet: The object which received the signal.
@direction: The direction of focus movement.

<!-- ##### TYPEDEF PanelAppletOrient ##### -->
<para>
The #PanelAppletOrient type specifies the orientation of the applet. The
values may seem backward (e.g. %PANEL_APPLET_ORIENT_LEFT 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>


<!-- ##### MACRO PANEL_APPLET_ORIENT_UP ##### -->
<para>
The applet is orientated up (i.e. the panel is at the bottom of the screen).
</para>



<!-- ##### MACRO PANEL_APPLET_ORIENT_DOWN ##### -->
<para>
The applet is orientated down (i.e. the panel is at the top of the screen).
</para>



<!-- ##### MACRO PANEL_APPLET_ORIENT_LEFT ##### -->
<para>
The applet is orientated left (i.e. the panel is at the right hand side of the screen).
</para>



<!-- ##### MACRO PANEL_APPLET_ORIENT_RIGHT ##### -->
<para>
The applet is orientated right (i.e. the panel is at the left hand side of the screen).
</para>



<!-- ##### ENUM PanelAppletBackgroundType ##### -->
<para>
The #PanelAppletBackgroundType enumerated type specifies the type of
background of a panel.
</para>

@PANEL_NO_BACKGROUND: The panel has no background, the default is used.
@PANEL_COLOR_BACKGROUND: The panel has a color, i.e rgb value,
background.
@PANEL_PIXMAP_BACKGROUND:  The panel has either an image background
or is translucent.

<!-- ##### ENUM PanelAppletFlags ##### -->
<para>
The #PanelAppletFlags associated with the applet are boolean flags which
the panel may read in order to figure out how to handle the applet.
</para>

@PANEL_APPLET_FLAGS_NONE: No flags are to be associated with the applet.
@PANEL_APPLET_EXPAND_MAJOR: The applet should expand horizontally on an
horizontal panel and vertically on a vertical panel - e.g. the behaviour
of the Window List applet.
@PANEL_APPLET_EXPAND_MINOR: 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.
@PANEL_APPLET_HAS_HANDLE: The panel should draw a grab handle around the
applet - e.g. the Window List and Notification Area applets both set this
flag.

<!-- ##### USER_FUNCTION PanelAppletFactoryCallback ##### -->
<para>
This callback is invoked when the applet is loaded onto the panel. Typically
the callback will check that @iid matches and fill the @applet with the
widgets which make up the applet.
</para>

<para>
Prior to the callback being invoked the #PanelApplet (or an instance of the
sub-class specified by the #GType passed to the factory macros) is instantiated
and initialized.
</para>

@applet: The #PanelApplet.
@iid: The Bonobo IID of the applet requested.
@user_data: The data passed to the factory macros.
@Returns: %TRUE on success, %FALSE on failure.


<!-- ##### FUNCTION panel_applet_new ##### -->
<para>
Creates a new #PanelApplet. This function is typically not
useful as the applet is created before the #PanelAppletFactoryCallback
is invoked.
</para>

@Returns: The #PanelApplet.


<!-- ##### FUNCTION panel_applet_get_orient ##### -->
<para>
Get the current orientation of the applet.
</para>

@applet: The #PanelApplet.
@Returns: The orientation of the applet.


<!-- ##### FUNCTION panel_applet_get_size ##### -->
<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>

@applet: The #PanelApplet.
@Returns: The panel's size hint.


<!-- ##### FUNCTION panel_applet_get_background ##### -->
<para>
Returns the current background type. If the background
type is %PANEL_NO_BACKGROUND both @color and @pixmap will
be unaffected. If the background type is %PANEL_COLOR_BACKGROUND
then @color will contain the current panel background colour.
If the background type is %PANEL_PIXMAP_BACKGROUND, @pixmap will
contain a pointer to a #GdkPixmap 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 -->

@applet: A #PanelApplet.
@color: A #GdkColor to be filled in.
@pixmap: Returned #GdkPixmap.
@Returns: The background type.


<!-- ##### FUNCTION panel_applet_get_preferences_key ##### -->
<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>

@applet: The #PanelApplet.
@Returns: A GConf path.


<!-- ##### FUNCTION panel_applet_add_preferences ##### -->
<para>
Associates each schema in @schema_dir with a key in the applet's
preferences directory (i.e. the directory returned by
panel_applet_get_preferences_key()). 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 %NULL for @opt_error, this function will print
a warning message from any #GError which GConf may return.
</para>

@applet: The #PanelApplet.
@schema_dir: The GConf path where the applet's schemas are installed
e.g. /schemas/apps/my_applet
@opt_error: Optional #GError.


<!-- ##### FUNCTION panel_applet_get_flags ##### -->
<para>
Retrieve the #PanelAppletFlags associated with the applet.
</para>

@applet: The #PanelApplet.
@Returns: The #PanelAppletFlags.


<!-- ##### FUNCTION panel_applet_set_flags ##### -->
<para>
Set the #PanelAppletFlags associated with the applet. See
#PanelAppletFlags for more details on the possible uses of
these flags.
</para>

@applet: The #PanelApplet.
@flags: The #PanelAppletFlags to associate.


<!-- ##### FUNCTION panel_applet_set_size_hints ##### -->
<para>
Set a list of desired size ranges for an applet with the
#PANEL_APPLET_EXPAND_MAJOR flags set. @size_hints 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 (@base + max, @base + min) ranges.
</para>

@applet: The #PanelApplet.
@size_hints: Array of size_hints.
@n_elements: Number of elements in the array. <emphasis>
Not</emphasis> the number of pairs.
@base_size: The base size of the applet.


<!-- ##### FUNCTION panel_applet_get_locked_down ##### -->
<para>
Check if the @applet is locked down. A locked down applet should not allow any change to its configuration.
</para>

@applet: The #PanelApplet.
@Returns: %TRUE if the @applet is locked down, %FALSE otherwise.


<!-- ##### FUNCTION panel_applet_request_focus ##### -->
<para>
Set keyboard focus to @applet.
</para>

@applet: The #PanelApplet.
@timestamp: timestamp of the event triggering the window focus


<!-- ##### FUNCTION panel_applet_get_control ##### -->
<para>
Retrieves the #BonoboControl associated with @applet.
</para>

@applet: The #PanelApplet.
@Returns: A #BonoboControl.


<!-- ##### FUNCTION panel_applet_get_popup_component ##### -->
<para>
Retrieves the #BonoboUIComponent used for popup menus associated
with @applet.
</para>

@applet: The #PanelApplet.
@Returns: A #BonoboUIComponent.


<!-- ##### FUNCTION panel_applet_setup_menu ##### -->
<para>
Sets up a popup menu for @applet described by the xml
string, @xml. See <xref linkend="applet-writing" /> section
for a description of the format of the xml.
</para>

@applet: A #PanelApplet.
@xml: The xml character string describing the popup menu.
@verb_list: The list of #BonoboUIVerbs for the menu.
@user_data: The user data pointer for the menu.


<!-- ##### FUNCTION panel_applet_setup_menu_from_file ##### -->
<para>
Sets up a popup menu for @applet described by the xml
file, @file. See <xref linkend="applet-writing" /> for a description of
the format of the xml.
</para>

@applet: A #PanelApplet.
@opt_datadir: The data directory - i.e. ${prefix}/share (optional).
@file: The file's name.
@opt_app_name: The application's name (optional).
@verb_list: The list of #BonoboUIVerbs for the menu.
@user_data: The user data pointer for the menu.


<!-- ##### FUNCTION panel_applet_factory_main ##### -->
<para>
A generic 'main' routine for applets. This should not normally be
used directly because it is invoked by #PANEL_APPLET_BONOBO_FACTORY.
</para>

@iid: The bonobo-activation iid of the factory.
@applet_type: The #GType to instantiate.
@callback: The factory callback.
@data: The factory user data pointer.
@Returns: 0 on success, 1 on failure.


<!-- ##### FUNCTION panel_applet_factory_main_closure ##### -->
<para>
A generic 'main' routine for applets. This should not normally be
used directly because it is invoked by #PANEL_APPLET_BONOBO_FACTORY.
</para>

@iid: The bonobo-activation iid of the factory.
@applet_type: The #GType to instantiate.
@closure: The factory callback closure.
@Returns: 0 on success, 1 on failure.


<!-- ##### MACRO PANEL_APPLET_BONOBO_FACTORY ##### -->
<para>
Defines a 'main' routine for the applet factory.
</para>

@iid: The bonobo-activation iid of the factory.
@type: The #GType to instantiate.
@name: The applet ID string.
@version: The applet version string.
@callback: The factory callback.
@data: The factory user data pointer.


<!-- ##### FUNCTION panel_applet_shlib_factory ##### -->
<para>
A generic shared library factory routine for applets. This should not
normally be used directly as it is invoked by #PANEL_APPLET_BONOBO_SHLIB_FACTORY.
</para>

@iid: The bonobo-activation iid of the factory.
@applet_type: The #GType to instantiate.
@poa: The #PortableServer_POA passed to the shlib factory
callback.
@impl_ptr: The #gpointer passed to the shlib factory callback.
@callback: The applet factory callback.
@user_data: The factory user data pointer.
@ev: The $CORBA_Environment passed to the shlib factory callback.
@Returns: A #Bonobo_Unknown to return from the shlib factory
callback.


<!-- ##### FUNCTION panel_applet_shlib_factory_closure ##### -->
<para>
A generic shared library factory routine for applets. This should not
normally be used directly as it is invoked by #PANEL_APPLET_BONOBO_SHLIB_FACTORY.
</para>

@iid: The bonobo-activation iid of the factory.
@applet_type: The #GType to instantiate.
@poa: The #PortableServer_POA passed to the shlib factory
callback.
@impl_ptr: The #gpointer passed to the shlib factory callback.
@closure: The applet factory closure.
@ev: The $CORBA_Environment passed to the shlib factory callback.
@Returns: A #Bonobo_Unknown to return from the shlib factory
callback.


<!-- ##### MACRO PANEL_APPLET_BONOBO_SHLIB_FACTORY ##### -->
<para>
Defines a Bonobo Activation shared library plugin and associated
factory callback.
</para>

@iid: The bonobo-activation iid of the factory.
@type: The #GType to instantiate.
@descr: A description of the applet.
@callback: The factory callback.
@data: The factory user data pointer.


