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