# PanelApplet

## Name

PanelApplet -- The PanelApplet object.

## Synopsis

    #include <panel-applet.h>

    struct      PanelApplet;
    typedef     PanelAppletOrient;
    #define     PANEL_APPLET_ORIENT_UP
    #define     PANEL_APPLET_ORIENT_DOWN
    #define     PANEL_APPLET_ORIENT_LEFT
    #define     PANEL_APPLET_ORIENT_RIGHT
    enum        PanelAppletBackgroundType;
    enum        PanelAppletFlags;
    gboolean    (*PanelAppletFactoryCallback)   (PanelApplet *applet,
                                                 const gchar *iid,
                                                 gpointer user_data);
    GtkWidget*  panel_applet_new                (void);
    PanelAppletOrient panel_applet_get_orient   (PanelApplet *applet);
    guint       panel_applet_get_size           (PanelApplet *applet);
    PanelAppletBackgroundType panel_applet_get_background
                                                (PanelApplet *applet,
                                                 GdkColor *color,
                                                 GdkPixmap **pixmap);
    gchar*      panel_applet_get_preferences_key
                                                (PanelApplet *applet);
    void        panel_applet_add_preferences    (PanelApplet *applet,
                                                 const gchar *schema_dir,
                                                 GError **opt_error);
    PanelAppletFlags panel_applet_get_flags     (PanelApplet *applet);
    void        panel_applet_set_flags          (PanelApplet *applet,
                                                 PanelAppletFlags flags);
    void        panel_applet_set_size_hints     (PanelApplet *applet,
                                                 const int *size_hints,
                                                 int n_elements,
                                                 int base_size);
    BonoboControl* panel_applet_get_control     (PanelApplet *applet);
    BonoboUIComponent* panel_applet_get_popup_component
                                                (PanelApplet *applet);
    void        panel_applet_setup_menu         (PanelApplet *applet,
                                                 const gchar *xml,
                                                 const BonoboUIVerb *verb_list,
                                                 gpointer user_data);
    void        panel_applet_setup_menu_from_file
                                                (PanelApplet *applet,
                                                 const gchar *opt_datadir,
                                                 const gchar *file,
                                                 const gchar *opt_app_name,
                                                 const BonoboUIVerb *verb_list,
                                                 gpointer user_data);
    int         panel_applet_factory_main       (const gchar *iid,
                                                 GType applet_type,
                                                 PanelAppletFactoryCallback callback,
                                                 gpointer data);
    int         panel_applet_factory_main_closure
                                                (const gchar *iid,
                                                 GType applet_type,
                                                 GClosure *closure);
    #define     PANEL_APPLET_BONOBO_FACTORY     (iid, type, name, version, callback, data)
    Bonobo_Unknown panel_applet_shlib_factory   (const char *iid,
                                                 GType applet_type,
                                                 PortableServer_POA poa,
                                                 gpointer impl_ptr,
                                                 PanelAppletFactoryCallback callback,
                                                 gpointer user_data,
                                                 CORBA_Environment *ev);
    Bonobo_Unknown panel_applet_shlib_factory_closure
                                                (const char *iid,
                                                 GType applet_type,
                                                 PortableServer_POA poa,
                                                 gpointer impl_ptr,
                                                 GClosure *closure,
                                                 CORBA_Environment *ev);
    #define     PANEL_APPLET_BONOBO_SHLIB_FACTORY(iid, type, descr, callback, data)

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkEventBox
                                     +----PanelApplet

## Implemented Interfaces

PanelApplet implements AtkImplementorIface.

## Signal Prototypes

    "change-background"
                void        user_function      (PanelApplet *panelapplet,
                                                PanelAppletBackgroundType arg1,
                                                gpointer arg2,
                                                GdkPixmap *arg3,
                                                gpointer user_data);
    "change-orient"
                void        user_function      (PanelApplet *panelapplet,
                                                gint arg1,
                                                gpointer user_data);
    "change-size"
                void        user_function      (PanelApplet *panelapplet,
                                                gint arg1,
                                                gpointer user_data);
    "move-focus-out-of-applet"
                void        user_function      (PanelApplet *panelapplet,
                                                GtkDirectionType arg1,
                                                gpointer user_data);

## Description

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.

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

## Details

### struct PanelApplet

    struct PanelApplet;

The PanelApplet struct contains private data only.

### PanelAppletOrient

    typedef GNOME_Vertigo_PanelOrient PanelAppletOrient;

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 orientation, not the panel's position.

### PANEL_APPLET_ORIENT_UP

    #define PANEL_APPLET_ORIENT_UP    GNOME_Vertigo_PANEL_ORIENT_UP

The applet is orientated up (i.e. the panel is at the bottom of the screen).

### PANEL_APPLET_ORIENT_DOWN

    #define PANEL_APPLET_ORIENT_DOWN  GNOME_Vertigo_PANEL_ORIENT_DOWN

The applet is orientated down (i.e. the panel is at the top of the screen).

### PANEL_APPLET_ORIENT_LEFT

    #define PANEL_APPLET_ORIENT_LEFT  GNOME_Vertigo_PANEL_ORIENT_LEFT

The applet is orientated left (i.e. the panel is at the right hand side of the screen).

### PANEL_APPLET_ORIENT_RIGHT

    #define PANEL_APPLET_ORIENT_RIGHT GNOME_Vertigo_PANEL_ORIENT_RIGHT

The applet is orientated right (i.e. the panel is at the left hand side of the screen).

### enum PanelAppletBackgroundType

    typedef enum {
    	PANEL_NO_BACKGROUND,
    	PANEL_COLOR_BACKGROUND,
    	PANEL_PIXMAP_BACKGROUND
    } PanelAppletBackgroundType;

The PanelAppletBackgroundType enumerated type specifies the type of background of a panel.

`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

    typedef enum {
    	PANEL_APPLET_FLAGS_NONE   = 0,
    	PANEL_APPLET_EXPAND_MAJOR = 1 << 0,
    	PANEL_APPLET_EXPAND_MINOR = 1 << 1,
    	PANEL_APPLET_HAS_HANDLE   = 1 << 2
    } PanelAppletFlags;

The PanelAppletFlags associated with the applet are boolean flags which the panel may read in order to figure out how to handle the applet.

`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.

### PanelAppletFactoryCallback ()

    gboolean    (*PanelAppletFactoryCallback)   (PanelApplet *applet,
                                                 const gchar *iid,
                                                 gpointer user_data);

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.

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.

`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.

### panel_applet_new ()

    GtkWidget*  panel_applet_new                (void);

Creates a new PanelApplet. This function is typically not useful as the applet is created before the PanelAppletFactoryCallback is invoked.

Returns : | The PanelApplet.

### panel_applet_get_orient ()

    PanelAppletOrient panel_applet_get_orient   (PanelApplet *applet);

Get the current orientation of the applet.

`applet` : | The PanelApplet.
Returns : | The orientation of the applet.

### panel_applet_get_size ()

    guint       panel_applet_get_size           (PanelApplet *applet);

Get the current size hint for the panel. The size hint is not useful for most applets.

Note: The return value is not an integer value specifying the pixel size of the panel. 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.

`applet` : | The PanelApplet.
Returns : | The panel's size hint.

### panel_applet_get_background ()

    PanelAppletBackgroundType panel_applet_get_background
                                                (PanelApplet *applet,
                                                 GdkColor *color,
                                                 GdkPixmap **pixmap);

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.

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

### panel_applet_get_preferences_key ()

    gchar*      panel_applet_get_preferences_key
                                                (PanelApplet *applet);

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 Panel Applet GConf Utilities(3) for more information.

`applet` : | The PanelApplet.
Returns : | A GConf path.

### panel_applet_add_preferences ()

    void        panel_applet_add_preferences    (PanelApplet *applet,
                                                 const gchar *schema_dir,
                                                 GError **opt_error);

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.

If you pass `NULL` for `opt_error`, this function will print a warning message from any GError which GConf may return.

`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.

### panel_applet_get_flags ()

    PanelAppletFlags panel_applet_get_flags     (PanelApplet *applet);

Retrieve the PanelAppletFlags associated with the applet.

`applet` : | The PanelApplet.
Returns : | The PanelAppletFlags.

### panel_applet_set_flags ()

    void        panel_applet_set_flags          (PanelApplet *applet,
                                                 PanelAppletFlags flags);

Set the PanelAppletFlags associated with the applet. See PanelAppletFlags for more details on the possible uses of these flags.

`applet` : | The PanelApplet.
`flags` : | The PanelAppletFlags to associate.

### panel_applet_set_size_hints ()

    void        panel_applet_set_size_hints     (PanelApplet *applet,
                                                 const int *size_hints,
                                                 int n_elements,
                                                 int base_size);

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).

The panel will endeavour to allocate the applet a size in one of the (`base` + max, `base` + min) ranges.

`applet` : | The PanelApplet.
`size_hints` : | Array of size_hints.
`n_elements` : | Number of elements in the array. Not the number of pairs.
`base_size` : | The base size of the applet.

### panel_applet_get_control ()

    BonoboControl* panel_applet_get_control     (PanelApplet *applet);

Retrieves the BonoboControl associated with `applet`.

`applet` : | The PanelApplet.
Returns : | A BonoboControl.

### panel_applet_get_popup_component ()

    BonoboUIComponent* panel_applet_get_popup_component
                                                (PanelApplet *applet);

Retrieves the BonoboUIComponent used for popup menus associated with `applet`.

`applet` : | The PanelApplet.
Returns : | A BonoboUIComponent.

### panel_applet_setup_menu ()

    void        panel_applet_setup_menu         (PanelApplet *applet,
                                                 const gchar *xml,
                                                 const BonoboUIVerb *verb_list,
                                                 gpointer user_data);

Sets up a popup menu for `applet` described by the xml string, `xml`. See the chapter called Writing Applets section for a description of the format of the xml.

`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.

### panel_applet_setup_menu_from_file ()

    void        panel_applet_setup_menu_from_file
                                                (PanelApplet *applet,
                                                 const gchar *opt_datadir,
                                                 const gchar *file,
                                                 const gchar *opt_app_name,
                                                 const BonoboUIVerb *verb_list,
                                                 gpointer user_data);

Sets up a popup menu for `applet` described by the xml file, `file`. See the chapter called Writing Applets for a description of the format of the xml.

`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.

### panel_applet_factory_main ()

    int         panel_applet_factory_main       (const gchar *iid,
                                                 GType applet_type,
                                                 PanelAppletFactoryCallback callback,
                                                 gpointer data);

A generic 'main' routine for applets. This should not normally be used directly because it is invoked by PANEL_APPLET_BONOBO_FACTORY.

`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.

### panel_applet_factory_main_closure ()

    int         panel_applet_factory_main_closure
                                                (const gchar *iid,
                                                 GType applet_type,
                                                 GClosure *closure);

A generic 'main' routine for applets. This should not normally be used directly because it is invoked by PANEL_APPLET_BONOBO_FACTORY.

`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.

### PANEL_APPLET_BONOBO_FACTORY()

    #define     PANEL_APPLET_BONOBO_FACTORY(iid, type, name, version, callback, data)

Defines a 'main' routine for the applet factory.

`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.

### panel_applet_shlib_factory ()

    Bonobo_Unknown panel_applet_shlib_factory   (const char *iid,
                                                 GType applet_type,
                                                 PortableServer_POA poa,
                                                 gpointer impl_ptr,
                                                 PanelAppletFactoryCallback callback,
                                                 gpointer user_data,
                                                 CORBA_Environment *ev);

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.

`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.

### panel_applet_shlib_factory_closure ()

    Bonobo_Unknown panel_applet_shlib_factory_closure
                                                (const char *iid,
                                                 GType applet_type,
                                                 PortableServer_POA poa,
                                                 gpointer impl_ptr,
                                                 GClosure *closure,
                                                 CORBA_Environment *ev);

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.

`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.

### PANEL_APPLET_BONOBO_SHLIB_FACTORY()

    #define     PANEL_APPLET_BONOBO_SHLIB_FACTORY(iid, type, descr, callback, data)

Defines a Bonobo Activation shared library plugin and associated factory callback.

`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.

## Signals

### The "change-background" signal

    void        user_function                  (PanelApplet *panelapplet,
                                                PanelAppletBackgroundType arg1,
                                                gpointer arg2,
                                                GdkPixmap *arg3,
                                                gpointer user_data);

Emitted when the background of the panel changes. Use `type` to determine which, if any, of `color` and `pimxap` is valid.

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

### The "change-orient" signal

    void        user_function                  (PanelApplet *panelapplet,
                                                gint arg1,
                                                gpointer user_data);

Emitted when the orientation of the panel changes.

`panelapplet` : | The object which received the signal.
`orient` : | The new PanelAppletOrient of the applet.
`user_data` : | user data set when the signal handler was connected.

### The "change-size" signal

    void        user_function                  (PanelApplet *panelapplet,
                                                gint arg1,
                                                gpointer user_data);

Emitted when the size of the panel changes.

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().

`panelapplet` : | The object which received the signal.
`size` : | The size hint of the panel.
`user_data` : | user data set when the signal handler was connected.

### The "move-focus-out-of-applet" signal

    void        user_function                  (PanelApplet *panelapplet,
                                                GtkDirectionType arg1,
                                                gpointer user_data);

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