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...


Compounds

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,
  Taskbar = 64
}
enum  { Notification = 1, Warning = 2, Error = 4, Catastrophe = 8 }
enum  StandardEvent {
  cannotOpenFile, notification, warning, fatalError,
  catastrophe
}

Functions

bool startDaemon ()
int event (const QString &message, const QString &text=QString::null) KDE_DEPRECATED
int event (StandardEvent event, const QString &text=QString::null) KDE_DEPRECATED
int userEvent (const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null) KDE_DEPRECATED
int event (int winId, const QString &message, const QString &text=QString::null)
int event (int winId, StandardEvent event, const QString &text=QString::null)
int userEvent (int winId, const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null)
void beep (const QString &reason=QString::null)
int getPresentation (const QString &eventname)
QString getFile (const QString &eventname, int present)
int getDefaultPresentation (const QString &eventname)
QString getDefaultFile (const QString &eventname, int present)
KInstanceinstance ()


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_logfile=logfile.txt
 default_commandline=command
 default_presentation=1
  ...
default_presentation contains these ORed events: None=0, Sound=1, Messagebox=2, Logfile=4, Stderr=8, PassivePopup=16, Execute=32, Taskbar=64

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.
Taskbar 
Since:
3.2.

Definition at line 136 of file knotifyclient.h.

anonymous enum
 

Describes the level of the error.

Definition at line 151 of file knotifyclient.h.

enum KNotifyClient::StandardEvent
 

default events you can use.

Definition at line 161 of file knotifyclient.h.

Referenced by event().


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 192 of file knotifyclient.cpp.

References KApplication::startServiceByDesktopName().

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

Deprecated:
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:
a value > 0, unique for this event if successful, 0 otherwise

Definition at line 79 of file knotifyclient.cpp.

Referenced by beep(), and event().

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

Deprecated:
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:
a value > 0, unique for this event if successful, 0 otherwise

Definition at line 74 of file knotifyclient.cpp.

References event(), and StandardEvent.

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

Deprecated:
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 append the message to if selected with present
Returns:
a value > 0, unique for this event if successful, 0 otherwise

Definition at line 84 of file knotifyclient.cpp.

Referenced by KAudioPlayer::play().

int KNotifyClient::event int    winId,
const QString   message,
const QString   text = QString::null
 

This should be the most used method in here.

Pass the origin-widget's winId() here so that a PassivePopup can be placed appropriately.

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

Parameters:
winId  The winId() of the widget where the event originates
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:
a value > 0, unique for this event if successful, 0 otherwise
Since:
3.1.1

Definition at line 117 of file knotifyclient.cpp.

int KNotifyClient::event int    winId,
StandardEvent    event,
const QString   text = QString::null
 

You should pass the origin-widget's winId() here so that a PassivePopup can be placed appropriately.

Parameters:
winId  The winId() of the widget where the event originates
event  The event you want to raise
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:
a value > 0, unique for this event if successful, 0 otherwise
Since:
3.1.1

Definition at line 91 of file knotifyclient.cpp.

References QString::fromLatin1(), and StandardEvent.

int KNotifyClient::userEvent int    winId,
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.

You should pass the origin-widget's winId() here so that a PassivePopup can be placed appropriately.

Parameters:
winId  The winId() of the originating widget
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 append the message to if selected with present
Returns:
a value > 0, unique for this event if successful, 0 otherwise
Since:
3.1.1

Definition at line 123 of file knotifyclient.cpp.

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 203 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 130 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 143 of file knotifyclient.cpp.

References QString::isEmpty(), KConfigBase::readPathEntry(), 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 161 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 174 of file knotifyclient.cpp.

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

KInstance * KNotifyClient::instance  
 

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

Returns:
the current KInstance.

Definition at line 231 of file knotifyclient.cpp.

References KNotifyClient::Instance::current().

Referenced by KIconLoader::BarIcon(), KIconLoader::BarIconSet(), KCrash::defaultCrashHandler(), KIconLoader::DesktopIcon(), KIconLoader::DesktopIconSet(), KCmdLineArgs::enable_i18n(), KLibLoader::findLibrary(), KLocale::i18n(), KIconLoader::IconSize(), KNotifyClient::Instance::Instance(), KIconLoader::MainBarIcon(), KIconLoader::MainBarIconSet(), KIconLoader::SmallIcon(), KIconLoader::SmallIconSet(), KIconLoader::UserIcon(), and KIconLoader::UserIconSet().

KDE Logo
This file is part of the documentation for kdecore Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun May 16 22:01:32 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003