KStatusNotifierItem Class Reference

from PyKDE4.kdeui import *

Inherits: QObject

Detailed Description

KDE Status notifier Item protocol implementation

This class implements the Status notifier Item Dbus specification. It provides an icon similar to the classical systemtray icons, with some key differences:

- the actual representation is done by the systemtray (or the app behaving like it) itself, not by this app. Since 4.5 this also includes the menu, which means you cannot use embed widgets in the menu.

- there is communication between the systemtray and the icon owner, so the system tray can know if the application is in a normal or in a requesting attention state.

- icons are divided in categories, so the systemtray can represent in a different way the icons from normal applications and for instance the ones about hardware status.

Whenever possible you should prefer passing icon by name rather than by pixmap because:

- it is much lighter on Dbus (no need to pass all image pixels).

- it makes it possible for the systemtray to load an icon of the appropriate size or to replace your icon with a systemtray specific icon which matches with the desktop theme.

- some implementations of the system tray do not support passing icons by pixmap and will show a blank icon instead.

Author:: Marco Martin <notmart@gmail.com>

Since:: 4.4

Enumerations
ItemCategory	{ ApplicationStatus, Communications, SystemServices, Hardware, Reserved }
ItemStatus	{ Passive, Active, NeedsAttention }
Signals
	activateRequested (bool active, QPoint pos)
	scrollRequested (int delta, Qt::Orientation orientation)
	secondaryActivateRequested (QPoint pos)
Methods
	__init__ (self, QObject parent=0)
	__init__ (self, QString id, QObject parent=0)
KActionCollection	actionCollection (self)
	activate (self, QPoint pos=QPoint())
QWidget	associatedWidget (self)
QString	attentionIconName (self)
QIcon	attentionIconPixmap (self)
QString	attentionMovieName (self)
KStatusNotifierItem.ItemCategory	category (self)
KMenu	contextMenu (self)
bool	eventFilter (self, QObject watched, QEvent event)
QString	iconName (self)
QIcon	iconPixmap (self)
QString	id (self)
QString	overlayIconName (self)
QIcon	overlayIconPixmap (self)
	setAssociatedWidget (self, QWidget parent)
	setAttentionIconByName (self, QString name)
	setAttentionIconByPixmap (self, QIcon icon)
	setAttentionMovieByName (self, QString name)
	setCategory (self, KStatusNotifierItem.ItemCategory category)
	setContextMenu (self, KMenu menu)
	setIconByName (self, QString name)
	setIconByPixmap (self, QIcon icon)
	setOverlayIconByName (self, QString name)
	setOverlayIconByPixmap (self, QIcon icon)
	setStandardActionsEnabled (self, bool enabled)
	setStatus (self, KStatusNotifierItem.ItemStatus status)
	setTitle (self, QString title)
	setToolTip (self, QString iconName, QString title, QString subTitle)
	setToolTip (self, QIcon icon, QString title, QString subTitle)
	setToolTipIconByName (self, QString name)
	setToolTipIconByPixmap (self, QIcon icon)
	setToolTipSubTitle (self, QString subTitle)
	setToolTipTitle (self, QString title)
	showMessage (self, QString title, QString message, QString icon, int timeout=10000)
bool	standardActionsEnabled (self)
KStatusNotifierItem.ItemStatus	status (self)
QString	title (self)
QString	toolTipIconName (self)
QIcon	toolTipIconPixmap (self)
QString	toolTipSubTitle (self)
QString	toolTipTitle (self)

Signal Documentation

activateRequested	(	bool	active,
		QPoint	pos
	)

Inform the host application that an activation has been requested, for instance left mouse click, but this is not guaranteed since it's dependent from the visualization

Parameters:

	active	if it's true the application asked for the activatin of the main window, if it's false it asked for hiding
	pos	the position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.

Signal syntax:: QObject.connect(source, SIGNAL("activateRequested(bool, const QPoint&)"), target_slot)

scrollRequested	(	int	delta,
		Qt::Orientation	orientation
	)

Inform the host application that the mouse wheel (or another mean of scrolling that the visualization provides) has been used

Parameters:

	delta	the amount of scrolling, can be either positive or negative
	orientation	direction of the scrolling, can be either horizontal or vertical

Signal syntax:: QObject.connect(source, SIGNAL("scrollRequested(int, Qt::Orientation)"), target_slot)

secondaryActivateRequested	(	QPoint	pos
	)

Alternate activate action, for instance right mouse click, but this is not guaranteed since it's dependent from the visualization

Parameters:

pos

the position in the screen where the user clicked to trigger this signal, QPoint() if it's not the consequence of a mouse click.

Signal syntax:: QObject.connect(source, SIGNAL("secondaryActivateRequested(const QPoint&)"), target_slot)

Method Documentation

__init__	(	self,
		QObject	parent=0
	)

Construct a new status notifier item

Parameters:

parent

the parent object for this object. If the object passed in as a parent is also a QWidget, it will be used as the main application window represented by this icon and will be shown/hidden when an activation is requested.

See also:: associatedWidget

__init__	(	self,
		QString	id,
		QObject	parent=0
	)

Construct a new status notifier item with a unique identifier. If your application has more than one status notifier item and the user should be able to manipulate them separately (e.g. mark them for hiding in a user interface), the id can be used to differentiate between them.

The id should remain consistent even between application restarts. Status notifier items without ids default to the application's name for the id. This id may be used, for instance, by hosts displaying status notifier items to associate configuration information with this item in a way that can persist between sessions or application restarts.

Parameters:

	id	the unique id for this icon
	parent	the parent object for this object. If the object passed in as a parent is also a QWidget, it will be used as the main application window represented by this icon and will be shown/hidden when an activation is requested.

See also:: associatedWidget

KActionCollection actionCollection ( self )

All the actions present in the menu

activate	(	self,
		QPoint	pos=QPoint()
	)

Shows the main widget and try to position it on top of the other windows, if the widget is already visible, hide it.

Parameters:

pos

if it's a valid position it represents the mouse coordinates when the event was triggered

QWidget associatedWidget ( self )

Access the main widget associated with this StatusNotifierItem

QString attentionIconName ( self )

Returns:: the name of the icon to be displayed when the application is requesting the user's attention if attentionImage() is not empty this will always return an empty string

QIcon attentionIconPixmap ( self )

Returns:: a pixmap of the requesting attention icon

QString attentionMovieName ( self )

Returns:: the name of the movie to be displayed when the application is requesting the user attention

KStatusNotifierItem.ItemCategory category ( self )

Returns:: the application category

KMenu contextMenu ( self )

Access the context menu associated to this status notifier item

bool eventFilter	(	self,
		QObject	watched,
		QEvent	event
	)

QString iconName ( self )

Returns:: the name of the main icon to be displayed if image() is not empty this will always return an empty string

QIcon iconPixmap ( self )

Returns:: a pixmap of the icon

QString id ( self )

Returns:: The id which was specified in the constructor. This should be guaranteed to be consistent between application starts and untranslated, as host applications displaying items may use it for storing configuration related to this item.

QString overlayIconName ( self )

Returns:: the name of the icon to be used as overlay fr the main one

QIcon overlayIconPixmap ( self )

Returns:: a pixmap of the icon

setAssociatedWidget	(	self,
		QWidget	parent
	)

Sets the main widget associated with this StatusNotifierItem

If you pass contextMenu() as a parent then the menu will be displayed when the user activate the icon. In this case the activate() method will not be called and the activateRequested() signal will not be emitted

Parameters:

parent

the new main widget: must be a top level window, if it's not parent->window() will be used instead.

setAttentionIconByName	(	self,
		QString	name
	)

Sets a new icon that should be used when the application wants to request attention (usually the systemtray will blink between this icon and the main one)

Parameters:

name

KIconLoader-compatible name of icon to use

setAttentionIconByPixmap	(	self,
		QIcon	icon
	)

Sets the pixmap of the requesting attention icon. Use setAttentionIcon(const QString) instead when possible.

Parameters:

icon

QIcon to use for requesting attention.

setAttentionMovieByName	(	self,
		QString	name
	)

Sets a movie as the requesting attention icon. This overrides anything set in setAttentionIcon()

setCategory	(	self,
		KStatusNotifierItem.ItemCategory	category
	)

Sets the category for this icon, usually it's needed to call this function only once

Parameters:

category

the new category for this icon

setContextMenu	(	self,
		KMenu	menu
	)

Sets a new context menu for this StatusNotifierItem. the menu will be shown with a contextMenu(int,int) call by the systemtray over dbus usually you don't need to call this unless you want to use a custom KMenu subclass as context menu

setIconByName	(	self,
		QString	name
	)

Sets a new main icon for the system tray

Parameters:

name

it must be a KIconLoader compatible name, this is the preferred way to set an icon

setIconByPixmap	(	self,
		QIcon	icon
	)

Sets a new main icon for the system tray

Parameters:

pixmap

our icon, use setIcon(const QString) when possible

setOverlayIconByName	(	self,
		QString	name
	)

Sets an icon to be used as overlay for the main one

Parameters:

icon

name, if name is and empty QString() (and overlayIconPixmap() is empty too) the icon will be removed

setOverlayIconByPixmap	(	self,
		QIcon	icon
	)

Sets an icon to be used as overlay for the main one setOverlayIconByPixmap(QIcon()) will remove the overlay when overlayIconName() is empty too.

Parameters:

pixmap

our overlay icon, use setOverlayIcon(const QString) when possible.

setStandardActionsEnabled	(	self,
		bool	enabled
	)

Sets whether to show the standard items in the menu, such as Quit

setStatus	(	self,
		KStatusNotifierItem.ItemStatus	status
	)

Sets a new status for this icon.

setTitle	(	self,
		QString	title
	)

Sets a title for this icon

setToolTip	(	self,
		QString	iconName,
		QString	title,
		QString	subTitle
	)

Sets a new toolTip or this status notifier item. This is an overloaded member provided for convenience

setToolTip	(	self,
		QIcon	icon,
		QString	title,
		QString	subTitle
	)

Sets a new toolTip or this status notifier item. This is an overloaded member provided for convenience

setToolTipIconByName	(	self,
		QString	name
	)

Set a new icon for the toolTip

Parameters:

name

the name for the icon

setToolTipIconByPixmap	(	self,
		QIcon	icon
	)

Set a new icon for the toolTip.

Use setToolTipIconByName(QString) if possible.

Parameters:

pixmap

representing the icon

setToolTipSubTitle	(	self,
		QString	subTitle
	)

Sets a new subtitle for the toolTip

setToolTipTitle	(	self,
		QString	title
	)

Sets a new title for the toolTip

showMessage	(	self,
		QString	title,
		QString	message,
		QString	icon,
		int	timeout=10000
	)

Shows the user a notification. If possible use KNotify instead

Parameters:

	title	message title
	message	the actual text shown to the user
	icon	icon to be shown to the user
	timeout	how much time will elaps before hiding the message

bool standardActionsEnabled ( self )

Returns:: if the standard items in the menu, such as Quit

KStatusNotifierItem.ItemStatus status ( self )

Returns:: the current application status

QString title ( self )

Returns:: the title of this icon

QString toolTipIconName ( self )

Returns:: the name of the toolTip icon if toolTipImage() is not empty this will always return an empty string

QIcon toolTipIconPixmap ( self )

Returns:: a serialization of the toolTip icon data

QString toolTipSubTitle ( self )

Returns:: the subtitle of the main icon toolTip

QString toolTipTitle ( self )

Returns:: the title of the main icon toolTip

Enumeration Documentation

ItemCategory

Different kinds of applications announce their type to the systemtray, so can be drawn in a different way or in a different place

Enumerator:

ApplicationStatus = 1
Communications = 2
SystemServices = 3
Hardware = 4
Reserved = 129

ItemStatus

All the possible status this icon can have, depending on the importance of the events that happens in the parent application

Enumerator:

Passive = 1
Active = 2
NeedsAttention = 3

KStatusNotifierItem Class Reference

Detailed Description

Enumerations

Signals

Methods

Signal Documentation

Method Documentation

Enumeration Documentation

Modules