libkdepim/kwidgetlister.h

   1 /*  -*- c++ -*-
   2
   3   kwidgetlister.h
   4
   5   This file is part of libkdepim
   6   Copyright (c) 2001 Marc Mutz <mutz@kde.org>
   7
   8   This library is free software; you can redistribute it and/or
   9   modify it under the terms of the GNU General Public License,
  10   version 2, as published by the Free Software Foundation.
  11
  12   This library is distributed in the hope that it will be useful,
  13   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15   General Public License for more details.
  16
  17   You should have received a copy of the GNU General Public License
  18   along with this library; if not, write to the Free Software
  19   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  20
  21   In addition, as a special exception, the copyright holders give
  22   permission to link the code of this library with any edition of
  23   the Qt library by Trolltech AS, Norway (or with modified versions
  24   of Qt that use the same license as Qt), and distribute linked
  25   combinations including the two.  You must obey the GNU General
  26   Public License in all respects for all of the code used other than
  27   Qt.  If you modify this file, you may extend this exception to
  28   your version of the file, but you are not obligated to do so.  If
  29   you do not wish to do so, delete this exception statement from
  30   your version.
  31 */
  32
  33 #ifndef KDEPIM_KWIDGETLISTER_H
  34 #define KDEPIM_KWIDGETLISTER_H
  35
  36 #include "kdepim_export.h"
  37 #include <QWidget>
  38
  39 class QPushButton;
  40 class QVBoxLayout;
  41 class KHBox;
  42
  43 namespace KPIM {
  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
  71   public:
  72     /**
  73      * Creates a new widget lister.
  74      *
  75      * @param minWidgets The minimum number of widgets to stay on the screen.
  76      * @param maxWidgets The maximum number of widgets to stay on the screen.
  77      * @param parent The parent widget.
  78      */
  79     explicit KWidgetLister( int minWidgets = 1, int maxWidgets = 8, QWidget *parent = 0 );
  80
  81     /**
  82      * Destroys the widget lister.
  83      */
  84     virtual ~KWidgetLister();
  85
  86   protected Q_SLOTS:
  87     /**
  88      * Called whenever the user clicks on the 'more' button.
  89      * Reimplementations should call this method, because this
  90      * implementation does all the dirty work with adding the widgets
  91      * to the layout (through @ref addWidgetAtEnd) and enabling/disabling
  92      * the control buttons.
  93      */
  94     virtual void slotMore();
  95
  96     /**
  97      * Called whenever the user clicks on the 'fewer' button.
  98      * Reimplementations should call this method, because this
  99      * implementation does all the dirty work with removing the widgets
 100      * from the layout (through @ref removeLastWidget) and
 101      * enabling/disabling the control buttons.
 102      */
 103     virtual void slotFewer();
 104
 105     /**
 106      * Called whenever the user clicks on the 'clear' button.
 107      * Reimplementations should call this method, because this
 108      * implementation does all the dirty work with removing all but
 109      * @ref mMinWidgets widgets from the layout and enabling/disabling
 110      * the control buttons.
 111      */
 112     virtual void slotClear();
 113
 114   protected:
 115     /**
 116      * Adds a single widget. Doesn't care if there are already @ref
 117      * mMaxWidgets on screen and whether it should enable/disable any
 118      * controls. It simply does what it is asked to do.  You want to
 119      * reimplement this method if you want to initialize the widget
 120      * when showing it on screen. Make sure you call this
 121      * implementaion, though, since you cannot put the widget on screen
 122      * from derived classes (@p mLayout is private).
 123      * Make sure the parent of the QWidget to add is this KWidgetLister.
 124      */
 125     virtual void addWidgetAtEnd( QWidget *widget = 0 );
 126
 127     /**
 128      * Removes a single (always the last) widget. Doesn't care if there
 129      * are still only @ref mMinWidgets left on screen and whether it
 130      * should enable/disable any controls. It simply does what it is
 131      * asked to do. You want to reimplement this method if you want to
 132      * save the widget's state before removing it from screen. Make
 133      * sure you call this implementaion, though, since you should not
 134      * remove the widget from screen from derived classes.
 135      */
 136     virtual void removeLastWidget();
 137
 138     /**
 139      * Called to clear a given widget. The default implementation does
 140      * nothing.
 141      */
 142     virtual void clearWidget( QWidget *w );
 143
 144     /**
 145      * Returns a new widget that shall be added to the lister.
 146      *
 147      * @param parent The parent widget of the new widget.
 148      */
 149     virtual QWidget *createWidget( QWidget *parent );
 150
 151     /**
 152      * Sets the number of widgets on scrren to exactly @p count. Doesn't
 153      * check if @p count is inside the range @p [mMinWidgets,mMaxWidgets].
 154      */
 155     virtual void setNumberOfShownWidgetsTo( int count );
 156
 157     /**
 158      * Returns the list of widgets.
 159      */
 160     QList<QWidget*> widgets() const;
 161
 162     /**
 163      * The minimum number of widgets that are to stay on screen.
 164      */
 165     int widgetsMinimum() const;
 166
 167     /**
 168      * The maximum number of widgets that are to be shown on screen.
 169      */
 170     int widgetsMaximum() const;
 171
 172   Q_SIGNALS:
 173     /**
 174      * This signal is emitted whenever a widget was added.
 175      */
 176     void widgetAdded();
 177
 178     /**
 179      * This signal is emitted whenever a widget was added.
 180      *
 181      * @param widget The added widget.
 182      */
 183     void widgetAdded( QWidget *widget );
 184
 185     /**
 186      * This signal is emitted whenever a widget was removed.
 187      */
 188     void widgetRemoved();
 189
 190     /**
 191      * This signal is emitted whenever the clear button is clicked.
 192      */
 193     void clearWidgets();
 194
 195   private:
 196     //@cond PRIVATE
 197     class Private;
 198     Private* const d;
 199     //@endcond
 200 };
 201
 202 }
 203
 204 #endif /* _KWIDGETLISTER_H_ */