KNotification Class Reference
from PyKDE4.kdeui import *
Inherits: QObject
Detailed Description
KNotification is used to notify the user of an event.
introduction
There are two main kinds of notifications:
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.
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 </pre> The icon filename is just the name, without extension, it's found with the KIconLoader
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 a bitmask of KNotification.NotifyPresentation
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=PassivePopup|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").arg( 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();
Enumerations | |
NotificationFlag | { RaiseWidgetOnActivation, CloseOnTimeout, Persistent, CloseWhenWidgetActivated, Persistant, DefaultEvent } Typesafe wrapper: NotificationFlags |
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) | |
action1Activated (self) | |
action2Activated (self) | |
action3Activated (self) | |
QStringList | actions (self) |
activate (self, long action=0) | |
activated (self) | |
activated (self, long action) | |
addContext (self, KNotification.Context context) | |
addContext (self, QString context_key, QString context_value) | |
close (self) | |
closed (self) | |
KNotification.ContextList | contexts (self) |
deref (self) | |
bool | eventFilter (self, QObject watched, QEvent event) |
QString | eventId (self) |
KNotification.NotificationFlags | flags (self) |
ignored (self) | |
QPixmap | pixmap (self) |
raiseWidget (self) | |
ref (self) | |
sendEvent (self) | |
setActions (self, QStringList actions) | |
setComponentData (self, KComponentData componentData) | |
setContexts (self, KNotification.ContextList contexts) | |
setFlags (self, KNotification.NotificationFlags flags) | |
setPixmap (self, QPixmap pix) | |
setText (self, QString text) | |
setWidget (self, QWidget widget) | |
QString | text (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) |
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
action1Activated | ( | self ) |
Convenience signal that is emitted when the first action is activated.
- Signal syntax:
QObject.connect(source, SIGNAL("action1Activated()"), target_slot)
action2Activated | ( | self ) |
- Signal syntax:
QObject.connect(source, SIGNAL("action2Activated()"), target_slot)
action3Activated | ( | self ) |
- Signal syntax:
QObject.connect(source, SIGNAL("action3Activated()"), target_slot)
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
activated | ( | self ) |
Emit only when the default activation has occurred
- Signal syntax:
QObject.connect(source, SIGNAL("activated()"), target_slot)
activated | ( | self, | ||
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)
addContext | ( | self, | ||
KNotification.Context | context | |||
) |
append a context at the list of contexts, see KNotificaiton.Context
- Parameters:
-
context the context which is added
- Parameters:
-
context_key is the key of the context context_value is the value of the context
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
close | ( | self ) |
Close the notification without activating it.
This will delete the notification.
closed | ( | self ) |
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)
KNotification.ContextList 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
KNotification event | ( | QString | eventId, | |
QString | text=QString(), | |||
QPixmap | pixmap=QPixmap(), | |||
QWidget | widget=0, | |||
KNotification.NotificationFlags | flags=KNotification.CloseOnTimeout, | |||
KComponentData | componentData=KComponentData() | |||
) |
emit an event
This method creates the KNotification, setting every parameter, and fire the event. You don't need to call sendEvent
A popup may be displayed or a sound may be played, depending the config.
return a KNotification . You may use that pointer to connect some signals or slot. the pointer is automatically deleted when the event is closed.
Make sure you use one of the CloseOnTimeOut or CloseWhenWidgetActivated, if not, you have to close yourself the notification.
- Note:
- the text is shown in a QLabel, you should escape HTML, if needed.
- Parameters:
-
eventId is the name of the event 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 componentData used to determine the location of the config file. by default, kapp is used
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 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
QString eventId | ( | self ) |
- Returns:
- the name of the event
KNotification.NotificationFlags flags | ( | self ) |
- Returns:
- the notification flags.
ignored | ( | self ) |
The notification has been ignored
- Signal syntax:
QObject.connect(source, SIGNAL("ignored()"), target_slot)
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, | ||
KNotification.ContextList | 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
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
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.
Enumeration Documentation
NotificationFlag |
When the notification is activated, raise the notification's widget.
This will change the desktop, raise the window, and switch to the tab. To do: doesn't work yet
- Note:
- It is necessary to wrap members of this enumeration in a
NotificationFlags
instance when passing them to a method as group of flags. For example:NotificationFlags( RaiseWidgetOnActivation | CloseOnTimeout)
- 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