Next: , Previous: GtkStatusbar, Up: Top

14 GtkStatusIcon

Display an icon in the system tray

14.1 Overview

The "system tray" or notification area is normally used for transient icons that indicate some special state. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines. The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog.

A <gtk-status-icon> object can be used to display an icon in a "system tray". The icon can have a tooltip, and the user can interact with it by activating it or popping up a context menu. Critical information should not solely be displayed in a <gtk-status-icon>, since it may not be visible (e.g. when the user doesn't have a notification area on his panel). This can be checked with gtk-status-icon-is-embedded.

On X11, the implementation follows the freedesktop.org "System Tray" specification. Implementations of the "tray" side of this specification can be found e.g. in the GNOME and KDE panel applications.

Note that a GtkStatusIcon is not a widget, but just a <gobject>. Making it a widget would be impractical, since the system tray on Win32 doesn't allow to embed arbitrary widgets.

14.2 Usage

— Class: <gtk-status-icon>

Derives from <gobject>.

This class defines the following slots:

pixbuf
A GdkPixbuf to display
file
Filename to load and display
stock
Stock ID for a stock image to display
icon-name
The name of the icon from the icon theme
storage-type
The representation being used for image data
size
The size of the icon
screen
The screen where this status icon will be displayed
visible
Whether or not the status icon is visible
orientation
The orientation of the tray
embedded
Whether or not the status icon is embedded
blinking
Whether or not the status icon is blinking
— Signal on <gtk-status-icon>: size-changed (arg0 <gint>) ⇒ <gboolean>

Gets emitted when the size available for the image changes, e.g. because the notification area got resized.

Since 2.10

— Signal on <gtk-status-icon>: popup-menu (arg0 <guint>) (arg1 <guint>)

Gets emitted when the user brings up the context menu of the status icon. Whether status icons can have context menus and how these are activated is platform-dependent.

The button and activate-timeout parameters should be passed as the last to arguments to gtk-menu-popup.

Since 2.10

— Signal on <gtk-status-icon>: activate

Gets emitted when the user activates the status icon. If and how status icons can activated is platform-dependent.

Since 2.10

— Function: gtk-status-icon-new ⇒  (ret <gtk-status-icon>)

Creates an empty status icon object.

ret
a new <gtk-status-icon>

Since 2.10

— Function: gtk-status-icon-new-from-pixbuf (pixbuf <gdk-pixbuf>) ⇒  (ret <gtk-status-icon>)

Creates a status icon displaying pixbuf.

The image will be scaled down to fit in the available space in the notification area, if necessary.

pixbuf
a <gdk-pixbuf>
ret
a new <gtk-status-icon>

Since 2.10

— Function: gtk-status-icon-new-from-file (filename mchars) ⇒  (ret <gtk-status-icon>)

Creates a status icon displaying the file filename.

The image will be scaled down to fit in the available space in the notification area, if necessary.

filename
a filename
ret
a new <gtk-status-icon>

Since 2.10

— Function: gtk-status-icon-new-from-stock (stock_id mchars) ⇒  (ret <gtk-status-icon>)

Creates a status icon displaying a stock icon. Sample stock icon names are <gtk-stock-open>, <gtk-stock-quit>. You can register your own stock icon names, see gtk-icon-factory-add-default and gtk-icon-factory-add.

stock-id
a stock icon id
ret
a new <gtk-status-icon>

Since 2.10

— Function: gtk-status-icon-new-from-icon-name (icon_name mchars) ⇒  (ret <gtk-status-icon>)

Creates a status icon displaying an icon from the current icon theme. If the current icon theme is changed, the icon will be updated appropriately.

icon-name
an icon name
ret
a new <gtk-status-icon>

Since 2.10

— Function: gtk-status-icon-set-from-pixbuf (self <gtk-status-icon>) (pixbuf <gdk-pixbuf>)
— Method: set-from-pixbuf

Makes status-icon display pixbuf. See gtk-status-icon-new-from-pixbuf for details.

status-icon
a <gtk-status-icon>
pixbuf
a <gdk-pixbuf> or ‘#f’

Since 2.10

— Function: gtk-status-icon-set-from-file (self <gtk-status-icon>) (filename mchars)
— Method: set-from-file

Makes status-icon display the file filename. See gtk-status-icon-new-from-file for details.

status-icon
a <gtk-status-icon>
filename
a filename

Since 2.10

— Function: gtk-status-icon-set-from-stock (self <gtk-status-icon>) (stock_id mchars)
— Method: set-from-stock

Makes status-icon display the stock icon with the id stock-id. See gtk-status-icon-new-from-stock for details.

status-icon
a <gtk-status-icon>
stock-id
a stock icon id

Since 2.10

— Function: gtk-status-icon-set-from-icon-name (self <gtk-status-icon>) (icon_name mchars)
— Method: set-from-icon-name

Makes status-icon display the icon named icon-name from the current icon theme. See gtk-status-icon-new-from-icon-name for details.

status-icon
a <gtk-status-icon>
icon-name
an icon name

Since 2.10

— Function: gtk-status-icon-get-storage-type (self <gtk-status-icon>) ⇒  (ret <gtk-image-type>)
— Method: get-storage-type

Gets the type of representation being used by the <gtk-status-icon> to store image data. If the <gtk-status-icon> has no image data, the return value will be ‘GTK_IMAGE_EMPTY’.

status-icon
a <gtk-status-icon>
ret
the image representation being used

Since 2.10

— Function: gtk-status-icon-get-pixbuf (self <gtk-status-icon>) ⇒  (ret <gdk-pixbuf>)
— Method: get-pixbuf

Gets the <gdk-pixbuf> being displayed by the <gtk-status-icon>. The storage type of the status icon must be ‘GTK_IMAGE_EMPTY’ or ‘GTK_IMAGE_PIXBUF’ (see gtk-status-icon-get-storage-type). The caller of this function does not own a reference to the returned pixbuf.

status-icon
a <gtk-status-icon>
ret
the displayed pixbuf, or ‘#f’ if the image is empty.

Since 2.10

— Function: gtk-status-icon-get-stock (self <gtk-status-icon>) ⇒  (ret mchars)
— Method: get-stock

Gets the id of the stock icon being displayed by the <gtk-status-icon>. The storage type of the status icon must be ‘GTK_IMAGE_EMPTY’ or ‘GTK_IMAGE_STOCK’ (see gtk-status-icon-get-storage-type). The returned string is owned by the <gtk-status-icon> and should not be freed or modified.

status-icon
a <gtk-status-icon>
ret
stock id of the displayed stock icon, or ‘#f’ if the image is empty.

Since 2.10

— Function: gtk-status-icon-get-icon-name (self <gtk-status-icon>) ⇒  (ret mchars)
— Method: get-icon-name

Gets the name of the icon being displayed by the <gtk-status-icon>. The storage type of the status icon must be ‘GTK_IMAGE_EMPTY’ or ‘GTK_IMAGE_ICON_NAME’ (see gtk-status-icon-get-storage-type). The returned string is owned by the <gtk-status-icon> and should not be freed or modified.

status-icon
a <gtk-status-icon>
ret
name of the displayed icon, or ‘#f’ if the image is empty.

Since 2.10

— Function: gtk-status-icon-get-size (self <gtk-status-icon>) ⇒  (ret int)
— Method: get-size

Gets the size in pixels that is available for the image. Stock icons and named icons adapt their size automatically if the size of the notification area changes. For other storage types, the size-changed signal can be used to react to size changes.

status-icon
a <gtk-status-icon>
ret
the size that is available for the image

Since 2.10

— Function: gtk-status-icon-set-tooltip (self <gtk-status-icon>) (tooltip_text mchars)
— Method: set-tooltip

Sets the tooltip of the status icon.

status-icon
a <gtk-status-icon>
tooltip-text
the tooltip text, or ‘#f’

Since 2.10

— Function: gtk-status-icon-set-visible (self <gtk-status-icon>) (visible bool)
— Method: set-visible

Shows or hides a status icon.

status-icon
a <gtk-status-icon>
visible
‘#t’ to show the status icon, ‘#f’ to hide it

Since 2.10

— Function: gtk-status-icon-get-visible (self <gtk-status-icon>) ⇒  (ret bool)
— Method: get-visible

Returns whether the status icon is visible or not. Note that being visible does not guarantee that the user can actually see the icon, see also gtk-status-icon-is-embedded.

status-icon
a <gtk-status-icon>
ret
‘#t’ if the status icon is visible

Since 2.10

— Function: gtk-status-icon-set-blinking (self <gtk-status-icon>) (blinking bool)
— Method: set-blinking

Makes the status icon start or stop blinking. Note that blinking user interface elements may be problematic for some users, and thus may be turned off, in which case this setting has no effect.

status-icon
a <gtk-status-icon>
blinking
‘#t’ to turn blinking on, ‘#f’ to turn it off

Since 2.10

— Function: gtk-status-icon-get-blinking (self <gtk-status-icon>) ⇒  (ret bool)
— Method: get-blinking

Returns whether the icon is blinking, see gtk-status-icon-set-blinking.

status-icon
a <gtk-status-icon>
ret
‘#t’ if the icon is blinking

Since 2.10

— Function: gtk-status-icon-is-embedded (self <gtk-status-icon>) ⇒  (ret bool)
— Method: is-embedded

Returns whether the status icon is embedded in a notification area.

status-icon
a <gtk-status-icon>
ret
‘#t’ if the status icon is embedded in a notification area.

Since 2.10