# 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 a panel.

### PANEL_APPLET_ORIENT_UP

    #define PANEL_APPLET_ORIENT_UP    GNOME_Vertigo_PANEL_ORIENT_UP

A panel at the top of the screen.

### PANEL_APPLET_ORIENT_DOWN

    #define PANEL_APPLET_ORIENT_DOWN  GNOME_Vertigo_PANEL_ORIENT_DOWN

A panel at the bottom of the screen.

### PANEL_APPLET_ORIENT_LEFT

    #define PANEL_APPLET_ORIENT_LEFT  GNOME_Vertigo_PANEL_ORIENT_LEFT

A panel at the left-hand side of the screen.

### PANEL_APPLET_ORIENT_RIGHT

    #define PANEL_APPLET_ORIENT_RIGHT GNOME_Vertigo_PANEL_ORIENT_RIGHT

A panel at the right-hand side of the screen.

### enum PanelAppletBackgroundType

    typedef enum {
    	PANEL_NO_BACKGROUND,
    	PANEL_COLOR_BACKGROUND,
    	PANEL_PIXMAP_BACKGROUND
    } PanelAppletBackgroundType;

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

`PANEL_NO_BACKGROUND` | The panel has no backround, the default is used.
`PANEL_COLOR_BACKGROUND` | The panel has a color, i.e rgb value, background.
`PANEL_PIXMAP_BACKGROUND` |

### 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;

### PanelAppletFactoryCallback ()

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

`applet` : |
`iid` : |
`user_data` : |
Returns : |

### panel_applet_new ()

    GtkWidget*  panel_applet_new                (void);

Creates a new PanelApplet.

Returns : | A GtkWidget on success, `NULL` on failure.

### panel_applet_get_orient ()

    PanelAppletOrient panel_applet_get_orient   (PanelApplet *applet);

Returns the current orientation of the panel which the applet is contained in.

`applet` : | A PanelApplet.
Returns : | a PanelAppletOrient value.

### panel_applet_get_size ()

    guint       panel_applet_get_size           (PanelApplet *applet);

Returns the current size of the panel which the applet is contained in.

`applet` : | A PanelApplet.
Returns : | a guint value.

### 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 : | a PanelAppletOrient value.

### panel_applet_get_preferences_key ()

    gchar*      panel_applet_get_preferences_key
                                                (PanelApplet *applet);

`applet` : |
Returns : |

### panel_applet_add_preferences ()

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

`applet` : |
`schema_dir` : |
`opt_error` : |

### panel_applet_get_flags ()

    PanelAppletFlags panel_applet_get_flags     (PanelApplet *applet);

`applet` : |
Returns : |

### panel_applet_set_flags ()

    void        panel_applet_set_flags          (PanelApplet *applet,
                                                 PanelAppletFlags flags);

`applet` : |
`flags` : |

### panel_applet_set_size_hints ()

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

`applet` : |
`size_hints` : |
`n_elements` : |
`base_size` : |

### panel_applet_get_control ()

    BonoboControl* panel_applet_get_control     (PanelApplet *applet);

Retrieves the BonoboControl associated with `applet`.

`applet` : | A PanelApplet.
Returns : | A BonobControl on success, `NULL` on failure.

### panel_applet_get_popup_component ()

    BonoboUIComponent* panel_applet_get_popup_component
                                                (PanelApplet *applet);

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

`applet` : | A PanelApplet.
Returns : | A BonoboUIComponent on success, or `NULL` on failure.

### 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 <link linkend="applet-writing">Applet Writing </link> 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 &applet-writing 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` : |
`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` : |
`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` : |
`name` : | The applet ID string.
`version` : | The applet version string.
`callback` : | The factory callback.
`data` : | he 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);

`iid` : |
`applet_type` : |
`poa` : |
`impl_ptr` : |
`callback` : |
`user_data` : |
`ev` : |
Returns : |

### 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);

`iid` : |
`applet_type` : |
`poa` : |
`impl_ptr` : |
`closure` : |
`ev` : |
Returns : |

### PANEL_APPLET_BONOBO_SHLIB_FACTORY()

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

`iid` : |
`type` : |
`descr` : |
`callback` : |
`data` : |

## 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.
`arg1` : |
`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.

`panelapplet` : | The object which received the signal.
`arg1` : |
`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.