namespace KNotifyClient

# namespace KNotifyClient | This namespace provides a method for issuing events to a KNotifyServer call KNotifyClient::event("eventname"); to issue it. More...
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

- class Instance
- enum { Default = -1, None = 0, Sound = 1, Messagebox = 2, Logfile = 4, Stderr = 8, PassivePopup = 16, Execute = 32 }
- enum { Notification=1, Warning=2, Error=4, Catastrophe=8 }
- enum StandardEvent { cannotOpenFile, notification, warning, fatalError, catastrophe }

#### Public Methods

- bool startDaemon ()
- bool event (const QString &message, const QString &text=QString::null)
- bool event ( StandardEvent event, const QString& text=QString::null )
- bool userEvent (const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null)
- bool event ( int winId, const QString& message, const QString& text = QString::null )
- bool event ( int winId, StandardEvent event, const QString& text = QString::null )
- bool 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)
- KInstance * instance ()

#### Public Members

- Forward InstancePrivate
- Forward InstanceStack

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

- cannotopenfile
- notification
- warning
- fatalerror
- catastrophe

Instance (class) | ### Instance

Makes it possible to use KNotifyClient with a KInstance that is not the application.

Use like this:

     KNotifyClient::Instance(myInstance);
     KNotifyClient::event("MyEvent");

enum { Default = -1, None = 0, Sound = 1, Messagebox = 2, Logfile = 4, Stderr = 8, PassivePopup = 16, Execute = 32 } | ###

Describes the notification method.

enum { Notification=1, Warning=2, Error=4, Catastrophe=8 } | ###

Describes the level of the error.

enum StandardEvent { cannotOpenFile, notification, warning, fatalError, catastrophe } | ### StandardEvent

default events you can use

bool startDaemon () | ### 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)

bool event (const QString &message, const QString &text=QString::null) | ### event

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

bool event ( StandardEvent event, const QString& text=QString::null ) | ### event

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

bool userEvent (const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null) | ### userEvent

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

bool event ( int winId, const QString& message, const QString& text = QString::null ) | ### event

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: true if successful, false otherwise

bool event ( int winId, StandardEvent event, const QString& text = QString::null ) | ### event

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

bool userEvent (int winId, const QString &text=QString::null, int present=Default, int level=Default, const QString &sound=QString::null, const QString &file=QString::null) | ### userEvent

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 play if selected with `present`

Returns: true if successful, false otherwise

void beep (const QString& reason=QString::null) | ### beep

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

     KNotifyClient::event( KNotifyClient::notification, reason );

Parameters:

reason | the reason, can be QString::null.

int getPresentation (const QString &eventname) | ### getPresentation

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

QString getFile (const QString &eventname, int present) | ### getFile

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.

int getDefaultPresentation (const QString &eventname) | ### getDefaultPresentation

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

QString getDefaultFile (const QString &eventname, int present) | ### getDefaultFile

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.

KInstance * instance () | ### instance

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

Returns: the current KInstance.

- Author: Charles Samuels
- Generated: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:15 2003, using kdoc 2.0a54.