FLTK 1.3.0
Fl_Tree Class Reference

Tree widget. More...

#include <Fl_Tree.H>

Inheritance diagram for Fl_Tree:
Fl_Group Fl_Widget

List of all members.

Public Member Functions

Fl_Tree_Itemadd (const char *path)
 Adds a new item, given a 'menu style' path, eg: "/Parent/Child/item".
Fl_Tree_Itemadd (Fl_Tree_Item *item, const char *name)
 Add a new child to a tree-item.
void callback_item (Fl_Tree_Item *item)
 Sets the item that was changed for this callback.
Fl_Tree_Itemcallback_item ()
 Gets the item that caused the callback.
void callback_reason (Fl_Tree_Reason reason)
 Sets the reason for this callback.
Fl_Tree_Reason callback_reason () const
 Gets the reason for this callback.
void clear ()
 Clear all children from the tree.
void clear_children (Fl_Tree_Item *item)
 Clear all the children of a particular node in the tree specified by item.
int close (Fl_Tree_Item *item, int docallback=1)
 Closes the specified item.
int close (const char *path, int docallback=1)
 Closes the item specified by path, eg: "Parent/child/item".
Fl_Imagecloseicon () const
 Returns the icon to be used as the 'close' icon.
void closeicon (Fl_Image *val)
 Sets the icon to be used as the 'close' icon.
Fl_Color connectorcolor () const
 Get the connector color used for tree connection lines.
void connectorcolor (Fl_Color val)
 Set the connector color used for tree connection lines.
Fl_Tree_Connector connectorstyle () const
 Returns the line drawing style for inter-connecting items.
void connectorstyle (Fl_Tree_Connector val)
 Sets the line drawing style for inter-connecting items.
int connectorwidth () const
 Gets the width of the horizontal connection lines (in pixels) that appear to the left of each tree item's label.
void connectorwidth (int val)
 Sets the width of the horizontal connection lines (in pixels) that appear to the left of each tree item's label.
int deselect (Fl_Tree_Item *item, int docallback=1)
 De-select the specified item.
int deselect (const char *path, int docallback=1)
 Deselect an item specified by path (eg: "Parent/child/item").
int deselect_all (Fl_Tree_Item *item=0, int docallback=1)
 Deselect item and all its children.
void display (Fl_Tree_Item *item)
 Displays item, scrolling the tree as necessary.
int displayed (Fl_Tree_Item *item)
 See if item is currently displayed on-screen (visible within the widget).
void draw ()
 Standard FLTK draw() method, handles draws the tree widget.
const Fl_Tree_Itemfind_clicked () const
 Find the item that was clicked.
Fl_Tree_Itemfind_item (const char *path)
 Find the item, given a menu style path, eg: "/Parent/Child/item".
const Fl_Tree_Itemfind_item (const char *path) const
 A const version of Fl_Tree::find_item(const char *path)
Fl_Tree_Itemfirst ()
 Returns the first item in the tree.
Fl_Tree_Itemfirst_selected_item ()
 Returns the first selected item in the tree.
 Fl_Tree (int X, int Y, int W, int H, const char *L=0)
 Constructor.
int handle (int e)
 Standard FLTK event handler for this widget.
Fl_Tree_Iteminsert (Fl_Tree_Item *item, const char *name, int pos)
 Insert a new item into a tree-item's children at a specified position.
Fl_Tree_Iteminsert_above (Fl_Tree_Item *above, const char *name)
 Inserts a new item above the specified Fl_Tree_Item, with the label set to 'name'.
int is_close (Fl_Tree_Item *item) const
 See if the specified item is closed.
int is_close (const char *path) const
 See if item specified by path (eg: "Parent/child/item") is closed.
int is_open (Fl_Tree_Item *item) const
 See if item is open.
int is_open (const char *path) const
 See if item specified by path (eg: "Parent/child/item") is open.
int is_scrollbar (Fl_Widget *w)
 See if widget w is one of the Fl_Tree widget's scrollbars.
int is_selected (Fl_Tree_Item *item) const
 See if the specified item is selected.
int is_selected (const char *path)
 See if item specified by path (eg: "Parent/child/item") is selected.
Fl_Tree_Itemitem_clicked ()
 Return the item that was last clicked.
Fl_Color item_labelbgcolor (void) const
 Get the default label background color used for creating new items.
void item_labelbgcolor (Fl_Color val)
 Set the default label background color used for creating new items.
Fl_Color item_labelfgcolor (void) const
 Get the default label foreground color used for creating new items.
void item_labelfgcolor (Fl_Color val)
 Set the default label foreground color used for creating new items.
void item_labelfont (Fl_Font val)
 Set the default font face used for creating new items.
Fl_Font item_labelfont () const
 Get the default font face used for creating new items.
void item_labelsize (Fl_Fontsize val)
 Set the default label font size used for creating new items.
Fl_Fontsize item_labelsize () const
 Get the default label fontsize used for creating new items.
int item_pathname (char *pathname, int pathnamelen, const Fl_Tree_Item *item) const
 Find the pathname for the specified item.
Fl_Tree_Itemlast ()
 Returns the last item in the tree.
void load (class Fl_Preferences &)
 Load FLTK preferences.
int marginleft () const
 Get the amount of white space (in pixels) that should appear between the widget's left border and the tree's contents.
void marginleft (int val)
 Set the amount of white space (in pixels) that should appear between the widget's left border and the left side of the tree's contents.
void margintop (int val)
 Sets the amount of white space (in pixels) that should appear between the widget's top border and the top of the tree's contents.
int margintop () const
 Get the amount of white space (in pixels) that should appear between the widget's top border and the top of the tree's contents.
Fl_Tree_Itemnext (Fl_Tree_Item *item=0)
 Return the next item after item, or 0 if no more items.
Fl_Tree_Itemnext_selected_item (Fl_Tree_Item *item=0)
 Returns the next selected item after item.
int open (Fl_Tree_Item *item, int docallback=1)
 Open the specified 'item'.
int open (const char *path, int docallback=1)
 Opens the item specified by path (eg: "Parent/child/item").
void open_toggle (Fl_Tree_Item *item, int docallback=1)
 Toggle the open state of item.
int openchild_marginbottom () const
 Get the amount of white space (in pixels) that should appear below an open child tree's contents.
void openchild_marginbottom (int val)
 Set the amount of white space (in pixels) that should appear below an open child tree's contents.
Fl_Imageopenicon () const
 Returns the icon to be used as the 'open' icon.
void openicon (Fl_Image *val)
 Sets the icon to be used as the 'open' icon.
Fl_Tree_Itemprev (Fl_Tree_Item *item=0)
 Return the previous item before item, or 0 if no more items.
int remove (Fl_Tree_Item *item)
 Remove the specified item from the tree.
Fl_Tree_Itemroot ()
 Returns the root item.
void root_label (const char *new_label)
 Set the label for the root item.
void scrollbar_size (int size)
 Sets the pixel size of the scrollbars' troughs to the size, in pixels.
int scrollbar_size () const
 Gets the current size of the scrollbars' troughs, in pixels.
int select (Fl_Tree_Item *item, int docallback=1)
 Select the specified item.
int select (const char *path, int docallback=1)
 Select the item specified by path (eg: "Parent/child/item").
int select_all (Fl_Tree_Item *item=0, int docallback=1)
 Select item and all its children.
int select_only (Fl_Tree_Item *selitem, int docallback=1)
 Select only the specified item, deselecting all others that might be selected.
void select_toggle (Fl_Tree_Item *item, int docallback=1)
 Toggle the select state of the specified item.
Fl_Boxtype selectbox () const
 Sets the style of box used to draw selected items.
void selectbox (Fl_Boxtype val)
 Gets the style of box used to draw selected items.
void selectmode (Fl_Tree_Select val)
 Sets the tree's selection mode.
Fl_Tree_Select selectmode () const
 Gets the tree's current selection mode.
void set_item_focus (Fl_Tree_Item *o)
 Set the item that currently should have keyboard focus.
void show_item (Fl_Tree_Item *item)
 Adjust the vertical scroll bar to show item at the top of the display IF it is currently off-screen (eg.
void show_item (Fl_Tree_Item *item, int yoff)
 Adjust the vertical scroll bar so that item is visible yoff pixels from the top of the Fl_Tree widget's display.
void show_item_bottom (Fl_Tree_Item *item)
 Adjust the vertical scrollbar so that item is at the bottom of the display.
void show_item_middle (Fl_Tree_Item *item)
 Adjust the vertical scrollbar so that item is in the middle of the display.
void show_item_top (Fl_Tree_Item *item)
 Adjust the vertical scrollbar so that item is at the top of the display.
void show_self ()
 Print the tree as 'ascii art' to stdout.
int showcollapse () const
 Returns 1 if the collapse icon is enabled, 0 if not.
void showcollapse (int val)
 Set if we should show the collapse icon or not.
int showroot () const
 Returns 1 if the root item is to be shown, or 0 if not.
void showroot (int val)
 Set if the root item should be shown or not.
void sortorder (Fl_Tree_Sort val)
 Gets the sort order used to add items to the tree.
Fl_Tree_Sort sortorder () const
 Set the default sort order used when items are added to the tree.
Fl_Imageusericon () const
 Returns the Fl_Image being used as the default user icon for all newly created items.
void usericon (Fl_Image *val)
 Sets the Fl_Image to be used as the default user icon for all newly created items.
void vposition (int ypos)
 Sets the vertical scroll offset to position pos.
int vposition () const
 Returns the vertical scroll position as a pixel offset.
 ~Fl_Tree ()
 Destructor.

Protected Member Functions

void do_callback_for_item (Fl_Tree_Item *item, Fl_Tree_Reason reason)
 Do the callback for the item, setting the item and reason.
void item_clicked (Fl_Tree_Item *val)
 Set the item that was last clicked.
Fl_Tree_Itemnext_visible_item (Fl_Tree_Item *start, int dir)
 Returns next visible item above (dir==Fl_Up) or below (dir==Fl_Down) the specified item.

Protected Attributes

Fl_Scrollbar_vscroll
 Vertical scrollbar.

Detailed Description

Tree widget.

tree-simple.png
Fl_Tree example program
     Fl_Tree                                         // Top level widget
        |--- Fl_Tree_Item                            // Items in the tree
        |--- Fl_Tree_Prefs                           // Preferences for the tree
                  |--- Fl_Tree_Connector (enum)      // Connection modes
                  |--- Fl_Tree_Select (enum)         // Selection modes
                  |--- Fl_Tree_Sort (enum)           // Sort behavior

Similar to Fl_Browser, Fl_Tree is a browser of Fl_Tree_Item's, which is arranged in a parented hierarchy, or 'tree'. Subtrees can be expanded or closed. Items can be added, deleted, inserted, sorted and re-ordered.

The tree items may also contain other FLTK widgets, like buttons, input fields, or even "custom" widgets.

The callback() is invoked depending on the value of when():

  • FL_WHEN_RELEASE -- callback invoked when left mouse button is released on an item
  • FL_WHEN_CHANGED -- callback invoked when left mouse changes selection state

The simple way to define a tree:

    #include <FL/Fl_Tree.H>
    [..]
    Fl_Tree tree(X,Y,W,H);
    tree.begin();
      tree.add("Flintstones/Fred");
      tree.add("Flintstones/Wilma");
      tree.add("Flintstones/Pebbles");
      tree.add("Simpsons/Homer");
      tree.add("Simpsons/Marge");
      tree.add("Simpsons/Bart");
      tree.add("Simpsons/Lisa");
    tree.end();

Items can be added with add(), removed with remove(), completely cleared with clear(), inserted with insert() and insert_above(), selected/deselected with select() and deselect(), open/closed with open() and closed(). Children of an item can be swapped around with Fl_Tree_Item::swap_children(), sorting can be controlled when items are add()ed via sortorder(). You can walk the entire tree with first() and next(). You can walk selected items with first_selected_item() and next_selected_item(). Items can be found by their pathname using find_item(const char*), and an item's pathname can be found with item_pathname(). The selected items' colors are controlled by selection_color() (inherited from Fl_Widget).

The tree can have different selection behaviors controlled by selectmode().

FLTK widgets (including custom widgets) can be assigned to tree items via Fl_Tree_Item::widget().

Icons for individual items can be changed with Fl_Tree_Item::openicon(), Fl_Tree_Item::closeicon(), Fl_Tree_Item::usericon().

Various default preferences can be globally manipulated via Fl_Tree_Prefs, including colors, margins, icons, connection lines.

The tree's callback() will be invoked when items change state or are open/closed. when() controls when mouse/keyboard events invoke the callback. callback_item() and callback_reason() can be used to determine the cause of the callback.

To walk all the items of the tree from top to bottom:

 // Walk all the items in the tree, and print their labels
 for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
     printf("Item: %s\n", item->label());
 }

To recursively walk all the children of a particular item, define a function that uses recursion:

 // Find all of the item's children and print an indented report of their labels
 void my_print_all_children(Fl_Tree_Item *item, int indent=0) {
     for ( int t=0; t<item->children(); t++ ) {
         printf("%*s Item: %s\n", indent, "", item->child(t)->label());
         my_print_all_children(item->child(t), indent+4);   // recurse
     }
 }

To change the default label font and color for creating new items:

  tree = new Fl_Tree(..);
  tree->item_labelfont(FL_COURIER);     // Use Courier font for all new items
  tree->item_labelfgcolor(FL_RED);      // Use red color for labels of all new items
  [..]
  // Now create the items in the tree using the above defaults.
  tree->add("Aaa");
  tree->add("Bbb");
  [..]

To change the font and color of all items in the tree:

 // Change the font and color of all items currently in the tree
 for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
     item->labelfont(FL_COURIER);
     item->labelcolor(FL_RED);
 }

The following image shows the tree's various visual elements and the methods that control them:

tree-elements.png

Member Function Documentation

Fl_Tree_Item * Fl_Tree::add ( const char *  path)

Adds a new item, given a 'menu style' path, eg: "/Parent/Child/item".

Any parent nodes that don't already exist are created automatically. Adds the item based on the value of sortorder().

Returns:
the child item created, or 0 on error.
Fl_Tree_Item * Fl_Tree::add ( Fl_Tree_Item item,
const char *  name 
)

Add a new child to a tree-item.

Parameters:
[in]itemThe existing item to add new child to. Must not be NULL.
[in]nameThe label for the new item
Returns:
the item that was added.
void Fl_Tree::callback_item ( Fl_Tree_Item item) [inline]

Sets the item that was changed for this callback.

Used internally to pass the item that invoked the callback.

Fl_Tree_Item* Fl_Tree::callback_item ( ) [inline]

Gets the item that caused the callback.

The callback() can use this value to see which item changed.

void Fl_Tree::callback_reason ( Fl_Tree_Reason  reason) [inline]

Sets the reason for this callback.

Used internally to pass the reason the callback was invoked.

Fl_Tree_Reason Fl_Tree::callback_reason ( ) const [inline]

Gets the reason for this callback.

The callback() can use this value to see why it was called. Example:

     void MyTreeCallback(Fl_Widget *w, void *userdata) {
         Fl_Tree *tree = (Fl_Tree*)w;
         Fl_Tree_Item *item = tree->callback_item();    // the item changed (can be NULL if more than one item was changed!)
         switch ( tree->callback_reason() ) {           // reason callback was invoked
             case     FL_TREE_REASON_OPENED: ..item was opened..
             case     FL_TREE_REASON_CLOSED: ..item was closed..
             case   FL_TREE_REASON_SELECTED: ..item was selected..
             case FL_TREE_REASON_DESELECTED: ..item was deselected..
         }
     }
void Fl_Tree::clear ( ) [inline]

Clear all children from the tree.

The tree will be left completely empty.

Reimplemented from Fl_Group.

void Fl_Tree::clear_children ( Fl_Tree_Item item) [inline]

Clear all the children of a particular node in the tree specified by item.

Item may not be NULL.

int Fl_Tree::close ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

Closes the specified item.

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item to be closed. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 -- item was closed
  • 0 -- item was already closed, no change
See also:
open(), close(), is_open(), is_close(), callback_item(), callback_reason()
int Fl_Tree::close ( const char *  path,
int  docallback = 1 
) [inline]

Closes the item specified by path, eg: "Parent/child/item".

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 -- OK: item closed
  • 0 -- OK: item was already closed, no change
  • -1 -- ERROR: item was not found
See also:
open(), close(), is_open(), is_close(), callback_item(), callback_reason()
Fl_Image* Fl_Tree::closeicon ( ) const [inline]

Returns the icon to be used as the 'close' icon.

If none was set, the internal default is returned, a simple '[-]' icon.

void Fl_Tree::closeicon ( Fl_Image val) [inline]

Sets the icon to be used as the 'close' icon.

This overrides the built in default '[-]' icon.

Parameters:
[in]val-- The new image, or zero to use the default [-] icon.
int Fl_Tree::deselect ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

De-select the specified item.

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item to be selected. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 0 - item was already deselected, no change was made
  • 1 - item's state was changed
int Fl_Tree::deselect ( const char *  path,
int  docallback = 1 
) [inline]

Deselect an item specified by path (eg: "Parent/child/item").

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 - OK: item's state was changed
  • 0 - OK: item was already deselected, no change was made
  • -1 - ERROR: item was not found
int Fl_Tree::deselect_all ( Fl_Tree_Item item = 0,
int  docallback = 1 
)

Deselect item and all its children.

If item is NULL, first() is used. Handles calling redraw() if anything was changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]itemThe item that will be deselected (along with all its children). If NULL, first() is used.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
count of how many items were actually changed to the deselected state.
void Fl_Tree::display ( Fl_Tree_Item item)

Displays item, scrolling the tree as necessary.

Parameters:
[in]itemThe item to be displayed. If NULL, first() is used.
int Fl_Tree::displayed ( Fl_Tree_Item item)

See if item is currently displayed on-screen (visible within the widget).

This can be used to detect if the item is scrolled off-screen. Checks to see if the item's vertical position is within the top and bottom edges of the display window. This does NOT take into account the hide()/show() or open()/close() status of the item.

Parameters:
[in]itemThe item to be checked. If NULL, first() is used.
Returns:
1 if displayed, 0 if scrolled off screen or no items are in tree.
const Fl_Tree_Item * Fl_Tree::find_clicked ( ) const

Find the item that was clicked.

You should use callback_item() instead, which is fast, and is meant to be used within a callback to determine the item clicked.

This method walks the entire tree looking for the first item that is under the mouse (ie. at Fl::event_x()/Fl:event_y().

Use this method /only/ if you've subclassed Fl_Tree, and are receiving events before Fl_Tree has been able to process and update callback_item().

Returns:
the item clicked, or 0 if no item was under the current event.
Fl_Tree_Item * Fl_Tree::find_item ( const char *  path)

Find the item, given a menu style path, eg: "/Parent/Child/item".

There is both a const and non-const version of this method. Const version allows pure const methods to use this method to do lookups without causing compiler errors.

Parameters:
[in]path-- the tree item's pathname to be found (eg. "Flintstones/Fred")
Returns:
the item, or NULL if not found.
See also:
item_pathname()
Fl_Tree_Item * Fl_Tree::first ( )

Returns the first item in the tree.

Use this to walk the tree in the forward direction, eg:

 for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
     printf("Item: %s\n", item->label());
 }
Returns:
first item in tree, or 0 if none (tree empty).
See also:
first(),next(),last(),prev()
Fl_Tree_Item * Fl_Tree::first_selected_item ( )

Returns the first selected item in the tree.

Use this to walk the tree looking for all the selected items, eg:

 for ( Fl_Tree_Item *item = tree->first_selected_item(); item; item = tree->next_selected_item(item) ) {
     printf("Item: %s\n", item->label());
 }
Returns:
The next selected item, or 0 if there are no more selected items.
Fl_Tree_Item * Fl_Tree::insert ( Fl_Tree_Item item,
const char *  name,
int  pos 
)

Insert a new item into a tree-item's children at a specified position.

Parameters:
[in]itemThe existing item to insert new child into. Must not be NULL.
[in]nameThe label for the new item
[in]posThe position of the new item in the child list
Returns:
the item that was added.
Fl_Tree_Item * Fl_Tree::insert_above ( Fl_Tree_Item above,
const char *  name 
)

Inserts a new item above the specified Fl_Tree_Item, with the label set to 'name'.

Parameters:
[in]above-- the item above which to insert the new item. Must not be NULL.
[in]name-- the name of the new item
Returns:
the item that was added, or 0 if 'above' could not be found.
int Fl_Tree::is_close ( Fl_Tree_Item item) const [inline]

See if the specified item is closed.

Parameters:
[in]item-- the item to be tested. Must not be NULL.
Returns:
  • 1 : item is open
  • 0 : item is closed
int Fl_Tree::is_close ( const char *  path) const [inline]

See if item specified by path (eg: "Parent/child/item") is closed.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
Returns:
  • 1 - OK: item is closed
  • 0 - OK: item is open
  • -1 - ERROR: item was not found
int Fl_Tree::is_open ( const char *  path) const [inline]

See if item specified by path (eg: "Parent/child/item") is open.

Items that are 'open' are themselves not necessarily visible; one of the item's parents might be closed.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
Returns:
  • 1 - OK: item is open
  • 0 - OK: item is closed
  • -1 - ERROR: item was not found
int Fl_Tree::is_open ( Fl_Tree_Item item) const [inline]

See if item is open.

Items that are 'open' are themselves not necessarily visible; one of the item's parents might be closed.

Parameters:
[in]item-- the item to be tested. Must not be NULL.
Returns:
  • 1 : item is open
  • 0 : item is closed
int Fl_Tree::is_scrollbar ( Fl_Widget w) [inline]

See if widget w is one of the Fl_Tree widget's scrollbars.

Use this to skip over the scrollbars when walking the child() array. Example:

 for ( int i=0; i<tree->children(); i++ ) {    // walk children
     Fl_Widget *w= tree->child(i);
     if ( brow->is_scrollbar(w) ) continue;    // skip scrollbars
     ..do work here..
 }
Parameters:
[in]wWidget to test
Returns:
1 if w is a scrollbar, 0 if not.
int Fl_Tree::is_selected ( Fl_Tree_Item item) const [inline]

See if the specified item is selected.

Parameters:
[in]item-- the item to be tested. Must not be NULL.
Returns:
  • 1 : item selected
  • 0 : item deselected
int Fl_Tree::is_selected ( const char *  path) [inline]

See if item specified by path (eg: "Parent/child/item") is selected.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
Returns:
  • 1 : item selected
  • 0 : item deselected
  • -1 : item was not found
void Fl_Tree::item_clicked ( Fl_Tree_Item val) [protected]

Set the item that was last clicked.

Should only be used by subclasses needing to change this value. Normally Fl_Tree manages this value.

Deprecated: use callback_item() instead.

Fl_Tree_Item* Fl_Tree::item_clicked ( ) [inline]

Return the item that was last clicked.

Valid only from within the callback().

Deprecated: use callback_item() instead.

Returns:
the item clicked, or 0 if none. 0 may also be used to indicate several items were clicked/changed.
void Fl_Tree::item_labelbgcolor ( Fl_Color  val) [inline]

Set the default label background color used for creating new items.

To change the background color on a per-item basis, use Fl_Tree_Item::labelbgcolor(Fl_Color)

void Fl_Tree::item_labelfgcolor ( Fl_Color  val) [inline]

Set the default label foreground color used for creating new items.

To change the foreground color on a per-item basis, use Fl_Tree_Item::labelfgcolor(Fl_Color)

void Fl_Tree::item_labelfont ( Fl_Font  val) [inline]

Set the default font face used for creating new items.

To change the font face on a per-item basis, use Fl_Tree_Item::labelfont(Fl_Font)

void Fl_Tree::item_labelsize ( Fl_Fontsize  val) [inline]

Set the default label font size used for creating new items.

To change the font size on a per-item basis, use Fl_Tree_Item::labelsize(Fl_Fontsize)

int Fl_Tree::item_pathname ( char *  pathname,
int  pathnamelen,
const Fl_Tree_Item item 
) const

Find the pathname for the specified item.

If item is NULL, root() is used. The tree's root will be included in the pathname of showroot() is on.

Parameters:
[in]pathnameThe string to use to return the pathname
[in]pathnamelenThe maximum length of the string (including NULL). Must not be zero.
[in]itemThe item whose pathname is to be returned.
Returns:
  • 0 : OK (pathname returns the item's pathname)
  • -1 : item not found (pathname="")
  • -2 : pathname not large enough (pathname="")
See also:
find_item()
Fl_Tree_Item * Fl_Tree::last ( )

Returns the last item in the tree.

This can be used to walk the tree in reverse, eg:

 for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() ) {
     printf("Item: %s\n", item->label());
 }
Returns:
last item in the tree, or 0 if none (tree empty).
See also:
first(),next(),last(),prev()
void Fl_Tree::load ( class Fl_Preferences prefs)

Load FLTK preferences.

Read a preferences database into the tree widget.

A preferences database is a hierarchical collection of data which can be directly loaded into the tree view for inspection.

Parameters:
[in]prefsthe Fl_Preferences database
Fl_Tree_Item * Fl_Tree::next ( Fl_Tree_Item item = 0)

Return the next item after item, or 0 if no more items.

Use this code to walk the entire tree:

 for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
     printf("Item: %s\n", item->label());
 }
Parameters:
[in]itemThe item to use to find the next item. If NULL, returns 0.
Returns:
Next item in tree, or 0 if at last item.
See also:
first(),next(),last(),prev()
Fl_Tree_Item * Fl_Tree::next_selected_item ( Fl_Tree_Item item = 0)

Returns the next selected item after item.

If item is 0, search starts at the first item (root).

Use this to walk the tree looking for all the selected items, eg:

 for ( Fl_Tree_Item *item = tree->first_selected_item(); item; item = tree->next_selected_item(item) ) {
     printf("Item: %s\n", item->label());
 }
Parameters:
[in]itemThe item to use to find the next selected item. If NULL, first() is used.
Returns:
The next selected item, or 0 if there are no more selected items.
Fl_Tree_Item * Fl_Tree::next_visible_item ( Fl_Tree_Item item,
int  dir 
) [protected]

Returns next visible item above (dir==Fl_Up) or below (dir==Fl_Down) the specified item.

If item is 0, returns first() if dir is Fl_Up, or last() if dir is FL_Down.

Parameters:
[in]itemThe item above/below which we'll find the next visible item
[in]dirThe direction to search. Can be FL_Up or FL_Down.
Returns:
The item found, or 0 if there's no visible items above/below the specified item.
int Fl_Tree::open ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

Open the specified 'item'.

This causes the item's children (if any) to be shown. Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item to be opened. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 -- item was opened
  • 0 -- item was already open, no change
See also:
open(), close(), is_open(), is_close(), callback_item(), callback_reason()
int Fl_Tree::open ( const char *  path,
int  docallback = 1 
) [inline]

Opens the item specified by path (eg: "Parent/child/item").

This causes the item's children (if any) to be shown. Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 -- OK: item opened
  • 0 -- OK: item was already open, no change
  • -1 -- ERROR: item was not found
See also:
open(), close(), is_open(), is_close(), callback_item(), callback_reason()
void Fl_Tree::open_toggle ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

Toggle the open state of item.

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item whose open state is to be toggled. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
See also:
open(), close(), is_open(), is_close(), callback_item(), callback_reason()
Fl_Image* Fl_Tree::openicon ( ) const [inline]

Returns the icon to be used as the 'open' icon.

If none was set, the internal default is returned, a simple '[+]' icon.

void Fl_Tree::openicon ( Fl_Image val) [inline]

Sets the icon to be used as the 'open' icon.

This overrides the built in default '[+]' icon.

Parameters:
[in]val-- The new image, or zero to use the default [+] icon.
Fl_Tree_Item * Fl_Tree::prev ( Fl_Tree_Item item = 0)

Return the previous item before item, or 0 if no more items.

This can be used to walk the tree in reverse, eg:

 for ( Fl_Tree_Item *item = tree->first(); item; item = tree->prev(item) ) {
     printf("Item: %s\n", item->label());
 }
Parameters:
[in]itemThe item to use to find the previous item. If NULL, returns 0.
Returns:
Previous item in tree, or 0 if at first item.
See also:
first(),next(),last(),prev()
int Fl_Tree::remove ( Fl_Tree_Item item) [inline]

Remove the specified item from the tree.

item may not be NULL. If it has children, all those are removed too.

Returns:
0 if done, -1 if 'item' not found.
void Fl_Tree::root_label ( const char *  new_label) [inline]

Set the label for the root item.

Makes an internally managed copy of 'new_label'.

void Fl_Tree::scrollbar_size ( int  size) [inline]

Sets the pixel size of the scrollbars' troughs to the size, in pixels.

Normally you should not need this method, and should use the global Fl::scrollbar_size(int) instead to manage the size of ALL your widgets' scrollbars. This ensures your application has a consistent UI, is the default behavior, and is normally what you want.

Only use THIS method if you really need to override the global scrollbar size. The need for this should be rare.

Setting size to the special value of 0 causes the widget to track the global Fl::scrollbar_size(), which is the default.

Parameters:
[in]sizeSets the scrollbar size in pixels.
If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()
See also:
Fl::scrollbar_size()
int Fl_Tree::scrollbar_size ( ) const [inline]

Gets the current size of the scrollbars' troughs, in pixels.

If this value is zero (default), this widget will use the global Fl::scrollbar_size() value as the scrollbar's width.

Returns:
Scrollbar size in pixels, or 0 if the global Fl::scrollsize() is being used.
See also:
Fl::scrollbar_size(int)
int Fl_Tree::select ( const char *  path,
int  docallback = 1 
) [inline]

Select the item specified by path (eg: "Parent/child/item").

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]path-- the tree item's pathname (eg. "Flintstones/Fred")
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 : OK: item's state was changed
  • 0 : OK: item was already selected, no change was made
  • -1 : ERROR: item was not found
int Fl_Tree::select ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

Select the specified item.

Use 'deselect()' to de-select it. Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item to be selected. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
  • 1 - item's state was changed
  • 0 - item was already selected, no change was made
int Fl_Tree::select_all ( Fl_Tree_Item item = 0,
int  docallback = 1 
)

Select item and all its children.

If item is NULL, first() is used. Handles calling redraw() if anything was changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]itemThe item that will be selected (along with all its children). If NULL, first() is used.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Returns:
count of how many items were actually changed to the selected state.
int Fl_Tree::select_only ( Fl_Tree_Item selitem,
int  docallback = 1 
)

Select only the specified item, deselecting all others that might be selected.

If item is 0, first() is used. Handles calling redraw() if anything was changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]selitemThe item to be selected. If NULL, first() is used.
[in]docallback-- A flag that determines if the callback() is invoked or not:
  • 0 - the callback() is not invoked
  • 1 - the callback() is invoked for each item that changed state, callback_reason() will be either FL_TREE_REASON_SELECTED or FL_TREE_REASON_DESELECTED
Returns:
the number of items whose selection states were changed, if any.
void Fl_Tree::select_toggle ( Fl_Tree_Item item,
int  docallback = 1 
) [inline]

Toggle the select state of the specified item.

Handles redrawing if anything was actually changed. Invokes the callback depending on the value of optional parameter docallback.

The callback can use callback_item() and callback_reason() respectively to determine the item changed and the reason the callback was called.

Parameters:
[in]item-- the item to be selected. Must not be NULL.
[in]docallback-- A flag that determines if the callback() is invoked or not:
Fl_Boxtype Fl_Tree::selectbox ( ) const [inline]

Sets the style of box used to draw selected items.

This is an fltk Fl_Boxtype. The default is influenced by FLTK's current Fl::scheme()

void Fl_Tree::selectbox ( Fl_Boxtype  val) [inline]

Gets the style of box used to draw selected items.

This is an fltk Fl_Boxtype. The default is influenced by FLTK's current Fl::scheme()

void Fl_Tree::set_item_focus ( Fl_Tree_Item item)

Set the item that currently should have keyboard focus.

Handles calling redraw() to update the focus box (if its visible).

Parameters:
[in]itemThe item that should take focus. If NULL, none will have focus.
void Fl_Tree::show_item ( Fl_Tree_Item item)

Adjust the vertical scroll bar to show item at the top of the display IF it is currently off-screen (eg.

show_item_top()). If it is already on-screen, no change is made.

Parameters:
[in]itemThe item to be shown. If NULL, first() is used.
See also:
show_item_top(), show_item_middle(), show_item_bottom()
void Fl_Tree::show_item ( Fl_Tree_Item item,
int  yoff 
)

Adjust the vertical scroll bar so that item is visible yoff pixels from the top of the Fl_Tree widget's display.

For instance, yoff=0 will position the item at the top.

If yoff is larger than the vertical scrollbar's limit, the value will be clipped. So if yoff=100, but scrollbar's max is 50, then 50 will be used.

Parameters:
[in]itemThe item to be shown. If NULL, first() is used.
[in]yoffThe pixel offset from the top for the displayed position.
See also:
show_item_top(), show_item_middle(), show_item_bottom()
void Fl_Tree::show_item_bottom ( Fl_Tree_Item item)

Adjust the vertical scrollbar so that item is at the bottom of the display.

Parameters:
[in]itemThe item to be shown. If NULL, first() is used.
void Fl_Tree::show_item_middle ( Fl_Tree_Item item)

Adjust the vertical scrollbar so that item is in the middle of the display.

Parameters:
[in]itemThe item to be shown. If NULL, first() is used.
void Fl_Tree::show_item_top ( Fl_Tree_Item item)

Adjust the vertical scrollbar so that item is at the top of the display.

Parameters:
[in]itemThe item to be shown. If NULL, first() is used.
void Fl_Tree::show_self ( ) [inline]

Print the tree as 'ascii art' to stdout.

Used mainly for debugging.

void Fl_Tree::showcollapse ( int  val) [inline]

Set if we should show the collapse icon or not.

If collapse icons are disabled, the user will not be able to interactively collapse items in the tree, unless the application provides some other means via open() and close().

Parameters:
[in]val1: shows collapse icons (default),
0: hides collapse icons.
void Fl_Tree::showroot ( int  val) [inline]

Set if the root item should be shown or not.

Parameters:
[in]val1 -- show the root item (default)
0 -- hide the root item.
Fl_Tree_Sort Fl_Tree::sortorder ( ) const [inline]

Set the default sort order used when items are added to the tree.

See Fl_Tree_Sort for possible values.

void Fl_Tree::usericon ( Fl_Image val) [inline]

Sets the Fl_Image to be used as the default user icon for all newly created items.

If you want to specify user icons on a per-item basis, use Fl_Tree_Item::usericon() instead.

Parameters:
[in]val-- The new image to be used, or zero to disable user icons.
Fl_Image* Fl_Tree::usericon ( ) const [inline]

Returns the Fl_Image being used as the default user icon for all newly created items.

Returns zero if no icon has been set, which is the default.

int Fl_Tree::vposition ( ) const

Returns the vertical scroll position as a pixel offset.

The position returned is how many pixels of the tree are scrolled off the top edge of the screen. Example: A position of '3' indicates the top 3 pixels of the tree are scrolled off the top edge of the screen.

See also:
vposition(), hposition()
void Fl_Tree::vposition ( int  pos)

Sets the vertical scroll offset to position pos.

The position is how many pixels of the tree are scrolled off the top edge of the screen. Example: A position of '3' scrolls the top three pixels of the tree off the top edge of the screen.

Parameters:
[in]posThe vertical position (in pixels) to scroll the browser to.

The documentation for this class was generated from the following files: