diff --git a/src/knotification.h b/src/knotification.h index 0657a78..1bd76fe 100644 --- a/src/knotification.h +++ b/src/knotification.h @@ -1,789 +1,789 @@ /* This file is part of the KDE libraries Copyright (C) 2005-2006 Olivier Goffart Copyright (C) 2013-2015 Martin Klapetek 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 KNOTIFICATION_H #define KNOTIFICATION_H #include #include #include #include #include #include class QWidget; class QDBusError; /** * @class KNotification knotification.h KNotification * * KNotification is used to notify the user of an event. * * \section Introduction * * There are two main kinds of notifications: * * @li Feedback events: * For notifying the user that he/she just performed an operation, like maximizing a * window. This allows us to play sounds when a dialog appears. * This is an instant notification. It ends automatically after a small timeout. * * @li persistant notifications: * Notify when the user received a new message, or when something else important happened * the user has to know about. This notification has a start and a end. It begins when * the event actually occurs, and finishes when the message is acknowledged or read. * * Example of a persistent notification in an instant messaging application: * The application emits the notification when the message is actually received, and closes it only * when the user has read the message (when the message window has received the focus) using the close() slot. * Persistent notifications must have the Persistent flag. * * By default a notification will use the application name as title, but you * can also provide a brief text in the title and a more precise description in * the body text. This is especially useful for notifications coming from * applications which should be considered "part of the system", like a battery * monitor or a network connection manager. * For example a battery indicator could use "Low Battery" as a title and "Only * 12 minutes left." as a body text. * * In order to perform a notification, you need to create a description file, which contains * default parameters of the notification, and use KNotification::event at the place in the * application code where the notification occurs. * The returned KNotification pointer may be used to connect signals or slots * * \section file The global config file * Your application should install a file called knotifications5/appname.notifyrc * in a QStandardPaths::GenericDataLocation directory. * * The filename must either match QCoreApplication::applicationName or be specified as the * component name to the KNotification object. * @warning Notifications won't be visible otherwise. * * You can do this with the following CMake command: * install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR})) * * This file contains mainly 3 parts *
  1. \ref global "Global information"
    2. *
  2. \ref context "Context information"
    3. *
  3. \ref events "Definition of individual events"
* * \subsection global Global information * The global part looks like that * 
            [Global]
            IconName=Filename
            Comment=Friendly Name of app
            Name=Name of app
  *
* The icon filename is just the name, without extension, it's found with the KIconLoader. * The Comment field will be used in KControl to describe the application. * The Name field is optional and may be used as the application name for popup, * if Name is not present, Comment is used instead * * \subsection context Context information * * This part consists of hints for the configuration widget * 
            [Context/group]
            Name=Group name
            Comment=The name of the group for contacts
 
            [Context/folder]
            Name=Group name
  *
* The second part of the groupname is the context identifier. * It should not contain special characters. * The Name field is the one the user will see (and which is translated) * * \subsection events Definition of Events * * The definition of the events forms the most important part of the config file * 
            [Event/newmail]
            Name=New email
            Comment=You have got a new email
            Contexts=folder,group
            Action=Sound|Popup
 
            [Event/contactOnline]
            Name=Contact goes online
            Comment=One of your contact has been connected
            Contexts=group
            Sound=filetoplay.ogg
            Action=None
  *
* These are the default settings for each notifiable event. * Action is the string representing the action. Actions can be added to * KNotification as plugins, by deriving from KNotificationPlugin. * At the time of writing, the following actions are available: Taskbar, * Sound, Popup, Logfile, TTS, Execute. * Actions can be combined by seperating them with '|'. * * Contexts is a comma separated list of possible context for this event. * * \section userfile The user's config file * * This is an implementation detail, and is described here for your information. * * In the config file, there are two parts: the event configuration, and the context information * \subsection context Context information * These are hints for the configuration dialog. They contain both the internal id of the context, and the user visible string. * 
            [Context/group]
            Values=1:Friends,2:Work,3:Family
  *
* \subsection event Events configuration * This contains the configuration of events for the user. * It contains the same fields as the description file. * The key of groups is in the form * Event/<EventName>/<ContextName>/<ContextValue> * 
            [Event/contactOnline]
            Action=Sound
            Sound=/usr/share/sounds/super.ogg
 
            [Event/contactOnline/group/1]
            Action=Popup|Sound
  *
* * \section example Example of code * * This portion of code will fire the event for the "contactOnline" event * * @code KNotification *notification= new KNotification ( "contactOnline", widget ); notification->setText( i18n("The contact %1 has gone online", contact->name() ); notification->setPixmap( contact->pixmap() ); notification->setActions( QStringList( i18n( "Open chat" ) ) ); foreach( const QString &group , contact->groups() ) { notification->addContext( "group" , group ) ; } connect(notification, SIGNAL(activated(unsigned int )), contact , SLOT(slotOpenChat()) ); notification->sendEvent(); * @endcode * * @author Olivier Goffart \ */ class KNOTIFICATIONS_EXPORT KNotification : public QObject { Q_OBJECT public: /** * Sometimes the user may want different notifications for the same event, * depending the source of the event. Example, you want to be notified for mails * that arrive in your folder "personal inbox" but not for those in "spam" folder * * A notification context is a pair of two strings. * The first string is a key from what the context is. example "group" or * "filter" (not translated). * The second is the id of the context. In our example, the group id or the * filter id in the applications. * These strings are the ones present in the config file, and are in theory not * shown in the user interface. * * The order of contexts in the list is is important, the most important context * should be placed first. They are processed in that order when the notification occurs. * * @see event */ typedef QPair Context; typedef QList< Context > ContextList; enum NotificationFlag { /** * When the notification is activated, raise the notification's widget. * * This will change the desktop, raise the window, and switch to the tab. * @todo doesn't work yet */ RaiseWidgetOnActivation = 0x01, /** * The notification will be automatically closed after a timeout. (this is the default) */ CloseOnTimeout = 0x00, /** * The notification will NOT be automatically closed after a timeout. * You will have to track the notification, and close it with the * close function manually when the event is done, otherwise there will be a memory leak */ Persistent = 0x02, /** * The notification will be automatically closed if the widget() becomes * activated. * * If the widget is already activated when the notification occurs, the * notification will be closed after a small timeout. * * This only works if the widget is the toplevel widget * @todo make it work with tabulated widget */ CloseWhenWidgetActivated = 0x04, /** * The audio plugin will loop the sound until the notification is closed */ LoopSound = 0x08, /** * Sends a hint to Plasma to skip grouping for this notification * * @since: 5.18 */ SkipGrouping = 0x10, /** * @internal * The event is a standard kde event, and not an event of the application */ DefaultEvent = 0xF000 }; Q_DECLARE_FLAGS(NotificationFlags, NotificationFlag) /** * default events you can use in the event function */ enum StandardEvent { Notification, Warning, Error, Catastrophe }; /** * Create a new notification. * * You have to use sendEvent to show the notification. * * The pointer is automatically deleted when the event is closed. * * Make sure you use one of the NotificationFlags CloseOnTimeOut or * CloseWhenWidgetActivated, if not, * you have to close the notification yourself. * * @param eventId is the name of the event * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag */ explicit KNotification(const QString &eventId, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout); /** * Create a new notification. * * You have to use sendEvent to show the notification. * * The pointer is automatically deleted when the event is closed. * * Make sure you use one of the NotificationFlags CloseOnTimeOut or * CloseWhenWidgetActivated, if not, * you have to close the notification yourself. * * @since 4.4 * * @param eventId is the name of the event * @param flags is a bitmask of NotificationFlag * @param parent parent object */ // KDE5: Clean up this mess // Only this constructor should stay with saner argument order and // defaults. Because of binary and source compatibility issues it has to // stay this way for now. The second argument CANNOT have a default // argument. if someone needs a widget associated with the notification he // should use setWidget after creating the object (or some xyz_cast magic) explicit KNotification(const QString &eventId, const NotificationFlags &flags, QObject *parent = nullptr); ~KNotification(); /** * @brief the widget associated to the notification * * If the widget is destroyed, the notification will be automatically cancelled. * If the widget is activated, the notification will be automatically closed if the NotificationFlags specify that * * When the notification is activated, the widget might be raised. * Depending on the configuration, the taskbar entry of the window containing the widget may blink. */ QWidget *widget() const; /** * Set the widget associated to the notification. * The notification is reparented to the new widget. * \see widget() * @param widget the new widget */ void setWidget(QWidget *widget); /** * @return the name of the event */ QString eventId() const; /** * @return the notification title * @see setTitle * @since 4.3 */ QString title() const; /** * Set the title of the notification popup. * If no title is set, the application name will be used. * * @param title The title of the notification * @since 4.3 */ void setTitle(const QString &title); /** * @return the notification text * @see setText */ QString text() const; /** * Set the notification text that will appear in the popup. * * In Plasma workspace, the text is shown in a QML label which uses Text.StyledText, * ie. it supports a small subset of HTML entities (mostly just formatting tags) * * If the notifications server does not advertise "body-markup" capability, * all HTML tags are stripped before sending it to the server * * @param text The text to display in the notification popup */ void setText(const QString &text); /** * \return the icon shown in the popup * \see setIconName * \since 5.4 */ QString iconName() const; /** * Set the icon that will be shown in the popup. * * @param icon the icon * @since 5.4 */ void setIconName(const QString &icon); /** * \return the pixmap shown in the popup * \see setPixmap */ QPixmap pixmap() const; /** * Set the pixmap that will be shown in the popup. * * @param pix the pixmap */ void setPixmap(const QPixmap &pix); /** * @return the default action, or an empty string if not set * @since 5.31 */ QString defaultAction() const; /** * Set a default action that will be triggered when the notification is * activated (typically, by clicking on the notification popup). The default * action should raise a window belonging to the application that sent it. * * The string will be used as a label for the action, so ideally it should * be wrapped in i18n() or tr() calls. * * The visual representation of actions depends on the notification server. * In Plasma and Gnome desktops, the actions are performed by clicking on * the notification popup, and the label is not presented to the user. * * * @param action Label of the default action. The label might or might not * be displayed to the user by the notification server, depending on the * implementation. Passing an empty string disables the default action. * @since 5.31 */ void setDefaultAction(const QString &defaultAction); /** * @return the list of actions */ //KF6: Rename to "additionalActions"? QStringList actions() const; /** * Set the list of actions shown in the popup. The strings passed * in that QStringList will be used as labels for those actions, * so ideally they should be wrapped in i18n() or tr() calls. * In Plasma workspace, these will be shown as buttons inside * the notification popup. * * The visual representation of actions however depends * on the notification server * * @param actions List of strings used as action labels */ //KF6: Rename to "setAdditionalActions"? void setActions(const QStringList &actions); /** * @return the list of contexts, see KNotification::Context */ ContextList contexts() const; /** * set the list of contexts, see KNotification::Context * * The list of contexts must be set before calling sendEvent; */ void setContexts(const ContextList &contexts); /** * append a context at the list of contexts, see KNotificaiton::Context * @param context the context which is added */ void addContext(const Context &context); /** * @overload * @param context_key is the key of the context * @param context_value is the value of the context */ void addContext(const QString &context_key, const QString &context_value); /** * @return the notification flags. */ NotificationFlags flags() const; /** * Set the notification flags. * These must be set before calling sendEvent() */ void setFlags(const NotificationFlags &flags); /** * The componentData is used to determine the location of the config file. * * If no componentName is set, the app name is used by default * * @param componentName the new component name */ void setComponentName(const QString &componentName); /** * URLs associated with this notification * @since 5.29 */ QList urls() const; /** * Sets URLs associated with this notification * * For example, a screenshot application might want to provide the * URL to the file that was just taken so the notification service * can show a preview. * * @note This feature might not be supported by the user's notification service * * @param urls A list of URLs * @since 5.29 */ void setUrls(const QList &urls); /** * @internal * the id given by the notification manager */ int id(); /** * @internal - * appname used for the dbus object + * appname used for the D-Bus object */ QString appName() const; Q_SIGNALS: /** * Emitted only when the default activation has occurred */ void activated(); /** * Emitted when an action has been activated. * * The parameter passed by the signal is the index of the action * in the QStringList set by setActions() call. * * @param action will be 0 if the default aciton was activated, or the index of the action in the actions QStringList */ void activated(unsigned int action); /** * Convenience signal that is emitted when the first action is activated. */ void action1Activated(); /** * \overload */ void action2Activated(); /** * \overload */ void action3Activated(); /** * Emitted when the notification is closed. * * Can be closed either by the user clicking the close button, * the timeout running out or when an action was triggered. */ void closed(); /** * The notification has been ignored */ void ignored(); public Q_SLOTS: /** * @brief Activate the action specified action * If the action is zero, then the default action is activated */ void activate(unsigned int action = 0); /** * Close the notification without activating it. * * This will delete the notification. */ void close(); /** * @brief Raise the widget. * This will change the desktop, activate the window, and the tab if needed. */ void raiseWidget(); /** * The notification will automatically be closed if all presentations are finished. * if you want to show your own presentation in your application, you should use this * function, so it will not be automatically closed when there is nothing to show. * * Don't forgot to deref, or the notification may be never closed if there is no timeout. * * @see deref */ void ref(); /** * Remove a reference made with ref(). If the ref counter hits zero, * the notification will be closed and deleted. * * @see ref */ void deref(); /** * Send the notification to the server. * * This will cause all the configured plugins to execute their actions on this notification * (eg. a sound will play, a popup will show, a command will be executed etc). */ void sendEvent(); /** * @internal * update the texts, the icon, and the actions of one existing notification */ void update(); private: struct Private; Private *const d; protected: /** * reimplemented for internal reasons */ bool eventFilter(QObject *watched, QEvent *event) Q_DECL_OVERRIDE; static QString standardEventToEventId(StandardEvent event); static QString standardEventToIconName(StandardEvent event); public: /** * @brief emit an event * * This method creates the KNotification, setting every parameter, and fire the event. * You don't need to call sendEvent * * A popup may be displayed or a sound may be played, depending the config. * * @return a KNotification . You may use that pointer to connect some signals or slot. * the pointer is automatically deleted when the event is closed. * * Make sure you use one of the CloseOnTimeOut or CloseWhenWidgetActivated, if not, * you have to close yourself the notification. * * @note the text is shown in a QLabel, you should escape HTML, if needed. * * @param eventId is the name of the event * @param title is title of the notification to show in the popup. * @param text is the text of the notification to show in the popup. * @param pixmap is a picture which may be shown in the popup. * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @param componentName used to determine the location of the config file. by default, appname is used * @since 4.4 */ static KNotification *event(const QString &eventId, const QString &title, const QString &text, const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString()); /** * @brief emit a standard event * * @overload * * This will emit a standard event * * @param eventId is the name of the event * @param text is the text of the notification to show in the popup. * @param pixmap is a picture which may be shown in the popup. * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @param componentName used to determine the location of the config file. by default, plasma_workspace is used */ static KNotification *event(const QString &eventId, const QString &text = QString(), const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString()); /** * @brief emit a standard event * * @overload * * This will emit a standard event * * @param eventId is the name of the event * @param text is the text of the notification to show in the popup * @param pixmap is a picture which may be shown in the popup * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag */ static KNotification *event(StandardEvent eventId, const QString &text = QString(), const QPixmap &pixmap = QPixmap(), QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout); /** * @brief emit a standard event * * @overload * * This will emit a standard event * * @param eventId is the name of the event * @param title is title of the notification to show in the popup. * @param text is the text of the notification to show in the popup * @param pixmap is a picture which may be shown in the popup * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @since 4.4 */ static KNotification *event(StandardEvent eventId, const QString &title, const QString &text, const QPixmap &pixmap, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout); /** * @brief emit a standard event with the possibility of setting an icon by icon name * * @overload * * This will emit a standard event * * @param eventId is the name of the event * @param title is title of the notification to show in the popup. * @param text is the text of the notification to show in the popup * @param iconName a Freedesktop compatible icon name to be shown in the popup * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @param componentName used to determine the location of the config file. by default, plasma_workspace is used * @since 5.4 */ static KNotification *event(const QString &eventId, const QString &title, const QString &text, const QString &iconName, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout, const QString &componentName = QString()); /** * @brief emit a standard event with the possibility of setting an icon by icon name * * @overload * * This will emit a standard event with a custom icon * * @param eventId the type of the standard (not app-defined) event * @param title is title of the notification to show in the popup. * @param text is the text of the notification to show in the popup * @param iconName a Freedesktop compatible icon name to be shown in the popup * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @since 5.9 */ static KNotification *event(StandardEvent eventId, const QString &title, const QString &text, const QString &iconName, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout); /** * @brief emit a standard event * * @overload * * This will emit a standard event with its standard icon * * @param eventId the type of the standard (not app-defined) event * @param title is title of the notification to show in the popup. * @param text is the text of the notification to show in the popup * @param widget is a widget where the notification reports to * @param flags is a bitmask of NotificationFlag * @since 5.9 */ static KNotification *event(StandardEvent eventId, const QString &title, const QString &text, QWidget *widget = nullptr, const NotificationFlags &flags = CloseOnTimeout); /** * This is a simple substitution for QApplication::beep() * * @param reason a short text explaining what has happened (may be empty) * @param widget the widget the notification refers to */ static void beep(const QString &reason = QString(), QWidget *widget = nullptr); //prevent warning using QObject::event; }; Q_DECLARE_OPERATORS_FOR_FLAGS(KNotification::NotificationFlags) #endif diff --git a/src/kstatusnotifieritem.h b/src/kstatusnotifieritem.h index 9fe1589..c0d82d6 100644 --- a/src/kstatusnotifieritem.h +++ b/src/kstatusnotifieritem.h @@ -1,499 +1,499 @@ /* This file is part of the KDE libraries Copyright 2009 by Marco Martin This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License (LGPL) as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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 KSTATUSNOTIFIERITEM_H #define KSTATUSNOTIFIERITEM_H #include #include #include #include #include class QAction; class QMenu; class KStatusNotifierItemPrivate; /** * @class KStatusNotifierItem kstatusnotifieritem.h KStatusNotifierItem * * \brief %KDE Status notifier Item protocol implementation * - * This class implements the Status notifier Item Dbus specification. + * This class implements the Status notifier Item D-Bus specification. * It provides an icon similar to the classical systemtray icons, * with some key differences: * * - the actual representation is done by the systemtray (or the app behaving * like it) itself, not by this app. Since 4.5 this also includes the menu, * which means you cannot use embed widgets in the menu. * * - there is communication between the systemtray and the icon owner, so the * system tray can know if the application is in a normal or in a requesting * attention state. * * - icons are divided in categories, so the systemtray can represent in a * different way the icons from normal applications and for instance the ones * about hardware status. * * Whenever possible you should prefer passing icon by name rather than by * pixmap because: * - * - it is much lighter on Dbus (no need to pass all image pixels). + * - it is much lighter on D-Bus (no need to pass all image pixels). * * - it makes it possible for the systemtray to load an icon of the appropriate * size or to replace your icon with a systemtray specific icon which matches * with the desktop theme. * * - some implementations of the system tray do not support passing icons by * pixmap and will show a blank icon instead. * * @author Marco Martin * @since 4.4 */ class KNOTIFICATIONS_EXPORT KStatusNotifierItem : public QObject { Q_OBJECT Q_PROPERTY(ItemCategory category READ category WRITE setCategory) Q_PROPERTY(QString title READ title WRITE setTitle) Q_PROPERTY(ItemStatus status READ status WRITE setStatus) Q_PROPERTY(QString iconName READ iconName WRITE setIconByName) Q_PROPERTY(QString overlayIconName READ overlayIconName WRITE setOverlayIconByName) Q_PROPERTY(QString attentionIconName READ attentionIconName WRITE setAttentionIconByName) Q_PROPERTY(QString toolTipIconName READ toolTipIconName WRITE setToolTipIconByName) Q_PROPERTY(QString toolTipTitle READ toolTipTitle WRITE setToolTipTitle) Q_PROPERTY(QString toolTipSubTitle READ toolTipSubTitle WRITE setToolTipSubTitle) friend class KStatusNotifierItemDBus; friend class KStatusNotifierItemPrivate; public: /** * All the possible status this icon can have, depending on the * importance of the events that happens in the parent application */ enum ItemStatus { /// Nothing is happening in the application, so showing this icon is not required Passive = 1, /// The application is doing something, or it is important that the /// icon is always reachable from the user Active = 2, /// The application requests the attention of the user, for instance /// battery running out or a new IM message was received NeedsAttention = 3 }; Q_ENUM(ItemStatus) /** * Different kinds of applications announce their type to the systemtray, * so can be drawn in a different way or in a different place */ enum ItemCategory { /// An icon for a normal application, can be seen as its taskbar entry ApplicationStatus = 1, /// This is a communication oriented application; this icon will be used /// for things such as the notification of a new message Communications = 2, /// This is a system service, it can show itself in the system tray if /// it requires interaction from the user or wants to inform him about /// something SystemServices = 3, /// This application shows hardware status or a means to control it Hardware = 4, Reserved = 129 }; Q_ENUM(ItemCategory) /** * Construct a new status notifier item * * @param parent the parent object for this object. If the object passed in as * a parent is also a QWidget, it will be used as the main application window * represented by this icon and will be shown/hidden when an activation is requested. * @see associatedWidget **/ explicit KStatusNotifierItem(QObject *parent = nullptr); /** * Construct a new status notifier item with a unique identifier. * If your application has more than one status notifier item and the user * should be able to manipulate them separately (e.g. mark them for hiding * in a user interface), the id can be used to differentiate between them. * * The id should remain consistent even between application restarts. * Status notifier items without ids default to the application's name for the id. * This id may be used, for instance, by hosts displaying status notifier items to * associate configuration information with this item in a way that can persist * between sessions or application restarts. * * @param id the unique id for this icon * @param parent the parent object for this object. If the object passed in as * a parent is also a QWidget, it will be used as the main application window * represented by this icon and will be shown/hidden when an activation is requested. * @see associatedWidget **/ explicit KStatusNotifierItem(const QString &id, QObject *parent = nullptr); ~KStatusNotifierItem(); /** * @return The id which was specified in the constructor. This should be * guaranteed to be consistent between application starts and * untranslated, as host applications displaying items may use it for * storing configuration related to this item. */ QString id() const; /** * Sets the category for this icon, usually it's needed to call this function only once * * @param category the new category for this icon */ void setCategory(const ItemCategory category); /** * @return the application category */ ItemCategory category() const; /** * Sets a title for this icon */ void setTitle(const QString &title); /** * @return the title of this icon */ QString title() const; /** * Sets a new status for this icon. */ void setStatus(const ItemStatus status); /** * @return the current application status */ ItemStatus status() const; //Main icon related functions /** * Sets a new main icon for the system tray * * @param name it must be a QIcon::fromTheme compatible name, this is * the preferred way to set an icon */ void setIconByName(const QString &name); /** * @return the name of the main icon to be displayed * if image() is not empty this will always return an empty string */ QString iconName() const; /** * Sets a new main icon for the system tray * * @param pixmap our icon, use setIcon(const QString) when possible */ void setIconByPixmap(const QIcon &icon); /** * @return a pixmap of the icon */ QIcon iconPixmap() const; /** * Sets an icon to be used as overlay for the main one * @param icon name, if name is and empty QString() * (and overlayIconPixmap() is empty too) the icon will be removed */ void setOverlayIconByName(const QString &name); /** * @return the name of the icon to be used as overlay fr the main one */ QString overlayIconName() const; /** * Sets an icon to be used as overlay for the main one * setOverlayIconByPixmap(QIcon()) will remove the overlay when * overlayIconName() is empty too. * * @param pixmap our overlay icon, use setOverlayIcon(const QString) when possible. */ void setOverlayIconByPixmap(const QIcon &icon); /** * @return a pixmap of the icon */ QIcon overlayIconPixmap() const; //Requesting attention icon /** * Sets a new icon that should be used when the application * wants to request attention (usually the systemtray * will blink between this icon and the main one) * * @param name QIcon::fromTheme compatible name of icon to use */ void setAttentionIconByName(const QString &name); /** * @return the name of the icon to be displayed when the application * is requesting the user's attention * if attentionImage() is not empty this will always return an empty string */ QString attentionIconName() const; /** * Sets the pixmap of the requesting attention icon. * Use setAttentionIcon(const QString) instead when possible. * * @param icon QIcon to use for requesting attention. */ void setAttentionIconByPixmap(const QIcon &icon); /** * @return a pixmap of the requesting attention icon */ QIcon attentionIconPixmap() const; /** * Sets a movie as the requesting attention icon. * This overrides anything set in setAttentionIcon() */ void setAttentionMovieByName(const QString &name); /** * @return the name of the movie to be displayed when the application is * requesting the user attention */ QString attentionMovieName() const; //ToolTip handling /** * Sets a new toolTip or this icon, a toolTip is composed of an icon, * a title and a text, all fields are optional. * * @param iconName a QIcon::fromTheme compatible name for the tootip icon * @param title tootip title * @param subTitle subtitle for the toolTip */ void setToolTip(const QString &iconName, const QString &title, const QString &subTitle); /** * Sets a new toolTip or this status notifier item. * This is an overloaded member provided for convenience */ void setToolTip(const QIcon &icon, const QString &title, const QString &subTitle); /** * Set a new icon for the toolTip * * @param name the name for the icon */ void setToolTipIconByName(const QString &name); /** * @return the name of the toolTip icon * if toolTipImage() is not empty this will always return an empty string */ QString toolTipIconName() const; /** * Set a new icon for the toolTip. * * Use setToolTipIconByName(QString) if possible. * @param pixmap representing the icon */ void setToolTipIconByPixmap(const QIcon &icon); /** * @return a serialization of the toolTip icon data */ QIcon toolTipIconPixmap() const; /** * Sets a new title for the toolTip */ void setToolTipTitle(const QString &title); /** * @return the title of the main icon toolTip */ QString toolTipTitle() const; /** * Sets a new subtitle for the toolTip */ void setToolTipSubTitle(const QString &subTitle); /** * @return the subtitle of the main icon toolTip */ QString toolTipSubTitle() const; /** * Sets a new context menu for this StatusNotifierItem. * the menu will be shown with a contextMenu(int,int) - * call by the systemtray over dbus + * call by the systemtray over D-Bus * usually you don't need to call this unless you want to use * a custom QMenu subclass as context menu. * * The KStatusNotifierItem instance takes ownerhip of the menu, * and will delete it upon its destruction. */ void setContextMenu(QMenu *menu); /** * Access the context menu associated to this status notifier item */ QMenu *contextMenu() const; /** * Sets the main widget associated with this StatusNotifierItem * * If you pass contextMenu() as a parent then the menu will be displayed * when the user activate the icon. In this case the activate() method will * not be called and the activateRequested() signal will not be emitted * * @param parent the new main widget: must be a top level window, * if it's not parent->window() will be used instead. */ void setAssociatedWidget(QWidget *parent); /** * Access the main widget associated with this StatusNotifierItem */ QWidget *associatedWidget() const; /** * All the actions present in the menu */ QList actionCollection() const; /** * Adds an action to the actionCollection() * * @param name the name of the action * @param action the action we want to add */ void addAction(const QString &name, QAction *action); /** * Removes an action from the collection * * @param name the name of the action */ void removeAction(const QString &name); /** * Retrieves an action from the action collection * by the action name * * @param name the name of the action to retrieve * @since 5.12 */ QAction *action(const QString &name) const; /** * Sets whether to show the standard items in the menu, such as Quit */ void setStandardActionsEnabled(bool enabled); /** * @return if the standard items in the menu, such as Quit */ bool standardActionsEnabled() const; /** * Shows the user a notification. If possible use KNotify instead * * @param title message title * @param message the actual text shown to the user * @param icon icon to be shown to the user * @param timeout how much time will elaps before hiding the message */ void showMessage(const QString &title, const QString &message, const QString &icon, int timeout = 10000); public Q_SLOTS: /** * Shows the main widget and try to position it on top * of the other windows, if the widget is already visible, hide it. * * @param pos if it's a valid position it represents the mouse coordinates when the event was triggered */ virtual void activate(const QPoint &pos = QPoint()); Q_SIGNALS: /** * Inform the host application that the mouse wheel * (or another mean of scrolling that the visualization provides) has been used * * @param delta the amount of scrolling, can be either positive or negative * @param orientation direction of the scrolling, can be either horizontal or vertical */ void scrollRequested(int delta, Qt::Orientation orientation); /** * Inform the host application that an activation has been requested, * for instance left mouse click, but this is not guaranteed since * it's dependent from the visualization * @param active if it's true the application asked for the activatin * of the main window, if it's false it asked for hiding * @param pos the position in the screen where the user clicked to * trigger this signal, QPoint() if it's not the consequence of a mouse click. */ void activateRequested(bool active, const QPoint &pos); /** * Alternate activate action, * for instance right mouse click, but this is not guaranteed since * it's dependent from the visualization * * @param pos the position in the screen where the user clicked to * trigger this signal, QPoint() if it's not the consequence of a mouse click. */ void secondaryActivateRequested(const QPoint &pos); protected: bool eventFilter(QObject *watched, QEvent *event) Q_DECL_OVERRIDE; private: KStatusNotifierItemPrivate *const d; Q_PRIVATE_SLOT(d, void serviceChange(const QString &name, const QString &oldOwner, const QString &newOwner)) Q_PRIVATE_SLOT(d, void checkForRegisteredHosts()) Q_PRIVATE_SLOT(d, void registerToDaemon()) Q_PRIVATE_SLOT(d, void contextMenuAboutToShow()) Q_PRIVATE_SLOT(d, void maybeQuit()) Q_PRIVATE_SLOT(d, void minimizeRestore()) Q_PRIVATE_SLOT(d, void hideMenu()) Q_PRIVATE_SLOT(d, void legacyWheelEvent(int)) Q_PRIVATE_SLOT(d, void legacyActivated(QSystemTrayIcon::ActivationReason)) }; #endif