kdecore Library API Documentation

KNotifyClient Namespace Reference

This namespace provides a method for issuing events to a KNotifyServer call KNotifyClient::event("eventname"); to issue it. More...


Classes

class  Instance
 Makes it possible to use KNotifyClient with a KInstance that is not the application. Enables KNotifyClient to use a different KInstance. More...


Enumerations

enum  {
  Default = -1, None = 0, Sound = 1, Messagebox = 2,
  Logfile = 4, Stderr = 8, PassivePopup = 16, Execute = 32
}
 Describes the notification method. More...

enum  { Notification = 1, Warning = 2, Error = 4, Catastrophe = 8 }
 Describes the level of the error. More...

enum  StandardEvent {
  cannotOpenFile, notification, warning, fatalError,
  catastrophe
}
 default events you can use More...


Functions

bool startDaemon ()
 This starts the KNotify Daemon, if it's not already started.

bool event (const QString &message, const QString &text=QString::null)
 This should be the most used method in here.

bool event (StandardEvent event, const QString &text=QString::null)
 Allows to easily emit standard events.

bool userEvent (const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null)
 Will fire an event that's not registered.

void beep (const QString &reason=QString::null)
 This is a simple substitution for QApplication::beep().

int getPresentation (const QString &eventname)
 Gets the presentation associated with a certain event name Remeber that they may be ORed:.

QString getFile (const QString &eventname, int present)
 Gets the default file associated with a certain event name The control panel module will list all the event names This has the potential for being slow.

int getDefaultPresentation (const QString &eventname)
 Gets the default presentation for the event of this program.

QString getDefaultFile (const QString &eventname, int present)
 Gets the default File for the event of this program.

KInstanceinstance ()
 Shortcut to KNotifyClient::Instance::current() :).


Detailed Description

This namespace provides a method for issuing events to a KNotifyServer call KNotifyClient::event("eventname"); to issue it.

On installation, there should be a file called $KDEDIR/share/apps/appname/eventsrc which contains the events.

The file looks like this:

[!Global!] IconName=Filename (e.g. kdesktop, without any extension) Comment=FriendlyNameOfApp

[eventname] Name=FriendlyNameOfEvent Comment=Description Of Event default_sound=filetoplay.wav default_presentation=1 ...
default_presentation contains these ORed events: None=0, Sound=1, Messagebox=2, Logfile=4, Stderr=8

KNotify will search for sound files given with a relative path first in the application's sound directory ( share/apps/Application Name/sounds ), then in the KDE global sound directory ( share/sounds ).

You can also use the "nopresentation" key, with any the presentations ORed. Those that are in that field will not appear in the kcontrol module. This was intended for software like KWin to not allow a window-opening that opens a window (e.g., allowing to disable KMessageBoxes from appearing) If the user edits the eventsrc file manually, it will appear. This only affects the KcmNotify.

You can also use the following events, which are system controlled and do not need to be placed in your eventsrc:

Author:
Charles Samuels <charles@kde.org>


Enumeration Type Documentation

anonymous enum
 

Describes the notification method.

Enumeration values:
PassivePopup 
Since:
3.1
Execute 
Since:
3.1

Definition at line 132 of file knotifyclient.h.

anonymous enum
 

Describes the level of the error.

Definition at line 146 of file knotifyclient.h.

enum KNotifyClient::StandardEvent
 

default events you can use

Definition at line 156 of file knotifyclient.h.


Function Documentation

bool KNotifyClient::startDaemon  ) 
 

This starts the KNotify Daemon, if it's not already started.

This will be useful for games that use sound effects. Run this at the start of the program, and there won't be a pause when it is first triggered.

Returns:
true if daemon is running (always true at the moment)

Definition at line 159 of file knotifyclient.cpp.

References KApplication::startServiceByDesktopName().

bool KNotifyClient::event const QString message,
const QString text = QString::null
 

This should be the most used method in here.

Call it by KNotifyClient::event("EventName"); It will use KApplication::kApplication->dcopClient() to communicate to the server

Parameters:
message The name of the event
text The text to put in a dialog box. This won't be shown if the user connected the event to sound, only. Can be QString::null.
Returns:
true if successful, false otherwise

Definition at line 86 of file knotifyclient.cpp.

Referenced by beep().

bool KNotifyClient::event StandardEvent  event,
const QString text = QString::null
 

Allows to easily emit standard events.

Parameters:
event The event you want to raise.
text The text explaining the event you raise. Can be QString::null.
Returns:
true if successful, false otherwise

Definition at line 60 of file knotifyclient.cpp.

References QString::fromLatin1().

bool KNotifyClient::userEvent const QString text = QString::null,
int  present = Default,
int  level = Default,
const QString sound = QString::null,
const QString file = QString::null
 

Will fire an event that's not registered.

Parameters:
text The error message text, if applicable
present The presentation method(s) of the event
level The error message level, defaulting to "Default"
sound The sound file to play if selected with present
file The log file to play if selected with present
Returns:
true if successful, false otherwise

Definition at line 91 of file knotifyclient.cpp.

Referenced by KAudioPlayer::play().

void KNotifyClient::beep const QString reason = QString::null  ) 
 

This is a simple substitution for QApplication::beep().

It simply calls

KNotifyClient::event( KNotifyClient::notification, reason );
Parameters:
reason the reason, can be QString::null.

Definition at line 167 of file knotifyclient.cpp.

References DCOPClient::attach(), QApplication::beep(), KNotifyClient::Instance::currentInstance(), event(), DCOPClient::isApplicationRegistered(), DCOPClient::isAttached(), and KNotifyClient::Instance::useSystemBell().

int KNotifyClient::getPresentation const QString eventname  ) 
 

Gets the presentation associated with a certain event name Remeber that they may be ORed:.

if (present & KNotifyClient::Sound) { [Yes, sound is a default] }
Parameters:
eventname the event name to check
Returns:
the presentation methods

Definition at line 97 of file knotifyclient.cpp.

References QString::isEmpty(), KConfigBase::readNumEntry(), and KConfigBase::setGroup().

QString KNotifyClient::getFile const QString eventname,
int  present
 

Gets the default file associated with a certain event name The control panel module will list all the event names This has the potential for being slow.

Parameters:
eventname the name of the event
present the presentation method
Returns:
the associated file. Can be QString::null if not found.

Definition at line 110 of file knotifyclient.cpp.

References QString::isEmpty(), KConfigBase::readEntry(), and KConfigBase::setGroup().

int KNotifyClient::getDefaultPresentation const QString eventname  ) 
 

Gets the default presentation for the event of this program.

Remember that the Presentation may be ORed. Try this:

if (present & KNotifyClient::Sound) { [Yes, sound is a default] }
Returns:
the presentation methods

Definition at line 128 of file knotifyclient.cpp.

References QString::isEmpty(), KConfigBase::readNumEntry(), and KConfigBase::setGroup().

QString KNotifyClient::getDefaultFile const QString eventname,
int  present
 

Gets the default File for the event of this program.

It gets it in relation to present. Some events don't apply to this function ("Message Box") Some do (Sound)

Parameters:
eventname the name of the event
present the presentation method
Returns:
the default file. Can be QString::null if not found.

Definition at line 141 of file knotifyclient.cpp.

References QString::isEmpty(), KConfigBase::readEntry(), and KConfigBase::setGroup().

KInstance * KNotifyClient::instance  ) 
 

Shortcut to KNotifyClient::Instance::current() :).

Returns:
the current KInstance.

Definition at line 195 of file knotifyclient.cpp.

References KNotifyClient::Instance::current().

Referenced by KNotifyClient::Instance::Instance().

KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Mon Oct 24 13:05:31 2011 by doxygen 1.3.5 written by Dimitri van Heesch, © 1997-2001