libkdepim/kcheckcombobox.h

   1 /*
   2   This file is part of libkdepim.
   3
   4   Copyright (c) 2008 Thomas Thrainer <tom_t@gmx.at>
   5   Copyright (c) 2010 Bertjan Broeksema <broeksema@kde.org>
   6
   7   This program is free software; you can redistribute it and/or modify
   8   it under the terms of the GNU General Public License as published by
   9   the Free Software Foundation; either version 2 of the License, or
  10   (at your option) any later version.
  11
  12   This program 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
  15   GNU General Public License for more details.
  16
  17   You should have received a copy of the GNU General Public License along
  18   with this program; if not, write to the Free Software Foundation, Inc.,
  19   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20
  21   As a special exception, permission is given to link this program
  22   with any edition of Qt, and distribute the resulting executable,
  23   without including the source code for Qt in the source distribution.
  24 */
  25
  26 #ifndef KCHECKCOMBOBOX_H
  27 #define KCHECKCOMBOBOX_H
  28
  29 #include "kdepim_export.h"
  30
  31 #include <KComboBox>
  32 #include <QModelIndex>
  33
  34 namespace KPIM {
  35
  36 /**
  37  * A combobox that shows its items in such a way that they can be checked in the
  38  * drop menu. It provides methods to set the default text when no items are selected
  39  * and the separator that is used to show the items that are selected in the line
  40  * edit.
  41  */
  42 class KDEPIM_EXPORT KCheckComboBox : public KComboBox
  43 {
  44   Q_OBJECT
  45
  46   Q_PROPERTY( QString separator READ separator WRITE setSeparator )
  47   Q_PROPERTY( QString defaultText READ defaultText WRITE setDefaultText )
  48   Q_PROPERTY( bool squeezeText READ squeezeText WRITE setSqueezeText )
  49   Q_PROPERTY( QStringList checkedItems READ checkedItems WRITE setCheckedItems )
  50
  51   public:
  52     /**
  53      * Creates a new checkable combobox.
  54      *
  55      * @param parent The parent widget.
  56      */
  57     explicit KCheckComboBox( QWidget *parent = 0 );
  58
  59     /**
  60      * Destroys the time zone combobox.
  61      */
  62     virtual ~KCheckComboBox();
  63
  64     /**
  65      * Hides the popup list if it is currently shown.
  66      */
  67     virtual void hidePopup();
  68
  69     /**
  70      * Returns the default text that is shown when no items are selected.
  71      */
  72     QString defaultText() const;
  73
  74     /**
  75      * Sets the default text that is shown when no items are selected.
  76      *
  77      * @param text The new default text
  78      */
  79     void setDefaultText( const QString &text );
  80
  81     /**
  82      * Returns whether the default text is always shown, even if there are
  83      * no checked items.
  84      */
  85     bool alwaysShowDefaultText() const;
  86
  87     /**
  88      * Sets if the default text should always be shown even if there are
  89      * no checked items.
  90      *
  91      * Default is false.
  92      */
  93     void setAlwaysShowDefaultText( bool always );
  94
  95     /**
  96      * Returns wether or not the text will be squeezed to fit in the combo's line
  97      * edit. This property is false by default.
  98      *
  99      * @see KSqueezedTextLabel
 100      */
 101     bool squeezeText() const;
 102
 103     /**
 104      * Sets wheter or not the text must be squeezed
 105      *
 106      * @param squeeze The new squeeze status
 107      */
 108     void setSqueezeText( bool squeeze );
 109
 110     /**
 111      * Return whether or not the item at @param index is enabled, i.e. if the
 112      * user can (un)check the item.
 113      */
 114     bool itemEnabled( int index );
 115
 116     /**
 117      * Set the item at @param index to @param enabled, i.e. if the
 118      * user can (un)check the item.
 119      */
 120     void setItemEnabled( int index, bool enabled = true );
 121
 122     /**
 123      * Returns the check state of item at given index.
 124      *
 125      * @param index The index for which to return the check state.
 126      */
 127     Qt::CheckState itemCheckState( int index ) const;
 128
 129     /**
 130      * Changes the check state of the given index to the given state.
 131      *
 132      * @param index The index of which the state needs to be changed
 133      * @param state The new state
 134      */
 135     void setItemCheckState( int index, Qt::CheckState state );
 136
 137     /**
 138      * Returns the current seperator used to seperate the selected items in the
 139      * line edit of the combo box.
 140      */
 141     QString separator() const;
 142
 143     /**
 144      * Sets the seperator used to seperate items in the line edit.
 145      *
 146      * @param seperator The new seperator
 147      */
 148     void setSeparator( const QString &separator );
 149
 150     /**
 151      * Returns The currently selected items.
 152      * @param role The role the returned values belong to.
 153      */
 154     QStringList checkedItems( int role = Qt::DisplayRole ) const;
 155
 156   public Q_SLOTS:
 157     /**
 158      * Sets the currently selected items. Items that are not found in the model
 159      * are silently ignored.
 160      *
 161      * @param items The items that will be set to checked.
 162      * @param role The role @p items belong to.
 163      */
 164     void setCheckedItems( const QStringList &items, int role = Qt::DisplayRole );
 165
 166   Q_SIGNALS:
 167     /**
 168      * Signal to notify listeners that the current selections has changed.
 169      *
 170      * @param items The new selection.
 171      */
 172     void checkedItemsChanged( const QStringList &items );
 173
 174   protected:
 175     virtual bool eventFilter( QObject *receiver, QEvent *event );
 176     virtual void keyPressEvent( QKeyEvent *event );
 177     virtual void resizeEvent( QResizeEvent * event );
 178 #ifndef QT_NO_WHEELEVENT
 179     virtual void wheelEvent( QWheelEvent *event );
 180 #endif
 181
 182   private:
 183     //@cond PRIVATE
 184     class Private;
 185     Private *const d;
 186
 187     Q_PRIVATE_SLOT( d, void makeInsertedItemsCheckable(const QModelIndex &, int start, int end) )
 188     Q_PRIVATE_SLOT( d, void updateCheckedItems( const QModelIndex &topLeft,
 189                                                 const QModelIndex &bottomRight ) )
 190     Q_PRIVATE_SLOT( d, void toggleCheckState() )
 191     //@endcond
 192 };
 193
 194 }
 195
 196 #endif // KCHECKCOMBOBOX_H