The GNOME Panel Libraries
<<< Previous Page | Home | Up | Next Page >>>

# Panel Interaction

## Name

Panel Interaction -- Functions to interact with the panel

## Synopsis

    #include <applet-widget.h>

    void        applet_widget_add               (AppletWidget *applet,
                                                 GtkWidget *widget);
    void        applet_widget_add_full          (AppletWidget *applet,
                                                 GtkWidget *widget,
                                                 gboolean bind_events);
    void        applet_widget_abort_load        (AppletWidget *applet);
    void        applet_widget_remove            (AppletWidget *applet);
    void        applet_widget_bind_events       (AppletWidget *applet,
                                                 GtkWidget *widget);
    void        applet_widget_set_tooltip       (AppletWidget *applet,
                                                 const char *text);
    void        applet_widget_set_widget_tooltip
                                                (AppletWidget *applet,
                                                 GtkWidget *widget,
                                                 const char *text);
    enum        GNOME_Panel_OrientType;
    typedef     PanelOrientType;
    PanelOrientType applet_widget_get_panel_orient
                                                (AppletWidget *applet);
    int         applet_widget_get_panel_pixel_size
                                                (AppletWidget *applet);
    int         applet_widget_get_free_space    (AppletWidget *applet);
    void        applet_widget_send_position     (AppletWidget *applet,
                                                 gboolean enable);
    void        applet_widget_send_draw         (AppletWidget *applet,
                                                 gboolean enable);
    void        applet_widget_get_rgb_bg        (AppletWidget *applet,
                                                 guchar **rgb,
                                                 int *w,
                                                 int *h,
                                                 int *rowstride);

## Description

## Details

### applet_widget_add ()

    void        applet_widget_add               (AppletWidget *applet,
                                                 GtkWidget *widget);

Add a child (`widget`) to the `applet`. This finishes the handshaking with the panel started in `applet_widget_new`. You should never call this function twice for the same `applet` and you should always use this function rather then gtk_container_add. If you have already created an applet widget with applet_widget_new, but need to cancel the loading of the applet, use applet_widget_abort_load.

`applet` : | the AppletWidget to work with
`widget` : | the child to add

### applet_widget_add_full ()

    void        applet_widget_add_full          (AppletWidget *applet,
                                                 GtkWidget *widget,
                                                 gboolean bind_events);

Add a child (`widget`) to the `applet`. This finishes the handshaking with the panel started in `applet_widget_new`. You should never call this function twice for the same `applet` and you should always use this function rather then gtk_container_add. If you have already created an applet widget with applet_widget_new, but need to cancel the loading of the applet, use applet_widget_abort_load. This function is only for special applets and you should use applet_widget_bind_events on some internal widget if `bind_events` was `FALSE`. Normally you'll just want to use applet_widget_add.

`applet` : | the AppletWidget to work with
`widget` : | the child to add
`bind_events` : | bind 2nd and 3rd button events over the applet if `TRUE`

### applet_widget_abort_load ()

    void        applet_widget_abort_load        (AppletWidget *applet);

Abort the applet loading, once applet has been created, this is a way to tell the panel to forget about us if we decide we want to quit before we add the actual applet to the applet-widget. This is only useful to abort after applet_widget_new was called but before applet_widget_add is called.

`applet` : | AppletWidget to work on.

### applet_widget_remove ()

    void        applet_widget_remove            (AppletWidget *applet);

Remove the plug from the panel, this will destroy the applet. You can only call this once for each applet.

`applet` : | AppletWidget to work on.

### applet_widget_bind_events ()

    void        applet_widget_bind_events       (AppletWidget *applet,
                                                 GtkWidget *widget);

Binds the 2nd and 3rd button clicks over this widget. Normally this is done during applet_widget_add, but if you need to bind events over a widget which you added later, use this function.

`applet` : | the AppletWidget to work with
`widget` : | the widget over which to bind events

### applet_widget_set_tooltip ()

    void        applet_widget_set_tooltip       (AppletWidget *applet,
                                                 const char *text);

Set a tooltip on the entire applet that will follow the tooltip setting from the panel configuration.

`applet` : | the AppletWidget to work with
`text` : | the tooltip text

### applet_widget_set_widget_tooltip ()

    void        applet_widget_set_widget_tooltip
                                                (AppletWidget *applet,
                                                 GtkWidget *widget,
                                                 const char *text);

Set a tooltip on the `widget` that will follow the tooltip setting from the panel configuration.

`applet` : | the AppletWidget to work with
`widget` : | the widget to set tooltip on
`text` : | the tooltip text

### enum GNOME_Panel_OrientType

       typedef enum
       {
          GNOME_Panel_ORIENT_UP,
          GNOME_Panel_ORIENT_DOWN,
          GNOME_Panel_ORIENT_LEFT,
          GNOME_Panel_ORIENT_RIGHT
       }
       GNOME_Panel_OrientType;

### PanelOrientType

    typedef GNOME_Panel_OrientType PanelOrientType;

### applet_widget_get_panel_orient ()

    PanelOrientType applet_widget_get_panel_orient
                                                (AppletWidget *applet);

Gets the orientation of the panel this widget is on. it can be one of ORIENT_UP, ORIENT_DOWN, ORIENT_LEFT and ORIENT_RIGHT. This is not the position of the panel, but rather the direction that the applet should be "reaching out". So any arrows should for example point in this direction. It will be ORIENT_UP or ORIENT_DOWN for horizontal panels and ORIENT_LEFT or ORIENT_RIGHT for vertical panels

`applet` : | the AppletWidget to work with
Returns : | PanelOrientType enum of the orientation

### applet_widget_get_panel_pixel_size ()

    int         applet_widget_get_panel_pixel_size
                                                (AppletWidget *applet);

Gets the width of the panel in pixels. This is not the actual size, but the recomended one. The panel may be streched if the applets use larger sizes then this.

`applet` : | the AppletWidget to work with
Returns : | Size of panel in pixels

### applet_widget_get_free_space ()

    int         applet_widget_get_free_space    (AppletWidget *applet);

Gets the free space left that you can use for your applet. This is the number of pixels around your applet to both sides. If you strech by this amount you will not disturb any other applets. If you are on a packed panel 0 will be returned.

`applet` : | the AppletWidget to work with
Returns : | Free space left for your applet.

### applet_widget_send_position ()

    void        applet_widget_send_position     (AppletWidget *applet,
                                                 gboolean enable);

If you need to get a signal everytime this applet changes position relative to the screen, you need to run this function with `TRUE` for `enable` and bind the change_position signal on the applet. This signal can be quite CPU/bandwidth consuming so only applets which need it should use it. By default change_position is not sent.

`applet` : | the AppletWidget to work with
`enable` : | whether to enable or disable change_position signal

### applet_widget_send_draw ()

    void        applet_widget_send_draw         (AppletWidget *applet,
                                                 gboolean enable);

If you are using rgb background drawing, call this function with `TRUE` for `enable`, and then bind the do_draw signal. Inside that signal you can get an RGB buffer to draw on with applet_widget_get_rgb_bg. The do_draw signal will only be sent when the RGB truly changed.

`applet` : | the AppletWidget to work with
`enable` : | whether to enable or disable do_draw signal

### applet_widget_get_rgb_bg ()

    void        applet_widget_get_rgb_bg        (AppletWidget *applet,
                                                 guchar **rgb,
                                                 int *w,
                                                 int *h,
                                                 int *rowstride);

Gets an rgb buffer that you can draw your applet on. Useful in conjunction with the do_draw signal and the applet_widget_send_draw method. The rgb should be freed after use with g_free.

`applet` : | the AppletWidget to work with
`rgb` : | pointer to a pointer to which the rgb buffer will be returned
`w` : | pointer to an integer in which the width will be stored
`h` : | pointer to an integer in which the height will be stored
`rowstride` : | pointer to an integer in which the rowstride will be stored

<<< Previous Page | Home | Up | Next Page >>>
AppletWidget | Context Menu