File: ktreeview.h

package info (click to toggle)
kdbg 1.2.4-2
  • links: PTS
  • area: main
  • in suites: woody
  • size: 2,504 kB
  • ctags: 1,945
  • sloc: cpp: 15,961; sh: 8,183; makefile: 481; perl: 71; ansic: 16
file content (1092 lines) | stat: -rw-r--r-- 37,354 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
/*
 * $Id: ktreeview.h,v 1.10.2.2 2001/12/29 20:12:16 jsixt Exp $
 * 
 * KTreeView class interface
 * 
 * Copyright (C) 1997 Johannes Sixt
 * 
 * based on KTreeList, which is
 * Copyright (C) 1996 Keith Brown and KtSoft
 * 
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABLILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details. You should have received a copy
 * of the GNU General Public License along with this program; if not, write
 * to the Free Software Foundation, Inc, 675 Mass Ave, Cambridge, MA 02139,
 * USA.
 */

#ifndef KDE_KTREE_VIEW_H
#define KDE_KTREE_VIEW_H

#include <qpixmap.h>			/* used in items */
#include <qstack.h>			/* used to specify tree paths */
#include <qstring.h>			/* used in items */
#include "tableview.h"			/* base class for widget */

// use stack of strings to represent path information
typedef QStack<QString> KPath;

class KTreeView;			/* forward declaration */

/** Items for the KTreeView widget */
class KTreeViewItem
#if QT_VERSION >= 200
: public Qt
#endif
{
    friend class KTreeView;
public:
    /**
     * Item constructor. While text defaults to a null string, and the
     * item can be constructed this way, the text has to be non-null when
     * the item is added to the tree, or it will not be inserted.
     *
     * The constructor sets the delete-children flag to false. This flag
     * tells the item whether it shall delete the child items when it is
     * itself deleted. By default the creator of the item is responsible to
     * also delete the child items. (However, the versions of @ref
     * #appendChildItem and @ref #insertChildItem that do not take a
     * KTreeViewItem set the delete-children flag to true.)
     *
     * @param text specifies the new item's text
     */
    KTreeViewItem(const QString& text = QString()); // text can not be null when added to the list!
    /**
     * This overloaded constructor allows to specify a pixmap for the new
     * item.
     *
     * @param text specifies the item's text
     * @param pixmap specifies the item's pixmap
     */
    KTreeViewItem(const QString& text, const QPixmap& pixmap);

    /**
     * Destructor. It destroys its children if this item has been marked
     * with setDeleteChildren(true).
     */
    virtual ~KTreeViewItem();

    /**
     * Appends a new (direct) child item at the end. It does not update
     * administrative data in newChild except for its parent (which is this
     * item) and owner.
     */
    virtual void appendChild(KTreeViewItem* newChild);

    /**
     * Returns a pointer to the child item at the given index in this
     * item's sub tree, or 0 if not found.
     *
     * @param index specifies the index of the direct child to return
     * @return the direct child at the specified index
     */	
    KTreeViewItem* childAt(int index) const;

    /**
     * Returns the number of child items in this item's sub tree.
     */
    uint childCount() const;

    /**
     * Returns the index in this items sub tree of the given item or -1 if
     * the specified item is not a direct child of this item.
     * 
     * @param child specifies the child to look up; must not be 0
     * @returns the index of the specified direct child
     */
    int childIndex(KTreeViewItem* child) const;

    /**
     * Determines whether the specified point is inside the expand button.
     */
    bool expandButtonClicked(const QPoint& coord) const;

    /**
     * Returns a pointer to the first child item in this item's sub tree, or
     * 0 if none.
     */
    KTreeViewItem* getChild() const;

    /**
     * Returns a pointer to the parent of this item, or 0 if none.
     */
    KTreeViewItem* getParent() const;

    /**
     * Returns a reference to this item's pixmap. If there is no pixmap
     * associated with this item, it will return a reference to a valid,
     * null QPixmap.
     */
    const QPixmap& getPixmap() const;

    /**
     * Returns a pointer to the next sibling item in the same branch below this
     * one, or 0 if this item has no siblings below it.
     */
    KTreeViewItem* getSibling() const;

    /**
     * Returns this item's text.
     */
    const QString& getText() const;

    /**
     * Indicates whether this item has any children.
     */
    bool hasChild() const;

    /**
     * Indicates whether this item has a parent.
     */
    bool hasParent() const;

    /**
     * Indicates whether this item has a sibling item, that is, an item
     * that would be displayed below it at the same level as this item.
     */
    bool hasSibling() const;

    /**
     * Inserts the a new (direct) child in this item before the child at
     * the specified index (first child is index 0). If there is no child
     * at the specified index, the item is appended. It does not update
     * administrative data in newChild except for its parent (which is this
     * item) and owner.
     * 
     * @param index specifies the index of a direct child of this item
     * @param newChild specifies the new item to insert
     */
    virtual void insertChild(int index, KTreeViewItem* newChild);

    /**
     * Indicates whether the item is expanded, that is, whether the child
     * items (if any) would be visible if this item were visible.
     * 
     * Note: If this function returns true, it does not necessarily indicate
     * that this item is visible or that this item has any children.
     */
    bool isExpanded() const;

    /**
     * Returns true if the item is visible. An item is visible if @ref
     * #isExpanded() returns true for all its ancestors.
     * 
     * Note: If this function returns true, it does not necessarily indicate
     * that the widget is visible.
     */
    bool isVisible() const;

    /**
     * Removes the specified (direct) child from this item and returns
     * true. If it is not a direct child of this item, nothing happens, and
     * false is returned. This function does not update the owning
     * KTreeView.
     */
    virtual bool removeChild(KTreeViewItem* child);

    /**
     * Sets the delayed-expanding flag. If this flag is true, the signal
     * @ref #expanding is emitted when the item is about to be expanded.
     * The expand button is always painted for this item, even if it
     * doesn't have children.
     */
    void setDelayedExpanding(bool flag);

    /**
     * Tells the item whether it should delete its children when it is
     * deleted. The default is false, which means that the child items must
     * be deleted explicitly.
     */
    void setDeleteChildren(bool flag);

    /**
     * Tells the item whether it should draw the expand button. The default
     * is true. This function does not update the owning tree widget.
     */
    virtual void setDrawExpandButton(bool doit);

    /**
     * Tells the item whether it should paint the text. The default is
     * true. This function does not update the owning tree widget.
     */
    virtual void setDrawText(bool doit);

    /**
     * Tells the item whether it should draw the tree lines. The default is
     * true. This function does not update the owning tree widget.
     */
    virtual void setDrawTree(bool doit);

    /**
     * Tells whether the item is expanded (i.e. whether its children are
     * visible). The default is false. This function does not update the
     * owning tree widget.
     */
    virtual void setExpanded(bool is);

    /**
     * Sets the item pixmap to the given pixmap. It does not redraw the
     * item or update the owning KTreeView.
     */
    virtual void setPixmap(const QPixmap& pm);

    /**
     * Sets the item text. This function does not redraw the item or update
     * the owning KTreeView.
     */
    virtual void setText(const QString& t);

protected:
    /**
     * Returns the bounding rectangle of the item.
     */
    virtual QRect boundingRect(int indent) const;

    /**
     * Returns the height of the item. The default implementation uses font
     * metrics of the owning KTreeView widget.
     */
    virtual int height() const;

    /*
     * Returns the height of the item depending on the passed-in font
     * metrics.
     */
    virtual int height(const QFontMetrics& fm) const;

    /*
     * The item is given a chance to process key events before the owning
     * KTreeView processes the event.
     * 
     * @param ev specifies the key event; use ev->type() to find out whether
     * this is a key down or up event (see @ref #QEvent).
     * @return true if the event has been processed, false if it has not
     * been processed. The default implementation just returns false to
     * indicate that the event has not been processed.
     */
    virtual bool keyEvent(QKeyEvent* ev);

    /*
     * The item is given a chance to process mouse events before the owning
     * KTreeView processes the event.
     *
     * @param ev specifies the mouse event; use ev->type() to find out whether
     * this is a mouse press, release, double click, or move event (see
     * @ref #QEvent).
     * @param itemCoord specifies the mouse even coordinates relative to this
     * item (the coordinates in ev are the original coordinates).
     * @return true if the event has been processed, false if it has not
     * been processed. The default implementation just returns false to
     * indicate that the event has not been processed.
     */
    virtual bool mouseEvent(QMouseEvent* ev, const QPoint& itemCoord);

    /**
     * Paints the item: pixmap, text, expand button, parent branches
     */
    virtual void paint(QPainter* p, int indent,
			const QColorGroup& cg, bool highlighted) const;

    /**
     * paints the expand button
     */
    virtual void paintExpandButton(QPainter* p, int indent, int cellHeight,
				   const QColorGroup& cg) const;

    /**
     * paints the highlighted text
     */
    virtual void paintHighlight(QPainter* p, int indent,
			const QColorGroup& cg, bool hasFocus) const;

    /**
     * paints the item's text
     */
    virtual void paintText(QPainter* p, int indent, int cellHeight,
			   const QColorGroup& cg, bool highlighted) const;

    /**
     * paints the item's tree part.
     */
    virtual void paintTree(QPainter* p, int indent, int cellHeight,
			   const QColorGroup& cg) const;

    /**
     * Internal function that updates the owner of this item and its
     * children and siblings (the latter only if requested).
     */
    void setOwner(KTreeView* newOwner, bool includeSiblings = false);

    /**
     * Internal function that counts the number of child items.
     */
    void synchNumChildren();
    
    /**
     * Returns the bounding rectangle of the text.
     */
    virtual QRect textBoundingRect(int indent) const;

    /**
     * Returns the width of the item taking into account the specified
     * indentation. The default implementation uses font metrics of the
     * owning KTreeView widget.
     */
    virtual int width(int indent) const;

    /**
     * Returns the width of the item depending on the passed-in font
     * metrics and taking into account the specified indentation.
     */
    virtual int width(int indent, const QFontMetrics& fm) const;

protected:
    /** The KTreeView that this item belongs to */
    KTreeView* owner;
    int numChildren;
    bool doExpandButton;
    bool expanded;
    bool delayedExpanding;
    bool doTree;
    bool doText;
    mutable QRect expandButton;		/* is set in paint() */
    KTreeViewItem* child;
    KTreeViewItem* parent;
    KTreeViewItem* sibling;
    QPixmap pixmap;
    QString text;
    bool deleteChildren;
};

/**
 * KTreeView is a class that provides a way to display hierarchical data in
 * a single-inheritance tree, similar to tree controls in Microsoft Windows
 * and other GUIs. It is most suitable for directory trees or outlines, but
 * I'm sure other uses will come to mind. It was designed mostly with the
 * above two functions in mind, but I have tried to make it as flexible as
 * I can to make it easy to adapt to other uses.
 *
 * Please read the source code if you have time. I have tried to comment it
 * adequately and make the source understandable.
 *
 * The class features the following:
 *
 * - Displays both text and an optional pixmap supplied by the programmer.
 * A support class, KTreeViewItem, can be inherited and modified to draw
 * items as needed by the programmer.
 *
 * - The list items can be returned by index or logical path and the tree
 * navigated by parent, child or sibling references contained in them.
 * Also, item information such as text, pixmap, branch level can be
 * obtained.
 *
 * - Items can be inserted, changed and removed either by index in the
 * visible structure, or by logical paths through the tree hierarchy.
 *
 * - The logical path through the tree for any item can be obtained with
 * the index of the item.
 *
 * - Tree structure display and expanding/collapsing of sub-trees is
 * handled with no intervention from the programmer.
 *
 * - entire tree can be expanded or collapsed to a specified sub-level
 *  (handy for outline views)
 *
 * @short A collapsible treelist widget
 * @author Johannes Sixt <Johannes.Sixt@telecom.at>, Keith Brown
 */
class KTreeView : public TableView
{
    friend class KTreeViewItem;
    Q_OBJECT
public:
    /**
     * Widget contructor. All parameters are passed on to base TableView,
     * and are not used directly.
     */
    KTreeView(QWidget* parent = 0, const char* name = 0, WFlags f = 0);

    /**
     * Desctructor. Deletes all items from the topmost level that have been
     * marked with setDeleteChildren(true).
     */
    virtual ~KTreeView();

    /**
     * Appends a new child item to the item at the specified row. If that
     * item already has children, the new item is appended below these
     * children. A KTreeViewItem is created for which the delete-children
     * flag is set to true.
     * 
     * @param text specifies text for the new item; must not be 0
     * @param pixmap specifies a pixmap for the new item
     * @param index specifies the item of which the new item will be a child
     */
    void appendChildItem(const char* text, const QPixmap& pixmap,
		      int index);

    /**
     * This overloaded function appends a new item to an item, which is
     * specified by a path.
     * 
     * @param text specifies text for the new item; must not be 0
     * @param pixmap specifies a pixmap for the new item
     * @param path specifies the item of which the new item will be a child
     * @see #appendChildItem
     */
    void appendChildItem(const char* text, const QPixmap& pixmap,
		      const KPath& path); 

    /**
     * Appends the specified item as a child of the item that is at the
     * specified row. If that item already has children, the new item is
     * appended below these children.
     * 
     * @param newItem specifies the new item
     * @param index specifies the item of which the new item will be a child
     * @see #appendChildItem
     */
    void appendChildItem(KTreeViewItem* newItem, int index);

    /**
     * This overloaded function appends a new item to an item, which is
     * specified by a path.
     * 
     * @param newItem specifies the new item
     * @param path specifies the item of which the new item will be a child
     * @see #appendChildItem
     */
    void appendChildItem(KTreeViewItem* newItem, const KPath& path);

    /**
     * Computes coordinates relative to the specified row from the given
     * coordinates. If the row is invalid, the input coordinates are
     * returned unchanged.
     * 
     * @param widget specifies widget coordinates (e.g. from a mouse event)
     * @return coordinates relative to the specified cell
     */
    virtual QPoint cellCoords(int row, const QPoint& widgetCoord);

  /**
	Changes the text and/or pixmap of the given item at the specified
	index to the given values and updates the display if auto update
	enabled. If changing only the text or pixmap, set the other parameter
	to 0.
	*/
  void changeItem(const char *newText, 
				  const QPixmap *newPixmap, 
				  int index);

  /**
	Same as above function, except item to change is specified by a path
	through the tree.
	*/
  void changeItem(const char *newText,
				  const QPixmap *newPixmap,
				  const KPath& thePath);

  /**
	Removes all items from the tree.

	*/
  void clear();

  /**
	Returns the total number of items in the tree, whether visible
	(expanded sub-trees) or not (collapsed).
	*/
  uint count();

  /**
	Returns the index of the current (highlighted) item. If no current
	item, returns -1.
	*/
  int currentItem() const;

    /**
     * Collapses the sub-tree at the specified row index. If the index is
     * out of range, or the item is already collpased, nothing happens.
     * 
     * @param index specifies the row index
     * @param emitSignal specifies whether the signal @ref #collapsed
     * should be emitted
     */
    void collapseItem(int index, bool emitSignal);

    /**
     * Expands the sub-tree at the specified row index. If the index is
     * out of range, or the item is already expanded, nothing happens.
     * 
     * @param index specifies the row index
     * @param emitSignal specifies whether the signal @ref #collapsed
     * should be emitted
     */
    void expandItem(int index, bool emitSignal);

  /**
	Returns the depth to which all parent items are automatically
	expanded.
	*/
  int expandLevel() const;

    /**
     * The type of member functions that is called by @ref #forEveryItem and
     * @ref #forEveryVisibleItem.
     */
    typedef bool (*KForEveryFunc)(KTreeViewItem*, void*);

    /**
     * Iterates every item in the tree, visible or not, and applies the
     * function func with a pointer to each item and user data supplied as
     * parameters. The children of the specified root item are visited
     * (root itself is not visited!). If root is 0 all items in the tree
     * are visited. KForEveryFunc is defined as:
     * 
     * typedef bool (KTreeView::*KForEveryFunc)(KTreeViewItem*, void*);
     * 
     * That is, a member function that returns bool and takes a pointer to
     * a KTreeViewItem and pointer to void as parameters. The traversal
     * ends earlier if the supplied function returns bool. In this case the
     * return value is also true.
     *
     * @param func the member function to call for every visited item
     * @param user extra data that is passed to func
     * @param root the root item of the subtree to scan; this item itself
     * is not scanned
     * @see #forEveryVisibleItem
     */
    bool forEveryItem(KForEveryFunc func, void* user,
		      KTreeViewItem* root = 0);

    /**
     * This function is like @ref #forEveryItem, but only iterates visible
     * items, in order. If the specified root item is invisible no items
     * are visited.
     *
     * @param func the member function to call for every visited item
     * @param user extra data that is passed to func
     * @param root the root item of the subtree to scan; this item itself
     * is not scanned
     * @see #forEveryItem
     */
    bool forEveryVisibleItem(KForEveryFunc func, void *user,
			     KTreeViewItem* root = 0);

  /**
	Returns a pointer to the current item if there is one, or 0.
	*/
  KTreeViewItem *getCurrentItem();

    /**
     * Returns the number of pixels an item is indented for each level. If,
     * in a derived class, the levels are indented differently this value
     * may be ignored.
     * 
     * @return the number of pixels of indentation for a level
     */
    int indentSpacing();

    /**
     * Inserts an item into the tree with the given text and pixmap either
     * before or after the item at the given row. The new item is added to
     * the same branch as the referenced item (that is, the new item will
     * be sibling of the reference item). If row is -1, the item is simply
     * appended to the tree at the topmost level. A KTreeViewItem is
     * created for which the delete-children flag is set to true.
     * 
     * @param text specifies text for the new item; must not be 0
     * @param pixmap specifies a pixmap for the new item
     * @param index specifies the insert position
     * @param prefix if true, the new item is inserted before the reference
     * item, otherwise after it
     * @return true if the item has been successfully inserted in the tree,
     * otherwise false.
     */
    bool insertItem(const char* text, const QPixmap& pixmap,
		    int row = -1, bool prefix = true);

    /**
     * This overloaded function inserts a new item into the tree, but a
     * path through the tree specifies the reference insert position. If
     * there is no item at the specified path, the item is simply appended
     * to the tree at the topmost level.
     * 
     * @param text specifies text for the new item; must not be 0
     * @param pixmap specifies a pixmap for the new item
     * @param path specifies the insert position
     * @param prefix if true, the new item is inserted before the reference
     * item, otherwise after it
     * @return true if the item has been successfully inserted in the tree,
     * otherwise false.
     * @see #insertItem
     */
    bool insertItem(const char* text, const QPixmap& pixmap,
		    const KPath& path, bool prefix = true);

    /**
     * This overloaded function inserts a new item into the tree, but the
     * new item is specified directly. The reference item is specified as a
     * row index.
     * 
     * @param newItem specifies the item to insert
     * @param path specifies the insert position
     * @param prefix if true, the new item is inserted before the reference
     * item, otherwise after it
     * @return true if the item has been successfully inserted in the tree,
     * otherwise false.
     * @see #insertItem
     */
    bool insertItem(KTreeViewItem *newItem, 
		    int row = -1, bool prefix = true); 

    /**
     * This overloaded function inserts a new item into the tree, but the
     * new item is specified directly. The reference item is specified by a
     * path.
     * 
     * @param newItem specifies the item to insert
     * @param path specifies the insert position
     * @param prefix if true, the new item is inserted before the reference
     * item, otherwise after it
     * @return true if the item has been successfully inserted in the tree,
     * otherwise false.
     * @see #insertItem
     */
    bool insertItem(KTreeViewItem *newItem,
		    const KPath& thePath, bool prefix = true);

    /**
     * Returns a pointer to the item in the specified row, or 0 if the
     * specified row is outside the limits. This is a cheap operation.
     * 
     * @param row specifies the row index
     * @return the item at the specified row
     * @see #itemRow
     * @see #itemPath
     */
    KTreeViewItem* itemAt(int row) const;

    /**
     * Returns a pointer to the item at the end of the path, or 0 if there
     * is no such item.
     * 
     * @param path specifies a path through the tree
     * @return the item at the end of the specified path
     * @see #itemRow
     * @see #itemPath
     */
    KTreeViewItem* itemAt(const KPath& path);

    /**
     * Looks up the row index at which the specified item is found in the
     * visible tree or -1 if the item is not visible or not in the tree.
     * 
     * @param specifies the item to search
     * @return the row index of the item
     * @see #itemAt
     * @see #itemPath
     */
    int itemRow(KTreeViewItem* item);

    /**
     * Fills path with the logical path to the item at the specified row.
     * The specified path variable should be empty. Any strings popped from
     * the path must be deleted by the caller. If the row is invalid, path
     * remains unchanged (i.e. empty).
     * 
     * @param row specifies the row index
     * @param path receives the path of the specified item
     * @see #itemAt
     * @see #itemRow
     */
    void itemPath(int row, KPath& path);

    /**
     * Outdents the item at the given row one level so that it becomes a
     * sibling of its parent.
     */
    void join(int index);

    /**
     * Same as above but uses a path to specify the item.
     */
    void join(const KPath& path);

    /**
     * Moves the item at the specified row down one row in its current
     * branch.
     */
    void lowerItem(int index);

    /**
     * Same as above but uses a path to specify the item.                              
     */
    void lowerItem(const KPath& path);

    /**
     * Moves the item at the specified row up one row in its current
     * branch.
     */
    void raiseItem(int row);

    /**
     * Same as above but uses a path to specify the item.
     */
    void raiseItem(const KPath& path);

    /**
     * Removes the item at the specified row.
     */
    void removeItem(int row);

    /**
     * Same as above except uses path through the tree to find the item.
     */
    void removeItem(const KPath& thePath);

    /**
     * The specified item is scrolled into view.  If the specified item is
     * already visible, nothing happens, unless children is true, in which
     * case the display is scrolled such that the item and as many of its
     * child items as possible are visible.
     * 
     * @param item specifies the item to make visible
     * @param children specifies whether children should be made visible
     */
    void scrollVisible(KTreeViewItem* item, bool children);

    /**
     * Makes the item at specifies row the current item and highlights it.
     * The signal @ref #highlighted is emitted if the current item changes.
     * 
     * @param row specifies the row to make the current item
     */
    void setCurrentItem(int row);

  void setExpandButtonDrawing(bool enable);

  void setExpandLevel(int level);

    /**
     * Sets the indentation stepping, in pixels.  If, in a derived class,
     * the levels are indented differently this value may be ignored.
     * 
     * @param spacing specifies the new indentation spacing, in pixels
     */
    void setIndentSpacing(int spacing);

    /**
     * If true, removing a top-level item that contains the current item
     * will move the current item to the following sibling (or to the
     * previous if there is none). Otherwise, there will not be a current
     * item.
     */
    void setMoveCurrentToSibling(bool m = true);

  /**
	If enable is TRUE (default), item text will be displayed, otherwise 
	it will not, and no highlight will be shown in the default widget.
	*/
  void setShowItemText(bool enable);

  /**
	If enable is TRUE (default), lines depicting the structure of the
	tree will be drawn, otherwise they will not.
	*/
  void setTreeDrawing(bool enable);

  /**
	Indicates whether item text is displayed.
	*/
  bool showItemText() const;

    /**
     * Indents the item at the specified index, creating a new branch.
     */
    void split(int index);

    /**
     * Same as above but uses a path to specify the item.                    
     */
    void split(const KPath& path);

    /**
     * Removes the item at the given index from the tree, but does not
     * delete it, returning a pointer to the removed item.
     */
    KTreeViewItem* takeItem(int index);

    /**
     * Same as above but uses a path to specify the item to take.
     */
    KTreeViewItem* takeItem(const KPath& path);

  /**
	Indicates whether the tree structure is drawn.
	*/
  bool treeDrawing() const;

public:
    /**
     * Use numRows() instead.
     * 
     * @return the number of items that are visible (their parents are
     * expanded).
     * @deprecated
     */
    int visibleCount() const { return numRows(); }

signals:
    /**
     * This signal is emitted when an item in the tree is collapsed.
     * The signal is not emitted for items that are invisible.
     * 
     * @param index the row index of the collapsed item
     */
    void collapsed(int index);
    
    /**
     * This signal is emitted when an item in the tree is expanded.
     * The signal is not emitted for items that are invisible.
     * 
     * @param index the row index of the expanded item
     */
    void expanded(int index);

    /**
     * This signal is emitted when an item that has the delayedExpanding
     * flag set is about to be expanded. The delayedExpanding flag is not
     * reset; the slot that the signal is connected to should do so if
     * necessary. The item being expanded is passed to the slot. The slot
     * gets the opportunity to insert child items into that item. It should
     * not change the item any other way. It can disallow the expansion by
     * setting allow to false; in this case the item is not expanded.
     *
     * The signal is always emitted, regardless whether the expansion was
     * triggered by the user or by the program.
     * 
     * @param item specifies the item that is about to be expanded
     * @param allow can be set to false to disallow expansion; no further
     * actions are taken then
     */
    void expanding(KTreeViewItem* item, bool& allow);

    /**
     * This signal is emitted when an item in the tree is highlighted.
     * 
     * @param index the row index of the highlighted item.
     */
    void highlighted(int index);

    /**
     * This signal is emitted when the user right-clicks.
     * 
     * @param index the row index of where the click occurred; it is -1 if
     * the click was not on an item.
     * @param pt the location (in widget coordinates) where the mouse click
     * happened.
     */
    void rightPressed(int index, const QPoint& pt);

    /**
     * This signal is emitted when an item in the tree is selected.
     * 
     * @param index the row index of the selected item.
     */
    void selected(int index);
  
protected:
    /**
     * Appends a new child item to a parent item as a new direct child. All
     * internal state is updated and the widget is repainted as necessary.
     * The new child remains invisible if any ancestor of it (including the
     * parent) is collapsed.
     * 
     * @param parent specifies the parent of which the new item will become
     * a child
     * @param child specifies the new child item
     * @see #appendChildItem
     */
    void appendChildItem(KTreeViewItem* parent,
			 KTreeViewItem* child);
    virtual int cellHeight(int row) const;
    virtual int cellWidth(int col) const;
    void changeItem(KTreeViewItem* toChange,
		    int itemRow, const char* newText,
		    const QPixmap* newPixmap);
    /**
     * Collapses the specified subtree and updates the display. The
     * specified item need not be visible. This function does nothing if
     * the item is already collapsed.
     * 
     * @param item specifies the item to collapse.
     * @param emitSignal specifies whether the signal @ref #collapsed should be emitted.
     */
    virtual void collapseSubTree(KTreeViewItem* item, bool emitSignal);

    /** Internal function used for counting items */
    static bool countItem(KTreeViewItem* item, void* total);

    /**
     * Expands the specified subtree and updates the display. The specified
     * item need not be visible. This function does nothing if the item is
     * already expanded.
     * 
     * @param item specifies the item to expand.
     * @param emitSignal specifies whether the signal @ref #expanded should be emitted.
     */
    virtual void expandSubTree(KTreeViewItem* item, bool emitSignal);
  void fixChildren(KTreeViewItem *parentItem);
    virtual void focusInEvent(QFocusEvent* e);
    virtual void focusOutEvent(QFocusEvent* e);

    /** internal function used to determine maximum item width */
    static bool getMaxItemWidth(KTreeViewItem* item, void *user);

    /**
     * @param specifies a tree item of this tree
     * @return the total indentation of the specified item, in pixels
     */
    virtual int indentation(KTreeViewItem* item) const;

    /**
     * Inserts a new item before or after a reference item. (That is, the
     * new item will become a sibling of the reference item.) If the
     * reference item is 0, the new item is appended at the topmost level.
     * If the reference item is not 0, it must be an item that is already
     * in this KTreeView. Internal data is updated and the display is
     * refreshed as necessary. The inserted item may still be invisible if
     * any of the parents is collapsed.
     * 
     * @param referenceItem specifies the reference item
     * @param newItem specifies the new item; must not be 0.
     * @return true if the item has been successfully inserted in the tree,
     * otherwise false.
     * @see #insertItem
     */
    bool insertItem(KTreeViewItem* referenceItem, KTreeViewItem* newItem,
		    bool prefix);

    /**
     * Finds the logical path of the specified item. The specified path
     * variable should be empty.
     * 
     * @param item specifies the item whose path is to determine
     * @param path receives the path of the item
     * @see #itemPath
     * @see #itemRow
     * @see #itemAt
     */
    void itemPath(KTreeViewItem* item, KPath& path) const;

  void join(KTreeViewItem *item);

    /**
     * Reimplemented for key handling. If there are any items in the
     * KTreeView, but there is no current item, the topmost item is made
     * current. The key press event is first forwarded to the current item
     * by calling @ref #KTreeViewItem::keyEvent.
     */
    virtual void keyPressEvent(QKeyEvent* e);

    /**
     * The key release event is first forwarded to the current item (if
     * there is one) by calling @ref #KTreeViewItem::keyEvent.
     */
    virtual void keyReleaseEvent(QKeyEvent* e);

    int level(KTreeViewItem* item) const;
  void lowerItem(KTreeViewItem *item);

    /**
     * Reimplemented for mouse event handling. The mouse double click event
     * is first forwarded to the item that has been clicked on (if there is
     * one) by calling @ref #KTreeViewItem::mouseEvent.
     */
    virtual void mouseDoubleClickEvent(QMouseEvent* e);

    /**
     * Reimplemented for mouse event handling. The mouse move event is
     * first forwarded to the current item (if there is one) by calling
     * @ref #KTreeViewItem::mouseEvent.
     */
    virtual void mouseMoveEvent(QMouseEvent* e);

    /**
     * Reimplemented for mouse event handling. The mouse press event is
     * first forwarded to the item that has been clicked on (if there is
     * one) by calling @ref #KTreeViewItem::mouseEvent. The clicked on item
     * is made the current item.
     */
    virtual void mousePressEvent(QMouseEvent* e);

    /**
     * Reimplemented for mouse event handling. The mouse release event is
     * first forwarded to the current item (if there is one) by calling
     * @ref #KTreeViewItem::mouseEvent.
     */
    virtual void mouseReleaseEvent(QMouseEvent* e);

  virtual void paintCell(QPainter *p, int row, int col);
    /*
     * virtual void paintItem(QPainter *p, KTreeViewItem *item, 
			      * bool highlighted);
     */
    /**
     * Internal. Needed to make kcontrol's color setup work.
     */
    void paletteChange(const QPalette&);
    void raiseItem(KTreeViewItem* item);

    /**
     * Internal function that finds the item at the given path. Returns 0
     * if the item cannot be found. The path is destroyed by this function.
     */
    KTreeViewItem* recursiveFind(KPath& path);

    void setItemExpanded(KTreeViewItem* item);
    static bool setItemExpandLevel(KTreeViewItem* item, void*);
    static bool setItemExpandButtonDrawing(KTreeViewItem* item, void*);
    static bool setItemShowText(KTreeViewItem* item, void*);
    static bool setItemTreeDrawing(KTreeViewItem* item, void*);
  void split(KTreeViewItem *item);
  void takeItem(KTreeViewItem *item);
    virtual void updateCellWidth();
    virtual void updateVisibleItems();
    void updateVisibleItemRec(KTreeViewItem* parent, int& count, int& width);

    KTreeViewItem* treeRoot;
    bool clearing;
    int current;
    bool drawExpandButton;
    bool drawTree;
    int expansion;
    bool goingDown;
    int itemIndent;
    int maxItemWidth;
    bool showText;
    bool moveCurrentToSibling;
    // list of visible items
    int itemCapacity;			/* for how many items we've space allocated */
    KTreeViewItem** visibleItems;

  // Rainer Bawidamann: move window in "rubberband" mode
  bool rubberband_mode;             // true if in "rubberband_mode"
  QPoint rubber_startMouse;         // where the user pressed the MMB
  int rubber_height, rubber_width,  // the size if the rubberband rect
	rubber_startX, rubber_startY; // the x/yOffset() when the MMB was pressed
  void draw_rubberband();
  void start_rubberband(const QPoint& where);
  void end_rubberband();
  void move_rubberband(const QPoint& where);
};

#endif // KDE_KTREE_VIEW_H