gtk.StatusIcon
Prev | The gtk Class Reference | Next

## gtk.StatusIcon

gtk.StatusIcon — display an icon in the system tray (new in PyGTK 2.10)

## Synopsis

    class gtk.StatusIcon(gobject.GObject):
        gtk.StatusIcon()
        def get_storage_type()
        def get_gicon()
        def get_pixbuf()
        def get_stock()
        def get_icon_name()
        def get_size()
        def get_x11_window_id()
        def set_tooltip(tooltip_text)
        def set_visible(visible)
        def get_visible()
        def set_blinking(blinking)
        def get_blinking()
        def is_embedded()
        def get_geometry(screen, area, orientation)
        def get_screen()
        def set_screen(screen)
        def set_from_pixbuf(pixbuf)
        def set_from_file(filename)
        def set_from_stock(stock_id)
        def set_from_icon_name(icon_name)
        def set_from_gicon(gicon)

    Functions

        def gtk.status_icon_new_from_pixbuf(pixbuf)
        def gtk.status_icon_new_from_file(filename)
        def gtk.status_icon_new_from_gicon(filename)
        def gtk.status_icon_new_from_stock(stock_id)
        def gtk.status_icon_new_from_icon_name(icon_name)
        def gtk.status_icon_position_menu(menu, statusicon)

## Ancestry

    +-- gobject.GObject
      +-- gtk.StatusIcon

## gtk.StatusIcon Properties

"blinking" | Read-Write | if `True` the status icon is blinking. Default value: `False`.
"embedded" | Read-Write | `True` if the status icon is embedded in a notification area. Default value: `False`. This property is available in GTK+ 2.12 and above.
"file" | Write | Filename to load and display. Default value: `None`.
"gicon" | Read-Write | The GIcon displayed in the GtkStatusIcon. For themed icons, the image will be updated automatically if the theme changes.
"icon-name" | Read-Write | The name of the icon from the icon theme. Default value: `None`.
"orientation" | Read-Write | The orientation of the tray in which the statusicon is embedded. Default value: gtk.ORIENTATION_HORIZONTAL. This property is available in GTK+ 2.12 and above.
"pixbuf" | Read-Write | A `gtk.gdk.Pixbuf` to display.
"size" | Read | The size of the icon. Default value: 0.
"stock" | Read-Write | Stock ID for a stock image to display. Default value: `None`.
"storage-type" | Read | The representation being used for image data. Default value: `gtk.IMAGE_EMPTY`.
"visible" | Read-Write | If `True` the status icon is visible. Default value: `True`.

## gtk.StatusIcon Signal Prototypes

gobject.GObject Signal Prototypes

"activate" | `def callback(`status_icon`, `user_param1`, `...`)`
"popup-menu" | `def callback(`status_icon`, `button`, `activate_time`, `user_param1`, `...`)`
"size-changed" | `def callback(`status_icon`, `size`, `user_param1`, `...`)`

## Description

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.StatusIcon` 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.StatusIcon`, 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 the `gtk.StatusIcon.is_embedded()` method.

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 `gtk.StatusIcon` is not a widget, but just a `gobject.GObject`. Making it a widget would be impractical, since the system tray on Win32 doesn't allow to embed arbitrary widgets.

## Constructor

### gtk.StatusIcon

        gtk.StatusIcon()

Returns : | a new `gtk.StatusIcon`

### Note

This constructor is available in PyGTK 2.10 and above.

Creates an empty status icon object.

## Methods

### gtk.StatusIcon.set_from_pixbuf

        def set_from_pixbuf(pixbuf)

`pixbuf` : | a `gtk.gdk.Pixbuf` or `None`

### Note

This method is available in PyGTK 2.10 and above.

Makes `status_icon` display `pixbuf`. See the `gtk.status_icon_new_from_pixbuf`() function for details.

### gtk.StatusIcon.set_from_file

        def set_from_file(filename)

`filename` : | a filename

### Note

This method is available in PyGTK 2.10 and above.

Makes `status_icon` display the file `filename`. See the `gtk.status_icon_new_from_file`() function for details.

### gtk.StatusIcon.set_from_stock

        def set_from_stock(stock_id)

`stock_id` : | a stock icon id

### Note

This method is available in PyGTK 2.10 and above.

Makes `status_icon` display the stock icon with the id `stock_id`. See the `gtk.status_icon_new_from_stock`() function for details.

### gtk.StatusIcon.set_from_icon_name

        def set_from_icon_name(icon_name)

`icon_name` : | an icon name

### Note

This method is available in PyGTK 2.10 and above.

Makes `status_icon` display the icon named `icon_name` from the current icon theme. See the `gtk.status_icon_new_from_icon_name`() function for details.

### gtk.StatusIcon.set_from_gicon

        def set_from_gicon(gicon)

`gicon` : | a gio.Icon()

### Note

This method is available in PyGTK 2.14 and above.

Makes `status_icon` display the `gio.Icon()` See `gtk.status_icon_new_from_gicon`() for details

### gtk.StatusIcon.get_storage_type

        def get_storage_type()

Returns : | the image representation being used - one of the GTK Image Type Constants.

### Note

This method is available in PyGTK 2.10 and above.

Gets the type of representation being used by the `gtk.StatusIcon` to store image data. If the `gtk.StatusIcon` has no image data, the return value will be `gtk.IMAGE_EMPTY`.

### gtk.StatusIcon.get_gicon

        def get_gicon()

Returns : | the displayed icon, or `None` if the image is empty.

### Note

This method is available in PyGTK 2.14 and above.

Retrieves the gio.Icon() being displayed by the `gtk.StatusIcon`. The storage type of the status icon must be gtk.IMAGE_EMPTY or gtk.IMAGE_GICON. If this method fails, icon is left unchanged;

### gtk.StatusIcon.get_x11_window_id

        def get_x11_window_id()

Returns : | An 32 bit unsigned integer identifier for the underlying X11 Window.

### Note

This method is available in PyGTK 2.14 and above.

This function is only useful on the X11/freedesktop.org platform. It returns a window ID for the widget in the underlying status icon implementation. This is useful for the Galago notification service, which can send a window ID in the protocol in order for the server to position notification windows pointing to a status icon reliably.

This function is not intended for other use cases which are more likely to be met by one of the non-X11 specific methods, such as `gtk.status_icon_position_menu`().

### gtk.StatusIcon.get_pixbuf

        def get_pixbuf()

Returns : | the displayed pixbuf, or `None` if the image is empty.

### Note

This method is available in PyGTK 2.10 and above.

Gets the `gtk.gdk.Pixbuf` being displayed by the `gtk.StatusIcon`. The storage type of the status icon must be `gtk.IMAGE_EMPTY` or `gtk.IMAGE_PIXBUF` (see the `gtk.StatusIcon.get_storage_type()` method).

### gtk.StatusIcon.get_stock

        def get_stock()

Returns : | stock id of the displayed stock icon, or `None` if the image is empty.

### Note

This method is available in PyGTK 2.10 and above.

Gets the id of the stock icon being displayed by the `gtk.StatusIcon`. The storage type of the status icon must be `gtk.IMAGE_EMPTY` or `gtk.IMAGE_STOCK` (see the `gtk.StatusIcon.get_storage_type()` method).

### gtk.StatusIcon.get_icon_name

        def get_icon_name()

Returns : | name of the displayed icon, or `None` if the image is empty.

### Note

This method is available in PyGTK 2.10 and above.

Gets the name of the icon being displayed by the `gtk.StatusIcon`. The storage type of the status icon must be `gtk.IMAGE_EMPTY` or `gtk.IMAGE_ICON_NAME` (see the `gtk.StatusIcon.get_storage_type()` method).

### gtk.StatusIcon.get_size

        def get_size()

Returns : | the size that is available for the image

### Note

This method is available in PyGTK 2.10 and above.

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.

### gtk.StatusIcon.set_tooltip

        def set_tooltip(tooltip_text)

`tooltip_text` : | the tooltip text, or `None`

### Note

This method is available in PyGTK 2.10 and above.

Sets the tooltip of the status icon.

### gtk.StatusIcon.set_visible

        def set_visible(visible)

`visible` : | if `True` show the status icon, if `False` hide it

### Note

This method is available in PyGTK 2.10 and above.

Shows or hides a status icon.

### gtk.StatusIcon.get_visible

        def get_visible()

Returns : | `True` if the status icon is visible

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if the status icon is visible. Note that being visible does not guarantee that the user can actually see the icon, see also the `gtk.StatusIcon.is_embedded()` method.

### gtk.StatusIcon.set_blinking

        def set_blinking(blinking)

`blinking` : | if `True` turn blinking on, if `False` turn it off

### Note

This method is available in PyGTK 2.10 and above.

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.

### gtk.StatusIcon.get_blinking

        def get_blinking()

Returns : | `True` if the icon is blinking

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if the icon is blinking, see the `gtk.StatusIcon.set_blinking()` method.

### gtk.StatusIcon.is_embedded

        def is_embedded()

Returns : | `True` if the status icon is embedded in a notification area.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if the status icon is embedded in a notification area.

### gtk.StatusIcon.get_geometry

        def get_geometry()

Returns : | a 3-tuple (containing the screen, area occupied by the status icon and the panel orientation) or None.

### Note

This method is available in PyGTK 2.10 and above.

Returns information in a 3-tuple about the location of the status icon on screen. The 3-tuple contains the `gtk.gdk.Screen`, the area occupied by the status icon as a `gtk.gdk.Rectangle` and the orientation of the panel containing the statis icon - one of the GTK Orientation Constants. This information can be used to e.g. position popups like notification bubbles. See the `gtk.status_icon_position_menu`() function for a more convenient alternative for positioning menus.

Note that some platforms do not provide this information.

### gtk.StatusIcon.get_screen

        def get_screen()

Returns : | a `gtk.gdk.Screen`.

### Note

This method is available in PyGTK 2.12 and above.

Returns the `gtk.gdk.Screen` associated with status_icon.

### gtk.StatusIcon.set_screen

        def set_screen(screen)

`screen` : | a `gtk.gdk.Screen`.

### Note

This method is available in PyGTK 2.12 and above.

Sets the `gtk.gdk.Screen` where status_icon is displayed; if the icon is already mapped, it will be unmapped, and then remapped on the new screen.

## Functions

### gtk.status_icon_new_from_pixbuf

        def gtk.status_icon_new_from_pixbuf(pixbuf)

`pixbuf` : |
Returns : | a new `gtk.StatusIcon`

Creates a status icon displaying `pixbuf`. The image will be scaled down to fit in the available space in the notification area, if necessary.

### gtk.status_icon_new_from_file

        def gtk.status_icon_new_from_file(filename)

`filename` : |
Returns : | a new `gtk.StatusIcon`

Creates a status icon displaying the image in the file specified by `filename`. The image will be scaled down to fit in the available space in the notification area, if necessary.

### gtk.status_icon_new_from_gicon

        def gtk.status_icon_new_from_gicon(gicon)

`gicon` : |
Returns : | a new `gtk.StatusIcon`

Creates a status icon displaying a gio.Icon(). If the icon is a themed icon, it will be updated when the theme changes.

### gtk.status_icon_new_from_stock

        def gtk.status_icon_new_from_stock(stock_id)

`stock_id` : | a stock icon id
Returns : | a new `gtk.StatusIcon`

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 the `gtk.IconFactory.add_default`() and `gtk.IconFactory.add`() methods.

### gtk.status_icon_new_from_icon_name

        def gtk.status_icon_new_from_icon_name(icon_name)

`icon_name` : | an icon name
Returns : | a new `gtk.StatusIcon`

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.

### gtk.status_icon_position_menu

        def gtk.status_icon_position_menu(menu, statusicon)

`menu` : | the `gtk.Menu`
`statusicon` : | the `gtk.StatusIcon`
Returns : | a 3-tuple containing the x and y coordinates for the menu and a boolean indicating whether the menu should be pushed in to be completely inside the screen instead of just clamped to the size to the screen.

Menu positioning function to use with the `popup`() method to position `menu` aligned to `statusicon` .

Eample use of this function is:

      menu.popup(None, None, gtk.status_icon_position_menu,
                 event.button, event.time, statusicon)

## Signals

### The "activate" gtk.StatusIcon Signal

        def callback(status_icon, user_param1, ...)

`status_icon` : | the object which received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

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

### The "popup-menu" gtk.StatusIcon Signal

        def callback(status_icon, button, activate_time, user_param1, ...)

`status_icon` : | the object which received the signal
`button` : | the button that was pressed, or 0 if the signal is not emitted in response to a button press event
`activate_time` : | the timestamp of the event that triggered the signal emission
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

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 two arguments to the `gtk.Menu.popup()` method.

### The "size-changed" gtk.StatusIcon Signal

        def callback(status_icon, size, statusicon, arg1, user_param1, ...)

`status_icon` : | the object which received the signal
`size` : | the new size
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the icon was updated for the new size. Otherwise, GTK+ will scale the icon as necessary.

### Note

This signal is available in GTK+ 2.10 and above.

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

Prev | Up | Next
gtk.Statusbar | Home | gtk.Style