summaryrefslogtreecommitdiffstats
path: root/kdecore/knotifyclient.h
blob: 2de3e297dde7ee347abe4a0a9c5f31cb3f32a9fa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
/* This file is part of the KDE libraries
   Copyright (C) 2000 Charles Samuels <charles@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/
#ifndef _KNOTIFY_CLIENT
#define _KNOTIFY_CLIENT
#include <tqstring.h>
#include "kdelibs_export.h"

class KInstance;
#undef None // X11 headers...

/**
 * 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:
 * \code
 * [!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
 *  ...
 * \endcode
 * 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:
 *
 *<ul>
 * <li>cannotopenfile
 * <li>notification
 * <li>warning
 * <li>fatalerror
 * <li>catastrophe
 *</ul>
 *
 * The events can be configured in an application using KNotifyDialog, which is part of KIO.
 * 
 * @author Charles Samuels <charles@kde.org>
 */


namespace KNotifyClient
{
    struct InstancePrivate;
	class InstanceStack;

    /**
     * Makes it possible to use KNotifyClient with a KInstance
     * that is not the application.
     *
     * Use like this:
     * \code
     * KNotifyClient::Instance(myInstance);
     * KNotifyClient::event("MyEvent");
     * \endcode
     *
     * @short Enables KNotifyClient to use a different KInstance
     */
    class KDECORE_EXPORT Instance
    {
    public:
        /**
         * Constructs a KNotifyClient::Instance to make KNotifyClient use
         * the specified KInstance for the event configuration.
	 * @param instance the instance for the event configuration
         */
        Instance(KInstance *instance);
        /**
         * Destructs the KNotifyClient::Instance and resets KNotifyClient
         * to the previously used KInstance.
         */
        ~Instance();
	/**
	 * Checks whether the system bell should be used.
	 * @returns true if this instance should use the System bell instead
	 * of KNotify.
	 */
	bool useSystemBell() const;
        /**
         * Returns the currently active KInstance.
	 * @return the active KInstance
         */
        static KInstance *current();

	/**
	 * Returns the current KNotifyClient::Instance (not the KInstance).
	 * @return the active Instance
	 */
	static Instance *currentInstance();
	
    private:
		static InstanceStack *instances();
		InstancePrivate *d;
		static InstanceStack *s_instances;
    };


    /**
     * Describes the notification method.
     */
	enum {
		Default = -1,
		None = 0,
		Sound = 1,
		Messagebox = 2,
		Logfile = 4,
		Stderr = 8,
		PassivePopup = 16, ///< @since 3.1
		Execute = 32,      ///< @since 3.1
		Taskbar = 64       ///< @since 3.2
	};

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

	/**
	 * default events you can use
	 */
	enum StandardEvent {
		cannotOpenFile,
		notification,
		warning,
		fatalError,
		catastrophe
	};

	/**
	 * 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.
	 * @return true if daemon is running (always true at the moment)
	 **/
	KDECORE_EXPORT bool startDaemon();

//#ifndef KDE_NO_COMPAT
	/**
	 * @deprecated
	 * @param message The name of the event
	 * @param 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 TQString::null.
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 */
	KDECORE_EXPORT int event(const TQString &message, const TQString &text=TQString::null) KDE_DEPRECATED;

	/**
	 * @deprecated
	 * Allows to easily emit standard events.
	 * @param event The event you want to raise.
	 * @param text The text explaining the event you raise. Can be TQString::null.
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 */
	KDECORE_EXPORT int event( StandardEvent event, const TQString& text=TQString::null ) KDE_DEPRECATED;

	/**
	 * @deprecated
	 * Will fire an event that's not registered.
	 * @param text The error message text, if applicable
	 * @param present The presentation method(s) of the event
	 * @param level The error message level, defaulting to "Default"
	 * @param sound The sound file to play if selected with @p present
	 * @param file The log file to append the message to if selected with @p present
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 */
	KDECORE_EXPORT int userEvent(const TQString &text=TQString::null, int present=Default, int level=Default,
	                             const TQString &sound=TQString::null, const TQString &file=TQString::null) KDE_DEPRECATED;
	
//#endif

	/**
	 * 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
	 * @param winId The winId() of the widget where the event originates
	 * @param message The name of the event
	 * @param 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 TQString::null.
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 * @since 3.1.1
	 */
	// KDE4: use WId instead of int
	KDECORE_EXPORT int event( int winId, const TQString& message,
                              const TQString& text = TQString::null );

	/**
	 * You should
	 * pass the origin-widget's winId() here so that a PassivePopup can be
	 * placed appropriately.
	 * @param winId The winId() of the widget where the event originates
	 * @param event The event you want to raise
	 * @param 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 TQString::null.
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 * @since 3.1.1
	 */
	// KDE4: use WId instead of int
	KDECORE_EXPORT int event( int winId, StandardEvent event,
                              const TQString& text = TQString::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.
	 * @param winId The winId() of the originating widget
	 * @param text The error message text, if applicable
	 * @param present The presentation method(s) of the event
	 * @param level The error message level, defaulting to "Default"
	 * @param sound The sound file to play if selected with @p present
	 * @param file The log file to append the message to if selected with @p present
	 * @return a value > 0, unique for this event if successful, 0 otherwise
	 * @since 3.1.1
	 */
	// KDE4: use WId instead of int
	KDECORE_EXPORT int userEvent(int winId, const TQString &text=TQString::null, int present=Default, int level=Default,
	                      const TQString &sound=TQString::null, const TQString &file=TQString::null);
	
	/**
	 * This is a simple substitution for TQApplication::beep().
	 * It simply calls
	 * \code
	 * KNotifyClient::event( KNotifyClient::notification, reason );
	 * \endcode
	 * @param reason the reason, can be TQString::null.
	 */
	KDECORE_EXPORT void beep(const TQString& reason=TQString::null);

	/**
	 * Gets the presentation associated with a certain event name
	 * Remeber that they may be ORed:
	 * \code
	 * if (present & KNotifyClient::Sound) { [Yes, sound is a default] }	
	 * \endcode
	 * @param eventname the event name to check
	 * @return the presentation methods
	 */
	KDECORE_EXPORT int getPresentation(const TQString &eventname);
	
	/**
	 * 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.
	 * @param eventname the name of the event
	 * @param present the presentation method
	 * @return the associated file. Can be TQString::null if not found.
	 */
	KDECORE_EXPORT TQString getFile(const TQString &eventname, int present);
	
	/**
	 * Gets the default presentation for the event of this program.
	 * Remember that the Presentation may be ORed.  Try this:
	 * \code
	 * if (present & KNotifyClient::Sound) { [Yes, sound is a default] }
	 * \endcode
	 * @return the presentation methods
	 */
	KDECORE_EXPORT int getDefaultPresentation(const TQString &eventname);
	
	/**
	 * 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)
	 * @param eventname the name of the event
	 * @param present the presentation method
	 * @return the default file. Can be TQString::null if not found.
	 */
	KDECORE_EXPORT TQString getDefaultFile(const TQString &eventname, int present);

	/**
	 * Shortcut to KNotifyClient::Instance::current() :)
	 * @returns the current KInstance.
	 */
	KDECORE_EXPORT KInstance * instance();
}

#endif