File indexing completed on 2021-12-21 16:33:22

0001 /* This file is part of the KDE libraries
0002    Copyright (C) 1999 Matthias Ettrich <ettrich@kde.org>
0003    Copyright (C) 2007      by Charles Connell <charles@connells.org>
0004    Copyright (C) 2008 Lukas Appelhans <l.appelhans@gmx.de>
0005 
0006    This library is free software; you can redistribute it and/or
0007    modify it under the terms of the GNU Library General Public
0008    License version 2 as published by the Free Software Foundation.
0009 
0010    This library is distributed in the hope that it will be useful,
0011    but WITHOUT ANY WARRANTY; without even the implied warranty of
0012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013    Library General Public License for more details.
0014 
0015    You should have received a copy of the GNU Library General Public License
0016    along with this library; see the file COPYING.LIB.  If not, write to
0017    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0018    Boston, MA 02110-1301, USA.
0019 */
0020 #ifndef KSYSTEMTRAY_H
0021 #define KSYSTEMTRAY_H
0022 
0023 #include <kdelibs4support_export.h>
0024 
0025 #include <kcomponentdata.h>
0026 #include <QSystemTrayIcon>
0027 
0028 class KActionCollection;
0029 class KSystemTrayIconPrivate;
0030 class QAction;
0031 class QMovie;
0032 
0033 /**
0034  * \brief %KDE System Tray Window class
0035  *
0036  * This class implements system tray windows.
0037  *
0038  * A tray window is a small window (typically 22x22 pixel) that docks
0039  * into the system tray in the desktop panel. It usually displays an
0040  * icon or an animated icon there. The icon represents
0041  * the application, similar to a taskbar button, but consumes less
0042  * screen space.
0043  *
0044  * When the user clicks with the left mouse button on the icon, the
0045  * main application window is shown/raised and activated. With the
0046  * right mouse button, she gets a popupmenu with application specific
0047  * commands, including "Minimize/Restore" and "Quit".
0048  *
0049  * Please note that this class is being phased out in favor of the KStatusNotifierItem
0050  * class, you should consider to use it instead if you are writing a new application
0051  * or consider porting the code that uses this class to the KStatusNotifierItem API.
0052  *
0053  * Also, QSystemTrayIcon::showMessage(..) should not be
0054  * used for KDE application because the popup message has no KDE standard
0055  * look & feel and cannot be controlled by KDE configurations.
0056  * Use KNotification instead.
0057  *
0058  * @author Matthias Ettrich <ettrich@kde.org>
0059  **/
0060 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KSystemTrayIcon : public QSystemTrayIcon //krazy:exclude=qclasses
0061 {
0062     Q_OBJECT
0063 public:
0064     /**
0065      * Construct a system tray icon.
0066      *
0067      * The parent widget @p parent has a special meaning:
0068      * Besides owning the tray window, the parent widget will
0069      * disappear from taskbars when it is iconified while the tray
0070      * window is visible. This is the desired behavior. After all,
0071      * the tray window @p is the parent's taskbar icon.
0072      *
0073      * Furthermore, the parent widget is shown or raised respectively
0074      * when the user clicks on the tray window with the left mouse
0075      * button.
0076      **/
0077     KDELIBS4SUPPORT_DEPRECATED explicit KSystemTrayIcon(QWidget *parent = nullptr);
0078 
0079     /**
0080      * Same as above but allows one to define the icon by name that should
0081      * be used for the system tray icon.
0082      */
0083     KDELIBS4SUPPORT_DEPRECATED explicit KSystemTrayIcon(const QString &icon, QWidget *parent = nullptr);
0084 
0085     /**
0086      * Same as above but allows one to define the icon by name that should
0087      * be used for the system tray icon.
0088      */
0089     KDELIBS4SUPPORT_DEPRECATED explicit KSystemTrayIcon(const QIcon &icon, QWidget *parent = nullptr);
0090 
0091     /**
0092      * Same as above but allows one to define the movie by QMovie that should
0093      * be used for the system tray icon. Memory management for the movie will
0094      * be handled by KSystemTrayIcon.
0095      */
0096     KDELIBS4SUPPORT_DEPRECATED explicit KSystemTrayIcon(QMovie *movie, QWidget *parent);
0097 
0098     /**
0099      * Destructor
0100      */
0101     ~KSystemTrayIcon() override;
0102 
0103     /**
0104      * Set the movie to use. To manipulate the movie (start, stop, pause), call
0105      * @see movie() and make calls on the QMovie* that it returns.
0106      * Memory management for the movie will be handled by KSystemTrayIcon.
0107      * @since 4.2
0108      */
0109     void setMovie(QMovie *movie);
0110 
0111     /**
0112      * Get a pointer to the movie. Use this pointer to manipulate the movie
0113      * (start, stop, pause).
0114      * Will return null if no movie has been set
0115      * @since 4.2
0116      */
0117     const QMovie *movie() const;
0118 
0119     /**
0120        Easy access to the actions in the context menu
0121        Currently includes KStandardAction::Quit and minimizeRestore
0122     */
0123     KActionCollection *actionCollection();
0124 
0125     /**
0126        Returns the QWidget set by the constructor
0127     */
0128     QWidget *parentWidget() const;
0129 
0130     /**
0131        Function to be used from function handling closing of the window associated
0132        with the tray icon (i.e. QWidget::closeEvent(), KMainWindow::queryClose() or
0133        similar). When false is returned, the window closing should proceed normally,
0134        when true is returned, special systray-related handling should take place.
0135      */
0136     bool parentWidgetTrayClose() const;
0137 
0138     /**
0139      * Loads an icon @p icon using the icon loader class of the given componentData @p componentData.
0140      * The icon is applied the panel effect as it should only be used to be shown in the
0141      * system tray.
0142      * It's commonly used in the form : systray->setPixmap( systray->loadIcon( "mysystray" ) );
0143      */
0144     static QIcon loadIcon(const QString &icon, const KComponentData &componentData = KComponentData::mainComponent());
0145 
0146     /**
0147      * Sets the context menu title action to @p action.
0148      * The following code shows how to change the current title.
0149      * <code>
0150      * QAction *titleAction = contextMenuTitle();
0151      * titleAction->setText("New Title");
0152      * setContextMenuTitle(titleAction);
0153      * </code>
0154      * @since 4.1
0155      */
0156     void setContextMenuTitle(QAction *action);
0157 
0158     /**
0159      * Returns the context menu title action.
0160      * @since 4.1
0161      */
0162     QAction *contextMenuTitle() const;
0163 
0164 Q_SIGNALS:
0165     /**
0166      * Emitted when quit is selected in the menu. If you want to perform any other
0167      * action than to close the main application window please connect to this signal.
0168      */
0169     void quitSelected();
0170 
0171 public Q_SLOTS:
0172     void toggleActive();
0173 
0174 private Q_SLOTS:
0175     void contextMenuAboutToShow();
0176     void minimizeRestoreAction();
0177     void maybeQuit();
0178     void activateOrHide(QSystemTrayIcon::ActivationReason reasonCalled);
0179 
0180 private:
0181     void init(QWidget *);
0182     void minimizeRestore(bool restore);
0183 
0184     KSystemTrayIconPrivate *const d;
0185 
0186     Q_PRIVATE_SLOT(d, void _k_slotNewFrame())
0187 };
0188 
0189 #endif
0190