class KNotification |
|
|
KNotification is used to notify some event to the user. introduction There is mainly two kind of notifications
Example of a persistant notification in an instant messaging application: The application emit the notification whe the message actually received, and close it only when the user has read the message (when the message window has received the focus) using the close() slot Persistant notification must have the Persistant flag. In order to do a notification, you need to create a description files, which contains default parametters of the notification, and use KNotification.event at the place of the code where the notification occurs. the returned KNotification pointer may be used to connect signals or slots The global config file On installation, there should be a file called $KDEDIR/share/apps/appname/appname.notifyrc This file contains mainly 3 parts
The global part looks like that [Global] IconName=Filename Comment=Freindly Name of appThe icon filename is just the name, without extension, it's found with the KIconLoader This part is only hints for the configuration widget [Context/group] Name=Group name Comment=The name of the group of the contactthe second part of the groupname is the context identifier. It should not contains special characters. The Name field is the one the user will see (and which is translated) Now comes the most important, the description of each events. [Event/newmail] Name=New email Comment=You have got a new email Contexts=folder,group Action=Sound|PopupAll you put there are the default value. 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 only an implementation detail, for your information. On the config file, there is two parts: the events configuration, and the context information This is only hints for the configuration dialog. It contains both the internal id of the context, and the user visible string. [Context/group] Values=1:Friends,2:Work,3:FamilyThis 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 Event/<EventName>/<ContextName>/<ContextValue> [Event/contactOnline] Action=Sound Sound=/usr/share/sounds/super.ogg Example of code This portion of code will fire the event for the "contactOnline" event
notification= new KNotification ( "contactOnline" ); notification->setText( i18n("The contact %1 has gone online").arg( contact->name() ) ); notification->setPixmap( contact->pixmap() ); notification->setActions( QStringList( i18n( "Open chat" ) ) );
Author Olivier Goffart \ |
|
Create a new notification. you need to use sendEvent to show the notification. 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.
eventId - is the name of the event widget - is a widget where the notification reports to flags - is a bitmask of NotificationFlag |
|
Convenance signal that is emitted when the first action is activated. |
|
|
|
|
|
Returns the list of actions |
|
Active the action specified action If the action is zero, then the default action is activated |
|
Emit only when the default activation has occurred |
|
Emit when an action has been activated. action - will be 0 is the default aciton was activated, or any actiton id |
|
append a context at the list of contexts, see KNotificaiton.Context context - the context which is added |
|
context_key - is the key of the context context_value - is the value of the context |
|
This is a simple substitution for QApplication.beep()
reason - a small text explaining what's happen (may be null) widget - the widget where the notification refer to |
|
close the notification without activate it. This will delete the notification |
|
Emit when the notification is closed. Both if it's activated or just ignored |
|
Returns the list of contexts, see KNotification.Context |
|
remove a reference made with ref() the notification may be closed when calling this. See also ref |
|
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. the text is shown in a QLabel, you should escape HTML, if needed.
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, KApplication.kApplication () is used |
|
emit standard an event
This will emit a standard event
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 |
|
reimplemented for internals raison |
|
Returns the name of the event |
|
Returns the notifications flags. |
|
The notification has been ignored |
|
Returns the pixmap shown in the popup See also setPixmap |
|
Raise the widget. This will change the desktop, activate the window, and the tab if needed. |
|
The notification will automatically be closed if all presentation 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 |
|
Emit or re-emit the event. |
|
Set the list of actions link shown in the popup. actions - the list of actions |
|
The componentData is used to determine the location of the config file. By default, KApplication.kApplication () is used componentData - the new componentData |
|
set the list of context, see KNotification.Context The list of context must be set before calling sendEvent; |
|
Set the notification flags. should be called before sendEvent(). |
|
set the pixmap that will be shown in the popup. pix - the pixmap |
|
Set the notification text that will appears in the popup. The text is shown in a QLabel, you should make sure to escape the html is needed. You can use some of the qt basic html tags.
text - the text |
|
Set the widget associated to the notification. The notification is reparented to the new widget. See also widget() widget - the new widget |
|
Returns the notification text See also setText |
|
the widget associated to the notification If the widget is destroyed, the notification will be automatically canceled. If the widget is activated, the notificaiton will be automatically closed if the flags said that When the notification is activated, the widget might be raised. Depending of the configuration, the taskbar entry of the window containing the widget may blink. |
RaiseWidgetOnActivation | - | When the notification is activated, raise the notification's widget. /p> p> This will change the desktop, raise the window, and switch to the tab. To do: doesn't works yet | |
CloseOnTimeout | - | The notification will be automatically closed after a timeout. (this is the default) | |
Persistant | - | The notification will NOT be automatically closed after a timeout. You will have to track the notification, and close it with the close function manually when the event is done, otherwise there will be a memory leak | |
CloseWhenWidgetActivated | - | The notification will be automatically closed if the widget() becomes activated. /p> p> If the widget is already activated when the notification occurs, the notification will be closed after a small timeout. /p> p> This only works if the widget is the toplevel widget To do: make it work with tabulated widget | |
DefaultEvent | - | b style="color : #ff0000;">Internal The event is a standard kde event, and not an event of the application |
Notification | - | ||
Warning | - | ||
Error | - | ||
Catastrophe | - |