# class KNotification

###

Module | kdeui
Namespace |
Class | KNotification
Inherits | QObject

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.

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: $KDEDIR/share/apps/appname/appname.notifyrc

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

This file contains mainly 3 parts

1. \ref global "Global information"
2. \ref context "Context information"
3. \ref events "Definition of individual events"

The global part looks like that

    [Global]
    IconName=Filename
    Comment=Friendly Name of app

The icon filename is just the name, without extension, it's found with the KIconLoader

This part consists of hints for the configuration widget

    [Context/group]
    Name=Group name
    Comment=The name of the group for contacts

    [Context/folder]
    Name=Group name

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

    [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

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.

    [Context/group]
    Values=1:Friends,2:Work,3:Family

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 Event/<EventName>/<ContextName>/<ContextValue>

    [Event/contactOnline]
    Action=Sound
    Sound=/usr/share/sounds/super.ogg

    [Event/contactOnline/group/1]
    Action=PassivePopup|Sound

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 %1 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();

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

### enums

- NotificationFlag { RaiseWidgetOnActivation, CloseOnTimeout, Persistent, CloseWhenWidgetActivated, Persistant, DefaultEvent }
  typesafe object: NotificationFlags
- StandardEvent { Notification, Warning, Error, Catastrophe }

enum details

### methods

- KNotification (eventId, widget, flags)

  returns ctor
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  eventId | QString |
  widget | QWidget | 0
  flags | KNotification.NotificationFlags | 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.

  eventId - is the name of the event

  widget - is a widget where the notification reports to

  flags - is a bitmask of NotificationFlag

- KNotification (a0, a1, a2)

  returns ctor
  before KDE 4.1.0 only

  Argument | Type | Default
  --- | --- | ---
  a0 | QString |
  a1 | QWidget | 0
  a2 | KNotification.NotificationFlags | KNotification.CloseOnTimeout

- action1Activated ( )

  returns Nothing
  SIGNAL ("action1Activated ()")

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

- action2Activated ( )

  returns Nothing
  SIGNAL ("action2Activated ()")

- action3Activated ( )

  returns Nothing
  SIGNAL ("action3Activated ()")

- actions ( )

  returns QStringList

  Returns the list of actions

- activate (action)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  action | unsigned int | 0

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

- activated ( )

  returns Nothing
  SIGNAL ("activated ()")

  Emit only when the default activation has occurred

- activated (action)

  returns Nothing
  SIGNAL ("activated (unsigned int)")

  Argument | Type | Default
  --- | --- | ---
  action | unsigned int |

  Emit when an action has been activated.

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

- addContext (context)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  context | KNotification.Context |

  append a context at the list of contexts, see KNotificaiton.Context

  context - the context which is added

- addContext (context_key, context_value)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  context_key | QString |
  context_value | QString |

  context_key - is the key of the context

  context_value - is the value of the context

- beep (reason, widget)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  reason | QString | QString()
  widget | QWidget | 0

  This is a simple substitution for QApplication.beep()

  reason - a short text explaining what has happened (may be empty)

  widget - the widget the notification refers to

- close ( )

  returns Nothing

  Close the notification without activating it.

  This will delete the notification.

- closed ( )

  returns Nothing
  SIGNAL ("closed ()")

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

- contexts ( )

  returns KNotification.ContextList

  Returns the list of contexts, see KNotification.Context

- deref ( )

  returns Nothing

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

  See also ref

- event (eventId, text, pixmap, widget, flags, componentData)

  returns KNotification
  static

  Argument | Type | Default
  --- | --- | ---
  eventId | QString |
  text | QString | QString()
  pixmap | QPixmap | QPixmap()
  widget | QWidget | 0
  flags | KNotification.NotificationFlags | KNotification.CloseOnTimeout
  componentData | KComponentData | 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.

  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, kapp is used

- event (eventId, text, pixmap, widget, flags)

  returns KNotification
  static

  Argument | Type | Default
  --- | --- | ---
  eventId | KNotification.StandardEvent |
  text | QString | QString()
  pixmap | QPixmap | QPixmap()
  widget | QWidget | 0
  flags | KNotification.NotificationFlags | KNotification.CloseOnTimeout

  emit a standard 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

- eventFilter (watched, event)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  watched | QObject |
  event | QEvent |

  reimplemented for internal reasons

- eventId ( )

  returns QString

  Returns the name of the event

- flags ( )

  returns KNotification.NotificationFlags

  Returns the notification flags.

- ignored ( )

  returns Nothing
  SIGNAL ("ignored ()")

  The notification has been ignored

- pixmap ( )

  returns QPixmap

  Returns the pixmap shown in the popup

  See also setPixmap

- raiseWidget ( )

  returns Nothing

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

- ref ( )

  returns Nothing

  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 ( )

  returns Nothing

  Emit or re-emit the event.

- setActions (actions)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  actions | QStringList |

  Set the list of actions link shown in the popup.

  actions - the list of actions

- setComponentData (componentData)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  componentData | KComponentData |

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

  componentData - the new componentData

- setContexts (contexts)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  contexts | KNotification.ContextList |

  set the list of contexts, see KNotification.Context

  The list of contexts must be set before calling sendEvent;

- setFlags (flags)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  flags | KNotification.NotificationFlags |

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

- setPixmap (pix)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  pix | QPixmap |

  set the pixmap that will be shown in the popup.

  pix - the pixmap

- setText (text)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  text | QString |

  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.

  text - the text

- setWidget (widget)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  widget | QWidget |

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

  See also widget()

  widget - the new widget

- text ( )

  returns QString

  Returns the notification text

  See also setText

- update ( )

  returns Nothing

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

- widget ( )

  returns QWidget

  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.

### enums - detail

- NotificationFlag { RaiseWidgetOnActivation, CloseOnTimeout, Persistent, CloseWhenWidgetActivated, Persistant, DefaultEvent }

  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

  typesafe object: NotificationFlags

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

- StandardEvent { Notification, Warning, Error, Catastrophe }

  default events you can use in the event function

  | Notification | - | - |
  | Warning | - | - |
  | Error | - | - |
  | Catastrophe | - | - |