gtk.StatusIcon

gtk.StatusIcon
Prev	The gtk Class Reference	Next

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

Synopsis

class gtk.StatusIcon(gobject.GObject):
    gtk.StatusIcon()
    def set_from_pixbuf(pixbuf)
    def set_from_file(filename)
    def set_from_stock(stock_id)
    def set_from_icon_name(icon_name)
    def get_storage_type()
    def get_pixbuf()
    def get_stock()
    def get_icon_name()
    def get_size()
    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)

Functions

    def gtk.status_icon_new_from_pixbuf(pixbuf)
    def gtk.status_icon_new_from_file(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`.
"file"	Write	Filename to load and display. Default value: `None`.
"icon-name"	Read-Write	The name of the icon from the icon theme. Default value: `None`.
"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.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_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.

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