## rb-tray-icon

rb-tray-icon — Notification area icon

## Synopsis

    typedef             RBTrayIconPrivate;
    RBTrayIcon*         rb_tray_icon_new                    (GtkUIManager *mgr,
                                                             RBShell *shell);
    void                rb_tray_icon_get_geom               (RBTrayIcon *icon,
                                                             int *x,
                                                             int *y,
                                                             int *width,
                                                             int *height);
    void                rb_tray_icon_notify                 (RBTrayIcon *icon,
                                                             guint timeout,
                                                             const char *primary_markup,
                                                             GtkWidget *msgicon,
                                                             const char *secondary_markup,
                                                             gboolean requested);
    void                rb_tray_icon_cancel_notify          (RBTrayIcon *icon);
    void                rb_tray_icon_set_tooltip_primary_text
                                                            (RBTrayIcon *icon,
                                                             const char *primary_text);
    void                rb_tray_icon_set_tooltip_icon       (RBTrayIcon *icon,
                                                             GtkWidget *msgicon);
    void                rb_tray_icon_set_tooltip_secondary_markup
                                                            (RBTrayIcon *icon,
                                                             const char *secondary_markup);

## Description

The tray icon handles a few different forms of input:

- left clicking hides and shows the main window
- right clicking brings up a popup menu
- dropping files on the icon adds them to the library
- scroll events change the playback volume

The tooltip for the tray icon consists of an image, the primary text (displayed in bold large type), and the secondary text (which can contain markup).

The tooltip is shown after the mouse pointer has been within the tray icon area for half a second. This delay is only reset once the pointer has been outside the tray icon area for more than one second.

The tray icon can also display notification bubbles (using libnotify). These contain the same set of elements as the tooltip. The tooltip is suppressed while a notification bubble is being displayed. A GConf setting allows the user to disable notification bubbles.

## Details

### RBTrayIconPrivate

    typedef struct RBTrayIconPrivate RBTrayIconPrivate;

### rb_tray_icon_new ()

    RBTrayIcon*         rb_tray_icon_new                    (GtkUIManager *mgr,
                                                             RBShell *shell);

`mgr` : | the GtkUIManager
`shell` : | the RBShell
Returns : | the RBTrayIcon

### rb_tray_icon_get_geom ()

    void                rb_tray_icon_get_geom               (RBTrayIcon *icon,
                                                             int *x,
                                                             int *y,
                                                             int *width,
                                                             int *height);

Retrieves the current position and size of the tray icon.

`icon` : | the RBTrayIcon
`x` : | returns the x position of the tray icon
`y` : | returns the y position of the tray icon
`width` : | returns the width of the tray icon
`height` : | returns the height of the tray icon

### rb_tray_icon_notify ()

    void                rb_tray_icon_notify                 (RBTrayIcon *icon,
                                                             guint timeout,
                                                             const char *primary_markup,
                                                             GtkWidget *msgicon,
                                                             const char *secondary_markup,
                                                             gboolean requested);

Displays a notification bubble attached to the tray icon. If the user has disabled notifications, the notification is only displayed if `requested` is `TRUE`.

`icon` : | the RBTrayIcon
`timeout` : | how long the notification should be displayed (in milliseconds)
`primary_markup` : | primary markup to display in the notification
`msgicon` : | GtkWidget to display as the image in the notification
`secondary_markup` : | secondary markup to display in the notification
`requested` : | if `TRUE`, the notification was directly requested by the user

### rb_tray_icon_cancel_notify ()

    void                rb_tray_icon_cancel_notify          (RBTrayIcon *icon);

Cancels any existing notification bubble.

`icon` : | the RBTrayIcon

### rb_tray_icon_set_tooltip_primary_text ()

    void                rb_tray_icon_set_tooltip_primary_text
                                                            (RBTrayIcon *icon,
                                                             const char *primary_text);

Updates the tooltip's primary text and updates the tooltip's visibility. The primary text cannot contain markup. It is always displayed in bold large type.

`icon` : | the RBTrayIcon
`primary_text` : | New primary text for the tooltip

### rb_tray_icon_set_tooltip_icon ()

    void                rb_tray_icon_set_tooltip_icon       (RBTrayIcon *icon,
                                                             GtkWidget *msgicon);

Updates the icon in the tooltip.

`icon` : | the RBTrayIcon
`msgicon` : | a GtkWidget to display as the icon in the tooltip

### rb_tray_icon_set_tooltip_secondary_markup ()

    void                rb_tray_icon_set_tooltip_secondary_markup
                                                            (RBTrayIcon *icon,
                                                             const char *secondary_markup);

Updates the secondary text in the tooltip. The secondary text can contain simple markup.

`icon` : | the RBTrayIcon
`secondary_markup` : | markup text to display as the secondary text in the toolip