kdat/ktreeview.h

   1 /*
   2  * KTreeView class interface
   3  *
   4  * Copyright (C) 1997 Johannes Sixt
   5  *
   6  * based on KTreeList, which is
   7  * Copyright (C) 1996 Keith Brown and KtSoft
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU General Public License as published by the
  11  * Free Software Foundation; either version 2 of the License, or (at your
  12  * option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABLILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17  * General Public License for more details. You should have received a copy
  18  * of the GNU General Public License along with this program; if not, write
  19  * to the Free Software Foundation, Inc, 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
  20  * USA.
  21  */
  22
  23 #ifndef KDE_KTREE_VIEW_H
  24 #define KDE_KTREE_VIEW_H
  25
  26 #include <qpixmap.h>                    /* used in items */
  27                         /* used in items */
  28 #include <q3gridview.h>                 /* base class for widget */
  29 //Added by qt3to4:
  30 #include <QMouseEvent>
  31 #include <QFocusEvent>
  32 #include <QKeyEvent>
  33 #include <QStack>
  34 // use stack of strings to represent path information
  35 typedef QStack<QString *> KPath;
  36
  37 class KTreeView;                        /* forward declaration */
  38
  39 /** Items for the KTreeView widget */
  40 class KTreeViewItem
  41 {
  42     friend class KTreeView;
  43 public:
  44     /**
  45      * Item constructor. While text defaults to a null string, and the
  46      * item can be constructed this way, the text has to be non-null when
  47      * the item is added to the tree, or it will not be inserted.
  48      *
  49      * The constructor sets the delete-children flag to false. This flag
  50      * tells the item whether it shall delete the child items when it is
  51      * itself deleted. By default the creator of the item is responsible to
  52      * also delete the child items. (However, the versions of
  53      * KTreeView::appendChildItem and KTreeView::insertChildItem that do
  54      * not take a KTreeViewItem set the delete-children flag to true.)
  55      */
  56     KTreeViewItem(const QString& theText = QString()); // text can not be null when added to the list!
  57     KTreeViewItem(const QString& theText, const QPixmap& thePixmap);
  58
  59     /**
  60      * Destructor. It destroys its children if this item has been marked
  61      * with setDeleteChildren(true).
  62      */
  63     virtual ~KTreeViewItem();
  64
  65     /**
  66      * Appends a new (direct) child item at the end. It does not update
  67      * administrative data in newChild except for its parent (which is this
  68      * item) and owner.
  69      */
  70     void appendChild(KTreeViewItem* newChild);
  71
  72     /**
  73      * Returns a pointer to the child item at the given index in this
  74      * item's sub tree, or 0 if not found.
  75      */
  76     KTreeViewItem* childAt(int index) const;
  77
  78     /**
  79      * Returns the number of child items in this item's sub tree.
  80      */
  81     uint childCount() const;
  82
  83     /**
  84      * Returns the index in this items sub tree of the given item or -1 if
  85      * not found. The specified child must not be 0.
  86      */
  87     int childIndex(KTreeViewItem* child) const;
  88
  89     /**
  90      * Determines whether the specified point is inside the expand button.
  91      */
  92     bool expandButtonClicked(const QPoint& coord) const;
  93
  94     /**
  95      * Give the item a chance to process the mouse event.
  96      */
  97     virtual bool mousePressEvent( const QPoint& coord );
  98
  99     /**
 100      * Returns a pointer to the first child item in this item's sub tree, or
 101      * 0 if none.
 102      */
 103     KTreeViewItem* getChild() const;
 104
 105     /**
 106      * Returns a pointer to the parent of this item, or 0 if none.
 107      */
 108     KTreeViewItem* getParent() const;
 109
 110     /**
 111      * Returns a reference to this item's pixmap. If there is no pixmap
 112      * associated with this item, it will return a reference to a valid,
 113      * null QPixmap.
 114      */
 115     const QPixmap& getPixmap() const;
 116
 117     /**
 118      * Returns a pointer to the next item in the same branch below this
 119      * one, or 0 if none.
 120      */
 121     KTreeViewItem* getSibling() const;
 122
 123     /**
 124      * Returns this item's text.
 125      */
 126     const QString& getText() const;
 127
 128     /**
 129      * Indicates whether this item has any children.
 130      */
 131     bool hasChild() const;
 132
 133     /**
 134      * Indicates whether this item has a parent.
 135      */
 136     bool hasParent() const;
 137
 138     /**
 139      * Indicates whether this item has a sibling item, that is, an item
 140      * that would be displayed below it at the same level as this item.
 141      */
 142     bool hasSibling() const;
 143
 144     /**
 145      * Inserts the a new (direct) child in this item before the child at
 146      * the specified index (first child is index 0). If there is no child
 147      * at the specified index, the item is appended. It does not update
 148      * administrative data in newChild except for its parent (which is this
 149      * item) and owner.
 150      */
 151     void insertChild(int index, KTreeViewItem* newChild);
 152
 153     /**
 154      * Indicateds whether the item is expanded, that is, whether the child
 155      * items (if any) would be visible if this item were visible.
 156      *
 157      * Note: If this function returns true, it does not necessarily indicate that
 158      * this item is visible or that this item has any children.
 159      */
 160     bool isExpanded() const;
 161
 162     /**
 163      * Returns true if the item is visible. An item is visible if all its
 164      * ancestors are expanded.
 165      */
 166     bool isVisible() const;
 167
 168     /**
 169      * Removes the specified (direct) child from this item and returns
 170      * true. If it is not a direct child of this item, nothing happens, and
 171      * false is returned. This function does not update the owning
 172      * KTreeView.
 173      */
 174     bool removeChild(KTreeViewItem* child);
 175
 176     /**
 177      * Sets the delayed-expanding flag. If this flag is true, the expanding
 178      * signal is emitted when the item is about to be expanded. The expand
 179      * button is always painted for this item, even if it doesn't have
 180      * children.
 181      */
 182     void setDelayedExpanding(bool flag);
 183
 184     /**
 185      * Tells the item whether it should delete its children when it is
 186      * deleted. The default is false, which means that the child items must
 187      * be deleted explicitly.
 188      */
 189     void setDeleteChildren(bool flag);
 190
 191     void setDrawExpandButton(bool doit);
 192
 193     void setDrawText(bool doit);
 194
 195     void setDrawTree(bool doit);
 196
 197     void setExpanded(bool is);
 198
 199     /**
 200      * Sets the item pixmap to the given pixmap. It does not redraw the
 201      * item or update the owning KTreeView.
 202      */
 203     void setPixmap(const QPixmap& pm);
 204
 205     /**
 206      * Sets the item text. This function does not redraw the item or update
 207      * the owning KTreeView.
 208      */
 209      void setText(const QString& t);
 210
 211 protected:
 212     /**
 213      * Returns the bounding rectangle of the item.
 214      */
 215     virtual QRect boundingRect(int indent) const;
 216
 217     /**
 218      * Returns the hieght of the item. The default implementation uses font
 219      * metrics of the owning KTreeView widget.
 220      */
 221     virtual int height() const;
 222
 223     /*
 224      * Returns the height of the item depending on the passed-in font
 225      * metrics.
 226      */
 227     virtual int height(const QFontMetrics& fm) const;
 228
 229     /**
 230      * Paints the item: pixmap, text, expand button, parent branches
 231      */
 232     virtual void paint(QPainter* p, int indent,
 233                         const QColorGroup& cg, bool highlighted) const;
 234
 235     /**
 236      * paints the expand button
 237      */
 238     virtual void paintExpandButton(QPainter* p, int indent, int cellHeight) const;
 239
 240     /**
 241      * paints the highlighted text
 242      */
 243     virtual void paintHighlight(QPainter* p, int indent,
 244                         const QColorGroup& cg, bool hasFocus,
 245                         Qt::GUIStyle style) const;
 246
 247     /**
 248      * paints the item's text
 249      */
 250     virtual void paintText(QPainter* p, int indent, int cellHeight,
 251                            const QColorGroup& cg, bool highlighted) const;
 252
 253     /**
 254      * paints the item's tree part.
 255      */
 256     virtual void paintTree(QPainter* p, int indent, int cellHeight) const;
 257
 258     /**
 259      * Internal function that counts the number of child items.
 260      */
 261     void synchNumChildren();
 262
 263     /**
 264      * Returns the bounding rectangle of the text.
 265      */
 266     virtual QRect textBoundingRect(int indent) const;
 267
 268     /**
 269      * Returns the width of the item taking into account the specified
 270      * indentation. The default implementation uses font metrics of the
 271      * owning KTreeView widget.
 272      */
 273     virtual int width(int indent) const;
 274
 275     /**
 276      * Returns the width of the item depending on the passed-in font
 277      * metrics and taking into account the specified indentation.
 278      */
 279     virtual int width(int indent, const QFontMetrics& fm) const;
 280
 281 protected:
 282     /** The KTreeView that this item belongs to */
 283     KTreeView* owner;
 284     int numChildren;
 285     bool doExpandButton;
 286     bool expanded;
 287     bool delayedExpanding;
 288     bool doTree;
 289     bool doText;
 290     mutable QRect expandButton;         /* is set in paint() */
 291     KTreeViewItem* child;
 292     KTreeViewItem* parent;
 293     KTreeViewItem* sibling;
 294     QPixmap pixmap;
 295     QString text;
 296     bool deleteChildren;
 297 };
 298
 299 // easier declarations of function prototypes for forEvery type functions
 300 typedef bool (KTreeView::*KForEveryM)
 301   (KTreeViewItem *, void *);
 302 typedef bool (*KForEvery)
 303   (KTreeViewItem *, void *);
 304
 305 /**
 306   A collapsible treelist widget.
 307
 308   1. Introduction
 309   2. Features
 310   3. Installation
 311   4. Public interface
 312
 313   1. Introduction
 314   ================================================================================
 315
 316   KTreeView is a class inherited from QTableView in the Qt user interface
 317   library. It provides a way to display hierarchical data in a single-inheritance
 318   tree, similar to tree controls in Microsoft Windows and other GUI's. It is most
 319   suitable for directory trees or outlines, but I'm sure other uses will come to
 320   mind. Frankly, it was designed mostly with the above two functions in mind, but
 321   I have tried to make it as flexible as I know how to make it easy to adapt to
 322   other uses.
 323
 324   In case of problems, I encourage you to read all of the other documentation
 325   files in this package before contacting me  as you may find the answer to your
 326   question in one of them. Also read the source code if you have time. I have
 327   tried to comment it adequately and make the source understandable.
 328
 329   2. Features
 330   ================================================================================
 331
 332   * Displays both text and optional pixmap supplied by the programmer. A support
 333   class, KTreeViewItem, can be inherited and modified to draw items as needed
 334   by the programmer.
 335
 336   * The list items can be returned by index or logical path and the tree
 337   navigated by parent, child or sibling references contained in them. Also,
 338   item information such as text, pixmap, branch level can be obtained.
 339
 340   * Items can be inserted, changed and removed either by index in the visible
 341   structure, or by logical paths through the tree hierarchy.
 342
 343   * The logical path through the tree for any item can be obtained with the index
 344   of the item.
 345
 346   * Tree structure display and expanding/collapsing of sub-trees is handled with
 347   no intervention from the programmer.
 348
 349   * entire tree can be expanded or collapsed to a specified sub-level (handy for
 350   outline views)
 351
 352   * Configuration as follows:
 353
 354   enable/disable item text display (if you only want to display pixmaps)
 355
 356   enable/disable drawing of expand/collapse button
 357
 358   enable/disable drawing of tree structure
 359
 360   * Keyboard support as follows:
 361
 362   up/down arrows move the highlight appropriately and scroll the list an item at
 363   a time, if necessary
 364
 365   pgup/pgdn move the highlight a 'page' up or down as applicable and scroll the
 366   view
 367
 368   +/- keys expand/collapse the highlighted item if it appropriate
 369
 370   enter key selects the highlighted item
 371
 372   * Mouse support as follows:
 373
 374   left click on item highlights it
 375
 376   left click on an item "hot button" expands or collapses its sub-tree, as
 377   applicable
 378
 379   double click on item selects it
 380
 381   normal scrolling functions in conjunction with scrollbars if present
 382
 383   2nd scrolling with the middle mouse button: pressing MMB inserts a
 384   rubberband, showing which part of the whole tree is currently visible.
 385   moving the mouse will scroll the visible part
 386
 387   * Signals/Slots
 388
 389   signal void highlighted(int) - emitted when an item in the tree is
 390   highlighted; sends the index of the item
 391
 392   signal void selected(int) - emitted when an item in the tree is
 393   selected; sends the index of the item
 394
 395   signal void expanded(int) - emitted when an item in the tree is expanded;
 396   sends the index of the item
 397
 398   signal void collpased(int) - emitted when an item in the tree is collapsed;
 399   sends the index of the item
 400   */
 401 class KTreeView : public Q3GridView
 402 {
 403     friend class KTreeViewItem;
 404     Q_OBJECT
 405 public:
 406     /**
 407      * Widget contructor. Passes all parameters on to base QTableView, and
 408      * does not use them directly. Does internal initialization, sets the
 409      * current item to -1, and sets default values for scroll bars (both
 410      * auto).
 411      */
 412     KTreeView(QWidget* parent = 0, const char* name = 0, Qt::WFlags f = 0);
 413
 414     /*
 415      * Desctructor. Deletes all items from the topmost level that have been
 416      * marked with setDeleteChildren(true).
 417      */
 418     virtual ~KTreeView();
 419
 420     /**
 421      * Appends a new child item to the item at the specified row. If that
 422      * item already has children, the new item is appended below these
 423      * children. A KTreeViewItem is created for which the delete-children
 424      * flag is set to true.
 425      */
 426     void appendChildItem(const QString & theText, const QPixmap& thePixmap,
 427                       int index);
 428
 429     /**
 430      * Same as above except that the parent item is specified by a path.
 431      */
 432     void appendChildItem(const QString & theText, const QPixmap& thePixmap,
 433                       const KPath& thePath);
 434
 435     /**
 436      * Appendss the specified item as a child of the item that is at the
 437      * specified row. If that item already has children, the new item is
 438      * appended below these children.
 439      */
 440     void appendChildItem(KTreeViewItem* newItem, int index);
 441
 442     /**
 443      * Same as above except that the parent item is specified by a path.
 444      */
 445     void appendChildItem(KTreeViewItem* newItem, const KPath& thePath);
 446
 447     /**
 448         Returns a bool value indicating whether the list will display a
 449         horizontal scrollbar if one of the displayed items is wider than can
 450         be displayed at the current width of the view.
 451         */
 452   bool autoBottomScrollBar() const;
 453
 454   /**
 455         Returns a bool value indicating whether the list will display a
 456         vertical scrollbar if the number of displayed items is more than can
 457         be displayed at the current height of the view.
 458         */
 459   bool autoScrollBar() const;
 460
 461   /**
 462         Returns a bool value indicating whether the list will update
 463         immediately on changing the state of the widget in some way.
 464         */
 465   bool autoUpdate() const;
 466
 467   /**
 468         Returns a bool value indicating whether the list has currently has a
 469         horizontal scroll bar.
 470         */
 471   bool bottomScrollBar() const;
 472
 473   /**
 474         Changes the text and/or pixmap of the given item at the specified
 475         index to the given values and updates the display if auto update
 476         enabled. If changing only the text or pixmap, set the other parameter
 477         to 0.
 478         */
 479   void changeItem(const QString & newText,
 480                                   const QPixmap *newPixmap,
 481                                   int index);
 482
 483   /**
 484         Same as above function, except item to change is specified by a path
 485         through the tree.
 486         */
 487   void changeItem(const QString & newText,
 488                                   const QPixmap *newPixmap,
 489                                   const KPath& thePath);
 490
 491   /**
 492         Removes all items from the tree.
 493
 494         */
 495   void clear();
 496
 497   /**
 498         Returns the total number of items in the tree, whether visible
 499         (expanded sub-trees) or not (collapsed).
 500         */
 501   uint count();
 502
 503   /**
 504         Returns the index of the current (highlighted) item. If no current
 505         item, returns -1.
 506         */
 507   int currentItem() const;
 508
 509   /**
 510         Collapses the sub-tree at the specified index.
 511         */
 512   void collapseItem(int index);
 513
 514   /**
 515         Expands the sub-tree at the specified index.
 516         */
 517   void expandItem(int index);
 518
 519   /**
 520         Returns the depth to which all parent items are automatically
 521         expanded.
 522         */
 523   int expandLevel() const;
 524
 525   /**
 526         Same as above functions combined into one. If sub-tree is expanded,
 527         collapses it, if it is collapsed, it expands it.
 528         */
 529   void expandOrCollapseItem(int index);
 530
 531     /**
 532      * Iterates every item in the tree, visible or not, and applies the
 533      * function func with a pointer to each item and user data supplied as
 534      * parameters. The children of the specified root item are visited
 535      * (root itself is not visited!). If root is 0 all items in the tree
 536      * are visited. KForEveryFunc is defined as:
 537      *
 538      * typedef bool (*KForEvery)(KTreeViewItem*, void*);
 539      *
 540      * That is, a function that returns bool and takes a pointer to a
 541      * KTreeViewItem and pointer to void as parameters. The traversal ends
 542      * earlier if the supplied function returns bool. In this case the
 543      * return value is also true.
 544      */
 545     bool forEveryItem(KForEvery func, void* user,
 546                       KTreeViewItem* root = 0);
 547
 548     /**
 549      * Same as above, but only iterates visible items, in order. If the
 550      * specified root item is invisible no items are visited.
 551      */
 552     bool forEveryVisibleItem(KForEvery func, void *user,
 553                              KTreeViewItem* root = 0);
 554
 555   /**
 556         Returns a pointer to the current item if there is one, or 0.
 557         */
 558   KTreeViewItem *getCurrentItem();
 559
 560     /**
 561      * Returns the number of pixels an item is indented for each level. If,
 562      * in a derived class, the levels are indented differently this value
 563      * may be ignored.
 564      */
 565     int indentSpacing();
 566
 567     /**
 568      * Inserts an item into the tree with the given text and pixmap either
 569      * before or after the item currently at the given row, depending on
 570      * the value of prefix. The new item is added to the same branch as the
 571      * referenced item. If row is -1, the item is simply appended to the
 572      * tree at the topmost level. A KTreeViewItem is created for which the
 573      * delete-children flag is set to true. Returns true if the item has
 574      * been successfully inserted in the tree, otherwise false.
 575      */
 576     bool insertItem(const QString & theText, const QPixmap& thePixmap,
 577                     int row = -1, bool prefix = true);
 578
 579     /**
 580      * Same as above, but uses a path through the tree to reference the
 581      * insert position. If there is no item at the specified path, the item
 582      * is simply appended to the tree at the topmost level.
 583      */
 584     bool insertItem(const QString & theText, const QPixmap& thePixmap,
 585                     const KPath& thePath, bool prefix = true);
 586
 587     /**
 588      * Same as above, but an item is specified instead of a text and a pixmap.
 589      */
 590     bool insertItem(KTreeViewItem *newItem,
 591                     int row = -1, bool prefix = true);
 592
 593     /**
 594      * Same as above, but uses a path through the tree to reference the
 595      * insert position.
 596      */
 597     bool insertItem(KTreeViewItem *newItem,
 598                     const KPath& thePath, bool prefix = true);
 599
 600     /**
 601      * Returns a pointer to the item in the specified row, or 0 if the
 602      * specified row is outside the limits. This is a cheap operation.
 603      */
 604     KTreeViewItem* itemAt(int row);
 605
 606     /**
 607      * Returns a pointer to the item at the end of the path.
 608      */
 609     KTreeViewItem* itemAt(const KPath& path);
 610
 611     /**
 612      * Returns the row at which the specified item is found in the visible
 613      * tree or -1 if the item is not visible or not in the tree.
 614      */
 615     int itemRow(KTreeViewItem* item);
 616
 617     /**
 618      * Fills path with the logical path to the item at the specified row.
 619      * The specified path variable should be empty. Any strings popped from
 620      * the path must be deleted by the caller. If the row is invalid, path
 621      * remains unchanged (i.e. empty).
 622      */
 623     void itemPath(int row, KPath& path);
 624
 625     /**
 626      * Outdents the item at the given row one level so that it becomes a
 627      * sibling of its parent.
 628      */
 629     void join(int index);
 630
 631     /**
 632      * Same as above but uses a path to specify the item.
 633      */
 634     void join(const KPath& path);
 635
 636     /**
 637      * Moves the item at the specified row down one row in its current
 638      * branch.
 639      */
 640     void lowerItem(int index);
 641
 642     /**
 643      * Same as above but uses a path to specify the item.
 644      */
 645     void lowerItem(const KPath& path);
 646
 647     /**
 648      * Moves the item at the specified row up one row in its current
 649      * branch.
 650      */
 651     void raiseItem(int row);
 652
 653     /**
 654      * Same as above but uses a path to specify the item.
 655      */
 656     void raiseItem(const KPath& path);
 657
 658     /**
 659      * Removes the item at the specified row.
 660      */
 661     void removeItem(int row);
 662
 663     /**
 664      * Same as above except uses path through the tree to find the item.
 665      */
 666     void removeItem(const KPath& thePath);
 667
 668   /**
 669         Returns bool value indicating whether the list currently displays a
 670         vertical scroll bar.
 671         */
 672   bool scrollBar() const;
 673
 674   /**
 675         If enable is TRUE (default), enables auto update, else disables it.
 676         */
 677   void setAutoUpdate(bool enable);
 678
 679   /**
 680         If enable is TRUE, displays a horizontal scroll bar, else hides it.
 681         */
 682   void setBottomScrollBar(bool enable);
 683
 684     /**
 685      * Makes the item at row current and highlights it. The signal
 686      * highlighted is emitted if the current item changes.
 687      */
 688     void setCurrentItem(int row);
 689
 690   void setExpandButtonDrawing(bool enable);
 691
 692   void setExpandLevel(int level);
 693
 694     /**
 695      * Sets the indentation stepping, in pixels.  If, in a derived class,
 696      * the levels are indented differently this value may be ignored.
 697      */
 698     void setIndentSpacing(int spacing);
 699
 700   /**
 701         If enable is TRUE, displays a vertical scroll bar, else hides it.
 702         */
 703   void setScrollBar(bool enable);
 704
 705   /**
 706         If enable is TRUE (default), item text will be displayed, otherwise
 707         it will not, and no highlight will be shown in the default widget.
 708         */
 709   void setShowItemText(bool enable);
 710
 711   /**
 712         If enable is TRUE, enables smooth scrolling, else disables
 713         it (default).
 714         */
 715   void setSmoothScrolling(bool enable);
 716
 717   /**
 718         If enable is TRUE (default), lines depicting the structure of the
 719         tree will be drawn, otherwise they will not.
 720         */
 721   void setTreeDrawing(bool enable);
 722
 723   /**
 724         Indicates whether item text is displayed.
 725         */
 726   bool showItemText() const;
 727
 728   /**
 729         Returns a bool value indicating whether smooth scrolling is enabled.
 730         */
 731   bool smoothScrolling() const;
 732
 733     /**
 734      * Indents the item at the specified index, creating a new branch.
 735      */
 736     void split(int index);
 737
 738     /**
 739      * Same as above but uses a path to specify the item.
 740      */
 741     void split(const KPath& path);
 742
 743     /**
 744      * Removes the item at the given index from the tree, but does not
 745      * delete it, returning a pointer to the removed item.
 746      */
 747     KTreeViewItem* takeItem(int index);
 748
 749     /**
 750      * Same as above but uses a path to specify the item to take.
 751      */
 752     KTreeViewItem* takeItem(const KPath& path);
 753
 754   /**
 755         Indicates whether the tree structure is drawn.
 756         */
 757   bool treeDrawing() const;
 758
 759     /**
 760      * This function is deprecated. Use numRows() instead.
 761      * Returns the number of items that are visible (their parents are
 762      * expanded).
 763      */
 764     int visibleCount() const { return numRows(); }
 765
 766 signals:
 767     void collapsed(int index);
 768     void expanded(int index);
 769     /**
 770      * The expanding signal is emitted when an item that has the
 771      * delayedExpanding flag set is about to be expanded. The
 772      * delayedExpanding flag is not reset; the slot that the signal is
 773      * connected to should do so. The item being expanded is passed to the
 774      * slot. The slot gets the opportunity to insert child items into that
 775      * item. It should not change the item any other way. It can allow or
 776      * disallow the expansion by setting the second parameter allow. If it
 777      * is set to false, the item is not expanded.
 778      *
 779      * The signal is always emitted, regardless whether the expansion was
 780      * triggered by the user or by the program.
 781      */
 782     void expanding(KTreeViewItem* item, bool& allow);
 783     void highlighted(int index);
 784     void selected(int index);
 785
 786     void popupMenu( int index, const QPoint& );
 787 protected:
 788     /**
 789      * Appends theChild to theParent as a new direct child. All internal
 790      * state is updated and the widget is repainted as necessary. theChild
 791      * remains invisible if any ancestor of theParent is collapsed.
 792      */
 793     void appendChildItem(KTreeViewItem* theParent,
 794                          KTreeViewItem* theChild);
 795     void changeItem(KTreeViewItem* toChange,
 796                     int itemRow, const QString & newText,
 797                     const QPixmap* newPixmap);
 798     /**
 799      * Collapses the specified subtree and updates the display. subRoot
 800      * need not be visible.
 801      */
 802     void collapseSubTree(KTreeViewItem* subRoot);
 803     /** Internal function used for counting items */
 804     bool countItem(KTreeViewItem* item, void* total);
 805
 806     void expandOrCollapse(KTreeViewItem *parentItem);
 807     /**
 808      * Expands the specified subtree and updates the display. subRoot need
 809      * not be visible.
 810      */
 811     void expandSubTree(KTreeViewItem* subRoot);
 812   void fixChildren(KTreeViewItem *parentItem);
 813   virtual void focusInEvent(QFocusEvent *e);
 814   void forEveryItem(KForEveryM func,
 815                                         void *user);
 816   void forEveryVisibleItem(KForEveryM func,
 817                                                    void *user);
 818
 819     /** internal function used to determine maximum item width */
 820     bool getMaxItemWidth(KTreeViewItem* item, void *user);
 821
 822     /**
 823      * Returns the indentation of the specified item in pixels.
 824      */
 825     virtual int indentation(KTreeViewItem* item) const;
 826
 827     /**
 828      * Inserts the specified newItem before or after the specified
 829      * referenceItem. If referenceItem is 0, the newItem is appended at the
 830      * topmost level. If referenceItem is not 0, it must be an item that is
 831      * already in the KTreeView. Internal data is updated and the display
 832      * is refreshed as necessary. The inserted item may still be invisible
 833      * if any of the parents is collapsed. newItem must not be 0.
 834      */
 835     bool insertItem(KTreeViewItem* referenceItem, KTreeViewItem* newItem,
 836                     bool prefix);
 837
 838     /**
 839      * Finds the logical path of the specified item. The specified path
 840      * variable should be empty.
 841      */
 842     void itemPath(KTreeViewItem* item, KPath& path) const;
 843
 844   void join(KTreeViewItem *item);
 845   virtual void keyPressEvent(QKeyEvent *e);
 846     int level(KTreeViewItem* item) const;
 847   void lowerItem(KTreeViewItem *item);
 848   virtual void mouseDoubleClickEvent(QMouseEvent *e);
 849   virtual void mouseMoveEvent(QMouseEvent *e);
 850   virtual void mousePressEvent(QMouseEvent *e);
 851   virtual void mouseReleaseEvent(QMouseEvent *e);
 852   virtual void paintCell(QPainter *p, int row, int col);
 853     /*
 854      * virtual void paintItem(QPainter *p, KTreeViewItem *item,
 855                               * bool highlighted);
 856      */
 857     void raiseItem(KTreeViewItem* item);
 858
 859     /**
 860      * Internal function that finds the item at the given path. Returns 0
 861      * if the item cannot be found. The path is destroyed by this function.
 862      */
 863     KTreeViewItem* recursiveFind(KPath& path);
 864
 865   bool setItemExpanded(KTreeViewItem *item, void *);
 866   bool setItemExpandButtonDrawing(KTreeViewItem *item, void *);
 867   bool setItemShowText(KTreeViewItem *item, void *);
 868   bool setItemTreeDrawing(KTreeViewItem *item, void *);
 869   void split(KTreeViewItem *item);
 870 public:
 871   void takeItem(KTreeViewItem *item);
 872 protected:
 873     virtual void updateCellWidth();
 874     virtual void updateVisibleItems();
 875     void updateVisibleItemRec(KTreeViewItem* parent, int& count, int& width);
 876
 877     KTreeViewItem* treeRoot;
 878     bool clearing;
 879     int current;
 880     bool drawExpandButton;
 881     bool drawTree;
 882     int expansion;
 883     bool goingDown;
 884     int itemIndent;
 885     int maxItemWidth;
 886     bool showText;
 887     // list of visible items
 888     int itemCapacity;                   /* for how many items we've space allocated */
 889     KTreeViewItem** visibleItems;
 890
 891   // Rainer Bawidamann: move window in "rubberband" mode
 892   bool rubberband_mode;             // true if in "rubberband_mode"
 893   QPoint rubber_startMouse;         // where the user pressed the MMB
 894   int rubber_height, rubber_width,  // the size if the rubberband rect
 895         rubber_startX, rubber_startY; // the x/yOffset() when the MMB was pressed
 896   void draw_rubberband();
 897   void start_rubberband(const QPoint& where);
 898   void end_rubberband();
 899   void move_rubberband(const QPoint& where);
 900 };
 901
 902 #endif // KDE_KTREE_VIEW_H