libkdepim/treewidget.h

   1 #ifndef KDEPIM_TREEWIDGET_H
   2 #define KDEPIM_TREEWIDGET_H
   3
   4 /******************************************************************************
   5  *
   6  * This file is part of libkdepim.
   7  *
   8  * Copyright (C) 2008 Szymon Tomasz Stefanek <pragma@kvirc.net>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Library General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Library General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Library General Public License
  21  * along with this library; see the file COPYING.LIB.  If not, write to
  22  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301, USA.
  24  *
  25  *****************************************************************************/
  26
  27 /**
  28  * @file treewidget.h A common QTreeWidget extension
  29  */
  30
  31 #include "kdepim_export.h"
  32 #include <QTreeWidget>
  33
  34 class KMenu;
  35 class KConfig;
  36 class KConfigGroup;
  37
  38 class QAction;
  39
  40 namespace KPIM
  41 {
  42
  43 /**
  44  * @brief A QTreeWidget with expanded capabilities
  45  *
  46  * This class extends the functionality provided by the standard QTreeWidget
  47  * by adding toggleable columns and a layout save/restore facility.
  48  *
  49  * At the time of writing the usage of QTreeWidget is a bit against the
  50  * reccomended Qt4 approach. On the other hand in many cases you just want
  51  * a simple tree of items and don't want to care about anything complex like
  52  * a "data model".
  53  *
  54  * @author Szymon Tomasz Stefanek <pragma@kvirc.net>
  55  */
  56 class KDEPIM_EXPORT TreeWidget : public QTreeWidget
  57 {
  58   Q_OBJECT
  59 public:
  60   /**
  61    * Constructs a TreeWidget. Sets up the default values
  62    * for properties.
  63    */
  64   explicit TreeWidget( QWidget *parent, const char *name = 0 );
  65
  66 public:
  67
  68   //
  69   // Layout Save/Restore facility
  70   //
  71
  72   /**
  73    * Stores the layout of this tree view to the specified KConfigGroup.
  74    * The stored data includes visible columns, column width and order.
  75    *
  76    * @param group The KConfigGroup to write the layout data to.
  77    * @param keyName The key to use, "TreeWidgetLayout" by default
  78    *
  79    * @returns true on success and false on failure (if keyName is 0, for example).
  80    */
  81   bool saveLayout(
  82       KConfigGroup &group,
  83       const QString &keyName = QString()
  84     ) const;
  85
  86   /**
  87    * Stores the layout of this tree view to the specified key of
  88    * the specified config group.
  89    * The stored data includes visible columns, column width and order.
  90    *
  91    * @param configGroup The KConfig group to write the layout data to.
  92    * @param keyName The key to use, "TreeWidgetLayout" by default
  93    *
  94    * @returns true on success and false on failure (if you can't write
  95    * to the configGroup).
  96    */
  97   bool saveLayout(
  98       KConfig *config,
  99       const QString &groupName,
 100       const QString &keyName = QString()
 101     ) const;
 102
 103   /**
 104    * Attempts to restore the layout of this tree from the specified
 105    * key of the specified KConfigGroup. The layout must have been
 106    * previously saved by a call to saveLayout().
 107    *
 108    * Please note that you must call this function after having added
 109    * all the relevant columns to the view. On the other hand if you're
 110    * setting some of the view properties programmatically (like default
 111    * section size) then you should set them after restoring the layout
 112    * because otherwise they might get overwritten by the stored data.
 113    * The proper order is: add columns, restore layout, set header properties.
 114    *
 115    * @param group The KConfigGroup to read the layout data from.
 116    * @param keyName The key to use, "TreeWidgetLayout" by default
 117    *
 118    * @returns true if the layout data has been successfully read and
 119    *          restored. Returns false if the specified key of the config
 120    *          group is empty, or the data contained inside is not valid.
 121    */
 122   bool restoreLayout(
 123       KConfigGroup &group,
 124       const QString &keyName = QString()
 125     );
 126
 127   /**
 128    * Attempts to restore the layout of this tree from the specified
 129    * key of the specified group. The layout must have been
 130    * previously saved by a call to saveLayout().
 131    *
 132    * Please note that you must call this function after having added
 133    * all the relevant columns to the view. On the other hand if you're
 134    * setting some of the view properties programmatically (like default
 135    * section size) then you should set them after restoring the layout
 136    * because otherwise they might get overwritten by the stored data.
 137    * The proper order is: add columns, restore layout, set header properties.
 138    *
 139    * @param configGroup The name of the KConfig group to read the layout data from.
 140    * @param keyName The key to use, "TreeWidgetLayout" by default
 141    *
 142    * @returns true if the layout data has been successfully read and
 143    *          restored. Returns false if the specified key of the config
 144    *          group is empty, or the data contained inside is not valid.
 145    */
 146   bool restoreLayout(
 147       KConfig *config,
 148       const QString &groupName,
 149       const QString &keyName = QString()
 150     );
 151
 152   //
 153   // Manual and programmatic column hiding
 154   //
 155
 156   /**
 157    * Enables or disables manual column hiding by the means of a contextual menu.
 158    * All columns but the first can be hidden by the user by toggling the
 159    * check on the popup menu that is displayed by right clicking the header
 160    * of this view.
 161    *
 162    * By default column hiding is enabled.
 163    */
 164   void setManualColumnHidingEnabled( bool enable );
 165
 166   /**
 167    * @returns true if manual column hiding is currently enabled, false otherwise.
 168    */
 169   bool manualColumnHidingEnabled() const
 170     { return mEnableManualColumnHiding; };
 171
 172   /**
 173    * Hides or shows the column specified by logicalIndex.
 174    * The column is hidden if hide is true and shown otherwise.
 175    */
 176   void setColumnHidden( int logicalIndex, bool hide );
 177
 178   /**
 179    * Returns true if the column specified by logicalIndex is actually hidden.
 180    */
 181   bool isColumnHidden( int logicalIndex ) const;
 182
 183   /**
 184    * Toggle the visibility state of the specified column.
 185    */
 186   void toggleColumn( int logicalIndex );
 187
 188   /**
 189    * Called by this class to fill the contextual menu shown when the
 190    * user right clicks on one of the header columns and column hiding
 191    * is enabled.
 192    *
 193    * If you override this, remember to call the base class implementation
 194    * if you want to keep column hiding working.
 195    *
 196    * You should return true if you want the menu to be shown or false
 197    * if you don't want it to be shown. The default implementation returns
 198    * true unless you have no columns at all, column hiding is disabled
 199    * or you pass some weird parameter.
 200    */
 201   virtual bool fillHeaderContextMenu( KMenu *menu, const QPoint &clickPoint );
 202
 203   //
 204   // Facilities for adding and manipulating columns
 205   //
 206
 207   /**
 208    * Convenience function that adds a column to this tree widget
 209    * and returns its logical index. Please note that in fact
 210    * this function manipulates the header item which in turn
 211    * plays with the underlying data model.
 212    *
 213    * The alignment flags refer to the header text only. For individual
 214    * items you must set the alignment manually.
 215    *
 216    * @param label The label for the column
 217    * @param alignment The alignment of the header text for this column
 218    */
 219   int addColumn(
 220       const QString &label,
 221       int headerAlignment = Qt::AlignLeft | Qt::AlignVCenter
 222     );
 223
 224   /**
 225    * Convenience function that changes the header text for the specified column.
 226    * Returns true if the text can be successfully changed or false
 227    * if the specified column index is out of range.
 228    */
 229   bool setColumnText( int columnIndex, const QString &label );
 230
 231   /**
 232    * Convenience function that returns the last item in the view.
 233    */
 234   QTreeWidgetItem *lastItem() const;
 235
 236   /**
 237    * Convenience function that returns the first item in the view.
 238    * This, in fact, is roughly equivalent to topLevelItem( 0 ).
 239    * It is included for symmetry with lastItem().
 240    */
 241   QTreeWidgetItem *firstItem() const;
 242
 243 Q_SIGNALS:
 244   /**
 245    * This signal is emitted when an existing column is shown or hidden
 246    * either by the means of the popup menu or by a call to setColumnHidden().
 247    * See also setManualColumnHidingEnabled().
 248    */
 249   void columnVisibilityChanged( int logicalIndex );
 250
 251 protected:
 252   /**
 253    * Reimplemented in order to catch style change events
 254    * and explicitly disable animations.
 255    */
 256   virtual void changeEvent( QEvent *e );
 257
 258 private Q_SLOTS:
 259   /**
 260    * Internal slot connected to the customContextMenuRequested()
 261    * signal of the header().
 262    */
 263   void slotHeaderContextMenuRequested( const QPoint &clickPoint );
 264
 265   /**
 266    * Internal slot connected to the show/hide actions in the
 267    * header contextual menu.
 268    */
 269   void slotToggleColumnActionTriggered( bool );
 270
 271 private:
 272   bool mEnableManualColumnHiding; ///< Is manual column hiding currently enabled ?
 273
 274 };
 275
 276 } // namespace KPIM
 277
 278 #endif //!__TREEWIDGET_H__