class TreeList : public BControl

A list control that displays a tree structure

Inheritance:


public members:

TreeList( BRect frame, const char* name, const char* label, BMessage* message, ulong resizing_mode = B_FOLLOW_LEFT | B_FOLLOW_TOP, ulong flags = 0 )
Constructor like any other BControl
virtual ~TreeList()
Destructor which destroys any items this list refers to.
enum EventTypes
Types of events that the base class will raise
LIST_INVOKED
User double-clicked on an item
ITEM_SELECTED
An item became selected
ITEM_DESELECTED
An item lost selection
virtual void Notify( int eventtype, const TreeItem * item)
Uses BMessages to notify the user of the list that something has happened
Adding and removing root items
virtual void AddItem( TreeItem *)
Add an item
virtual TreeItem * RemoveItem( TreeItem * item)
Remove an item
virtual void Purge()
Get rid of all items (recursively) and delete them
TreeItem * Root()
Get at the root of the list
virtual void ExplodeAll()
Open up the whole tree, I wanna see it all
virtual void SelectAll( bool select)
Select or deselect everything
List currency.
TreeItem * Current()
Find out the current item (may be 0)
virtual void SetCurrent( TreeItem * item)
Set the current item (you can pass 0 so that nothing is current)
void GetSelected( BList&)
Get a list of all items in list that are selected
TreeItem * GetSelected()
Get a pointer to the first item in the list that is selected
bool AnySelected()
Return true if any items in list are selected
enum SelectionStyle
Constants used to determine the style of selection
SINGLE_SELECT
Allow selection of a maximum of one item
MULTIPLE_SELECT
No maximum to the number of items that may be selected
virtual void SetSelectionMode( int mode)
Set the selection style
int SelectionMode()
Returns the current selection style
virtual void Refresh( bool refresh_all)
Refreshes the visuals of the list
Control general look of tree
virtual float ItemIndent() const
How much to indent each child from its parent
virtual float BoxIndent() const
How far is the exploder box from the left of the item
virtual bool DisplayLines() const
Should I bother to draw those lines at all
void SetBoring( bool boring)
Wanna be tedious - make it so
bool Boring() const
How boring am I anyway.
virtual BBitmap* ExploderImage( bool collapsed)
Access the image used for the exploder box
TreeView * TView()
Returns the child view I render my graphics into
enum ImageIndex
I have a few built-in images, this enumeration lists them
TL_DOWNTRIANGLE
Little blue triangle, pointing downward
TL_RIGHTTRIANGLE
Equally blue triangle pointing right
TL_MINUSBOX
Small box with a minus sign in it [-]
TL_PLUSBOX
Samll box with a plus sign in it [+]
TL_IMAGECOUNT
This marks the end of the enumeration
static BBitmap* GetStandardImage( ImageIndex image)
Roll-up, get your fresh images here
static void DrawCenteredImage( BView* v, BPoint where, const BBitmap* bitmap)
A helper function for drawing images in a view centered on a point
enum Interesting
Magic values
TL_DEFAULT_INDENT
Amount by which each level is indented
TL_DEFAULT_BOX_INDENT
Offset of center of exploder box
TL_DEFAULT_ITEM_HEIGHT
Height of each item
enum Boring
More magic values
TL_DEFAULT_BORING_INDENT
Indent value when in boring mode
TL_DEFAULT_BORING_BOX_INDENT
Offset of center of exploder box
TL_DEFAULT_BORING_ITEM_HEIGHT
Height of boring items

protected members:

void RecalculateScrollbars( float width, float height)
Recalculate the scrollbars based on new sizes
virtual void RecalculatePositions()
Force a recalculation of all child positions.
virtual TreeView * CreateTreeView( BRect rect)
Used to create my child view
virtual void Redraw()
Draw everything
virtual void DrawItem( TreeItem *)
Draw an item (and all it's visible children)
Draw Methods
Building blocks for DrawItem
virtual void DrawExploder( TreeItem *)
Draw exploder box
virtual void DrawParentLine( TreeItem *)
Draw line back to parent item
virtual void DrawChildLine( TreeItem *)
Draw line connecting children of this item
virtual void DrawCurrency( TreeItem *, bool on)
Draw indication of which is the "current" item

Documentation

A TreeList is a view that displays a list of items the user can select and invoke. TreeList is heavily dependent on the TreeItem class. The TreeList is really a composite object consisting of two BScrollbars, a child view of class TreeView to render the graphics and a collection of TreeItems.

The list keeps track of pointers to TreeItems. Adding an item to the list adds only the pointer; the data itself isn't copied. The TreeList provides methods to render list-wide aspects of the list such as the connecting lines, and the exploder boxes. It also keeps a track of the current item. However, much of what you may expect the TreeList to do is offloaded to the TreeItems. As a general policy, things that may change from item to item are atrributes of and methods on the items rather than the list.

When the contents of the list change, the TreeList makes sure the visible list on-screen is updated. TreeItems know that they are attached to a list, but in some circumstances you will have to manually ask to redraw the list by calling the TreeList::Redraw function or the TreeView's Invalidate.

The user can click an item in the list to select it and double-click an item to both select and invoke it. The user can also select and invoke items from the keyboard. The navigation keys (such as Down Arrow and Up Arrow) select items; Enter invokes the item that's currently selected.

The TreeList highlights the selected item, but otherwise it doesn't define what, if anything, should take place when an item is selected. You can determine that yourself by registering a "selection message" (a BMessage object) that should be delivered to a target destination whenever the user selects an item.

Similarly, the TreeList doesn't define what it means to "invoke" an item. You can register a separate "invocation message" that's posted whenever the user double-clicks an item or presses Enter while an item is selected. For example, if the user double-clicks an item in a list of file names, a message might be posted telling the BApplication object to open that file.

A TreeList doesn't have a default selection message or invocation message, invocation message functions are all inherited from BControl.

virtual ~TreeList ()
Frees up any dynamically allocated objects, also calls Purge to free all memory allocated to hold the list of items. A consequence of this is that ListItems should always be dynamically allocated.

virtual void Notify ( int eventtype, const TreeItem * item)
This method is called for anything that needs to be able to send a message (via Invoke) to the outside world, this function builds on the functionality of Invoke.

Invoke is not used directly as special values need to be set in the model message. You can overide this to avoid using BMessages, or to add data of your own. The parameter eventtype is an integer identification of the particular type of event (It would be nice if BControl handled this, but it doesn't). TreeItems and TreeLists only use values from the EventTypes enumeration, but any integer is OK, this may be useful in derived classes so that events the bases classes are unaware of can still be sent using the default implementation.

Internally this function adds two new pieces of information to the model BMessage, <I>eventtype</I> as a B_LONG_TYPE called "t_event" and "item" as a B_OBJECT_TYPE called "t_item". Because of the built in action of BControls Invoke you can also rely on "when" and more usefully "source" being added ("source" being a pointer to the TreeList).

Adding and removing root items
Add or remove items to/from top level of tree (yes, a tree can have multiple roots). To add/remove to lower levels use methods on ListItems. These methods are really shorthand for getting the root item then applying TreeItem methods to that These methods do not copy or delete any items, all items are held by reference.

TreeItem * Root ()
Get at the real root of the list. Although the tree may look as if it has multiple roots in fact there is a "magic" single root that all TreeLists own from the time they are constructed until they die. The root is an invisible item and should never be deleted unless you really want to test the robustness of your BeBox. Iterate over the roots children to get at the items you added. The root item never has a sibling (and please don't add one, I wouldn't like it).

List currency.
This is mainly to help with keyboard navigation of the list, the current is the one to which keystrokes apply.

This may have nothing to do with selection, although this is often updated as selection precedes.

void GetSelected ( BList&)
When getting a list of selected items, the list is cleared on entry. Be careful when working on the returned list since the list may become invalidated by other operations. This is particularly evil when deleting items. The safest way to remove selected items from the list is to loop getting the first selected and remove them one by one.

virtual void Refresh ( bool refresh_all)
When you change the list via purely item level operations so the list is not aware of this, you better call this to make sure the display gets updated Set the flag to TRUE to get everything updated, FALSE if the list layout was unaltered (selection,labels,etc.)

Control general look of tree
The values these virtuals return control some of the overall look of the tree. The base class does quite a lot and implements two overall styles, interesting and boring.

void SetBoring ( bool boring)
OK, so this betrays my bias, pass true in here to get no lines and dull little rotating triangles, I guess it does save some space though!

virtual BBitmap* ExploderImage ( bool collapsed)
The exploder box is the little gizmo the user clicks on to collapse or explode items that have children. The list controls these images rather than the item because we've gotta have some consistency, right?

Pass in true to get the image for a collapsed parent, false to get the image for an exploded one (I always wanted to explode my parents).

The base class will provide either the [+] [-] thingies or the rotating triangle thing.

TreeView * TView ()
Provide access to the view used to render that graphics. Logically the TreeList is the whole thing so pretty much all the operations are defined on it. In fact the TreeList is an enclosing view for three subviews, two scrollbars and the view used to render the graphical depiction of the list. Since you may want to get access to this child view I give you a direct way to get to it. This is mainly used by ListItems to decide which view they should render into.

static void DrawCenteredImage ( BView* v, BPoint where, const BBitmap* bitmap)
Since the actual mouse-clicks come in on a sub-view, it passes them off to this virtual after decoding the message. All the real handling of the click goes on in here. The parameters are simply the like-named entries in the message.

virtual TreeView * CreateTreeView ( BRect rect)
This is virtual in the unlikely event that you want to replace the view I use to render into!

virtual void Redraw ()
Entirely redraws the list view content. Useful if you are not sure everything is up-to-date. In general the list will keep itself up to date bu who knows

virtual void DrawItem ( TreeItem *)
This is the key drawing function, and it delegates all the actual drawing to helper functions. This function is concerned with the logic of drawing, determining the order of drawing and recursing through all the children.

Draw Methods
The various drawing operations are broken down into a number of "building-block" functions. This is intended to make it easy to modify parts of the redraw mechanism without having to reimplement all of it.

enum Interesting
A few default values, so you can see what I return when you call ItemIndent or BoxIndent or accept default item height

enum Boring
A few default values, so you can see what I return when you call ItemIndent or BoxIndent or accept default item height. This set is used when the list is set to boring mode.


this class has no child classes.

alphabetic index hierarchy of classes


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++