kparts/statusbarextension.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 2003 Daniel Molkentin <molkentin@kde.org>
   3    Copyright (C) 2003 David Faure <faure@kde.org>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9
  10    This library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Library General Public License for more details.
  14
  15    You should have received a copy of the GNU Library General Public License
  16    along with this library; see the file COPYING.LIB.  If not, write to
  17    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18    Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef KPARTS_STATUSBAREXTENSION_H
  22 #define KPARTS_STATUSBAREXTENSION_H
  23
  24 #include <QtGui/QWidget>
  25
  26 #include <kparts/kparts_export.h>
  27 #include <QtCore/QList>
  28
  29 class KStatusBar;
  30 class KMainWindow;
  31 class QEvent;
  32
  33 namespace KParts
  34 {
  35
  36   class ReadOnlyPart;
  37
  38   // Defined in impl
  39   class StatusBarItem;
  40   class StatusBarExtensionPrivate;
  41
  42
  43   /**
  44    * @short an extension for KParts that allows more sophisticated statusbar handling
  45    *
  46    * Every part can use this class to customize the statusbar as long as it is active.
  47    * Add items via addStatusBarItem and remove an item with removeStatusBarItem.
  48    *
  49    * IMPORTANT: do NOT add any items immediately after constructing the extension.
  50    * Give the application time to set the statusbar in the extension if necessary.
  51    */
  52   class KPARTS_EXPORT StatusBarExtension : public QObject
  53   {
  54     Q_OBJECT
  55
  56     public:
  57       StatusBarExtension( KParts::ReadOnlyPart *parent );
  58       ~StatusBarExtension();
  59
  60       /**
  61        * This adds a widget to the statusbar for this part.
  62        * If you use this method instead of using statusBar() directly,
  63        * this extension will take care of removing the items when the parts GUI
  64        * is deactivated and will re-add them when it is reactivated.
  65        * The parameters are the same as QStatusBar::addWidget().
  66        *
  67        * Note that you can't use KStatusBar methods (inserting text items by id)
  68        * but you can create a KStatusBarLabel with a dummy id instead, and use
  69        * it directly in order to get the same look and feel.
  70        *
  71        * @param widget the widget to add
  72        * @param stretch the stretch factor. 0 for a minimum size.
  73        * @param permanent passed to QStatusBar::addWidget as the "permanent" bool.
  74        * Note that the item isn't really permanent though, it goes away when
  75        * the part is unactivated. This simply controls where temporary messages
  76        * hide the @p widget, and whether it's added to the left or to the right side.
  77        *
  78        * IMPORTANT: do NOT add any items immediately after constructing the extension.
  79        * Give the application time to set the statusbar in the extension if necessary.
  80        */
  81       void addStatusBarItem( QWidget * widget, int stretch, bool permanent );
  82
  83       /**
  84        * Remove a widget from the statusbar for this part.
  85        */
  86       void removeStatusBarItem( QWidget * widget );
  87
  88       /**
  89        * @return the statusbar of the KMainWindow in which this part is currently embedded.
  90        * WARNING: this could return 0L
  91        */
  92       KStatusBar* statusBar() const;
  93
  94       /**
  95        * This allows the hosting application to set a particular KStatusBar
  96        * for this part. If it doesn't do this, the statusbar used will be
  97        * the one of the KMainWindow in which the part is embedded.
  98        * Konqueror uses this to assign a view-statusbar to the part.
  99        * The part should never call this method!
 100        */
 101       void setStatusBar( KStatusBar* status );
 102
 103       /**
 104        * Queries @p obj for a child object which inherits from this
 105        * BrowserExtension class. Convenience method.
 106        */
 107       static StatusBarExtension *childObject( QObject *obj );
 108
 109       /** @internal */
 110       virtual bool eventFilter( QObject *watched, QEvent* ev );
 111
 112     private:
 113      // for future extensions
 114      friend class StatusBarExtensionPrivate;
 115      StatusBarExtensionPrivate* const d;
 116   };
 117
 118 }
 119 #endif // KPARTS_STATUSBAREXTENSION_H
 120
 121 // vim: ts=2 sw=2 et