home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / ksystemtray.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  6.4 KB  |  206 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1999 Matthias Ettrich <ettrich@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef KSYSTEMTRAY_H
  19. #define KSYSTEMTRAY_H
  20.  
  21. #include <kglobal.h>
  22. #include <qlabel.h>
  23.  
  24. class KActionCollection;
  25. class KPopupMenu;
  26. class KSystemTrayPrivate;
  27.  
  28. /**
  29.  * \brief %KDE System Tray Window class
  30.  *
  31.  * This class implements system tray windows.
  32.  *
  33.  * A tray window is a small window (typically 24x24 pixel) that docks
  34.  * into the system tray in the desktop panel. It usually displays an
  35.  * icon or an animated icon there. The icon represents
  36.  * the application, similar to a taskbar button, but consumes less
  37.  * screen space.
  38.  *
  39.  * When the user clicks with the left mouse button on the icon, the
  40.  * main application window is shown/raised and activated. With the
  41.  * right mouse button, she gets a popupmenu with application specific
  42.  * commands, including "Minimize/Restore" and "Quit".
  43.  *
  44.  * Docking happens magically when calling show(). The window undocks
  45.  * with either hide() or when it is destroyed.
  46.  *
  47.  * KSystemTray inherits methods such as setPixmap() and setMovie() to
  48.  * specify an icon or movie (animated icon) respectively. It is
  49.  * designed to be usable "as is", without the need to subclass it. In
  50.  * case you need to provide something special (such as an additional
  51.  * popupmenu on a click with the left mouse button), you can subclass
  52.  * anyway, of course.
  53.  *
  54.  * Having an icon on the system tray is a useful technique for
  55.  * daemon-like applications that may run for some time without user
  56.  * interaction but have to be there immediately when the user needs
  57.  * them. Examples are kppp, kisdn, kscd, kmix or knotes. With kppp and
  58.  * kisdn, the docked icon even provides real-time information about
  59.  * the network status.
  60.  *
  61.  * @author Matthias Ettrich <ettrich@kde.org>
  62.  **/
  63. class KDEUI_EXPORT KSystemTray : public QLabel
  64. {
  65.     Q_OBJECT
  66. public:
  67.  
  68.     /**
  69.      * Construct a KSystemTray widget just like any other widget.
  70.      *
  71.      * The parent widget @p parent has a special meaning:
  72.      * Besides owning the tray window, the parent widget will
  73.      * dissappear from taskbars when it is iconified while the tray
  74.      * window is visible. This is the desired behavior. After all,
  75.      * the tray window @p is the parent's taskbar icon.
  76.      *
  77.      * Furthermore, the parent widget is shown or raised respectively
  78.      * when the user clicks on the trray window with the left mouse
  79.      * button.
  80.      **/
  81.     KSystemTray( QWidget* parent = 0, const char* name  = 0 );
  82.  
  83.     /*
  84.       Destructor
  85.      */
  86.     ~KSystemTray();
  87.  
  88.     /**
  89.        Access to the context menu. This makes it easy to add new items
  90.        to it.
  91.      */
  92.     KPopupMenu* contextMenu() const;
  93.  
  94.     /**
  95.        Easy access to the actions in the context menu
  96.        Currently includes KStdAction::Quit and minimizeRestore
  97.        @since 3.1
  98.     */
  99.     KActionCollection* actionCollection();
  100.  
  101.     /**
  102.      * Changes the tray's icon.
  103.      */
  104.     virtual void setPixmap( const QPixmap& icon );
  105.  
  106.     /**
  107.      * Changes the tray's text description (which can be seen e.g. in the systray
  108.      * configuration dialog). The default value is KAboutData::programName().
  109.      */
  110.     virtual void setCaption( const QString& title );
  111.     
  112.     /**
  113.      * Loads an icon @p icon using the icon loader class of the given instance @p instance.
  114.      * The icon is applied the panel effect as it should only be used to be shown in the
  115.      * system tray.
  116.      * It's commonly used in the form : systray->setPixmap( systray->loadIcon( "mysystray" ) );
  117.      *
  118.      * @since 3.2
  119.      */
  120.     static QPixmap loadIcon( const QString &icon, KInstance *instance=KGlobal::instance() );
  121.  
  122. signals:
  123.     /**
  124.      * Emitted when quit is selected in the menu. If you want to perform any other
  125.      * action than to close the main application window please connect to this signal.
  126.      * @since 3.1
  127.      */
  128.     void quitSelected();
  129.  
  130. public slots:
  131.  
  132.     /**
  133.      * Toggles the state of the window associated with this system tray icon (hides it,
  134.      * shows it or activates it depending on the window state). The default implementation
  135.      * of mousePressEvent() calls toggleActive() when the tray icon is left-clicked, use
  136.      * it when reimplementing mousePressEvent().
  137.      * @since 3.3
  138.      */
  139.     void toggleActive();
  140.     /**
  141.      * Activates the window associated with this system tray icon, regardless of its current state.
  142.      * @since 3.3
  143.      */
  144.     void setActive();
  145.     /**
  146.      * Hides the window associated with this system tray icon, regardless of its current state.
  147.      * @since 3.3
  148.      */
  149.     void setInactive();
  150.  
  151. protected:
  152.  
  153.     /**
  154.        Reimplemented to provide the standard show/raise behavior
  155.        for the parentWidget() and the context menu.
  156.  
  157.        Feel free to reimplement this if you need something special.
  158.      */
  159.     void mousePressEvent( QMouseEvent * );
  160.  
  161.     /**
  162.        Reimplemented to provide the standard show/raise behavior
  163.        for the parentWidget() and the context menu.
  164.  
  165.        Feel free to reimplement this if you need something special.
  166.      */
  167.     void mouseReleaseEvent( QMouseEvent * );
  168.  
  169.  
  170.  
  171.     /**
  172.        Makes it easy to adjust some menu items right before the
  173.        context menu becomes visible.
  174.      */
  175.     virtual void contextMenuAboutToShow( KPopupMenu* menu );
  176.  
  177.     /**
  178.        Reimplemented for internal reasons.
  179.      */
  180.     void showEvent( QShowEvent * );
  181.  
  182.     /**
  183.        Reimplemented for internal reasons.
  184.      */
  185.     void enterEvent( QEvent* );
  186.  
  187. private slots:
  188.     void minimizeRestoreAction();
  189.     void maybeQuit();
  190.  
  191. private:
  192.     void activateOrHide();
  193.     void minimizeRestore( bool restore );
  194.     KPopupMenu* menu;
  195.     // minimizeRestoreId is no longer needed. remove in KDE 4.0
  196.     int minimizeRestoreId;
  197.     uint hasQuit :1;
  198. protected:
  199.     virtual void virtual_hook( int id, void* data );
  200. private:
  201.     KSystemTrayPrivate* d;
  202. };
  203.  
  204.  
  205. #endif
  206.