class KNotification


Table of contents
Modules
kdeui Classes
All Classes
Module kdeui
Namespace global
Class KNotification
Inherits QObject

KNotification is used to notify some event to the user.

introduction

There is mainly two kind 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 one received a new message, or when something important happened the user has to know. This notification has a start and a end. It start when the event actually occurs, and finish when the message is acknowledged or read.

    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

    1. \ref global "Global information"
    2. \ref context "Context information"
    3. \ref events "Information about every events"

    The global part looks like that

    [Global]
    IconName=Filename
    Comment=Freindly Name of app
    
    The 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 contact
    

    [Context/folder] Name=Group name

    the 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|Popup
    

    [Event/contactOnline] Name=Contact goes online Comment=One of your contact has been connected Contexts=group Sound=filetoplay.ogg Action=None

    All 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: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

    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" ) ) );
    

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

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

    notification->sendEvent();

    Author Olivier Goffart \



    enums

    enum details

    methods