KNotification Class Reference

from PyKDE4.kdeui import *

Detailed Description

KNotification is used to notify the user of an event.

introduction

There are two main kinds of notifications:

Feedback events:

For notifying the user that he/she just performed an operation, like maximizing a window. This allows us to play sounds when a dialog appears. This is an instant notification. It ends automatically after a small timeout.

persistant notifications:

Notify when the user received a new message, or when something else important happened the user has to know about. This notification has a start and a end. It begins when the event actually occurs, and finishes when the message is acknowledged or read.

Example of a persistent notification in an instant messaging application: The application emits the notification when the message is actually received, and closes it only when the user has read the message (when the message window has received the focus) using the close() slot Persistent notifications must have the Persistent flag.

By default a notification will use the application name as title, but you can also provide a brief text in the title and a more precise description in the body text. This is especially useful for notifications coming from applications which should be considered "part of the system", like a battery monitor or a network connection manager. For example a battery indicator could use "Low Battery" as a title and "Only 12 minutes left." as a body text.

In order to perform a notification, you need to create a description file, which contains default parameters of the notification, and use KNotification.event at the place in the application code where the notification occurs. The returned KNotification pointer may be used to connect signals or slots

The global config file Your application should install a file called: <em>$KDEDIR/share/apps/appname/appname.notifyrc</em>

You can do this with the following CMake command: install( FILES appname.notifyrc DESTINATION ${DATA_INSTALL_DIR}/appname))

This file contains mainly 3 parts <ol><li>\ref global "Global information"</li> <li>\ref context "Context information"</li> <li>\ref events "Definition of individual events"</li></ol>

The global part looks like that <pre> [Global] IconName=Filename Comment=Friendly Name of app Name=Name of app </pre> The icon filename is just the name, without extension, it's found with the KIconLoader. The Comment field will be used in KControl to describe the application. The Name field is optional and may be used as the application name for popup, if Name is not present, Comment is used instead

This part consists of hints for the configuration widget <pre> [Context/group] Name=Group name Comment=The name of the group for contacts

[Context/folder] Name=Group name </pre> The second part of the groupname is the context identifier. It should not contain special characters. The Name field is the one the user will see (and which is translated)

The definition of the events forms the most important part of the config file <pre> [Event/newmail] Name=New email Comment=You have got a new email Contexts=folder,group Action=Sound|Popup

[Event/contactOnline] Name=Contact goes online Comment=One of your contact has been connected Contexts=group Sound=filetoplay.ogg Action=None </pre> These are the default settings for each notifiable event. Action is the string representing the action. Actions can be added to the KNotify daemon as plugins, by deriving from KNotifyPlugin. At the time of writing, the following actions are available: Taskbar, Sound, Popup, Logfile, KTTS, Execute. Actions can be combined by seperating them with '|'.

Contexts is a comma separated list of possible context for this event.

The user's config file

This is an implementation detail, and is described here for your information.

In the config file, there are two parts: the event configuration, and the context information These are hints for the configuration dialog. They contain both the internal id of the context, and the user visible string. <pre> [Context/group] Values=1:Friends,2:Work,3:Family </pre> This contains the configuration of events for the user. It contains the same fields as the description file. The key of groups is in the form <em>Event/<EventName>/<ContextName>/<ContextValue></em> <pre> [Event/contactOnline] Action=Sound Sound=/usr/share/sounds/super.ogg

[Event/contactOnline/group/1] Action=Popup|Sound </pre>

Example of code

This portion of code will fire the event for the "contactOnline" event

KNotification *notification= new KNotification ( "contactOnline", widget );
notification->setText( i18n("The contact <i>%1</i> has gone online", contact->name() );
notification->setPixmap( contact->pixmap() );
notification->setActions( QStringList( i18n( "Open chat" ) ) );

foreach( const QString &group , contact->groups() ) {
notification->addContext( "group" , group ) ;
}

connect(notification, SIGNAL(activated(unsigned int )), contact , SLOT(slotOpenChat()) );

notification->sendEvent();

Author:: Olivier Goffart <ogoffart at kde.org>

Enumerations
NotificationFlag	{ RaiseWidgetOnActivation, CloseOnTimeout, Persistent, CloseWhenWidgetActivated, Persistant, DefaultEvent }
StandardEvent	{ Notification, Warning, Error, Catastrophe }
Signals
	action1Activated ()
	action2Activated ()
	action3Activated ()
	activated ()
	activated (long action)
	closed ()
	ignored ()
Methods
	__init__ (self, QString eventId, QWidget widget=0, KNotification.NotificationFlags flags=KNotification.CloseOnTimeout)
	__init__ (self, QString eventId, KNotification.NotificationFlags flags, QObject parent=NULL)
QStringList	actions (self)
	activate (self, long action=0)
	addContext (self, (QString,QString) context)
	addContext (self, QString context_key, QString context_value)
	close (self)
[(QString,QString)]	contexts (self)
	deref (self)
bool	eventFilter (self, QObject watched, QEvent event)
QString	eventId (self)
KNotification.NotificationFlags	flags (self)
QPixmap	pixmap (self)
	raiseWidget (self)
	ref (self)
	sendEvent (self)
	setActions (self, QStringList actions)
	setComponentData (self, KComponentData componentData)
	setContexts (self, [(QString,QString)] contexts)
	setFlags (self, KNotification.NotificationFlags flags)
	setPixmap (self, QPixmap pix)
	setText (self, QString text)
	setTitle (self, QString title)
	setWidget (self, QWidget widget)
QString	text (self)
QString	title (self)
	update (self)
QWidget	widget (self)
Static Methods
	beep (QString reason=QString(), QWidget widget=0)
KNotification	event (QString eventId, QString text=QString(), QPixmap pixmap=QPixmap(), QWidget widget=0, KNotification.NotificationFlags flags=KNotification.CloseOnTimeout, KComponentData componentData=KComponentData())
KNotification	event (KNotification.StandardEvent eventId, QString text=QString(), QPixmap pixmap=QPixmap(), QWidget widget=0, KNotification.NotificationFlags flags=KNotification.CloseOnTimeout)
KNotification	event (QString eventId, QString title, QString text, QPixmap pixmap=QPixmap(), QWidget widget=0, KNotification.NotificationFlags flags=KNotification.CloseOnTimeout, KComponentData componentData=KComponentData())
KNotification	event (KNotification.StandardEvent eventId, QString title, QString text, QPixmap pixmap=QPixmap(), QWidget widget=0, KNotification.NotificationFlags flags=KNotification.CloseOnTimeout)

Signal Documentation

action1Activated ( )

Convenience signal that is emitted when the first action is activated.

Signal syntax:: QObject.connect(source, SIGNAL("action1Activated()"), target_slot)

action2Activated ( )

Signal syntax:: QObject.connect(source, SIGNAL("action2Activated()"), target_slot)

action3Activated ( )

Signal syntax:: QObject.connect(source, SIGNAL("action3Activated()"), target_slot)

activated ( )

Emit when an action has been activated.

Parameters:

action

will be 0 is the default aciton was activated, or any action id

Signal syntax:: QObject.connect(source, SIGNAL("activated()"), target_slot)

activated	(	long	action
	)

Emit when an action has been activated.

Parameters:

action

will be 0 is the default aciton was activated, or any action id

Signal syntax:: QObject.connect(source, SIGNAL("activated(unsigned int)"), target_slot)

closed ( )

Emitted when the notification is closed. Both when it is activated or if it is just ignored.

Signal syntax:: QObject.connect(source, SIGNAL("closed()"), target_slot)

ignored ( )

The notification has been ignored

Signal syntax:: QObject.connect(source, SIGNAL("ignored()"), target_slot)

Method Documentation

__init__	(	self,
		QString	eventId,
		QWidget	widget=0,
		KNotification.NotificationFlags	flags=KNotification.CloseOnTimeout
	)

Create a new notification.

You have to use sendEvent to show the notification.

The pointer is automatically deleted when the event is closed.

Make sure you use one of the NotificationFlags CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close the notification yourself.

Parameters:

	eventId	is the name of the event
	widget	is a widget where the notification reports to
	flags	is a bitmask of NotificationFlag

__init__	(	self,
		QString	eventId,
		KNotification.NotificationFlags	flags,
		QObject	parent=NULL
	)

Create a new notification.

You have to use sendEvent to show the notification.

The pointer is automatically deleted when the event is closed.

Make sure you use one of the NotificationFlags CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close the notification yourself.

Since:: 4.4

Parameters:

	eventId	is the name of the event
	flags	is a bitmask of NotificationFlag
	parent	parent object

QStringList actions ( self )

Returns:: the list of actions

activate	(	self,
		long	action=0
	)

Activate the action specified action If the action is zero, then the default action is activated

addContext	(	self,
		(QString,QString)	context
	)

Parameters:

	context_key	is the key of the context
	context_value	is the value of the context

addContext	(	self,
		QString	context_key,
		QString	context_value
	)

Parameters:

	context_key	is the key of the context
	context_value	is the value of the context

close ( self )

Close the notification without activating it.

This will delete the notification.

[(QString,QString)] contexts ( self )

Returns:: the list of contexts, see KNotification.Context

deref ( self )

remove a reference made with ref() the notification may be closed when calling this.

See also:: ref

bool eventFilter	(	self,
		QObject	watched,
		QEvent	event
	)

reimplemented for internal reasons

QString eventId ( self )

Returns:: the name of the event

KNotification.NotificationFlags flags ( self )

Returns:: the notification flags.

QPixmap pixmap ( self )

Returns:: the pixmap shown in the popup

See also:: setPixmap

raiseWidget ( self )

Raise the widget. This will change the desktop, activate the window, and the tab if needed.

ref ( self )

The notification will automatically be closed if all presentations are finished. if you want to show your own presentation in your application, you should use this function, so it will not be automatically closed when there is nothing to show.

don't forgot to deref, or the notification may be never closed if there is no timeout.

See also:: ref

sendEvent ( self )

Emit or re-emit the event.

setActions	(	self,
		QStringList	actions
	)

Set the list of actions link shown in the popup.

Parameters:

actions

the list of actions

setComponentData	(	self,
		KComponentData	componentData
	)

The componentData is used to determine the location of the config file. By default, kapp is used

Parameters:

componentData

the new componentData

setContexts	(	self,
		[(QString,QString)]	contexts
	)

set the list of contexts, see KNotification.Context

The list of contexts must be set before calling sendEvent;

setFlags	(	self,
		KNotification.NotificationFlags	flags
	)

Set the notification flags. should be called before sendEvent().

setPixmap	(	self,
		QPixmap	pix
	)

set the pixmap that will be shown in the popup.

Parameters:

pix

the pixmap

setText	(	self,
		QString	text
	)

Set the notification text that will appear in the popup.

The text is shown in a QLabel, you should make sure to escape any html that is needed. You can use some of the qt basic html tags.

Parameters:

text

the text

setTitle	(	self,
		QString	title
	)

Set the title of the notification popup. If no title is set, the application name will be used.

Parameters:

title

the title

Since:: 4.3

setWidget	(	self,
		QWidget	widget
	)

Set the widget associated to the notification. The notification is reparented to the new widget.

See also:: widget()

Parameters:

widget

the new widget

QString text ( self )

Returns:: the notification text

See also:: setText

QString title ( self )

Returns:: the notification title

See also:: setTitle

Since:: 4.3

update ( self )

Internal:: update the texts, the icon, and the actions of one existing notification

QWidget widget ( self )

the widget associated to the notification

If the widget is destroyed, the notification will be automatically cancelled. If the widget is activated, the notification will be automatically closed if the NotificationFlags specify that

When the notification is activated, the widget might be raised. Depending on the configuration, the taskbar entry of the window containing the widget may blink.

Static Method Documentation

beep	(	QString	reason=QString(),
		QWidget	widget=0
	)

This is a simple substitution for QApplication.beep()

Parameters:

	reason	a short text explaining what has happened (may be empty)
	widget	the widget the notification refers to

KNotification event	(	QString	eventId,
		QString	text=QString(),
		QPixmap	pixmap=QPixmap(),
		QWidget	widget=0,
		KNotification.NotificationFlags	flags=KNotification.CloseOnTimeout,
		KComponentData	componentData=KComponentData()
	)

emit a standard event

This will emit a standard event

Parameters:

	eventId	is the name of the event
	title	is title of the notification to show in the popup.
	text	is the text of the notification to show in the popup
	pixmap	is a picture which may be shown in the popup
	widget	is a widget where the notification reports to
	flags	is a bitmask of NotificationFlag

Since:: 4.4

KNotification event	(	KNotification.StandardEvent	eventId,
		QString	text=QString(),
		QPixmap	pixmap=QPixmap(),
		QWidget	widget=0,
		KNotification.NotificationFlags	flags=KNotification.CloseOnTimeout
	)

emit a standard event

This will emit a standard event

Parameters:

	eventId	is the name of the event
	title	is title of the notification to show in the popup.
	text	is the text of the notification to show in the popup
	pixmap	is a picture which may be shown in the popup
	widget	is a widget where the notification reports to
	flags	is a bitmask of NotificationFlag

Since:: 4.4

KNotification event	(	QString	eventId,
		QString	title,
		QString	text,
		QPixmap	pixmap=QPixmap(),
		QWidget	widget=0,
		KNotification.NotificationFlags	flags=KNotification.CloseOnTimeout,
		KComponentData	componentData=KComponentData()
	)

emit a standard event

This will emit a standard event

Parameters:

	eventId	is the name of the event
	title	is title of the notification to show in the popup.
	text	is the text of the notification to show in the popup
	pixmap	is a picture which may be shown in the popup
	widget	is a widget where the notification reports to
	flags	is a bitmask of NotificationFlag

Since:: 4.4

KNotification event	(	KNotification.StandardEvent	eventId,
		QString	title,
		QString	text,
		QPixmap	pixmap=QPixmap(),
		QWidget	widget=0,
		KNotification.NotificationFlags	flags=KNotification.CloseOnTimeout
	)

emit a standard event

This will emit a standard event

Parameters:

	eventId	is the name of the event
	title	is title of the notification to show in the popup.
	text	is the text of the notification to show in the popup
	pixmap	is a picture which may be shown in the popup
	widget	is a widget where the notification reports to
	flags	is a bitmask of NotificationFlag

Since:: 4.4

Enumeration Documentation

NotificationFlag

Sometimes the user may want different notifications for the same event, depending the source of the event. Example, you want to be notified for mails that arrive in your folder "personal inbox" but not for those in "spam" folder

A notification context is a pair of two strings. The first string is a key from what the context is. example "group" or "filter" (not translated). The second is the id of the context. In our example, the group id or the filter id in the applications. These strings are the ones present in the config file, and are in theory not shown in the user interface.

The order of contexts in the list is is important, the most important context should be placed first. They are processed in that order when the notification occurs.

See also:: event

Enumerator:

RaiseWidgetOnActivation = 0x01
CloseOnTimeout = 0x00
Persistent = 0x02
CloseWhenWidgetActivated = 0x04
Persistant = Persistent
DefaultEvent = 0xF000

StandardEvent

default events you can use in the event function

Enumerator:

Notification
Warning
Error
Catastrophe

KNotification Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Signal Documentation

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules