kdbg/ktreeview.h

   1 /*
   2  * $Id$
   3  *
   4  * KTreeView class interface
   5  *
   6  * Copyright (C) 1997 Johannes Sixt
   7  *
   8  * based on KTreeList, which is
   9  * Copyright (C) 1996 Keith Brown and KtSoft
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU General Public License as published by the
  13  * Free Software Foundation; either version 2 of the License, or (at your
  14  * option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABLILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19  * General Public License for more details. You should have received a copy
  20  * of the GNU General Public License along with this program; if not, write
  21  * to the Free Software Foundation, Inc, 675 Mass Ave, Cambridge, MA 02139,
  22  * USA.
  23  */
  24
  25 #ifndef KDE_KTREE_VIEW_H
  26 #define KDE_KTREE_VIEW_H
  27
  28 #include <qpixmap.h>                    /* used in items */
  29 #include <qvaluestack.h>                /* used to specify tree paths */
  30 #include <qstring.h>                    /* used in items */
  31 #include "tableview.h"                  /* base class for widget */
  32
  33 // use stack of strings to represent path information
  34 typedef QValueStack<QString> KPath;
  35
  36 class KTreeView;                        /* forward declaration */
  37
  38 /** Items for the KTreeView widget */
  39 class KTreeViewItem : public Qt
  40 {
  41     friend class KTreeView;
  42 public:
  43     /**
  44      * Item constructor. While text defaults to a null string, and the
  45      * item can be constructed this way, the text has to be non-null when
  46      * the item is added to the tree, or it will not be inserted.
  47      *
  48      * The constructor sets the delete-children flag to false. This flag
  49      * tells the item whether it shall delete the child items when it is
  50      * itself deleted. By default the creator of the item is responsible to
  51      * also delete the child items. (However, the versions of @ref
  52      * #appendChildItem and @ref #insertChildItem that do not take a
  53      * KTreeViewItem set the delete-children flag to true.)
  54      *
  55      * @param text specifies the new item's text
  56      */
  57     KTreeViewItem(const QString& text = QString()); // text can not be null when added to the list!
  58     /**
  59      * This overloaded constructor allows to specify a pixmap for the new
  60      * item.
  61      *
  62      * @param text specifies the item's text
  63      * @param pixmap specifies the item's pixmap
  64      */
  65     KTreeViewItem(const QString& text, const QPixmap& pixmap);
  66
  67     /**
  68      * Destructor. It also destroys its children.
  69      */
  70     virtual ~KTreeViewItem();
  71
  72     /**
  73      * Appends a new (direct) child item at the end. It does not update
  74      * administrative data in newChild except for its parent (which is this
  75      * item) and owner.
  76      */
  77     virtual void appendChild(KTreeViewItem* newChild);
  78
  79     /**
  80      * Returns a pointer to the child item at the given index in this
  81      * item's sub tree, or 0 if not found.
  82      *
  83      * @param index specifies the index of the direct child to return
  84      * @return the direct child at the specified index
  85      */
  86     KTreeViewItem* childAt(int index) const;
  87
  88     /**
  89      * Returns the number of child items in this item's sub tree.
  90      */
  91     uint childCount() const;
  92
  93     /**
  94      * Returns the index in this items sub tree of the given item or -1 if
  95      * the specified item is not a direct child of this item.
  96      *
  97      * @param child specifies the child to look up; must not be 0
  98      * @returns the index of the specified direct child
  99      */
 100     int childIndex(KTreeViewItem* child) const;
 101
 102     /**
 103      * Determines whether the specified point is inside the expand button.
 104      */
 105     bool expandButtonClicked(const QPoint& coord) const;
 106
 107     /**
 108      * Returns a pointer to the first child item in this item's sub tree, or
 109      * 0 if none.
 110      */
 111     KTreeViewItem* getChild() const;
 112
 113     /**
 114      * Returns a pointer to the parent of this item, or 0 if none.
 115      */
 116     KTreeViewItem* getParent() const;
 117
 118     /**
 119      * Returns a reference to this item's pixmap. If there is no pixmap
 120      * associated with this item, it will return a reference to a valid,
 121      * null QPixmap.
 122      */
 123     const QPixmap& getPixmap() const;
 124
 125     /**
 126      * Returns a pointer to the next sibling item in the same branch below this
 127      * one, or 0 if this item has no siblings below it.
 128      */
 129     KTreeViewItem* getSibling() const;
 130
 131     /**
 132      * Returns this item's text.
 133      */
 134     const QString& getText() const;
 135
 136     /**
 137      * Indicates whether this item has any children.
 138      */
 139     bool hasChild() const;
 140
 141     /**
 142      * Indicates whether this item has a parent.
 143      */
 144     bool hasParent() const;
 145
 146     /**
 147      * Indicates whether this item has a sibling item, that is, an item
 148      * that would be displayed below it at the same level as this item.
 149      */
 150     bool hasSibling() const;
 151
 152     /**
 153      * Inserts the a new (direct) child in this item before the child at
 154      * the specified index (first child is index 0). If there is no child
 155      * at the specified index, the item is appended. It does not update
 156      * administrative data in newChild except for its parent (which is this
 157      * item) and owner.
 158      *
 159      * @param index specifies the index of a direct child of this item
 160      * @param newChild specifies the new item to insert
 161      */
 162     virtual void insertChild(int index, KTreeViewItem* newChild);
 163
 164     /**
 165      * Indicates whether the item is expanded, that is, whether the child
 166      * items (if any) would be visible if this item were visible.
 167      *
 168      * Note: If this function returns true, it does not necessarily indicate
 169      * that this item is visible or that this item has any children.
 170      */
 171     bool isExpanded() const;
 172
 173     /**
 174      * Returns true if the item is visible. An item is visible if @ref
 175      * #isExpanded() returns true for all its ancestors.
 176      *
 177      * Note: If this function returns true, it does not necessarily indicate
 178      * that the widget is visible.
 179      */
 180     bool isVisible() const;
 181
 182     /**
 183      * Removes the specified (direct) child from this item and returns
 184      * true. If it is not a direct child of this item, nothing happens, and
 185      * false is returned. This function does not update the owning
 186      * KTreeView.
 187      */
 188     virtual bool removeChild(KTreeViewItem* child);
 189
 190     /**
 191      * Sets the delayed-expanding flag. If this flag is true, the signal
 192      * @ref #expanding is emitted when the item is about to be expanded.
 193      * The expand button is always painted for this item, even if it
 194      * doesn't have children.
 195      */
 196     void setDelayedExpanding(bool flag);
 197
 198     /**
 199      * Tells the item whether it should draw the expand button. The default
 200      * is true. This function does not update the owning tree widget.
 201      */
 202     virtual void setDrawExpandButton(bool doit);
 203
 204     /**
 205      * Tells the item whether it should paint the text. The default is
 206      * true. This function does not update the owning tree widget.
 207      */
 208     virtual void setDrawText(bool doit);
 209
 210     /**
 211      * Tells the item whether it should draw the tree lines. The default is
 212      * true. This function does not update the owning tree widget.
 213      */
 214     virtual void setDrawTree(bool doit);
 215
 216     /**
 217      * Tells whether the item is expanded (i.e. whether its children are
 218      * visible). The default is false. This function does not update the
 219      * owning tree widget.
 220      */
 221     virtual void setExpanded(bool is);
 222
 223     /**
 224      * Sets the item pixmap to the given pixmap. It does not redraw the
 225      * item or update the owning KTreeView.
 226      */
 227     virtual void setPixmap(const QPixmap& pm);
 228
 229     /**
 230      * Sets the item text. This function does not redraw the item or update
 231      * the owning KTreeView.
 232      */
 233     virtual void setText(const QString& t);
 234
 235 protected:
 236     /**
 237      * Returns the bounding rectangle of the item.
 238      */
 239     virtual QRect boundingRect(int indent) const;
 240
 241     /**
 242      * Returns the height of the item. The default implementation uses font
 243      * metrics of the owning KTreeView widget.
 244      */
 245     virtual int height() const;
 246
 247     /*
 248      * Returns the height of the item depending on the passed-in font
 249      * metrics.
 250      */
 251     virtual int height(const QFontMetrics& fm) const;
 252
 253     /*
 254      * The item is given a chance to process key events before the owning
 255      * KTreeView processes the event.
 256      *
 257      * @param ev specifies the key event; use ev->type() to find out whether
 258      * this is a key down or up event (see @ref #QEvent).
 259      * @return true if the event has been processed, false if it has not
 260      * been processed. The default implementation just returns false to
 261      * indicate that the event has not been processed.
 262      */
 263     virtual bool keyEvent(QKeyEvent* ev);
 264
 265     /*
 266      * The item is given a chance to process mouse events before the owning
 267      * KTreeView processes the event.
 268      *
 269      * @param ev specifies the mouse event; use ev->type() to find out whether
 270      * this is a mouse press, release, double click, or move event (see
 271      * @ref #QEvent).
 272      * @param itemCoord specifies the mouse even coordinates relative to this
 273      * item (the coordinates in ev are the original coordinates).
 274      * @return true if the event has been processed, false if it has not
 275      * been processed. The default implementation just returns false to
 276      * indicate that the event has not been processed.
 277      */
 278     virtual bool mouseEvent(QMouseEvent* ev, const QPoint& itemCoord);
 279
 280     /**
 281      * Paints the item: pixmap, text, expand button, parent branches
 282      */
 283     virtual void paint(QPainter* p, int indent,
 284                         const QColorGroup& cg, bool highlighted) const;
 285
 286     /**
 287      * paints the expand button
 288      */
 289     virtual void paintExpandButton(QPainter* p, int indent, int cellHeight,
 290                                    const QColorGroup& cg) const;
 291
 292     /**
 293      * paints the highlighted text
 294      */
 295     virtual void paintHighlight(QPainter* p, int indent,
 296                         const QColorGroup& cg, bool hasFocus) const;
 297
 298     /**
 299      * paints the item's text
 300      */
 301     virtual void paintText(QPainter* p, int indent, int cellHeight,
 302                            const QColorGroup& cg, bool highlighted) const;
 303
 304     /**
 305      * paints the item's tree part.
 306      */
 307     virtual void paintTree(QPainter* p, int indent, int cellHeight,
 308                            const QColorGroup& cg) const;
 309
 310     /**
 311      * Internal function that updates the owner of this item and its
 312      * children and siblings (the latter only if requested).
 313      */
 314     void setOwner(KTreeView* newOwner, bool includeSiblings = false);
 315
 316     /**
 317      * Internal function that counts the number of child items.
 318      */
 319     void synchNumChildren();
 320
 321     /**
 322      * Returns the bounding rectangle of the text.
 323      */
 324     virtual QRect textBoundingRect(int indent) const;
 325
 326     /**
 327      * Returns the width of the item taking into account the specified
 328      * indentation. The default implementation uses font metrics of the
 329      * owning KTreeView widget.
 330      */
 331     virtual int width(int indent) const;
 332
 333     /**
 334      * Returns the width of the item depending on the passed-in font
 335      * metrics and taking into account the specified indentation.
 336      */
 337     virtual int width(int indent, const QFontMetrics& fm) const;
 338
 339 protected:
 340     /** The KTreeView that this item belongs to */
 341     KTreeView* owner;
 342     int numChildren;
 343     bool doExpandButton;
 344     bool expanded;
 345     bool delayedExpanding;
 346     bool doTree;
 347     bool doText;
 348     mutable QRect expandButton;         /* is set in paint() */
 349     KTreeViewItem* child;
 350     KTreeViewItem* parent;
 351     KTreeViewItem* sibling;
 352     QPixmap pixmap;
 353     QString text;
 354 };
 355
 356 /**
 357  * KTreeView is a class that provides a way to display hierarchical data in
 358  * a single-inheritance tree, similar to tree controls in Microsoft Windows
 359  * and other GUIs. It is most suitable for directory trees or outlines, but
 360  * I'm sure other uses will come to mind. It was designed mostly with the
 361  * above two functions in mind, but I have tried to make it as flexible as
 362  * I can to make it easy to adapt to other uses.
 363  *
 364  * Please read the source code if you have time. I have tried to comment it
 365  * adequately and make the source understandable.
 366  *
 367  * The class features the following:
 368  *
 369  * - Displays both text and an optional pixmap supplied by the programmer.
 370  * A support class, KTreeViewItem, can be inherited and modified to draw
 371  * items as needed by the programmer.
 372  *
 373  * - The list items can be returned by index or logical path and the tree
 374  * navigated by parent, child or sibling references contained in them.
 375  * Also, item information such as text, pixmap, branch level can be
 376  * obtained.
 377  *
 378  * - Items can be inserted, changed and removed either by index in the
 379  * visible structure, or by logical paths through the tree hierarchy.
 380  *
 381  * - The logical path through the tree for any item can be obtained with
 382  * the index of the item.
 383  *
 384  * - Tree structure display and expanding/collapsing of sub-trees is
 385  * handled with no intervention from the programmer.
 386  *
 387  * - entire tree can be expanded or collapsed to a specified sub-level
 388  *  (handy for outline views)
 389  *
 390  * @short A collapsible treelist widget
 391  * @author Johannes Sixt <Johannes.Sixt@telecom.at>, Keith Brown
 392  */
 393 class KTreeView : public TableView
 394 {
 395     friend class KTreeViewItem;
 396     Q_OBJECT
 397 public:
 398     /**
 399      * Widget contructor. All parameters are passed on to base TableView,
 400      * and are not used directly.
 401      */
 402     KTreeView(QWidget* parent = 0, const char* name = 0, WFlags f = 0);
 403
 404     /**
 405      * Desctructor. Deletes all items.
 406      */
 407     virtual ~KTreeView();
 408
 409     /**
 410      * Appends a new child item to the item at the specified row. If that
 411      * item already has children, the new item is appended below these
 412      * children. A KTreeViewItem is created for which the delete-children
 413      * flag is set to true.
 414      *
 415      * @param text specifies text for the new item; must not be 0
 416      * @param pixmap specifies a pixmap for the new item
 417      * @param index specifies the item of which the new item will be a child
 418      */
 419     void appendChildItem(const char* text, const QPixmap& pixmap,
 420                       int index);
 421
 422     /**
 423      * This overloaded function appends a new item to an item, which is
 424      * specified by a path.
 425      *
 426      * @param text specifies text for the new item; must not be 0
 427      * @param pixmap specifies a pixmap for the new item
 428      * @param path specifies the item of which the new item will be a child
 429      * @see #appendChildItem
 430      */
 431     void appendChildItem(const char* text, const QPixmap& pixmap,
 432                       const KPath& path);
 433
 434     /**
 435      * Appends the specified item as a child of the item that is at the
 436      * specified row. If that item already has children, the new item is
 437      * appended below these children.
 438      *
 439      * @param newItem specifies the new item
 440      * @param index specifies the item of which the new item will be a child
 441      * @see #appendChildItem
 442      */
 443     void appendChildItem(KTreeViewItem* newItem, int index);
 444
 445     /**
 446      * This overloaded function appends a new item to an item, which is
 447      * specified by a path.
 448      *
 449      * @param newItem specifies the new item
 450      * @param path specifies the item of which the new item will be a child
 451      * @see #appendChildItem
 452      */
 453     void appendChildItem(KTreeViewItem* newItem, const KPath& path);
 454
 455     /**
 456      * Computes coordinates relative to the specified row from the given
 457      * coordinates. If the row is invalid, the input coordinates are
 458      * returned unchanged.
 459      *
 460      * @param widget specifies widget coordinates (e.g. from a mouse event)
 461      * @return coordinates relative to the specified cell
 462      */
 463     virtual QPoint cellCoords(int row, const QPoint& widgetCoord);
 464
 465   /**
 466         Changes the text and/or pixmap of the given item at the specified
 467         index to the given values and updates the display if auto update
 468         enabled. If changing only the text or pixmap, set the other parameter
 469         to 0.
 470         */
 471   void changeItem(const char *newText,
 472                                   const QPixmap *newPixmap,
 473                                   int index);
 474
 475   /**
 476         Same as above function, except item to change is specified by a path
 477         through the tree.
 478         */
 479   void changeItem(const char *newText,
 480                                   const QPixmap *newPixmap,
 481                                   const KPath& thePath);
 482
 483   /**
 484         Removes all items from the tree.
 485
 486         */
 487   void clear();
 488
 489   /**
 490         Returns the total number of items in the tree, whether visible
 491         (expanded sub-trees) or not (collapsed).
 492         */
 493   uint count();
 494
 495   /**
 496         Returns the index of the current (highlighted) item. If no current
 497         item, returns -1.
 498         */
 499   int currentItem() const;
 500
 501     /**
 502      * Collapses the sub-tree at the specified row index. If the index is
 503      * out of range, or the item is already collpased, nothing happens.
 504      *
 505      * @param index specifies the row index
 506      * @param emitSignal specifies whether the signal @ref #collapsed
 507      * should be emitted
 508      */
 509     void collapseItem(int index, bool emitSignal);
 510
 511     /**
 512      * Expands the sub-tree at the specified row index. If the index is
 513      * out of range, or the item is already expanded, nothing happens.
 514      *
 515      * @param index specifies the row index
 516      * @param emitSignal specifies whether the signal @ref #collapsed
 517      * should be emitted
 518      */
 519     void expandItem(int index, bool emitSignal);
 520
 521   /**
 522         Returns the depth to which all parent items are automatically
 523         expanded.
 524         */
 525   int expandLevel() const;
 526
 527     /**
 528      * The type of member functions that is called by @ref #forEveryItem and
 529      * @ref #forEveryVisibleItem.
 530      */
 531     typedef bool (*KForEveryFunc)(KTreeViewItem*, void*);
 532
 533     /**
 534      * Iterates every item in the tree, visible or not, and applies the
 535      * function func with a pointer to each item and user data supplied as
 536      * parameters. The children of the specified root item are visited
 537      * (root itself is not visited!). If root is 0 all items in the tree
 538      * are visited. KForEveryFunc is defined as:
 539      *
 540      * typedef bool (KTreeView::*KForEveryFunc)(KTreeViewItem*, void*);
 541      *
 542      * That is, a member function that returns bool and takes a pointer to
 543      * a KTreeViewItem and pointer to void as parameters. The traversal
 544      * ends earlier if the supplied function returns bool. In this case the
 545      * return value is also true.
 546      *
 547      * @param func the member function to call for every visited item
 548      * @param user extra data that is passed to func
 549      * @param root the root item of the subtree to scan; this item itself
 550      * is not scanned
 551      * @see #forEveryVisibleItem
 552      */
 553     bool forEveryItem(KForEveryFunc func, void* user,
 554                       KTreeViewItem* root = 0);
 555
 556     /**
 557      * This function is like @ref #forEveryItem, but only iterates visible
 558      * items, in order. If the specified root item is invisible no items
 559      * are visited.
 560      *
 561      * @param func the member function to call for every visited item
 562      * @param user extra data that is passed to func
 563      * @param root the root item of the subtree to scan; this item itself
 564      * is not scanned
 565      * @see #forEveryItem
 566      */
 567     bool forEveryVisibleItem(KForEveryFunc func, void *user,
 568                              KTreeViewItem* root = 0);
 569
 570   /**
 571         Returns a pointer to the current item if there is one, or 0.
 572         */
 573   KTreeViewItem *getCurrentItem() const;
 574
 575     /**
 576      * Returns the number of pixels an item is indented for each level. If,
 577      * in a derived class, the levels are indented differently this value
 578      * may be ignored.
 579      *
 580      * @return the number of pixels of indentation for a level
 581      */
 582     int indentSpacing();
 583
 584     /**
 585      * Inserts an item into the tree with the given text and pixmap either
 586      * before or after the item at the given row. The new item is added to
 587      * the same branch as the referenced item (that is, the new item will
 588      * be sibling of the reference item). If row is -1, the item is simply
 589      * appended to the tree at the topmost level. A KTreeViewItem is
 590      * created for which the delete-children flag is set to true.
 591      *
 592      * @param text specifies text for the new item; must not be 0
 593      * @param pixmap specifies a pixmap for the new item
 594      * @param index specifies the insert position
 595      * @param prefix if true, the new item is inserted before the reference
 596      * item, otherwise after it
 597      * @return true if the item has been successfully inserted in the tree,
 598      * otherwise false.
 599      */
 600     bool insertItem(const char* text, const QPixmap& pixmap,
 601                     int row = -1, bool prefix = true);
 602
 603     /**
 604      * This overloaded function inserts a new item into the tree, but a
 605      * path through the tree specifies the reference insert position. If
 606      * there is no item at the specified path, the item is simply appended
 607      * to the tree at the topmost level.
 608      *
 609      * @param text specifies text for the new item; must not be 0
 610      * @param pixmap specifies a pixmap for the new item
 611      * @param path specifies the insert position
 612      * @param prefix if true, the new item is inserted before the reference
 613      * item, otherwise after it
 614      * @return true if the item has been successfully inserted in the tree,
 615      * otherwise false.
 616      * @see #insertItem
 617      */
 618     bool insertItem(const char* text, const QPixmap& pixmap,
 619                     const KPath& path, bool prefix = true);
 620
 621     /**
 622      * This overloaded function inserts a new item into the tree, but the
 623      * new item is specified directly. The reference item is specified as a
 624      * row index.
 625      *
 626      * @param newItem specifies the item to insert
 627      * @param path specifies the insert position
 628      * @param prefix if true, the new item is inserted before the reference
 629      * item, otherwise after it
 630      * @return true if the item has been successfully inserted in the tree,
 631      * otherwise false.
 632      * @see #insertItem
 633      */
 634     bool insertItem(KTreeViewItem *newItem,
 635                     int row = -1, bool prefix = true);
 636
 637     /**
 638      * This overloaded function inserts a new item into the tree, but the
 639      * new item is specified directly. The reference item is specified by a
 640      * path.
 641      *
 642      * @param newItem specifies the item to insert
 643      * @param path specifies the insert position
 644      * @param prefix if true, the new item is inserted before the reference
 645      * item, otherwise after it
 646      * @return true if the item has been successfully inserted in the tree,
 647      * otherwise false.
 648      * @see #insertItem
 649      */
 650     bool insertItem(KTreeViewItem *newItem,
 651                     const KPath& thePath, bool prefix = true);
 652
 653     /**
 654      * Returns a pointer to the item in the specified row, or 0 if the
 655      * specified row is outside the limits. This is a cheap operation.
 656      *
 657      * @param row specifies the row index
 658      * @return the item at the specified row
 659      * @see #itemRow
 660      * @see #itemPath
 661      */
 662     KTreeViewItem* itemAt(int row) const;
 663
 664     /**
 665      * Returns a pointer to the item at the end of the path, or 0 if there
 666      * is no such item.
 667      *
 668      * @param path specifies a path through the tree
 669      * @return the item at the end of the specified path
 670      * @see #itemRow
 671      * @see #itemPath
 672      */
 673     KTreeViewItem* itemAt(const KPath& path);
 674
 675     /**
 676      * Looks up the row index at which the specified item is found in the
 677      * visible tree or -1 if the item is not visible or not in the tree.
 678      *
 679      * @param specifies the item to search
 680      * @return the row index of the item
 681      * @see #itemAt
 682      * @see #itemPath
 683      */
 684     int itemRow(KTreeViewItem* item);
 685
 686     /**
 687      * Fills path with the logical path to the item at the specified row.
 688      * The specified path variable should be empty. Any strings popped from
 689      * the path must be deleted by the caller. If the row is invalid, path
 690      * remains unchanged (i.e. empty).
 691      *
 692      * @param row specifies the row index
 693      * @param path receives the path of the specified item
 694      * @see #itemAt
 695      * @see #itemRow
 696      */
 697     void itemPath(int row, KPath& path);
 698
 699     /**
 700      * Outdents the item at the given row one level so that it becomes a
 701      * sibling of its parent.
 702      */
 703     void join(int index);
 704
 705     /**
 706      * Same as above but uses a path to specify the item.
 707      */
 708     void join(const KPath& path);
 709
 710     /**
 711      * Moves the item at the specified row down one row in its current
 712      * branch.
 713      */
 714     void lowerItem(int index);
 715
 716     /**
 717      * Same as above but uses a path to specify the item.
 718      */
 719     void lowerItem(const KPath& path);
 720
 721     /**
 722      * Moves the item at the specified row up one row in its current
 723      * branch.
 724      */
 725     void raiseItem(int row);
 726
 727     /**
 728      * Same as above but uses a path to specify the item.
 729      */
 730     void raiseItem(const KPath& path);
 731
 732     /**
 733      * Removes the item at the specified row.
 734      */
 735     void removeItem(int row);
 736
 737     /**
 738      * Same as above except uses path through the tree to find the item.
 739      */
 740     void removeItem(const KPath& thePath);
 741
 742     /**
 743      * The specified item is scrolled into view.  If the specified item is
 744      * already visible, nothing happens, unless children is true, in which
 745      * case the display is scrolled such that the item and as many of its
 746      * child items as possible are visible.
 747      *
 748      * @param item specifies the item to make visible
 749      * @param children specifies whether children should be made visible
 750      */
 751     void scrollVisible(KTreeViewItem* item, bool children);
 752
 753     /**
 754      * Makes the item at specifies row the current item and highlights it.
 755      * The signal @ref #highlighted is emitted if the current item changes.
 756      *
 757      * @param row specifies the row to make the current item
 758      */
 759     void setCurrentItem(int row);
 760
 761   void setExpandButtonDrawing(bool enable);
 762
 763   void setExpandLevel(int level);
 764
 765     /**
 766      * Sets the indentation stepping, in pixels.  If, in a derived class,
 767      * the levels are indented differently this value may be ignored.
 768      *
 769      * @param spacing specifies the new indentation spacing, in pixels
 770      */
 771     void setIndentSpacing(int spacing);
 772
 773     /**
 774      * If true, removing a top-level item that contains the current item
 775      * will move the current item to the following sibling (or to the
 776      * previous if there is none). Otherwise, there will not be a current
 777      * item.
 778      */
 779     void setMoveCurrentToSibling(bool m = true);
 780
 781   /**
 782         If enable is TRUE (default), item text will be displayed, otherwise
 783         it will not, and no highlight will be shown in the default widget.
 784         */
 785   void setShowItemText(bool enable);
 786
 787   /**
 788         If enable is TRUE (default), lines depicting the structure of the
 789         tree will be drawn, otherwise they will not.
 790         */
 791   void setTreeDrawing(bool enable);
 792
 793   /**
 794         Indicates whether item text is displayed.
 795         */
 796   bool showItemText() const;
 797
 798     /**
 799      * Indents the item at the specified index, creating a new branch.
 800      */
 801     void split(int index);
 802
 803     /**
 804      * Same as above but uses a path to specify the item.
 805      */
 806     void split(const KPath& path);
 807
 808     /**
 809      * Removes the item at the given index from the tree, but does not
 810      * delete it, returning a pointer to the removed item.
 811      */
 812     KTreeViewItem* takeItem(int index);
 813
 814     /**
 815      * Same as above but uses a path to specify the item to take.
 816      */
 817     KTreeViewItem* takeItem(const KPath& path);
 818
 819   /**
 820         Indicates whether the tree structure is drawn.
 821         */
 822   bool treeDrawing() const;
 823
 824 public:
 825     /**
 826      * Use numRows() instead.
 827      *
 828      * @return the number of items that are visible (their parents are
 829      * expanded).
 830      * @deprecated
 831      */
 832     int visibleCount() const { return numRows(); }
 833
 834 signals:
 835     /**
 836      * This signal is emitted when an item in the tree is collapsed.
 837      * The signal is not emitted for items that are invisible.
 838      *
 839      * @param index the row index of the collapsed item
 840      */
 841     void collapsed(int index);
 842
 843     /**
 844      * This signal is emitted when an item in the tree is expanded.
 845      * The signal is not emitted for items that are invisible.
 846      *
 847      * @param index the row index of the expanded item
 848      */
 849     void expanded(int index);
 850
 851     /**
 852      * This signal is emitted when an item that has the delayedExpanding
 853      * flag set is about to be expanded. The delayedExpanding flag is not
 854      * reset; the slot that the signal is connected to should do so if
 855      * necessary. The item being expanded is passed to the slot. The slot
 856      * gets the opportunity to insert child items into that item. It should
 857      * not change the item any other way. It can disallow the expansion by
 858      * setting allow to false; in this case the item is not expanded.
 859      *
 860      * The signal is always emitted, regardless whether the expansion was
 861      * triggered by the user or by the program.
 862      *
 863      * @param item specifies the item that is about to be expanded
 864      * @param allow can be set to false to disallow expansion; no further
 865      * actions are taken then
 866      */
 867     void expanding(KTreeViewItem* item, bool& allow);
 868
 869     /**
 870      * This signal is emitted when an item in the tree is highlighted.
 871      *
 872      * @param index the row index of the highlighted item.
 873      */
 874     void highlighted(int index);
 875
 876     /**
 877      * This signal is emitted when the user right-clicks.
 878      *
 879      * @param index the row index of where the click occurred; it is -1 if
 880      * the click was not on an item.
 881      * @param pt the location (in widget coordinates) where the mouse click
 882      * happened.
 883      */
 884     void rightPressed(int index, const QPoint& pt);
 885
 886     /**
 887      * This signal is emitted when an item in the tree is selected.
 888      *
 889      * @param index the row index of the selected item.
 890      */
 891     void selected(int index);
 892
 893 protected:
 894     /**
 895      * Appends a new child item to a parent item as a new direct child. All
 896      * internal state is updated and the widget is repainted as necessary.
 897      * The new child remains invisible if any ancestor of it (including the
 898      * parent) is collapsed.
 899      *
 900      * @param parent specifies the parent of which the new item will become
 901      * a child
 902      * @param child specifies the new child item
 903      * @see #appendChildItem
 904      */
 905     void appendChildItem(KTreeViewItem* parent,
 906                          KTreeViewItem* child);
 907     virtual int cellHeight(int row) const;
 908     virtual int cellWidth(int col) const;
 909     void changeItem(KTreeViewItem* toChange,
 910                     int itemRow, const char* newText,
 911                     const QPixmap* newPixmap);
 912     /**
 913      * Collapses the specified subtree and updates the display. The
 914      * specified item need not be visible. This function does nothing if
 915      * the item is already collapsed.
 916      *
 917      * @param item specifies the item to collapse.
 918      * @param emitSignal specifies whether the signal @ref #collapsed should be emitted.
 919      */
 920     virtual void collapseSubTree(KTreeViewItem* item, bool emitSignal);
 921
 922     /** Internal function used for counting items */
 923     static bool countItem(KTreeViewItem* item, void* total);
 924
 925     /**
 926      * Expands the specified subtree and updates the display. The specified
 927      * item need not be visible. This function does nothing if the item is
 928      * already expanded.
 929      *
 930      * @param item specifies the item to expand.
 931      * @param emitSignal specifies whether the signal @ref #expanded should be emitted.
 932      */
 933     virtual void expandSubTree(KTreeViewItem* item, bool emitSignal);
 934   void fixChildren(KTreeViewItem *parentItem);
 935     virtual void focusInEvent(QFocusEvent* e);
 936     virtual void focusOutEvent(QFocusEvent* e);
 937
 938     /** internal function used to determine maximum item width */
 939     static bool getMaxItemWidth(KTreeViewItem* item, void *user);
 940
 941     /**
 942      * @param specifies a tree item of this tree
 943      * @return the total indentation of the specified item, in pixels
 944      */
 945     virtual int indentation(KTreeViewItem* item) const;
 946
 947     /**
 948      * Inserts a new item before or after a reference item. (That is, the
 949      * new item will become a sibling of the reference item.) If the
 950      * reference item is 0, the new item is appended at the topmost level.
 951      * If the reference item is not 0, it must be an item that is already
 952      * in this KTreeView. Internal data is updated and the display is
 953      * refreshed as necessary. The inserted item may still be invisible if
 954      * any of the parents is collapsed.
 955      *
 956      * @param referenceItem specifies the reference item
 957      * @param newItem specifies the new item; must not be 0.
 958      * @return true if the item has been successfully inserted in the tree,
 959      * otherwise false.
 960      * @see #insertItem
 961      */
 962     bool insertItem(KTreeViewItem* referenceItem, KTreeViewItem* newItem,
 963                     bool prefix);
 964
 965     /**
 966      * Finds the logical path of the specified item. The specified path
 967      * variable should be empty.
 968      *
 969      * @param item specifies the item whose path is to determine
 970      * @param path receives the path of the item
 971      * @see #itemPath
 972      * @see #itemRow
 973      * @see #itemAt
 974      */
 975     void itemPath(KTreeViewItem* item, KPath& path) const;
 976
 977   void join(KTreeViewItem *item);
 978
 979     /**
 980      * Reimplemented for key handling. If there are any items in the
 981      * KTreeView, but there is no current item, the topmost item is made
 982      * current. The key press event is first forwarded to the current item
 983      * by calling @ref #KTreeViewItem::keyEvent.
 984      */
 985     virtual void keyPressEvent(QKeyEvent* e);
 986
 987     /**
 988      * The key release event is first forwarded to the current item (if
 989      * there is one) by calling @ref #KTreeViewItem::keyEvent.
 990      */
 991     virtual void keyReleaseEvent(QKeyEvent* e);
 992
 993     int level(KTreeViewItem* item) const;
 994   void lowerItem(KTreeViewItem *item);
 995
 996     /**
 997      * Reimplemented for mouse event handling. The mouse double click event
 998      * is first forwarded to the item that has been clicked on (if there is
 999      * one) by calling @ref #KTreeViewItem::mouseEvent.
1000      */
1001     virtual void mouseDoubleClickEvent(QMouseEvent* e);
1002
1003     /**
1004      * Reimplemented for mouse event handling. The mouse move event is
1005      * first forwarded to the current item (if there is one) by calling
1006      * @ref #KTreeViewItem::mouseEvent.
1007      */
1008     virtual void mouseMoveEvent(QMouseEvent* e);
1009
1010     /**
1011      * Reimplemented for mouse event handling. The mouse press event is
1012      * first forwarded to the item that has been clicked on (if there is
1013      * one) by calling @ref #KTreeViewItem::mouseEvent. The clicked on item
1014      * is made the current item.
1015      */
1016     virtual void mousePressEvent(QMouseEvent* e);
1017
1018     /**
1019      * Reimplemented for mouse event handling. The mouse release event is
1020      * first forwarded to the current item (if there is one) by calling
1021      * @ref #KTreeViewItem::mouseEvent.
1022      */
1023     virtual void mouseReleaseEvent(QMouseEvent* e);
1024
1025   virtual void paintCell(QPainter *p, int row, int col);
1026     /*
1027      * virtual void paintItem(QPainter *p, KTreeViewItem *item,
1028                               * bool highlighted);
1029      */
1030     /**
1031      * Internal. Needed to make kcontrol's color setup work.
1032      */
1033     void paletteChange(const QPalette&);
1034     void raiseItem(KTreeViewItem* item);
1035
1036     /**
1037      * Internal function that finds the item at the given path. Returns 0
1038      * if the item cannot be found. The path is destroyed by this function.
1039      */
1040     KTreeViewItem* recursiveFind(KPath& path);
1041
1042     void setItemExpanded(KTreeViewItem* item);
1043     static bool setItemExpandLevel(KTreeViewItem* item, void*);
1044     static bool setItemExpandButtonDrawing(KTreeViewItem* item, void*);
1045     static bool setItemShowText(KTreeViewItem* item, void*);
1046     static bool setItemTreeDrawing(KTreeViewItem* item, void*);
1047   void split(KTreeViewItem *item);
1048   void takeItem(KTreeViewItem *item);
1049     virtual void updateCellWidth();
1050     virtual void updateVisibleItems();
1051     void updateVisibleItemRec(KTreeViewItem* parent, int& count, int& width);
1052
1053     KTreeViewItem* treeRoot;
1054     bool clearing;
1055     int current;
1056     bool drawExpandButton;
1057     bool drawTree;
1058     int expansion;
1059     bool goingDown;
1060     int itemIndent;
1061     int maxItemWidth;
1062     bool showText;
1063     bool moveCurrentToSibling;
1064     // list of visible items
1065     int itemCapacity;                   /* for how many items we've space allocated */
1066     KTreeViewItem** visibleItems;
1067
1068   // Rainer Bawidamann: move window in "rubberband" mode
1069   bool rubberband_mode;             // true if in "rubberband_mode"
1070   QPoint rubber_startMouse;         // where the user pressed the MMB
1071   int rubber_height, rubber_width,  // the size if the rubberband rect
1072         rubber_startX, rubber_startY; // the x/yOffset() when the MMB was pressed
1073   void draw_rubberband();
1074   void start_rubberband(const QPoint& where);
1075   void end_rubberband();
1076   void move_rubberband(const QPoint& where);
1077 };
1078
1079 #endif // KDE_KTREE_VIEW_H