Panel Applet Writer's Reference Manual
<<< Previous Page | Home | Up |

# 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;
    GtkWidget*  panel_applet_new                (void);
    guint       panel_applet_get_size           (PanelApplet *applet);
    PanelAppletOrient panel_applet_get_orient   (PanelApplet *applet);
    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);
    #define     PANEL_APPLET_BONOBO_FACTORY     (iid, type, name, version, callback, data)

## Object Hierarchy

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

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

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

### panel_applet_new ()

    GtkWidget*  panel_applet_new                (void);

Creates a new PanelApplet which exposes `widget`.

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

### 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_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_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_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.

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

<<< Previous Page | Home | Up |
The Panel Applet Library |