Changeset View
Changeset View
Standalone View
Standalone View
src/knotification.h
Show All 28 Lines | |||||
29 | #include <QtCore/QUrl> | 29 | #include <QtCore/QUrl> | ||
30 | 30 | | |||
31 | class QWidget; | 31 | class QWidget; | ||
32 | class QDBusError; | 32 | class QDBusError; | ||
33 | 33 | | |||
34 | /** | 34 | /** | ||
35 | * KNotification is used to notify the user of an event. | 35 | * KNotification is used to notify the user of an event. | ||
36 | * | 36 | * | ||
37 | * \section introduction | 37 | * \section Introduction | ||
38 | * | 38 | * | ||
39 | * There are two main kinds of notifications: | 39 | * There are two main kinds of notifications: | ||
40 | * | 40 | * | ||
41 | * @li Feedback events: | 41 | * @li Feedback events: | ||
42 | * For notifying the user that he/she just performed an operation, like maximizing a | 42 | * For notifying the user that he/she just performed an operation, like maximizing a | ||
43 | * window. This allows us to play sounds when a dialog appears. | 43 | * window. This allows us to play sounds when a dialog appears. | ||
44 | * This is an instant notification. It ends automatically after a small timeout. | 44 | * This is an instant notification. It ends automatically after a small timeout. | ||
45 | * | 45 | * | ||
46 | * @li persistant notifications: | 46 | * @li persistant notifications: | ||
47 | * Notify when the user received a new message, or when something else important happened | 47 | * Notify when the user received a new message, or when something else important happened | ||
48 | * the user has to know about. This notification has a start and a end. It begins when | 48 | * the user has to know about. This notification has a start and a end. It begins when | ||
49 | * the event actually occurs, and finishes when the message is acknowledged or read. | 49 | * the event actually occurs, and finishes when the message is acknowledged or read. | ||
50 | * | 50 | * | ||
51 | * Example of a persistent notification in an instant messaging application: | 51 | * Example of a persistent notification in an instant messaging application: | ||
52 | * The application emits the notification when the message is actually received, and closes it only | 52 | * The application emits the notification when the message is actually received, and closes it only | ||
53 | * when the user has read the message (when the message window has received the focus) using the close() slot | 53 | * when the user has read the message (when the message window has received the focus) using the close() slot. | ||
54 | * Persistent notifications must have the Persistent flag. | 54 | * Persistent notifications must have the Persistent flag. | ||
55 | * | 55 | * | ||
56 | * By default a notification will use the application name as title, but you | 56 | * By default a notification will use the application name as title, but you | ||
57 | * can also provide a brief text in the title and a more precise description in | 57 | * can also provide a brief text in the title and a more precise description in | ||
58 | * the body text. This is especially useful for notifications coming from | 58 | * the body text. This is especially useful for notifications coming from | ||
59 | * applications which should be considered "part of the system", like a battery | 59 | * applications which should be considered "part of the system", like a battery | ||
60 | * monitor or a network connection manager. | 60 | * monitor or a network connection manager. | ||
61 | * For example a battery indicator could use "Low Battery" as a title and "Only | 61 | * For example a battery indicator could use "Low Battery" as a title and "Only | ||
62 | * 12 minutes left." as a body text. | 62 | * 12 minutes left." as a body text. | ||
63 | * | 63 | * | ||
64 | * In order to perform a notification, you need to create a description file, which contains | 64 | * In order to perform a notification, you need to create a description file, which contains | ||
65 | * default parameters of the notification, and use KNotification::event at the place in the | 65 | * default parameters of the notification, and use KNotification::event at the place in the | ||
66 | * application code where the notification occurs. | 66 | * application code where the notification occurs. | ||
67 | * The returned KNotification pointer may be used to connect signals or slots | 67 | * The returned KNotification pointer may be used to connect signals or slots | ||
68 | * | 68 | * | ||
69 | * \section file The global config file | 69 | * \section file The global config file | ||
70 | * Your application should install a file called <em>knotifications5/appname.notifyrc</em> | 70 | * Your application should install a file called <em>knotifications5/appname.notifyrc</em> | ||
71 | * in a QStandardPaths::GenericDataLocation directory. | 71 | * in a QStandardPaths::GenericDataLocation directory. | ||
72 | * | 72 | * | ||
73 | * The filename should either match QCoreApplication::applicationName or be specified as the | 73 | * The filename must either match QCoreApplication::applicationName or be specified as the | ||
74 | * component name to the KNotification object. | 74 | * component name to the KNotification object. | ||
75 | * @warning Notifications won't be visible otherwise. | ||||
75 | * | 76 | * | ||
76 | * You can do this with the following CMake command: | 77 | * You can do this with the following CMake command: | ||
77 | * install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR})) | 78 | * install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR})) | ||
78 | * | 79 | * | ||
79 | * This file contains mainly 3 parts | 80 | * This file contains mainly 3 parts | ||
80 | * <ol><li>\ref global "Global information"</li> | 81 | * <ol><li>\ref global "Global information"</li> | ||
81 | * <li>\ref context "Context information"</li> | 82 | * <li>\ref context "Context information"</li> | ||
82 | * <li>\ref events "Definition of individual events"</li></ol> | 83 | * <li>\ref events "Definition of individual events"</li></ol> | ||
▲ Show 20 Lines • Show All 441 Lines • ▼ Show 20 Line(s) | 522 | Q_SIGNALS: | |||
524 | */ | 525 | */ | ||
525 | void activated(); | 526 | void activated(); | ||
526 | /** | 527 | /** | ||
527 | * Emitted when an action has been activated. | 528 | * Emitted when an action has been activated. | ||
528 | * | 529 | * | ||
529 | * The parameter passed by the signal is the index of the action | 530 | * The parameter passed by the signal is the index of the action | ||
530 | * in the QStringList set by setActions() call. | 531 | * in the QStringList set by setActions() call. | ||
531 | * | 532 | * | ||
532 | * @param action will be 0 is the default aciton was activated, or the index of the action in the actions QStringList | 533 | * @param action will be 0 if the default aciton was activated, or the index of the action in the actions QStringList | ||
533 | */ | 534 | */ | ||
534 | void activated(unsigned int action); | 535 | void activated(unsigned int action); | ||
535 | 536 | | |||
536 | /** | 537 | /** | ||
537 | * Convenience signal that is emitted when the first action is activated. | 538 | * Convenience signal that is emitted when the first action is activated. | ||
538 | */ | 539 | */ | ||
539 | void action1Activated(); | 540 | void action1Activated(); | ||
540 | 541 | | |||
▲ Show 20 Lines • Show All 246 Lines • Show Last 20 Lines |