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     //TODO KDE5 merge two constructors
  73     /**
  74      * Creates a new widget lister.
  75      *
  76      * @param minWidgets The minimum number of widgets to stay on the screen.
  77      * @param maxWidgets The maximum number of widgets to stay on the screen.
  78      * @param parent The parent widget.
  79      */
  80     explicit KWidgetLister( int minWidgets = 1, int maxWidgets = 8, QWidget *parent = 0 );
  81
  82     /**
  83      * Creates a new widget lister.
  84      * @param fewerMoreButton Add or Not fewerMoreButton
  85      * @param minWidgets The minimum number of widgets to stay on the screen.
  86      * @param maxWidgets The maximum number of widgets to stay on the screen.
  87      * @param parent The parent widget.
  88      */
  89     explicit KWidgetLister( bool fewerMoreButton, int minWidgets = 1, int maxWidgets = 8, QWidget *parent = 0 );
  90
  91     /**
  92      * Destroys the widget lister.
  93      */
  94     virtual ~KWidgetLister();
  95
  96   protected Q_SLOTS:
  97     /**
  98      * Called whenever the user clicks on the 'more' button.
  99      * Reimplementations should call this method, because this
 100      * implementation does all the dirty work with adding the widgets
 101      * to the layout (through @ref addWidgetAtEnd) and enabling/disabling
 102      * the control buttons.
 103      */
 104     virtual void slotMore();
 105
 106     /**
 107      * Called whenever the user clicks on the 'fewer' button.
 108      * Reimplementations should call this method, because this
 109      * implementation does all the dirty work with removing the widgets
 110      * from the layout (through @ref removeLastWidget) and
 111      * enabling/disabling the control buttons.
 112      */
 113     virtual void slotFewer();
 114
 115     /**
 116      * Called whenever the user clicks on the 'clear' button.
 117      * Reimplementations should call this method, because this
 118      * implementation does all the dirty work with removing all but
 119      * @ref mMinWidgets widgets from the layout and enabling/disabling
 120      * the control buttons.
 121      */
 122     virtual void slotClear();
 123
 124   protected:
 125     /**
 126      * Adds a single widget. Doesn't care if there are already @ref
 127      * mMaxWidgets on screen and whether it should enable/disable any
 128      * controls. It simply does what it is asked to do.  You want to
 129      * reimplement this method if you want to initialize the widget
 130      * when showing it on screen. Make sure you call this
 131      * implementaion, though, since you cannot put the widget on screen
 132      * from derived classes (@p mLayout is private).
 133      * Make sure the parent of the QWidget to add is this KWidgetLister.
 134      */
 135     virtual void addWidgetAtEnd( QWidget *widget = 0 );
 136
 137     /**
 138      * Removes a single (always the last) widget. Doesn't care if there
 139      * are still only @ref mMinWidgets left on screen and whether it
 140      * should enable/disable any controls. It simply does what it is
 141      * asked to do. You want to reimplement this method if you want to
 142      * save the widget's state before removing it from screen. Make
 143      * sure you call this implementaion, though, since you should not
 144      * remove the widget from screen from derived classes.
 145      */
 146     virtual void removeLastWidget();
 147
 148     /**
 149      * Called to clear a given widget. The default implementation does
 150      * nothing.
 151      */
 152     virtual void clearWidget( QWidget *w );
 153
 154     /**
 155      * Returns a new widget that shall be added to the lister.
 156      *
 157      * @param parent The parent widget of the new widget.
 158      */
 159     virtual QWidget *createWidget( QWidget *parent );
 160
 161     /**
 162      * Sets the number of widgets on scrren to exactly @p count. Doesn't
 163      * check if @p count is inside the range @p [mMinWidgets,mMaxWidgets].
 164      */
 165     virtual void setNumberOfShownWidgetsTo( int count );
 166
 167     /**
 168      * Returns the list of widgets.
 169      */
 170     QList<QWidget*> widgets() const;
 171
 172     /**
 173      * The minimum number of widgets that are to stay on screen.
 174      */
 175     int widgetsMinimum() const;
 176
 177     /**
 178      * The maximum number of widgets that are to be shown on screen.
 179      */
 180     int widgetsMaximum() const;
 181
 182     /**
 183      * Remove specific widget
 184      */
 185     virtual void removeWidget(QWidget*widget);
 186     /**
 187      * Add widget after specific widget
 188      */
 189     virtual void addWidgetAfterThisWidget(QWidget*currentWidget, QWidget* widget = 0);
 190
 191   private:
 192     void init( bool fewerMoreButton = true );
 193
 194   Q_SIGNALS:
 195     /**
 196      * This signal is emitted whenever a widget was added.
 197      */
 198     void widgetAdded();
 199
 200     /**
 201      * This signal is emitted whenever a widget was added.
 202      *
 203      * @param widget The added widget.
 204      */
 205     void widgetAdded( QWidget *widget );
 206
 207     /**
 208      * This signal is emitted whenever a widget was removed.
 209      */
 210     void widgetRemoved();
 211
 212   /**
 213      * This signal is emitted whenever a widget was removed.
 214      */
 215     void widgetRemoved( QWidget *widget );
 216
 217     /**
 218      * This signal is emitted whenever the clear button is clicked.
 219      */
 220     void clearWidgets();
 221
 222   private:
 223     //@cond PRIVATE
 224     class Private;
 225     Private* const d;
 226     //@endcond
 227 };
 228
 229 }
 230
 231 #endif /* _KWIDGETLISTER_H_ */