class KTreeList

A collapsible treelist widget. More...

Definition#include <ktreelist.h>
InheritsQTableView
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Signals

Protected Methods

Protected Members


Detailed Description

A collapsible treelist widget.

1. Introduction 2. Features 3. Installation 4. Public interface

1. Introduction ================================================================================

KTreeList is a class inherited from QTableView in the Qt user interface library. It provides a way to display hierarchical data in a single-inheritance tree, similar to tree controls in Microsoft Windows and other GUI's. It is most suitable for directory trees or outlines, but I'm sure other uses will come to mind. Frankly, it was designed mostly with the above two functions in mind, but I have tried to make it as flexible as I know how to make it easy to adapt to other uses.

In case of problems, I encourage you to read all of the other documentation files in this package before contacting me as you may find the answer to your question in one of them. Also read the source code if you have time. I have tried to comment it adequately and make the source understandable.

2. Features ================================================================================

Displays both text and optional pixmap supplied by the programmer. A support class, KTreeListItem, 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)

Configuration as follows:

enable/disable item text display (if you only want to display pixmaps)

enable/disable drawing of expand/collapse button

enable/disable drawing of tree structure

Keyboard support as follows:

up/down arrows move the highlight appropriately and scroll the list an item at a time, if necessary

pgup/pgdn move the highlight a 'page' up or down as applicable and scroll the view

+/- keys expand/collapse the highlighted item if it appropriate

enter key selects the highlighted item

Mouse support as follows:

left click on item highlights it

left click on an item "hot button" expands or collapses its sub-tree, as applicable

double click on item selects it

normal scrolling functions in conjunction with scrollbars if present

2nd scrolling with the middle mouse button: pressing MMB inserts a rubberband, showing which part of the whole tree is currently visible. moving the mouse will scroll the visible part

Signals/Slots

signal void highlighted(int) - emitted when an item in the tree is highlighted; sends the index of the item

signal void selected(int) - emitted when an item in the tree is selected; sends the index of the item

signal void expanded(int) - emitted when an item in the tree is expanded; sends the index of the item

signal void collpased(int) - emitted when an item in the tree is collapsed; sends the index of the item

 KTreeList (QWidget *parent = 0, const char *name = 0, WFlags f = 0)

Widget contructor. Passes all parameters on to base QTableView, and does not use them directly. Does internal initialization, sets the current item to -1, and sets default values for scroll bars (both auto) and grid snap (snap to grid vertically).

KTreeList ()

[virtual]

void  addChildItem (const char *theText, const QPixmap *thePixmap, int index)

Adds a new item to the tree with the given text and pixmap as a child of the item currently at the given index. If the current item already has children, the new item is appended below them.

void  addChildItem (const char *theText, const QPixmap *thePixmap, const KPath *thePath)

Same as above except parent item is specified by path.

void  addChildItem (KTreeListItem *newItem, int index)

Adds the given item as a child of the item currently at the given index. If the current item already has children, the new item is appended below them.

void  addChildItem (KTreeListItem *newItem, const KPath *thePath)

Same as above except parent item is specified by path.

bool  autoBottomScrollBar ()

[const]

Returns a bool value indicating whether the list will display a horizontal scrollbar if one of the displayed items is wider than can be displayed at the current width of the view.

bool  autoScrollBar ()

[const]

Returns a bool value indicating whether the list will display a vertical scrollbar if the number of displayed items is more than can be displayed at the current height of the view.

bool  autoUpdate ()

[const]

Returns a bool value indicating whether the list will update immediately on changing the state of the widget in some way.

bool  bottomScrollBar ()

[const]

Returns a bool value indicating whether the list has currently has a horizontal scroll bar.

void  changeItem (const char *newText, const QPixmap *newPixmap, int index)

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, const KPath *thePath)

Same as above function, except item to change is specified by a path through the tree.

void  clear ()

Removes all items from the tree.

uint  count ()

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

int  currentItem ()

[const]

Returns the index of the current (highlighted) item. If no current item, returns -1.

void  collapseItem (int index)

Collapses the sub-tree at the specified index.

void  expandItem (int index)

Expands the sub-tree at the specified index.

int  expandLevel ()

[const]

Returns the depth to which all parent items are automatically expanded.

void  expandOrCollapseItem (int index)

Same as above functions combined into one. If sub-tree is expanded, collapses it, if it is collapsed, it expands it.

void  forEveryItem (KForEvery func, void *user)

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. KForEveryFunc is defined as:

typedef void (*KForEveryFunc)(KTreeListItem *, void *);

That is, a function that returns void and takes a pointer to a KTreeListItem and pointer to void as parameters.

void  forEveryVisibleItem (KForEvery func, void *user)

Same as above, but only iterates visible items, in order.

KTreeListItemgetCurrentItem ()

Returns a pointer to the current item if there is one, or 0.

int  indentSpacing ()

Returns the number of pixels an item is indented for each level.

void  insertItem (const char *theText, const QPixmap *thePixmap, int index = -1, bool prefix = TRUE)

Inserts an item into the tree with the given text and pixmap either before or after the item currently at the given index, depending on the value of prefix. The new item is added to the same branch as the reference item. If index is -1, the item is simply appended to the tree at the root level. The item text must not be null.

void  insertItem (const char *theText, const QPixmap *thePixmap, const KPath *thePath, bool prefix = TRUE)

Same as above, but uses a path through the tree to reference the insert position.

void  insertItem (KTreeListItem *newItem, int index = -1, bool prefix = TRUE)

Inserts the given item into the tree either before or after the item currently at the given index, depending on the value of prefix. The new item is add to the same branch as the reference item. If index is -1, the item is simply appended to the tree at the root level. The item text must not be null.

void  insertItem (KTreeListItem *newItem, const KPath *thePath, bool prefix = TRUE)

Same as above, but uses a path through the tree to reference the insert position.

KTreeListItemitemAt (int index)

Returns a pointer to the item at index.

KTreeListItemitemAt (const KPath *path)

Returns a pointer ot the item at the end of thePath.

int  itemIndex (KTreeListItem *item)

Returns the index of the given item in the visible tree or -1 if not found.

KPathitemPath (int index)

Returns a pointer to the logical path to the item at the specified index. The return KPath object must be deleted by the caller. Any strings still contained in the stack will be automatically deleted, but any popped from the path must also be deleted by the caller.

void  join (int index)

Outdents the item at the given index one level so that it becomes a sibling of its parent.

void  join (const KPath *path)

void  lowerItem (int index)

Moves the item at the specified index down one slot in its current branch.

void  lowerItem (const KPath *path)

Same as above but uses a path to specify the item.

void  raiseItem (int index)

Moves the item at the specified index up one slot in its current branch.

void  raiseItem (const KPath *path)

Same as above but uses a path to specify the item.

void  removeItem (int index)

Removes the item at the specified index.

void  removeItem (const KPath *thePath)

Same as above except uses path through the tree to find the item.

bool  scrollBar ()

[const]

Returns bool value indicating whether the list currently displays a vertical scroll bar.

void  setAutoUpdate (bool enable)

If enable is TRUE (default), enables auto update, else disables it.

void  setBottomScrollBar (bool enable)

If enable is TRUE, displays a horizontal scroll bar, else hides it.

void  setCurrentItem (int index)

Makes the item at index current and highlights it.

void  setExpandButtonDrawing (bool enable)

void  setExpandLevel (int level)

void  setIndentSpacing (int spacing)

void  setScrollBar (bool enable)

If enable is TRUE, displays a vertical scroll bar, else hides it.

void  setShowItemText (bool enable)

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  setSmoothScrolling (bool enable)

If enable is TRUE, enables smooth scrolling, else disables it (default).

void  setTreeDrawing (bool enable)

If enable is TRUE (default), lines depicting the structure of the tree will be drawn, otherwise they will not.

bool  showItemText ()

[const]

Indicates whether item text is displayed.

bool  smoothScrolling ()

[const]

Returns a bool value indicating whether smooth scrolling is enabled.

void  split (int index)

Indents the item at the specified index, creating a new branch.

void  split (const KPath *path)

Same as above but uses a path to specify the item.

KTreeListItemtakeItem (int index)

Removes the item at the given index from the tree, but does not delete it, returning a pointer to the removed item.

KTreeListItemtakeItem (const KPath *path)

Same as above but uses a path to specify the item to take.

bool  treeDrawing ()

[const]

Indicates whether the tree structure is drawn.

int  visibleCount ()

Returns the number of items that are visible (their parents are expanded).

void  collapsed (int index)

[signal]

void  expanded (int index)

[signal]

void  highlighted (int index)

[signal]

void  selected (int index)

[signal]

void  singleSelected (int index)

[signal]

void  paletteChange (const QPalette &)

[protected]

void  addChildItem (KTreeListItem *theParent, KTreeListItem *theChild)

[protected]

int  cellHeight (int row)

[protected virtual]

void  changeItem (KTreeListItem *toChange, int itemIndex, const char *newText, const QPixmap *newPixmap)

[protected]

bool  checkItemPath (const KPath *path)

[protected const]

bool  checkItemText (const char *text)

[protected const]

void  collapseSubTree (KTreeListItem *subRoot)

[protected]

bool  countItem (KTreeListItem *item, void *total)

[protected]

void  expandOrCollapse (KTreeListItem *parentItem)

[protected]

void  expandSubTree (KTreeListItem *subRoot)

[protected]

bool  findItemAt (KTreeListItem *item, void *user)

[protected]

void  fixChildBranches (KTreeListItem *parentItem)

[protected]

void  focusInEvent (QFocusEvent *e)

[protected virtual]

void  forEveryItem (KForEveryM func, void *user)

[protected]

void  forEveryVisibleItem (KForEveryM func, void *user)

[protected]

bool  getItemIndex (KTreeListItem *item, void *user)

[protected]

bool  getMaxItemWidth (KTreeListItem *item, void *user)

[protected]

void  insertItem (KTreeListItem *referenceItem, KTreeListItem *newItem, bool prefix)

[protected]

void  join (KTreeListItem *item)

[protected]

void  keyPressEvent (QKeyEvent *e)

[protected virtual]

void  lowerItem (KTreeListItem *item)

[protected]

void  mouseDoubleClickEvent (QMouseEvent *e)

[protected virtual]

void  mouseMoveEvent (QMouseEvent *e)

[protected virtual]

void  mousePressEvent (QMouseEvent *e)

[protected virtual]

void  mouseReleaseEvent (QMouseEvent *e)

[protected virtual]

void  paintCell (QPainter *p, int row, int col)

[protected virtual]

void  paintHighlight (QPainter *p, KTreeListItem *item)

[protected virtual]

void  paintItem (QPainter *p, KTreeListItem *item, bool highlighted)

[protected virtual]

void  raiseItem (KTreeListItem *item)

[protected]

KTreeListItemrecursiveFind (KTreeListItem *subRoot, KPath *path)

[protected]

bool  setItemExpanded (KTreeListItem *item, void *)

[protected]

bool  setItemExpandButtonDrawing (KTreeListItem *item, void *)

[protected]

bool  setItemIndent (KTreeListItem *item, void *)

[protected]

bool  setItemShowText (KTreeListItem *item, void *)

[protected]

bool  setItemTreeDrawing (KTreeListItem *item, void *)

[protected]

void  split (KTreeListItem *item)

[protected]

void  takeItem (KTreeListItem *item)

[protected]

void  updateCellWidth ()

[protected virtual]

KTreeListItem * treeRoot

[protected]

bool clearing

[protected]

int current

[protected]

bool drawExpandButton

[protected]

bool drawTree

[protected]

int expansion

[protected]

bool goingDown

[protected]

int indent

[protected]

int maxItemWidth

[protected]

bool showText

[protected]

bool rubberband_mode

[protected]

QPoint rubber_startMouse

[protected]

int rubber_height

[protected]

int rubber_width

[protected]

int rubber_startX

[protected]

int rubber_startY

[protected]

void  draw_rubberband ()

[protected]

void  start_rubberband (const QPoint& where)

[protected]

void  end_rubberband ()

[protected]

void  move_rubberband (const QPoint& where)

[protected]


Generated by: prospector@porky.devel.redhat.com on Tue Aug 15 09:55:36 2000, using kdoc 2.0a36.