libkdepim/kwidgetlister.h

   1 /*  -*- c++ -*-
   2     kwidgetlister.h
   3
   4     This file is part of libkdenetwork.
   5     Copyright (c) 2001 Marc Mutz <mutz@kde.org>
   6
   7     This library is free software; you can redistribute it and/or
   8     modify it under the terms of the GNU General Public License,
   9     version 2, as published by the Free Software Foundation.
  10
  11     This library is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14     General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with this library; if not, write to the Free Software
  18     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20     In addition, as a special exception, the copyright holders give
  21     permission to link the code of this library with any edition of
  22     the Qt library by Trolltech AS, Norway (or with modified versions
  23     of Qt that use the same license as Qt), and distribute linked
  24     combinations including the two.  You must obey the GNU General
  25     Public License in all respects for all of the code used other than
  26     Qt.  If you modify this file, you may extend this exception to
  27     your version of the file, but you are not obligated to do so.  If
  28     you do not wish to do so, delete this exception statement from
  29     your version.
  30 */
  31
  32 #ifndef _KWIDGETLISTER_H_
  33 #define _KWIDGETLISTER_H_
  34
  35 #include <QWidget>
  36 #include <q3ptrlist.h>
  37 //Added by qt3to4:
  38 #include <QVBoxLayout>
  39 #include <kdepim_export.h>
  40
  41 class QPushButton;
  42 class QVBoxLayout;
  43 class KHBox;
  44
  45 /**
  46     @short Widget that manages a list of other widgets (incl. 'more', 'fewer' and 'clear' buttons).
  47
  48     Simple widget that nonetheless does a lot of the dirty work for
  49     the filter edit widgets (KMSearchPatternEdit and
  50     KMFilterActionEdit). It provides a growable and shrinkable area
  51     where widget may be displayed in rows. Widgets can be added by
  52     hitting the provided 'More' button, removed by the 'Fewer' button
  53     and cleared (e.g. reset, if an derived class implements that and
  54     removed for all but @ref mMinWidgets).
  55
  56     To use this widget, derive from it with the template changed to
  57     the type of widgets this class should list. Then reimplement @ref
  58     addWidgetAtEnd, @ref removeLastWidget, calling the original
  59     implementation as necessary. Instantiate an object of the class and
  60     put it in your dialog.
  61
  62     @author Marc Mutz <Marc@Mutz.com>
  63     @see KMSearchPatternEdit::WidgetLister KMFilterActionEdit::WidgetLister
  64
  65 */
  66
  67 class KDEPIM_EXPORT KWidgetLister : public QWidget
  68 {
  69   Q_OBJECT
  70 public:
  71   KWidgetLister( int minWidgets=1, int maxWidgets=8, QWidget* parent=0, const char* name=0 );
  72   virtual ~KWidgetLister();
  73
  74 protected slots:
  75   /** Called whenever the user clicks on the 'more' button.
  76       Reimplementations should call this method, because this
  77       implementation does all the dirty work with adding the widgets
  78       to the layout (through @ref addWidgetAtEnd) and enabling/disabling
  79       the control buttons. */
  80   virtual void slotMore();
  81   /** Called whenever the user clicks on the 'fewer' button.
  82       Reimplementations should call this method, because this
  83       implementation does all the dirty work with removing the widgets
  84       from the layout (through @ref removeLastWidget) and
  85       enabling/disabling the control buttons. */
  86   virtual void slotFewer();
  87   /** Called whenever the user clicks on the 'clear' button.
  88       Reimplementations should call this method, because this
  89       implementation does all the dirty work with removing all but
  90       @ref mMinWidgets widgets from the layout and enabling/disabling
  91       the control buttons. */
  92   virtual void slotClear();
  93
  94
  95
  96 protected:
  97   /** Adds a single widget. Doesn't care if there are already @ref
  98       mMaxWidgets on screen and whether it should enable/disable any
  99       controls. It simply does what it is asked to do.  You want to
 100       reimplement this method if you want to initialize the the widget
 101       when showing it on screen. Make sure you call this
 102       implementaion, though, since you cannot put the widget on screen
 103       from derived classes (@p mLayout is private).
 104       Make sure the parent of the QWidget to add is this KWidgetLister. */
 105   virtual void addWidgetAtEnd(QWidget *w =0);
 106   /** Removes a single (always the last) widget. Doesn't care if there
 107       are still only @ref mMinWidgets left on screen and whether it
 108       should enable/disable any controls. It simply does what it is
 109       asked to do. You want to reimplement this method if you want to
 110       save the the widget's state before removing it from screen. Make
 111       sure you call this implementaion, though, since you should not
 112       remove the widget from screen from derived classes. */
 113   virtual void removeLastWidget();
 114   /** Called to clear a given widget. The default implementation does
 115       nothing. */
 116   virtual void clearWidget( QWidget* );
 117   /** Because QT 2.x does not support signals/slots in template
 118       classes, we are forced to emulate this by forcing the
 119       implementers of subclasses of KWidgetLister to reimplement this
 120       function which replaces the "@p new @p T" call. */
 121   virtual QWidget* createWidget( QWidget *parent );
 122   /** Sets the number of widgets on scrren to exactly @p aNum. Doesn't
 123       check if @p aNum is inside the range @p
 124       [mMinWidgets,mMaxWidgets]. */
 125   virtual void setNumberOfShownWidgetsTo( int aNum );
 126   /** The list of widgets. Note that this list is set to auto-delete,
 127       meaning that widgets that are removed from the screen by either
 128       @ref slotFewer or @ref slotClear will be destroyed! */
 129   Q3PtrList<QWidget> mWidgetList;
 130   /** The minimum number of widgets that are to stay on screen. */
 131   int mMinWidgets;
 132   /** The maximum number of widgets that are to be shown on screen. */
 133   int mMaxWidgets;
 134
 135 signals:
 136   /** This signal is emitted whenever a widget was added */
 137   void widgetAdded();
 138   /** This signal is emitted whenever a widget was added */
 139   void widgetAdded(QWidget *);
 140   /** This signal is emitted whenever a widget was removed */
 141   void widgetRemoved();
 142   /** This signal is emitted whenever the clear button is clicked */
 143   void clearWidgets();
 144
 145 private:
 146   void enableControls();
 147
 148   QPushButton *mBtnMore, *mBtnFewer, *mBtnClear;
 149   QVBoxLayout *mLayout;
 150   KHBox       *mButtonBox;
 151 };
 152
 153
 154
 155 #endif /* _KWIDGETLISTER_H_ */