Fl_Tree

Hierarchical tree widget with expandable/collapsible items

Overview

The Fl_Tree widget displays a hierarchical tree of items that can be expanded or collapsed. Items can contain other FLTK widgets, support drag-and-drop, and have custom icons.

Constructor

Fl_Tree · constructor

Creates a new tree widget.

X · int · required

X position of the widget

Y · int · required

Y position of the widget

W · int · required

Width of the widget

H · int · required

Height of the widget

L · const char* · default: "0"

Optional label for the widget

Item Management

add · Fl_Tree_Item*

Adds an item to the tree using a path string.

path · const char* · required

Path to the item (e.g., “Parent/Child/Item”)

newitem · Fl_Tree_Item* · default: "0"

Optional pre-created item to add

Returns pointer to the added item.

insert · Fl_Tree_Item*

Inserts an item at a specific position.

item · Fl_Tree_Item* · required

Parent item

name · const char* · required

Name of the new item

pos · int · required

Position to insert at

Returns pointer to the inserted item.

insert_above · Fl_Tree_Item*

Inserts an item above another item.

above · Fl_Tree_Item* · required

Item to insert above

name · const char* · required

Name of the new item

Returns pointer to the inserted item.

remove · int

Removes an item from the tree.

item · Fl_Tree_Item* · required

Item to remove

Returns 0 on success, -1 on error.

clear · void

Removes all items from the tree.

clear_children · void

Removes all children of an item.

item · Fl_Tree_Item* · required

Parent item whose children to clear

Finding Items

find_item · Fl_Tree_Item*

Finds an item by its path.

path · const char* · required

Path to find (e.g., “Parent/Child”)

Returns pointer to item, or NULL if not found.

item_pathname · int

Gets the pathname for an item.

pathname · char* · required

Buffer to store pathname

pathnamelen · int · required

Size of pathname buffer

item · const Fl_Tree_Item* · required

Item to get path for

Returns 0 on success.

first · Fl_Tree_Item*

Returns the first item in the tree.

next · Fl_Tree_Item*

Returns the next item after the specified item.

item · Fl_Tree_Item* · default: "0"

Item to get next from (NULL for first)

prev · Fl_Tree_Item*

Returns the previous item before the specified item.

item · Fl_Tree_Item* · default: "0"

Item to get previous from

last · Fl_Tree_Item*

Returns the last item in the tree.

Opening/Closing

open · int

Opens an item (shows its children).

item · Fl_Tree_Item* · required

Item to open

docallback · int · default: "1"

Whether to invoke callback

Returns 1 if item was opened, 0 if already open.

close · int

Closes an item (hides its children).

item · Fl_Tree_Item* · required

Item to close

docallback · int · default: "1"

Whether to invoke callback

Returns 1 if item was closed, 0 if already closed.

is_open · int

Checks if an item is open.

item · Fl_Tree_Item* · required

Item to check

Returns 1 if open, 0 if closed.

is_close · int

Checks if an item is closed.

item · Fl_Tree_Item* · required

Item to check

Returns 1 if closed, 0 if open.

Selection

select · int

Selects an item.

item · Fl_Tree_Item* · required

Item to select

docallback · int · default: "1"

Whether to invoke callback

Returns 1 if state changed.

deselect · int

Deselects an item.

item · Fl_Tree_Item* · required

Item to deselect

docallback · int · default: "1"

Whether to invoke callback

Returns 1 if state changed.

select_all · int

Selects all items in the tree.

item · Fl_Tree_Item* · default: "0"

Root item (NULL for all)

docallback · int · default: "1"

Whether to invoke callback

Returns count of items selected.

deselect_all · int

Deselects all items in the tree.

item · Fl_Tree_Item* · default: "0"

Root item (NULL for all)

docallback · int · default: "1"

Whether to invoke callback

Returns count of items deselected.

select_only · int

Selects only the specified item, deselecting all others.

selitem · Fl_Tree_Item* · required

Item to select

docallback · int · default: "1"

Whether to invoke callback

is_selected · int

Checks if an item is selected.

item · Fl_Tree_Item* · required

Item to check

Returns 1 if selected, 0 otherwise.

first_selected_item · Fl_Tree_Item*

Returns the first selected item in the tree.

next_selected_item · Fl_Tree_Item*

Returns the next selected item after the specified item.

item · Fl_Tree_Item* · default: "0"

Item to get next from

dir · int · default: "FL_Down"

Direction (FL_Down or FL_Up)

Display Control

show_item · void

Scrolls the tree to make an item visible.

item · Fl_Tree_Item* · required

Item to show

show_item_top · void

Scrolls item to the top of the display.

item · Fl_Tree_Item* · required

Item to show at top

show_item_middle · void

Scrolls item to the middle of the display.

item · Fl_Tree_Item* · required

Item to show in middle

show_item_bottom · void

Scrolls item to the bottom of the display.

item · Fl_Tree_Item* · required

Item to show at bottom

vposition · int

Gets or sets the vertical scroll position.

pos · int · required

Scroll position in pixels

Appearance

item_labelfont · void

Sets the default font for item labels.

val · Fl_Font · required

Font face

item_labelsize · void

Sets the default font size for item labels.

val · Fl_Fontsize · required

Font size

item_labelfgcolor · void

Sets the default foreground color for item labels.

val · Fl_Color · required

Foreground color

item_labelbgcolor · void

Sets the default background color for item labels.

val · Fl_Color · required

Background color (0xffffffff for transparent)

connectorcolor · void

Sets the color of the connector lines.

val · Fl_Color · required

Connector color

selectmode · void

Sets the selection mode.

val · Fl_Tree_Select · required

Selection mode (NONE, SINGLE, MULTI, SINGLE_DRAGGABLE)

Callbacks

callback_item · Fl_Tree_Item*

Returns the item that triggered the callback.

callback_reason · Fl_Tree_Reason

Returns why the callback was invoked:

• FL_TREE_REASON_SELECTED
• FL_TREE_REASON_DESELECTED
• FL_TREE_REASON_OPENED
• FL_TREE_REASON_CLOSED
• FL_TREE_REASON_DRAGGED

Example

#include <FL/Fl_Tree.H>
#include <FL/Fl_Window.H>

void tree_callback(Fl_Widget *w, void *) {
  Fl_Tree *tree = (Fl_Tree*)w;
  Fl_Tree_Item *item = tree->callback_item();
  if (!item) return;
  
  switch (tree->callback_reason()) {
    case FL_TREE_REASON_SELECTED:
      printf("Item '%s' selected\n", item->label());
      break;
    case FL_TREE_REASON_OPENED:
      printf("Item '%s' opened\n", item->label());
      break;
  }
}

int main() {
  Fl_Window *win = new Fl_Window(400, 300);
  Fl_Tree *tree = new Fl_Tree(10, 10, 380, 280);
  
  tree->callback(tree_callback);
  tree->begin();
  
  // Add items
  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();
  win->end();
  win->show();
  return Fl::run();
}

Walking the Tree

// Walk all items top to bottom
for (Fl_Tree_Item *item = tree->first(); item; item = tree->next(item)) {
  printf("Item: %s\n", item->label());
}

// Walk only selected items
for (Fl_Tree_Item *item = tree->first_selected_item(); 
     item; 
     item = tree->next_selected_item(item)) {
  printf("Selected: %s\n", item->label());
}

See Also

• Fl_Tree_Item - Individual tree items
• Fl_Tree_Prefs - Tree appearance preferences