class TreeItem : public BObject

TreeItem, Base item that can be added to a TreeList

Inheritance:


public members:

Constructors
TreeItem()
Construct a nameless TreeItem
TreeItem( const char* name)
Constructor
virtual ~TreeItem()
Destructor
void DeleteChildren()
Delete all my descendents.
Tree builders
virtual void AddChild( TreeItem * item, int at = INT_MAX)
Adds a child at a specified position, by default at the end
virtual void AddSibling( TreeItem * item)
Adds an item as a sibling
void AddFirstChild( TreeItem * item)
Adds an item as the first child
TreeItem * RemoveChild( TreeItem *)
Remove may return 0 if item not found
Simple iterators
TreeItem * Sibling() const
Finds immediate sibling of current item
TreeItem * Children() const
Finds first child of current item
TreeItem * Parent() const
Finds parent of current item
Visual iterators
TreeItem * Prev() const
Returns the item immediately before this one
TreeItem * Next() const
Returns the item immediately after this one
TreeItem * Last() const
Searches for the last visible child of this item
Method applicators
void DoForAllChildren( void (TreeItem::*mf)())
Apply function with no parameters
void DoForAllChildren( void (TreeItem::*mf)(bool), bool p)
Apply function with no parameters
void DoForAllChildren( void (TreeItem::*mf)( TreeList *), TreeList * p)
Apply function with no parameters
TreeItem * FindChild( bool (TreeItem::*mf)())
Search for descendant that satisfies the supplied predicate
Predicates
bool isSelected() const
Returns true if item is in the selected state
bool isCollapsed() const
Returns true if the item is hiding its descendents
bool isHidden() const
Returns true if one of my ancestors is collapsed
bool isInvalid() const
is item in a state where it needs a redraw
virtual const BBitmap* Icon() const
Get iconic representation of item
void SetLabel( const char* newtext)
Sets the stored text for the item
const char* Label() const
Accesses the stored text for the item
virtual bool HasChildren() const
Returns true if item has any children
const BPoint& Position() const
Accesses the current position of the item
virtual float Height() const
Gets the recommended height for the item
virtual TreeList * Owner() const
Find out which list (if any) this item is in.
int FindSelectedChildren( BList& results)
Augments the provided list with all selected descendents
Hit tests
enum HitResult
Enumeration for result of HitTest method
NOHIT
Not on this item at all
PLUSMINUS_BOX
On the exploder box
LABEL_BOX
On the icon or label area
virtual int HitTest( TreeList * owner, BPoint where)
Tells which area in this object is underneath the point
TreeItem * ItemAt( BPoint where)
Look for the item under the point provided
virtual void Notify( int event)
Notify
virtual void Collapse()
Collapse this item, hiding all children
virtual void Explode()
Explode this item, showing its first level children
virtual void Select( bool select)
Controls selection status for this child
virtual void SetPosition( BPoint newpos)
Modifies position stored for child
Births and deaths
virtual void ChildAdded( TreeItem * new_child)
Notifies when a new child is added, invoked on parent
virtual void ChildRemoved( TreeItem * ex_child)
Notifies when an existing child has been removed, invoked on ex-parent.
virtual void CurrencyChanged( bool current)
Called whenever an item gains or loses currency
virtual void Draw( TreeList * owner)
Draw item in view provided, uses DrawIcon and DrawLabel
virtual void Invalidate( TreeList * owner)
Conditionally Invalidate this items rectangle
static BBitmap* CreateDimBitmap( const BBitmap* bitmap)
Creates a new bitmap based on an old one, but with all the colors subdued

protected members:

Building blocks for Draw of an item
virtual void DrawIcon( TreeList * owner)
Draws the icon for the list item
virtual void DrawLabel( TreeList * owner)
Draws the label for the list item

Documentation

A TreeItem is an item that can be displayed in a TreeList. A TreeItem is heavily dependent on the TreeList class. TreeItems control the behaviours that vary from item to item. List wide behaviours are the perogative of the TreeList class.

TreeList assumes all it's items are TreeItems, but you can derive from this to get notifications, add your own data and overide methods. It is done this way so that trees that contain different types of items do not have to spend time switching on the item type.

Constructors
Create a TreeItem, optionally providing a name. Items will not be displayed until they are inserted into a list.

virtual ~TreeItem ()
Frees up any dynamically allocated objects, also calls DeleteChildren to free items that are children of this one. A consequence of this is that ListItems should always be dynamically allocated.

Tree builders
The next group of functions manipulate the tree None of them copy or delete the items concerned Items are held by reference. Various ways to Add, added items MUST NOT have siblings before the addition!

virtual void AddChild ( TreeItem * item, int at = INT_MAX)
Add a child to this one. The second parameter determines where the child is added, 0 indicates that the added child should be first, 1 after the first, 2 after the second etc. The default is to tag the child on at the end.

virtual void AddSibling ( TreeItem * item)
Add an item as the immediate sibling to this one. An example may help... assume that we have a parent P and three children A, B and C; if I now apply AddSibling to B with a new child X then I end up with the parent P and four children A, B, X and C.

I could achieve the same with Addchild, but AddSibling is often useful when the only context is that I want to add an item after the current one (as happens often when adding items to a list).

void AddFirstChild ( TreeItem * item)
Adds a new first child to the parent, all the existing children move on. This is just an inline for AddChild( item, 0).

TreeItem * RemoveChild ( TreeItem *)
Looks for the provided item as a child of the item this method is applied to then removes it from the tree. This function will search as deep as it needs to to find the child. When the child is removed all its children come with it. If the child is not found this function returns 0.

Simple iterators
These are the simplest iterators, and are very lightweight, all inlines for minimal overhead as we spend a lot of time chasing all over the tree. They all return 0 if the required item is not found.

Visual iterators
These are the iterators move over the list in visible order rather than simply tree order as is the case with Children, Parent and Sibling. Since these functions have to "flatten" the list to traverse it and pay attention to whether something is hidden or not, they are rather more expensive than the simple iterators. These are used (for example) when the list cursor is moved up and down.

Method applicators
These are used to apply a TreeItem method to all connected children (preorder).

TreeItem * FindChild ( bool (TreeItem::*mf)())
In a similar fashion to the DoForAllChildren method, this method applies a simple predicate method to all children, in preorder. Unlike the DoForAllChildren methods this one stops as soon as the predicate returns true, in this case FindChild returns a pointer to the child that returned true. If no children satisfy the predicate then FindChild returns 0.

As an example, by calling "item->FindChild(&TreeItem::isCollapsed)" one can get a pointer to the first collapsed child.

Predicates
These are used to test for various binary conditions. The apply only to the item in question. These may usefully be used in conjunction with FindChild to look for a descendant that satisfies the given predicate.

virtual const BBitmap* Icon () const
This is a virtual function which is used to obtain the icon (BBitmap) which is displayed to indicate the type and state of the item. It is very likely that you will need to override this. The BBitmap returned is not a copy and the caller must not delete it. Most items will need to return one of two bitmaps, one for the selected state and one for the non-selected state.

A good size of icon to return is a MiniIcon, although other sizes are fine and may be used to good effect if the item height is changed.

If this function returns 0 no icon will be displayed and the item text will be moved over to fill the space that would have been occupied otherwise.

Normally selection is displayed using a dimmed form of the icon, a static helper function, CreateDimBitmap is available to create such a bitmap.

void SetLabel ( const char* newtext)
Unlike the Icon, the text label is stored in the base class. Label is used to access it and SetLabel is used to set the text. SetLabel copies the provided text into an internal buffer. It is OK to set the text using a NULL pointer, this clears out the internal stored text.

virtual bool HasChildren () const
The result of this function defines whether or not the exploder box is drawn for this item. The base class simply returns true if the current item has children attached.

The important subtlety here is that by overiding this you can display a sparse tree. This is a tree where not all the children are actually held in the tree, only the visbile childre need be around. This may be very useful when displaying a very large list, for example a file tree. As long as this function tells whether the item <I>may</I> have children or not, the actual TreeItem children need only be created when the item is exploded, and the children can be freed again when the item is collapsed.

const BPoint& Position () const
This lets you find out where the top-left of the items rectangle is positioned. The position is set dynamically by the TreeList control the layout of the items.

virtual float Height () const
The Height is an attribute of the item that normally stays the same for the lifetime of the item. Height defaults to a good size for MiniIcons, but can be modified (though derivation) to provide a value that is more appropriate for larger (or smaller) images.

virtual TreeList * Owner () const
Access a pointer to the TreeList control that this item belongs to. This may return NULL if the item is not part of a tree rooted on a TreeList.

This is virtual for a mainly internal reason. A TreeList control accesses all its items through a special internal derivation of a TreeItem (this is a little like the root view that is part of a BWindow I guess). Base class TreeItems return the Parents Owner, of NIL if they do not have a Parent. The special root Item in the TreeList "knows" to return a pointer to the TreeList.

I cannot think of a good reason for user derived classes to overide this function.

int FindSelectedChildren ( BList& results)
Looks for all descendants that are selected. Adds any it finds to the provided list and then returns the number of children it added.

This does NOT clear the list before the addition. This function only considers descendants, not the item itself.

Hit tests
Hit testing is the mechanism the list uses to determine what is under the mouse pointer.

enum HitResult
The base class only uses the provided values. A more sophisticated derived class could add to this since "HitTest" returns an "int"

virtual int HitTest ( TreeList * owner, BPoint where)
Checks which area of the subject item is under the given point. Returns an integer to categorize the area. The base class will only return one of the values defined in the HitResult enumeration.

In derived items that have custom drawing routines, this method will probably need to be overridden to ensure that mouse-clicks work correctly.

TreeItem * ItemAt ( BPoint where)
Looks for a hit anywhere over this item or any of it's descendants (this does not recurse into hidden children). Returns a pointer to the hit child, or NIL for no child found.

virtual void Notify ( int event)
This is a key function to override in your items if you want to know what is going on at an item level. Alternatives are to overide the similar function on the list itself, or to wait for messsages to arrive.

The base class implementation simply invokes TreeList::Notify to pass on the event, so be careful when overiding to decide whether or not you want to send these notification.

The integer parameter defines what happened. Values are defined in the enumeration TreeList::EventTypes. You will only see selection events right now. Derived classes can augment this with other values.

Births and deaths
Notifications are passed up the tree when items are added or removed. These methods pass this up the parentage chain to the root, where they cause a refresh of the list.

virtual void Invalidate ( TreeList * owner)
This function determines whether the item could be visible an if so calculates its rectangle and invalidates that area of the list provided.

static BBitmap* CreateDimBitmap ( const BBitmap* bitmap)
A static function to perform a common BBitmap function This returns a new copy of the provded bitmap with all the colors somewhat subdued, this imitates what the browser does.

Building blocks for Draw of an item
When items need to draw themselves they call on these functions to draw to icon and text. You can override these to change the appearence, either to get a different look, or to take into account other information.


this class has no child classes.

alphabetic index hierarchy of classes

See Also: TreeList TreeView


The TreeList Control Documentation, HTML Edition, for Release 1.1d8 of the Be OS.

Copyright © 1996 Designer Logic (xyzzy). All rights reserved.

Be, the Be logo, BeBox, Be OS, Be Operating System, and GeekPort are trademarks of Be, Inc.

Last modified December 31, 1996.

generated by doc++