FLTK: Fl_Tree Class Reference

FLTK

Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
Fl_Tree Class Reference

Tree widget. More...

`#include <Fl_Tree.H>`

Inheritance diagram for Fl_Tree:

## Public Member Functions
Fl_Tree_Item * | add (const char *path, Fl_Tree_Item *newitem=0)
| Adds a new item, given a menu style `'path'`. More...
Fl_Tree_Item * | add (Fl_Tree_Item *parent_item, const char *name)
| Add a new child item labeled `'name'` to the specified `'parent_item'`. More...
void | calc_dimensions ()
| Recalculate widget dimensions and scrollbar visibility, normally managed automatically. More...
void | calc_tree ()
| Recalculates the tree's sizes and scrollbar visibility, normally managed automatically. More...
Fl_Tree_Item * | callback_item ()
| Gets the item that caused the callback. More...
void | callback_item (Fl_Tree_Item *item)
| Sets the item that was changed for this callback. More...
Fl_Tree_Reason | callback_reason () const
| Gets the reason for this callback. More...
void | callback_reason (Fl_Tree_Reason reason)
| Sets the reason for this callback. More...
void | clear ()
| Clear the entire tree's children, including the root. More...
void | clear_children (Fl_Tree_Item *item)
| Clear all the children for `'item'`. More...
int | close (const char *path, int docallback=1)
| Closes the item specified by `'path'`. More...
int | close (Fl_Tree_Item *item, int docallback=1)
| Closes the specified `'item'`. More...
Fl_Image * | closeicon () const
| Returns the icon to be used as the 'close' icon. More...
void | closeicon (Fl_Image *val)
| Sets the icon to be used as the 'close' icon. More...
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. More...
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 (const char *path, int docallback=1)
| Deselect an item specified by `'path'`. More...
int | deselect (Fl_Tree_Item *item, int docallback=1)
| Deselect the specified `item`. More...
int | deselect_all (Fl_Tree_Item *item=0, int docallback=1)
| Deselect `'item'` and all its children. More...
void | display (Fl_Tree_Item *item)
| Displays `'item'`, scrolling the tree as necessary. More...
int | displayed (Fl_Tree_Item *item)
| See if `'item'` is currently displayed on-screen (visible within the widget). More...
void | draw ()
| Standard FLTK draw() method, handles drawing the tree widget.
int | extend_selection (Fl_Tree_Item *from, Fl_Tree_Item *to, int val=1, bool visible=false)
| Extend a selection between `'from'` and `'to'` depending on `'visible'`. More...
int | extend_selection_dir (Fl_Tree_Item *from, Fl_Tree_Item *to, int dir, int val, bool visible)
| Extend the selection between and including `'from'` and `'to'` depending on direction `'dir'`, `'val'`, and `'visible'`. More...
Fl_Tree_Item * | find_clicked (int yonly=0)
| Non-const version of Fl_Tree::find_clicked(int yonly) const.
const Fl_Tree_Item * | find_clicked (int yonly=0) const
| Find the item that was last clicked on. More...
Fl_Tree_Item * | find_item (const char *path)
| Non-const version of Fl_Tree::find_item(const char *path) const.
const Fl_Tree_Item * | find_item (const char *path) const
| Find the item, given a menu style path, e.g. More...
Fl_Tree_Item * | first ()
| Returns the first item in the tree, or 0 if none. More...
Fl_Tree_Item * | first_selected_item ()
| Returns the first selected item in the tree. More...
Fl_Tree_Item * | first_visible ()
| Returns the first open(), visible item in the tree, or 0 if none. More...
Fl_Tree_Item * | first_visible_item ()
| Returns the first open(), visible item in the tree, or 0 if none. More...
| Fl_Tree (int X, int Y, int W, int H, const char *L=0)
| Constructor.
Fl_Tree_Item * | get_item_focus () const
| Get the item that currently has keyboard focus.
int | get_selected_items (Fl_Tree_Item_Array &ret_items)
| Returns the currently selected items as an array of `'ret_items'`. More...
int | handle (int e)
| Standard FLTK event handler for this widget. More...
int | hposition () const
| Returns the horizontal scroll position as a pixel offset. More...
void | hposition (int pos)
| Sets the horizontal scroll offset to position `'pos'`. More...
Fl_Tree_Item * | insert (Fl_Tree_Item *item, const char *name, int pos)
| Insert a new item `'name'` into `'item's` children at position `'pos'`. More...
Fl_Tree_Item * | insert_above (Fl_Tree_Item *above, const char *name)
| Inserts a new item `'name'` above the specified Fl_Tree_Item `'above'`. More...
int | is_close (const char *path) const
| See if item specified by `'path'` is closed. More...
int | is_close (Fl_Tree_Item *item) const
| See if the specified `'item'` is closed. More...
int | is_hscroll_visible () const
| See if the horizontal scrollbar is currently visible. More...
int | is_open (const char *path) const
| See if item specified by `'path'` is open. More...
int | is_open (Fl_Tree_Item *item) const
| See if `'item'` is open. More...
int | is_scrollbar (Fl_Widget *w)
| See if widget `'w'` is one of the Fl_Tree widget's scrollbars. More...
int | is_selected (const char *path)
| See if item specified by `'path'` is selected. More...
int | is_selected (Fl_Tree_Item *item) const
| See if the specified `'item'` is selected. More...
int | is_vscroll_visible () const
| See if the vertical scrollbar is currently visible. More...
Fl_Tree_Item * | item_clicked ()
| Return the item that was last clicked. More...
Fl_Tree_Item_Draw_Mode | item_draw_mode () const
| Get the 'item draw mode' used for the tree. More...
void | item_draw_mode (Fl_Tree_Item_Draw_Mode mode)
| Set the 'item draw mode' used for the tree to `'mode'`. More...
void | item_draw_mode (int mode)
| Set the 'item draw mode' used for the tree to integer `'mode'`. More...
void | item_labelbgcolor (Fl_Color val)
| Set the default label background color used for creating new items. More...
Fl_Color | item_labelbgcolor (void) const
| Get the default label background color used for creating new items. More...
void | item_labelfgcolor (Fl_Color val)
| Set the default label foreground color used for creating new items. More...
Fl_Color | item_labelfgcolor (void) const
| Get the default label foreground color used for creating new items.
Fl_Font | item_labelfont () const
| Get the default font face used for creating new items.
void | item_labelfont (Fl_Font val)
| Set the default font face used for creating new items. More...
Fl_Fontsize | item_labelsize () const
| Get the default label fontsize used for creating new items.
void | item_labelsize (Fl_Fontsize val)
| Set the default label font size used for creating new items. More...
int | item_pathname (char *pathname, int pathnamelen, const Fl_Tree_Item *item) const
| Return `'pathname'` of size `'pathnamelen'` for the specified `'item'`. More...
Fl_Tree_Item_Reselect_Mode | item_reselect_mode () const
| Returns the current item re/selection mode. More...
void | item_reselect_mode (Fl_Tree_Item_Reselect_Mode mode)
| Sets the item re/selection mode. More...
int | labelmarginleft () const
| Get the amount of white space (in pixels) that should appear to the left of the label text.
void | labelmarginleft (int val)
| Set the amount of white space (in pixels) that should appear to the left of the label text.
Fl_Tree_Item * | last ()
| Returns the last item in the tree. More...
Fl_Tree_Item * | last_selected_item ()
| Returns the last selected item in the tree. More...
Fl_Tree_Item * | last_visible ()
| Returns the last open(), visible item in the tree. More...
Fl_Tree_Item * | last_visible_item ()
| Returns the last open(), visible item in the tree. More...
int | linespacing () const
| Get the amount of white space (in pixels) that should appear between items in the tree.
void | linespacing (int val)
| Sets the amount of white space (in pixels) that should appear between items in the tree.
void | load (class Fl_Preferences &)
| Load FLTK preferences. More...
int | marginbottom () const
| Get the amount of white space (in pixels) that should appear below the last visible item when the vertical scroller is scrolled to the bottom.
void | marginbottom (int val)
| Sets the amount of white space (in pixels) that should appear below the last visible item when the vertical scroller is scrolled to the bottom.
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.
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.
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.
Fl_Tree_Item * | next (Fl_Tree_Item *item=0)
| Return the next item after `'item'`, or 0 if no more items. More...
Fl_Tree_Item * | next_item (Fl_Tree_Item *item, int dir=FL_Down, bool visible=false)
| Returns next item after `'item'` in direction `'dir'` depending on `'visible'`. More...
Fl_Tree_Item * | next_selected_item (Fl_Tree_Item *item=0, int dir=FL_Down)
| Returns the next selected item above or below `'item'`, depending on `'dir'`. More...
Fl_Tree_Item * | next_visible_item (Fl_Tree_Item *start, int dir)
| Returns next open(), visible item above (`dir==FL_Up`) or below (`dir==FL_Down`) the specified `'item'`, or 0 if no more items. More...
int | open (const char *path, int docallback=1)
| Opens the item specified by `'path'`. More...
int | open (Fl_Tree_Item *item, int docallback=1)
| Open the specified `'item'`. More...
void | open_toggle (Fl_Tree_Item *item, int docallback=1)
| Toggle the open state of `'item'`. More...
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_Image * | openicon () const
| Returns the icon to be used as the 'open' icon. More...
void | openicon (Fl_Image *val)
| Sets the icon to be used as the 'open' icon. More...
const Fl_Tree_Prefs & | prefs () const
Fl_Tree_Item * | prev (Fl_Tree_Item *item=0)
| Return the previous item before `'item'`, or 0 if no more items. More...
void | recalc_tree ()
| Schedule tree to recalc the entire tree size. More...
int | remove (Fl_Tree_Item *item)
| Remove the specified `'item'` from the tree. More...
void | resize (int, int, int, int)
| Resizes the Fl_Group widget and all of its children. More...
Fl_Tree_Item * | root ()
| Returns the root item.
void | root (Fl_Tree_Item *newitem)
| Sets the root item to `'newitem'`. More...
void | root_label (const char *new_label)
| Set the label for the root item to `'new_label'`. More...
int | scrollbar_size () const
| Gets the default size of scrollbars' troughs for this widget in pixels. More...
void | scrollbar_size (int size)
| Sets the pixel size of the scrollbars' troughs to `'size'` for this widget, in pixels. More...
int | select (const char *path, int docallback=1)
| Select the item specified by `'path'`. More...
int | select (Fl_Tree_Item *item, int docallback=1)
| Select the specified `'item'`. More...
int | select_all (Fl_Tree_Item *item=0, int docallback=1)
| Select `'item'` and all its children. More...
int | select_only (Fl_Tree_Item *selitem, int docallback=1)
| Select only the specified item, deselecting all others that might be selected. More...
void | select_toggle (Fl_Tree_Item *item, int docallback=1)
| Toggle the select state of the specified `'item'`. More...
Fl_Boxtype | selectbox () const
| Sets the style of box used to draw selected items. More...
void | selectbox (Fl_Boxtype val)
| Gets the style of box used to draw selected items. More...
Fl_Tree_Select | selectmode () const
| Gets the tree's current selection mode. More...
void | selectmode (Fl_Tree_Select val)
| Sets the tree's selection mode. More...
void | set_item_focus (Fl_Tree_Item *item)
| Set the item that currently should have keyboard focus. More...
void | show_item (Fl_Tree_Item *item)
| Adjust the vertical scrollbar to show `'item'` at the top of the display IF it is currently off-screen (for instance show_item_top()). More...
void | show_item (Fl_Tree_Item *item, int yoff)
| Adjust the vertical scrollbar so that `'item'` is visible `'yoff'` pixels from the top of the Fl_Tree widget's display. More...
void | show_item_bottom (Fl_Tree_Item *item)
| Adjust the vertical scrollbar so that `'item'` is at the bottom of the display. More...
void | show_item_middle (Fl_Tree_Item *item)
| Adjust the vertical scrollbar so that `'item'` is in the middle of the display. More...
void | show_item_top (Fl_Tree_Item *item)
| Adjust the vertical scrollbar so that `'item'` is at the top of the display. More...
void | show_self ()
| Print the tree as 'ascii art' to stdout. More...
int | showcollapse () const
| Returns 1 if the collapse icon is enabled, 0 if not. More...
void | showcollapse (int val)
| Set if we should show the collapse icon or not. More...
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. More...
Fl_Tree_Sort | sortorder () const
| Set the default sort order used when items are added to the tree. More...
void | sortorder (Fl_Tree_Sort val)
| Gets the sort order used to add items to the tree.
Fl_Image * | usericon () const
| Returns the Fl_Image being used as the default user icon for all newly created items. More...
void | usericon (Fl_Image *val)
| Sets the Fl_Image to be used as the default user icon for all newly created items. More...
int | usericonmarginleft () const
| Get the amount of white space (in pixels) that should appear to the left of the usericon.
void | usericonmarginleft (int val)
| Set the amount of white space (in pixels) that should appear to the left of the usericon.
int | vposition () const
| Returns the vertical scroll position as a pixel offset. More...
void | vposition (int pos)
| Sets the vertical scroll offset to position `'pos'`. More...
int | widgetmarginleft () const
| Get the amount of white space (in pixels) that should appear to the left of the child fltk widget (if any).
void | widgetmarginleft (int val)
| Set the amount of white space (in pixels) that should appear to the left of the child fltk widget (if any).
| ~Fl_Tree ()
| Destructor.
Public Member Functions inherited from Fl_Group
Fl_Widget *& | _ddfdesign_kludge ()
| This is for forms compatibility only.
void | add (Fl_Widget &)
| The widget is removed from its current group (if any) and then added to the end of this group.
void | add (Fl_Widget *o)
| See void Fl_Group::add(Fl_Widget &w)
void | add_resizable (Fl_Widget &o)
| Adds a widget to the group and makes it the resizable widget.
Fl_Widget *const * | array () const
| Returns a pointer to the array of children. More...
virtual Fl_Group * | as_group ()
| Returns an Fl_Group pointer if this widget is an Fl_Group. More...
void | begin ()
| Sets the current group so you can build the widget tree by just constructing the widgets. More...
Fl_Widget * | child (int n) const
| Returns array()[n]. More...
int | children () const
| Returns how many child widgets the group has.
void | clear ()
| Deletes all child widgets from memory recursively. More...
unsigned int | clip_children ()
| Returns the current clipping mode. More...
void | clip_children (int c)
| Controls whether the group widget clips the drawing of child widgets to its bounding box. More...
void | end ()
| Exactly the same as current(this->parent()). More...
int | find (const Fl_Widget &o) const
| See int Fl_Group::find(const Fl_Widget *w) const.
int | find (const Fl_Widget *) const
| Searches the child array for the widget and returns the index. More...
| Fl_Group (int, int, int, int, const char *=0)
| Creates a new Fl_Group widget using the given position, size, and label string. More...
void | focus (Fl_Widget *W)
void | forms_end ()
| This is for forms compatibility only.
void | init_sizes ()
| Resets the internal array of widget sizes and positions. More...
void | insert (Fl_Widget &, int i)
| The widget is removed from its current group (if any) and then inserted into this group. More...
void | insert (Fl_Widget &o, Fl_Widget *before)
| This does insert(w, find(before)). More...
void | remove (Fl_Widget &)
| Removes a widget from the group but does not delete it. More...
void | remove (Fl_Widget *o)
| Removes the widget `o` from the group. More...
void | remove (int index)
| Removes the widget at `index` from the group but does not delete it. More...
Fl_Widget * | resizable () const
| See void Fl_Group::resizable(Fl_Widget *box)
void | resizable (Fl_Widget &o)
| See void Fl_Group::resizable(Fl_Widget *box)
void | resizable (Fl_Widget *o)
| The resizable widget defines the resizing box for the group. More...
virtual | ~Fl_Group ()
| The destructor also deletes all the children. More...
Public Member Functions inherited from Fl_Widget
void | _clear_fullscreen ()
void | _set_fullscreen ()
void | activate ()
| Activates the widget. More...
unsigned int | active () const
| Returns whether the widget is active. More...
int | active_r () const
| Returns whether the widget and all of its parents are active. More...
Fl_Align | align () const
| Gets the label alignment. More...
void | align (Fl_Align alignment)
| Sets the label alignment. More...
long | argument () const
| Gets the current user data (long) argument that is passed to the callback function. More...
void | argument (long v)
| Sets the current user data (long) argument that is passed to the callback function. More...
virtual class Fl_Gl_Window * | as_gl_window ()
| Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window. More...
virtual Fl_Window * | as_window ()
| Returns an Fl_Window pointer if this widget is an Fl_Window. More...
Fl_Boxtype | box () const
| Gets the box type of the widget. More...
void | box (Fl_Boxtype new_box)
| Sets the box type for the widget. More...
Fl_Callback_p | callback () const
| Gets the current callback function for the widget. More...
void | callback (Fl_Callback *cb)
| Sets the current callback function for the widget. More...
void | callback (Fl_Callback *cb, void *p)
| Sets the current callback function for the widget. More...
void | callback (Fl_Callback0 *cb)
| Sets the current callback function for the widget. More...
void | callback (Fl_Callback1 *cb, long p=0)
| Sets the current callback function for the widget. More...
unsigned int | changed () const
| Checks if the widget value changed since the last callback. More...
void | clear_active ()
| Marks the widget as inactive without sending events or changing focus. More...
void | clear_changed ()
| Marks the value of the widget as unchanged. More...
void | clear_damage (uchar c=0)
| Clears or sets the damage flags. More...
void | clear_output ()
| Sets a widget to accept input. More...
void | clear_visible ()
| Hides the widget. More...
void | clear_visible_focus ()
| Disables keyboard focus navigation with this widget. More...
Fl_Color | color () const
| Gets the background color of the widget. More...
void | color (Fl_Color bg)
| Sets the background color of the widget. More...
void | color (Fl_Color bg, Fl_Color sel)
| Sets the background and selection color of the widget. More...
Fl_Color | color2 () const
| For back compatibility only. More...
void | color2 (unsigned a)
| For back compatibility only. More...
int | contains (const Fl_Widget *w) const
| Checks if w is a child of this widget. More...
void | copy_label (const char *new_label)
| Sets the current label. More...
void | copy_tooltip (const char *text)
| Sets the current tooltip text. More...
uchar | damage () const
| Returns non-zero if draw() needs to be called. More...
void | damage (uchar c)
| Sets the damage bits for the widget. More...
void | damage (uchar c, int x, int y, int w, int h)
| Sets the damage bits for an area inside the widget. More...
int | damage_resize (int, int, int, int)
| Internal use only.
void | deactivate ()
| Deactivates the widget. More...
Fl_Image * | deimage ()
| Gets the image that is used as part of the widget label. More...
const Fl_Image * | deimage () const
void | deimage (Fl_Image &img)
| Sets the image to use as part of the widget label. More...
void | deimage (Fl_Image *img)
| Sets the image to use as part of the widget label. More...
void | do_callback ()
| Calls the widget callback. More...
void | do_callback (Fl_Widget *o, long arg)
| Calls the widget callback. More...
void | do_callback (Fl_Widget *o, void *arg=0)
| Calls the widget callback. More...
void | draw_label (int, int, int, int, Fl_Align) const
| Draws the label in an arbitrary bounding box with an arbitrary alignment. More...
int | h () const
| Gets the widget height. More...
virtual void | hide ()
| Makes a widget invisible. More...
Fl_Image * | image ()
| Gets the image that is used as part of the widget label. More...
const Fl_Image * | image () const
void | image (Fl_Image &img)
| Sets the image to use as part of the widget label. More...
void | image (Fl_Image *img)
| Sets the image to use as part of the widget label. More...
int | inside (const Fl_Widget *wgt) const
| Checks if this widget is a child of `wgt`. More...
int | is_label_copied () const
| Returns whether the current label was assigned with copy_label(). More...
const char * | label () const
| Gets the current label text. More...
void | label (const char *text)
| Sets the current label pointer. More...
void | label (Fl_Labeltype a, const char *b)
| Shortcut to set the label text and type in one call. More...
Fl_Color | labelcolor () const
| Gets the label color. More...
void | labelcolor (Fl_Color c)
| Sets the label color. More...
Fl_Font | labelfont () const
| Gets the font to use. More...
void | labelfont (Fl_Font f)
| Sets the font to use. More...
Fl_Fontsize | labelsize () const
| Gets the font size in pixels. More...
void | labelsize (Fl_Fontsize pix)
| Sets the font size in pixels. More...
Fl_Labeltype | labeltype () const
| Gets the label type. More...
void | labeltype (Fl_Labeltype a)
| Sets the label type. More...
void | measure_label (int &ww, int &hh) const
| Sets width ww and height hh accordingly with the label size. More...
unsigned int | output () const
| Returns if a widget is used for output only. More...
Fl_Group * | parent () const
| Returns a pointer to the parent widget. More...
void | parent (Fl_Group *p)
| Internal use only - "for hacks only". More...
void | position (int X, int Y)
| Repositions the window or widget. More...
void | redraw ()
| Schedules the drawing of the widget. More...
void | redraw_label ()
| Schedules the drawing of the label. More...
Fl_Color | selection_color () const
| Gets the selection color. More...
void | selection_color (Fl_Color a)
| Sets the selection color. More...
void | set_active ()
| Marks the widget as active without sending events or changing focus. More...
void | set_changed ()
| Marks the value of the widget as changed. More...
void | set_output ()
| Sets a widget to output only. More...
void | set_visible ()
| Makes the widget visible. More...
void | set_visible_focus ()
| Enables keyboard focus navigation with this widget. More...
virtual void | show ()
| Makes a widget visible. More...
void | size (int W, int H)
| Changes the size of the widget. More...
int | take_focus ()
| Gives the widget the keyboard focus. More...
unsigned int | takesevents () const
| Returns if the widget is able to take events. More...
int | test_shortcut ()
| Returns true if the widget's label contains the entered '&x' shortcut. More...
const char * | tooltip () const
| Gets the current tooltip text. More...
void | tooltip (const char *text)
| Sets the current tooltip text. More...
Fl_Window * | top_window () const
| Returns a pointer to the top-level window for the widget. More...
Fl_Window * | top_window_offset (int &xoff, int &yoff) const
| Finds the x/y offset of the current widget relative to the top-level window. More...
uchar | type () const
| Gets the widget type. More...
void | type (uchar t)
| Sets the widget type. More...
int | use_accents_menu ()
| Returns non zero if MAC_USE_ACCENTS_MENU flag is set, 0 otherwise.
void * | user_data () const
| Gets the user data for this widget. More...
void | user_data (void *v)
| Sets the user data for this widget. More...
unsigned int | visible () const
| Returns whether a widget is visible. More...
unsigned int | visible_focus ()
| Checks whether this widget has a visible focus. More...
void | visible_focus (int v)
| Modifies keyboard focus navigation. More...
int | visible_r () const
| Returns whether a widget and all its parents are visible. More...
int | w () const
| Gets the widget width. More...
Fl_When | when () const
| Returns the conditions under which the callback is called. More...
void | when (uchar i)
| Sets the flags used to decide when a callback is called. More...
Fl_Window * | window () const
| Returns a pointer to the nearest parent window up the widget hierarchy. More...
int | x () const
| Gets the widget position in its window. More...
int | y () const
| Gets the widget position in its window. More...
virtual | ~Fl_Widget ()
| Destroys the widget. More...

## Protected Member Functions
void | do_callback_for_item (Fl_Tree_Item *item, Fl_Tree_Reason reason)
| Do the callback for the specified `'item'` using `'reason'`, setting the callback_item() and callback_reason().
void | item_clicked (Fl_Tree_Item *val)
| Set the item that was last clicked. More...
Protected Member Functions inherited from Fl_Group
void | draw_child (Fl_Widget &widget) const
| Forces a child to redraw. More...
void | draw_children ()
| Draws all children of the group. More...
void | draw_outside_label (const Fl_Widget &widget) const
| Parents normally call this to draw outside labels of child widgets.
int * | sizes ()
| Returns the internal array of widget sizes and positions. More...
void | update_child (Fl_Widget &widget) const
| Draws a child only if it needs it. More...
Protected Member Functions inherited from Fl_Widget
void | clear_flag (unsigned int c)
| Clears a flag in the flags mask.
void | draw_backdrop () const
| If FL_ALIGN_IMAGE_BACKDROP is set, the image or deimage will be drawn.
void | draw_box () const
| Draws the widget box according its box style.
void | draw_box (Fl_Boxtype t, Fl_Color c) const
| Draws a box of type t, of color c at the widget's position and size.
void | draw_box (Fl_Boxtype t, int x, int y, int w, int h, Fl_Color c) const
| Draws a box of type t, of color c at the position X,Y and size W,H.
void | draw_focus ()
| draws a focus rectangle around the widget
void | draw_focus (Fl_Boxtype t, int x, int y, int w, int h) const
| Draws a focus box for the widget at the given position and size.
void | draw_label () const
| Draws the widget's label at the defined label position. More...
void | draw_label (int, int, int, int) const
| Draws the label in an arbitrary bounding box. More...
| Fl_Widget (int x, int y, int w, int h, const char *label=0L)
| Creates a widget at the given position and size. More...
unsigned int | flags () const
| Gets the widget flags mask.
void | h (int v)
| Internal use only. More...
void | set_flag (unsigned int c)
| Sets a flag in the flags mask.
void | w (int v)
| Internal use only. More...
void | x (int v)
| Internal use only. More...
void | y (int v)
| Internal use only. More...

## Protected Attributes
Fl_Scrollbar * | _hscroll
| Horizontal scrollbar.
int | _tih
| Tree widget inner xywh dimension: inside borders + scrollbars.
int | _tiw
int | _tix
int | _tiy
int | _toh
| Tree widget outer xywh dimension: outside scrollbars, inside widget border.
int | _tow
int | _tox
int | _toy
int | _tree_h
| the calculated height of the entire tree hierarchy. See calc_tree()
int | _tree_w
| the calculated width of the entire tree hierarchy. See calc_tree()
Fl_Scrollbar * | _vscroll
| Vertical scrollbar.

## Friends
class | Fl_Tree_Item

## Additional Inherited Members
Static Public Member Functions inherited from Fl_Group
static Fl_Group * | current ()
| Returns the currently active group. More...
static void | current (Fl_Group *g)
| Sets the current group. More...
Static Public Member Functions inherited from Fl_Widget
static void | default_callback (Fl_Widget *cb, void *d)
| The default callback for all widgets that don't set a callback. More...
static unsigned int | label_shortcut (const char *t)
| Returns the Unicode value of the '&x' shortcut in a given text. More...
static int | test_shortcut (const char *, const bool require_alt=false)
| Returns true if the given text `t` contains the entered '&x' shortcut. More...
Protected Types inherited from Fl_Widget
enum | { INACTIVE = 1<<0, INVISIBLE = 1<<1, OUTPUT = 1<<2, NOBORDER = 1<<3, FORCE_POSITION = 1<<4, NON_MODAL = 1<<5, SHORTCUT_LABEL = 1<<6, CHANGED = 1<<7, OVERRIDE = 1<<8, VISIBLE_FOCUS = 1<<9, COPIED_LABEL = 1<<10, CLIP_CHILDREN = 1<<11, MENU_WINDOW = 1<<12, TOOLTIP_WINDOW = 1<<13, MODAL = 1<<14, NO_OVERLAY = 1<<15, GROUP_RELATIVE = 1<<16, COPIED_TOOLTIP = 1<<17, FULLSCREEN = 1<<18, MAC_USE_ACCENTS_MENU = 1<<19, USERFLAG3 = 1<<29, USERFLAG2 = 1<<30, USERFLAG1 = 1<<31 }
| flags possible values enumeration. More...

## Detailed Description

Tree widget.

    \image html tree-simple.png "Fl_Tree example program"
    \image latex tree-simple.png "Fl_Tree example program" width=4cm

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 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();

FEATURES
  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 close(),
  positioned on the screen with show_item_top(), show_item_middle() and show_item_bottom(),
  item children 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 visible items with first_visible_item() and next_visible_item().
  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).
  A hook is provided to allow you to redefine how item's labels are drawn via Fl_Tree::item_draw_callback().

SELECTION OF ITEMS
  The tree can have different selection behaviors controlled by selectmode(). The background color used for selected items is the Fl_Tree::selection_color(). The foreground color for selected items is controlled internally with fl_contrast().

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

  When an Fl_Tree_Item::widget() is defined, the default behavior is for the widget() to be shown in place of the item's label (if it has one). Only the widget()'s width will be used; the widget()'s x() and y() position will be managed by the tree, and the h() will track the item's height. This default behavior can be altered (ABI 1.3.1): Setting Fl_Tree::item_draw_mode()'s FL_TREE_ITEM_DRAW_LABEL_AND_WIDGET flag causes the label + widget to be displayed together in that order, and adding the FL_TREE_ITEM_HEIGHT_FROM_WIDGET flag causes widget's height to define the widget()'s height.

ICONS
  The tree's open/close icons can be redefined with Fl_Tree::openicon(), Fl_Tree::closeicon(). User icons can either be changed globally with Fl_Tree::usericon(), or on a per-item basis with Fl_Tree_Item::usericon().

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

FONTS AND COLORS
  When adding new items to the tree, the new items get the defaults for fonts and colors from:

  - Fl_Tree::item_labelfont() – The default item label font (default: FL_HELVETICA)
  - Fl_Tree::item_labelsize() – The default item label size (default: FL_NORMAL_SIZE)
  - Fl_Tree::item_labelfgcolor() – The default item label foreground color (default: FL_FOREGROUND_COLOR)
  - Fl_Tree::item_labelbgcolor() – The default item label background color (default: 0xffffffff, which tree uses as 'transparent')

  Each item (Fl_Tree_Item) inherits a copy of these font/color attributes when created, and each item has its own methods to let the app change these values on a per-item basis using methods of the same name:

  - Fl_Tree_Item::labelfont() – The item's label font (default: FL_HELVETICA)
  - Fl_Tree_Item::labelsize() – The item's label size (default: FL_NORMAL_SIZE)
  - Fl_Tree_Item::labelfgcolor() – The item's label foreground color (default: FL_FOREGROUND_COLOR)
  - Fl_Tree_Item::labelbgcolor() – The item's label background color (default: 0xffffffff, which uses the tree's own bg color)

CALLBACKS
  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. e.g.

  void MyTreeCallback(Fl_Widget *w, void *data) {
  Fl_Tree *tree = (Fl_Tree*)w;
  Fl_Tree_Item *item = (Fl_Tree_Item*)tree->callback_item(); // get selected item
  switch ( tree->callback_reason() ) {
  case FL_TREE_REASON_SELECTED: [..]
  case FL_TREE_REASON_DESELECTED: [..]
  case FL_TREE_REASON_RESELECTED: [..]
  case FL_TREE_REASON_OPENED: [..]
  case FL_TREE_REASON_CLOSED: [..]
  }

SIMPLE EXAMPLES
  To find all the selected items:
  for ( Fl_Tree_Item *i=first_selected_item(); i; i=next_selected_item(i) )
  printf("Item %s is selected\n", i->label());
  To get an item's full menu pathname, use Fl_Tree::item_pathname(), e.g.
  char pathname[256] = "???";
  tree->item_pathname(pathname, sizeof(pathname), item); // eg. "Parent/Child/Item"

  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 when 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 existing 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);
  }

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

  The following shows the protected dimension variables 'tree inner' (tix..) and 'tree outer' (tox..):
  Fl_Tree inner/outer dimensions

KEYBOARD BINDINGS
  The following table lists keyboard bindings for navigating the tree:

Keyboard bindings.
Keyboard | FL_TREE_SELECT_MULTI | FL_TREE_SELECT_SINGLE | FL_TREE_SELECT_NONE
Ctrl-A (Linux/Windows) Command-A (Mac) | Select all items. | N/A | N/A
Space | Selects item. | Selects item. | N/A
Ctrl-Space | Toggle item. | Toggle item. | N/A
Shift-Space | Extends selection from last item. | Selects item. | N/A
Enter, Ctrl-Enter, Shift-Enter | Toggles open/close | Toggles open/close | Toggles open/close
Right / Left | Open/Close item. | Open/Close item. | Open/Close item.
Up / Down | Move focus box up/down. | Move focus box up/down. | N/A
Shift-Up / Shift-Down | Extend selection up/down. | Move focus up/down. | N/A
Home / End | Move to top/bottom of tree. | Move to top/bottom of tree. | Move to top/bottom of tree.
PageUp / PageDown | Page up/down. | Page up/down. | Page up/down.

## Member Function Documentation

## ◆ add() [1/2]

Fl_Tree_Item * Fl_Tree::add | ( | const char * | path,
|  | Fl_Tree_Item * | item = `0`
| ) |  |

Adds a new item, given a menu style `'path'`.

Any parent nodes that don't already exist are created automatically. Adds the item based on the value of sortorder(). If `'item'` is NULL, a new item is created.

To specify items or submenus that contain slashes ('/' or '\') use an escape character to protect them, e.g.

tree->add("/Holidays/Photos/12\\/25\\/2010"); // Adds item "12/25/2010"
tree->add("/Pathnames/c:\\\\Program Files\\\\MyApp"); // Adds item "c:\Program Files\MyApp"

Parameters

  [in] | path | The path to the item, e.g. "Flintstone/Fred".
  [in] | item | The new item to be added. If NULL, a new item is created with a name that is the last element in `'path'`.

Returns
  The new item added, or 0 on error.

Version
  1.3.3

## ◆ add() [2/2]

Fl_Tree_Item * Fl_Tree::add | ( | Fl_Tree_Item * | parent_item,
|  | const char * | name
| ) |  |

Add a new child item labeled `'name'` to the specified `'parent_item'`.

Parameters

  [in] | parent_item | The parent item the new child item will be added to. Must not be NULL.
  [in] | name | The label for the new item

Returns
  The new item added.

Version
  1.3.0 release

## ◆ calc_dimensions()

void Fl_Tree::calc_dimensions | ( |  | ) |

Recalculate widget dimensions and scrollbar visibility, normally managed automatically.

Low overhead way to update the tree widget's outer/inner dimensions and re-determine scrollbar visibility based on these changes without recalculating the entire size of the tree data.

Assumes that either the tree's size in _tree_w/_tree_h are correct so that scrollbar visibility can be calculated easily, or are both zero indicating scrollbar visibility can't be calculated yet.

This method is called when the widget is resize()ed or if the scrollbar's sizes are changed (affects tree widget's inner dimensions tix/y/w/h), and also used by calc_tree().

Version
  1.3.3 ABI feature

## ◆ calc_tree()

void Fl_Tree::calc_tree | ( |  | ) |

Recalculates the tree's sizes and scrollbar visibility, normally managed automatically.

On return:

    - _tree_w will be the overall pixel width of the entire viewable tree
    - _tree_h will be the overall pixel height ""
    - scrollbar visibility and pan sizes are updated
    - internal _tix/_tiy/_tiw/_tih dimensions are updated

_tree_w/_tree_h include the tree's margins (e.g. marginleft()), whether items are open or closed, label contents and font sizes, etc.

The tree hierarchy's size is managed separately from the widget's size as an optimization; this way resize() on the widget doesn't involve recalculating the tree's hierarchy needlessly, as widget size has no bearing on the tree hierarchy.

The tree hierarchy's size only changes when items are added/removed, open/closed, label contents or font sizes changed, margins changed, etc.

This calculation involves walking the entire tree from top to bottom, potentially a slow calculation if the tree has many items (potentially hundreds of thousands), and should therefore be called sparingly.

For this reason, recalc_tree() is used as a way to /schedule/ calculation when changes affect the tree hierarchy's size.

Apps may want to call this method directly if the app makes changes to the tree's geometry, then immediately needs to work with the tree's new dimensions before an actual redraw (and recalc) occurs. (This use by an app should only rarely be needed)

## ◆ callback_item() [1/2]

Fl_Tree_Item * Fl_Tree::callback_item | ( |  | ) |

Gets the item that caused the callback.

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

## ◆ callback_item() [2/2]

void Fl_Tree::callback_item | ( | Fl_Tree_Item * | item | ) |

Sets the item that was changed for this callback.

Used internally to pass the item that invoked the callback.

## ◆ callback_reason() [1/2]

Fl_Tree_Reason Fl_Tree::callback_reason | ( |  | ) | const

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_RESELECTED: ..item was reselected (double-clicked, etc)..
case FL_TREE_REASON_DESELECTED: ..item was deselected..
}
}

See also
  item_reselect_mode() – enables FL_TREE_REASON_RESELECTED events

## ◆ callback_reason() [2/2]

void Fl_Tree::callback_reason | ( | Fl_Tree_Reason | reason | ) |

Sets the reason for this callback.

Used internally to pass the reason the callback was invoked.

## ◆ clear()

void Fl_Tree::clear | ( |  | ) |

Clear the entire tree's children, including the root.

The tree will be left completely empty.

## ◆ clear_children()

void Fl_Tree::clear_children | ( | Fl_Tree_Item * | item | ) |

Clear all the children for `'item'`.

Item may not be NULL.

## ◆ close() [1/2]

int Fl_Tree::close | ( | const char * | path,
|  | int | docallback = `1`
| ) |  |

Closes the item specified by `'path'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. close("Holidays/12\\/25\\/2010").

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 (e.g. "Flintstones/Fred")
  [in] | docallback | – A flag that determines if the callback() is invoked or not: 0 - callback() is not invoked 1 - callback() is invoked if item changed (default), callback_reason() will be FL_TREE_REASON_CLOSED

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()

## ◆ close() [2/2]

int Fl_Tree::close | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Closes the specified `'item'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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: 0 - callback() is not invoked 1 - callback() is invoked if item changed (default), callback_reason() will be FL_TREE_REASON_CLOSED

Returns
  - 1 – item was closed
  - 0 – item was already closed, no change

See also
  open(), close(), is_open(), is_close(), callback_item(), callback_reason()

## ◆ closeicon() [1/2]

Fl_Image * Fl_Tree::closeicon | ( |  | ) | const

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

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

## ◆ closeicon() [2/2]

void Fl_Tree::closeicon | ( | Fl_Image * | val | ) |

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.

## ◆ connectorstyle()

void Fl_Tree::connectorstyle | ( | Fl_Tree_Connector | val | ) |

Sets the line drawing style for inter-connecting items.

See Fl_Tree_Connector for possible values.

## ◆ deselect() [1/2]

int Fl_Tree::deselect | ( | const char * | path,
|  | int | docallback = `1`
| ) |  |

Deselect an item specified by `'path'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. deselect("Holidays/12\\/25\\/2010").

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 (e.g. "Flintstones/Fred")
  [in] | docallback | – A flag that determines if the callback() is invoked or not: 0 - the callback() is not invoked 1 - the callback() is invoked if item changed state (default), callback_reason() will be FL_TREE_REASON_DESELECTED

Returns
  - 1 - OK: item's state was changed
  - 0 - OK: item was already deselected, no change was made
  - -1 - ERROR: item was not found

## ◆ deselect() [2/2]

int Fl_Tree::deselect | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Deselect the specified `item`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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 deselected. Must not be NULL.
  [in] | docallback | – A flag that determines if the callback() is invoked or not: 0 - the callback() is not invoked 1 - the callback() is invoked if item changed state (default), callback_reason() will be FL_TREE_REASON_DESELECTED

Returns
  - 0 - item was already deselected, no change was made
  - 1 - item's state was changed

## ◆ deselect_all()

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.
Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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 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: 0 - the callback() is not invoked 1 - the callback() is invoked for each item that changed state (default), callback_reason() will be FL_TREE_REASON_DESELECTED

Returns
  Count of how many items were actually changed to the deselected state.

## ◆ display()

void Fl_Tree::display | ( | Fl_Tree_Item * | item | ) |

Displays `'item'`, scrolling the tree as necessary.

Parameters

  [in] | item | The item to be displayed. If NULL, first() is used.

## ◆ displayed()

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] | item | The item to be checked. If NULL, first() is used.

Returns
  1 if displayed, 0 if scrolled off screen or no items are in tree.

## ◆ extend_selection()

int Fl_Tree::extend_selection | ( | Fl_Tree_Item * | from,
|  | Fl_Tree_Item * | to,
|  | int | val = `1`,
|  | bool | visible = `false`
| ) |  |

Extend a selection between `'from'` and `'to'` depending on `'visible'`.

Similar to the more efficient extend_selection_dir(Fl_Tree_Item*,Fl_Tree_Item*,int dir,int val,bool vis) method, but direction (up or down) doesn't need to be known.
We're less efficient because we search the tree for to/from, then operate on items in between. The more efficient method avoids the "search", but necessitates a direction to be specified to find `'to'`.
Used by SHIFT-click to extend a selection between two items inclusive.
Handles calling redraw() if anything changed.

Parameters

  [in] | from | Starting item
  [in] | to | Ending item
  [in] | val | Select or deselect items (0=deselect, 1=select, 2=toggle)
  [in] | visible | true=affect only open(), visible items, false=affect open or closed items (default)

Returns
  The number of items whose selection states were changed, if any.

Version
  1.3.3 ABI feature

## ◆ extend_selection_dir()

int Fl_Tree::extend_selection_dir | ( | Fl_Tree_Item * | from,
|  | Fl_Tree_Item * | to,
|  | int | dir,
|  | int | val,
|  | bool | visible
| ) |  |

Extend the selection between and including `'from'` and `'to'` depending on direction `'dir'`, `'val'`, and `'visible'`.

Efficient: does not walk entire tree; starts with `'from'` and stops at `'to'` while moving in direction `'dir'`. Dir must be specified though. If dir cannot be known in advance, such as during SHIFT-click operations, the method extend_selection(Fl_Tree_Item*,Fl_Tree_Item*,int,bool) should be used. Handles calling redraw() if anything changed.

Parameters

  [in] | from | Starting item
  [in] | to | Ending item
  [in] | dir | Direction to extend selection (FL_Up or FL_Down)
  [in] | val | 0=deselect, 1=select, 2=toggle
  [in] | visible | true=affect only open(), visible items, false=affect open or closed items (default)

Returns
  The number of items whose selection states were changed, if any.

Version
  1.3.3

## ◆ find_clicked()

const Fl_Tree_Item * Fl_Tree::find_clicked | ( | int | yonly = `0` | ) | const

Find the item that was last clicked on.

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. (The value of the `'yonly'` flag affects whether both x and y events are checked, or just 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().

Parameters

  [in] | yonly | – 0: check both event's X and Y values. – 1: only check event's Y value, don't care about X.

Returns
  The item clicked, or NULL if no item was under the current event.

Version
  1.3.0
  1.3.3 ABI feature: added yonly parameter

## ◆ find_item()

const Fl_Tree_Item * Fl_Tree::find_item | ( | const char * | path | ) | const

Find the item, given a menu style path, e.g.

"/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.

To specify items or submenus that contain slashes ('/' or '\') use an escape character to protect them, e.g.

tree->add("/Holidays/Photos/12\\/25\\/2010"); // Adds item "12/25/2010"
tree->add("/Pathnames/c:\\\\Program Files\\\\MyApp"); // Adds item "c:\Program Files\MyApp"

Parameters

  [in] | path | – the tree item's pathname to be found (e.g. "Flintstones/Fred")

Returns
  The item, or NULL if not found.

See also
  item_pathname()

## ◆ first()

Fl_Tree_Item * Fl_Tree::first | ( |  | ) |

Returns the first item in the tree, or 0 if none.

Use this to walk the tree in the forward direction, e.g.

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()

## ◆ first_selected_item()

Fl_Tree_Item * Fl_Tree::first_selected_item | ( |  | ) |

Returns the first selected item in the tree.

Use this to walk the tree from top to bottom looking for all the selected items, e.g.

// Walk tree forward, from top to bottom
for ( Fl_Tree_Item *i=tree->first_selected_item(); i; i=tree->next_selected_item(i) )
printf("Selected item: %s\n", i->label());

Returns
  The first selected item, or 0 if none.

See also
  first_selected_item(), last_selected_item(), next_selected_item()

## ◆ first_visible()

Fl_Tree_Item * Fl_Tree::first_visible | ( |  | ) |

Returns the first open(), visible item in the tree, or 0 if none.

Deprecated:
  in 1.3.3 ABI – use first_visible_item() instead.

## ◆ first_visible_item()

Fl_Tree_Item * Fl_Tree::first_visible_item | ( |  | ) |

Returns the first open(), visible item in the tree, or 0 if none.

Returns
  First visible item in tree, or 0 if none.

See also
  first_visible_item(), last_visible_item(), next_visible_item()

Version
  1.3.3

## ◆ get_selected_items()

int Fl_Tree::get_selected_items | ( | Fl_Tree_Item_Array & | ret_items | ) |

Returns the currently selected items as an array of `'ret_items'`.

Example:

// Get selected items as an array
Fl_Tree_Item_Array items;
tree->get_selected_items(items);
// Manipulate the returned array
for ( int t=0; t<items.total(); t++ ) {
Fl_Tree_Item &item = items[t];
..do stuff with each selected item..
}

Parameters

  [out] | ret_items | The returned array of selected items.

Returns
  The number of items in the returned array.

See also
  first_selected_item(), next_selected_item()

Version
  1.3.3 ABI feature

## ◆ handle()

int Fl_Tree::handle | ( | int | e | ) |
| virtual

Standard FLTK event handler for this widget.

Todo:
  add Fl_Widget_Tracker (see Fl_Browser_.cxx::handle())

Reimplemented from Fl_Group.

## ◆ hposition() [1/2]

int Fl_Tree::hposition | ( |  | ) | const

Returns the horizontal scroll position as a pixel offset.

The position returned is how many pixels of the tree are scrolled off the left edge of the screen.

See also
  hposition(int), vposition(), vposition(int)

Note
  Must be using FLTK ABI 1.3.3 or higher for this to be effective.

## ◆ hposition() [2/2]

void Fl_Tree::hposition | ( | int | pos | ) |

Sets the horizontal scroll offset to position `'pos'`.

The position is how many pixels of the tree are scrolled off the left edge of the screen.

Parameters

  [in] | pos | The vertical position (in pixels) to scroll the tree to.

See also
  hposition(), vposition(), vposition(int)

Note
  Must be using FLTK ABI 1.3.3 or higher for this to be effective.

## ◆ insert()

Fl_Tree_Item * Fl_Tree::insert | ( | Fl_Tree_Item * | item,
|  | const char * | name,
|  | int | pos
| ) |  |

Insert a new item `'name'` into `'item's` children at position `'pos'`.

If `pos` is out of range the new item is

- prepended if `pos` < 0 or
- appended if `pos` > item->children().

Note: `pos` == children() is not considered out of range: the item is appended to the child list. Example:

tree->add("Aaa/000"); // "000" is index 0 in Aaa's children
tree->add("Aaa/111"); // "111" is index 1 in Aaa's children
tree->add("Aaa/222"); // "222" is index 2 in Aaa's children
..
// How to use insert() to insert a new item between Aaa/111 + Aaa/222
Fl_Tree_Item *item = tree->find_item("Aaa"); // get parent item Aaa
if (item) tree->insert(item, "New item", 2); // insert as a child of Aaa at index #2

Parameters

  [in] | item | The existing item to insert new child into. Must not be NULL.
  [in] | name | The label for the new item
  [in] | pos | The position of the new item in the child list

Returns
  The new item added.

See also
  insert_above()

## ◆ insert_above()

Fl_Tree_Item * Fl_Tree::insert_above | ( | Fl_Tree_Item * | above,
|  | const char * | name
| ) |  |

Inserts a new item `'name'` above the specified Fl_Tree_Item `'above'`.

Example:

tree->add("Aaa/000"); // "000" is index 0 in Aaa's children
tree->add("Aaa/111"); // "111" is index 1 in Aaa's children
tree->add("Aaa/222"); // "222" is index 2 in Aaa's children
..
// How to use insert_above() to insert a new item above Aaa/222
Fl_Tree_Item *item = tree->find_item("Aaa/222"); // get item Aaa/222
if (item) tree->insert_above(item, "New item"); // insert new item above it

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 new item added, or 0 if 'above' could not be found.

See also
  insert()

## ◆ is_close() [1/2]

int Fl_Tree::is_close | ( | const char * | path | ) | const

See if item specified by `'path'` is closed.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. is_close("Holidays/12\\/25\\/2010").

Parameters

  [in] | path | – the tree item's pathname (e.g. "Flintstones/Fred")

Returns
  - 1 - OK: item is closed
  - 0 - OK: item is open
  - -1 - ERROR: item was not found

## ◆ is_close() [2/2]

int Fl_Tree::is_close | ( | Fl_Tree_Item * | item | ) | const

See if the specified `'item'` is closed.

Parameters

  [in] | item | – the item to be tested. Must not be NULL.

Returns
  - 1 : item is closed
  - 0 : item is open

## ◆ is_hscroll_visible()

int Fl_Tree::is_hscroll_visible | ( |  | ) | const

See if the horizontal scrollbar is currently visible.

Returns
  1 if scrollbar visible, 0 if not.

Note
  Must be using FLTK ABI 1.3.3 or higher for this to be effective.

## ◆ is_open() [1/2]

int Fl_Tree::is_open | ( | const char * | path | ) | const

See if item specified by `'path'` is open.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. is_open("Holidays/12\\/25\\/2010").

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 (e.g. "Flintstones/Fred")

Returns
  - 1 - OK: item is open
  - 0 - OK: item is closed
  - -1 - ERROR: item was not found

See also
  Fl_Tree_Item::visible_r()

## ◆ is_open() [2/2]

int Fl_Tree::is_open | ( | Fl_Tree_Item * | item | ) | const

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

## ◆ is_scrollbar()

int Fl_Tree::is_scrollbar | ( | Fl_Widget * | w | ) |

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 ( tree->is_scrollbar(w) ) continue; // skip scrollbars
..do work here..
}

Parameters

  [in] | w | Widget to test

Returns
  1 if `w` is a scrollbar, 0 if not.

Todo:
  should be const

## ◆ is_selected() [1/2]

int Fl_Tree::is_selected | ( | const char * | path | ) |

See if item specified by `'path'` is selected.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. is_selected("Holidays/12\\/25\\/2010").

Parameters

  [in] | path | – the tree item's pathname (e.g. "Flintstones/Fred")

Returns
  - 1 : item selected
  - 0 : item deselected
  - -1 : item was not found

## ◆ is_selected() [2/2]

int Fl_Tree::is_selected | ( | Fl_Tree_Item * | item | ) | const

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

## ◆ is_vscroll_visible()

int Fl_Tree::is_vscroll_visible | ( |  | ) | const

See if the vertical scrollbar is currently visible.

Returns
  1 if scrollbar visible, 0 if not.

## ◆ item_clicked() [1/2]

Fl_Tree_Item * Fl_Tree::item_clicked | ( |  | ) |

Return the item that was last clicked.

Valid only from within the callback().

Returns
  The item clicked, or 0 if none. 0 may also be used to indicate several items were clicked/changed.

Deprecated:
  in 1.3.3 ABI – use callback_item() instead.

## ◆ item_clicked() [2/2]

void Fl_Tree::item_clicked | ( | Fl_Tree_Item * | item | ) |
| 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:
  in 1.3.3 ABI – use callback_item() instead.

## ◆ item_draw_mode() [1/3]

Fl_Tree_Item_Draw_Mode Fl_Tree::item_draw_mode | ( |  | ) | const

Get the 'item draw mode' used for the tree.

Version
  1.3.1 ABI feature

## ◆ item_draw_mode() [2/3]

void Fl_Tree::item_draw_mode | ( | Fl_Tree_Item_Draw_Mode | mode | ) |

Set the 'item draw mode' used for the tree to `'mode'`.

This affects how items in the tree are drawn, such as when a widget() is defined. See Fl_Tree_Item_Draw_Mode for possible values.

Version
  1.3.1 ABI feature

## ◆ item_draw_mode() [3/3]

void Fl_Tree::item_draw_mode | ( | int | mode | ) |

Set the 'item draw mode' used for the tree to integer `'mode'`.

This affects how items in the tree are drawn, such as when a widget() is defined. See Fl_Tree_Item_Draw_Mode for possible values.

Version
  1.3.1 ABI feature

## ◆ item_labelbgcolor() [1/2]

void Fl_Tree::item_labelbgcolor | ( | Fl_Color | val | ) |

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

A special case is made for color 0xffffffff (default) which is treated as 'transparent'. To change the background color on a per-item basis, use Fl_Tree_Item::labelbgcolor(Fl_Color)

## ◆ item_labelbgcolor() [2/2]

Fl_Color Fl_Tree::item_labelbgcolor | ( | void |  | ) | const

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

If the color is 0xffffffff, it is 'transparent'.

## ◆ item_labelfgcolor()

void Fl_Tree::item_labelfgcolor | ( | Fl_Color | val | ) |

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)

## ◆ item_labelfont()

void Fl_Tree::item_labelfont | ( | Fl_Font | val | ) |

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)

## ◆ item_labelsize()

void Fl_Tree::item_labelsize | ( | Fl_Fontsize | val | ) |

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)

## ◆ item_pathname()

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

Return `'pathname'` of size `'pathnamelen'` for the specified `'item'`.

If `'item'` is NULL, root() is used.
The tree's root will be included in the pathname if showroot() is on.
Menu items or submenus that contain slashes ('/' or '\') in their names will be escaped with a backslash. This is symmetrical with the add() function which uses the same escape pattern to set names.

Parameters

  [out] | pathname | The string to use to return the pathname
  [in] | pathnamelen | The maximum length of the string (including NULL). Must not be zero.
  [in] | item | The 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()

## ◆ item_reselect_mode() [1/2]

Fl_Tree_Item_Reselect_Mode Fl_Tree::item_reselect_mode | ( |  | ) | const

Returns the current item re/selection mode.

Version
  1.3.1 ABI feature

## ◆ item_reselect_mode() [2/2]

void Fl_Tree::item_reselect_mode | ( | Fl_Tree_Item_Reselect_Mode | mode | ) |

Sets the item re/selection mode.

See Fl_Tree_Item_Reselect_Mode for possible values.

Version
  1.3.1 ABI feature

## ◆ last()

Fl_Tree_Item * Fl_Tree::last | ( |  | ) |

Returns the last item in the tree.

This can be used to walk the tree in reverse, e.g.

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()

## ◆ last_selected_item()

Fl_Tree_Item * Fl_Tree::last_selected_item | ( |  | ) |

Returns the last selected item in the tree.

Use this to walk the tree in reverse from bottom to top looking for all the selected items, e.g.

// Walk tree in reverse, from bottom to top
for ( Fl_Tree_Item *i=tree->last_selected_item(); i; i=tree->next_selected_item(i, FL_Up) )
printf("Selected item: %s\n", i->label());

Returns
  The last selected item, or 0 if none.

See also
  first_selected_item(), last_selected_item(), next_selected_item()

Version
  1.3.3

## ◆ last_visible()

Fl_Tree_Item * Fl_Tree::last_visible | ( |  | ) |

Returns the last open(), visible item in the tree.

Deprecated:
  in 1.3.3 – use last_visible_item() instead.

## ◆ last_visible_item()

Fl_Tree_Item * Fl_Tree::last_visible_item | ( |  | ) |

Returns the last open(), visible item in the tree.

Returns
  Last visible item in the tree, or 0 if none.

See also
  first_visible_item(), last_visible_item(), next_visible_item()

Version
  1.3.3

## ◆ load()

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] | prefs | the Fl_Preferences database

## ◆ next()

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 *i = tree->first(); i; i = tree->next(i) )
printf("Item: %s\n", i->label());

Parameters

  [in] | item | The 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()

## ◆ next_item()

Fl_Tree_Item * Fl_Tree::next_item | ( | Fl_Tree_Item * | item,
|  | int | dir = `FL_Down`,
|  | bool | visible = `false`
| ) |  |

Returns next item after `'item'` in direction `'dir'` depending on `'visible'`.

Next item will be above (if dir==FL_Up) or below (if dir==FL_Down). If `'visible'` is true, only items whose parents are open() will be returned. If `'visible'` is false, even items whose parents are close()ed will be returned.

If `item` is 0, the return value will be the result of this truth table:

                           visible=true           visible=false
                           -------------------    -------------
             dir=FL_Up:    last_visible_item()    last()
           dir=FL_Down:    first_visible_item()   first()

Example use:
  // Walk down the tree showing open(), visible items
  for ( Fl_Tree_Item *i=tree->first_visible_item(); i; i=tree->next_item(i, FL_Down, true) )
  printf("Item: %s\n", i->label());
  // Walk up the tree showing open(), visible items
  for ( Fl_Tree_Item *i=tree->last_visible_item(); i; i=tree->next_item(i, FL_Up, true) )
  printf("Item: %s\n", i->label());
  // Walk down the tree showing all items (open or closed)
  for ( Fl_Tree_Item *i=tree->first(); i; i=tree->next_item(i, FL_Down, false) )
  printf("Item: %s\n", i->label());
  // Walk up the tree showing all items (open or closed)
  for ( Fl_Tree_Item *i=tree->last(); i; i=tree->next_item(i, FL_Up, false) )
  printf("Item: %s\n", i->label());

Parameters

  [in] | item | The item to use to find the next item. If NULL, returns 0.
  [in] | dir | Can be FL_Up or FL_Down (default=FL_Down or 'next')
  [in] | visible | true=return only open(), visible items, false=return open or closed items (default)

Returns
  Next item in tree in the direction and visibility specified, or 0 if no more items of specified visibility in that direction.

See also
  first(), last(), next(),
  first_visible_item(), last_visible_item(), next_visible_item(),
  first_selected_item(), last_selected_item(), next_selected_item()

Version
  1.3.3

## ◆ next_selected_item()

Fl_Tree_Item * Fl_Tree::next_selected_item | ( | Fl_Tree_Item * | item = `0`,
|  | int | dir = `FL_Down`
| ) |  |

Returns the next selected item above or below `'item'`, depending on `'dir'`.

If `'item'` is 0, search starts at either first() or last(), depending on `'dir'`: first() if `'dir'` is FL_Down (default), last() if `'dir'` is FL_Up.

Use this to walk the tree looking for all the selected items, e.g.

// Walk down the tree (forwards)
for ( Fl_Tree_Item *i=tree->first_selected_item(); i; i=tree->next_selected_item(i, FL_Down) )
printf("Item: %s\n", i->label());
// Walk up the tree (backwards)
for ( Fl_Tree_Item *i=tree->last_selected_item(); i; i=tree->next_selected_item(i, FL_Up) )
printf("Item: %s\n", i->label());

Parameters

  [in] | item | The item above or below which we'll find the next selected item. If NULL, first() is used if FL_Down, last() if FL_Up. (default=NULL)
  [in] | dir | The direction to go. FL_Up for moving up the tree, FL_Down for down the tree (default)

Returns
  The next selected item, or 0 if there are no more selected items.

See also
  first_selected_item(), last_selected_item(), next_selected_item()

Version
  1.3.3

## ◆ next_visible_item()

Fl_Tree_Item * Fl_Tree::next_visible_item | ( | Fl_Tree_Item * | item,
|  | int | dir
| ) |  |

Returns next open(), visible item above (`dir==FL_Up`) or below (`dir==FL_Down`) the specified `'item'`, or 0 if no more items.

If `'item'` is 0, returns last() if `'dir'` is FL_Up, or first() if `dir` is FL_Down.

// Walk down the tree (forwards)
for ( Fl_Tree_Item *i=tree->first_visible_item(); i; i=tree->next_visible_item(i, FL_Down) )
printf("Item: %s\n", i->label());
// Walk up the tree (backwards)
for ( Fl_Tree_Item *i=tree->last_visible_item(); i; i=tree->next_visible_item(i, FL_Up) )
printf("Item: %s\n", i->label());

Parameters

  [in] | item | The item above/below which we'll find the next visible item
  [in] | dir | The 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`.

Version
  1.3.3

## ◆ open() [1/2]

int Fl_Tree::open | ( | const char * | path,
|  | int | docallback = `1`
| ) |  |

Opens the item specified by `'path'`.

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

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. open("Holidays/12\\/25\\/2010").

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 (e.g. "Flintstones/Fred")
  [in] | docallback | – A flag that determines if the callback() is invoked or not: 0 - callback() is not invoked 1 - callback() is invoked if item changed (default), callback_reason() will be FL_TREE_REASON_OPENED

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()

## ◆ open() [2/2]

int Fl_Tree::open | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Open the specified `'item'`.

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

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: 0 - callback() is not invoked 1 - callback() is invoked if item changed (default), callback_reason() will be FL_TREE_REASON_OPENED

Returns
  - 1 – item was opened
  - 0 – item was already open, no change

See also
  open(), close(), is_open(), is_close(), callback_item(), callback_reason()

## ◆ open_toggle()

void Fl_Tree::open_toggle | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Toggle the open state of `'item'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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: 0 - callback() is not invoked 1 - callback() is invoked (default), callback_reason() will be either FL_TREE_REASON_OPENED or FL_TREE_REASON_CLOSED

See also
  open(), close(), is_open(), is_close(), callback_item(), callback_reason()

## ◆ openicon() [1/2]

Fl_Image * Fl_Tree::openicon | ( |  | ) | const

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

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

## ◆ openicon() [2/2]

void Fl_Tree::openicon | ( | Fl_Image * | val | ) |

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.

## ◆ prev()

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, e.g.

for ( Fl_Tree_Item *item = tree->first(); item; item = tree->prev(item) )
printf("Item: %s\n", item->label());

Parameters

  [in] | item | The 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()

## ◆ recalc_tree()

void Fl_Tree::recalc_tree | ( |  | ) |

Schedule tree to recalc the entire tree size.

Note
  Must be using FLTK ABI 1.3.3 or higher for this to be effective.

## ◆ remove()

int Fl_Tree::remove | ( | Fl_Tree_Item * | item | ) |

Remove the specified `'item'` from the tree.

`item` may not be NULL. If it has children, all those are removed too. If item being removed has focus, no item will have focus.

Returns
  0 if done, -1 if 'item' not found.

## ◆ resize()

void Fl_Tree::resize | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H
| ) |  |
| virtual

Resizes the Fl_Group widget and all of its children.

The Fl_Group widget first resizes itself, and then it moves and resizes all its children according to the rules documented for Fl_Group::resizable(Fl_Widget*)

See also
  Fl_Group::resizable(Fl_Widget*)
  Fl_Group::resizable()
  Fl_Widget::resize(int,int,int,int)

Reimplemented from Fl_Group.

## ◆ root()

void Fl_Tree::root | ( | Fl_Tree_Item * | newitem | ) |

Sets the root item to `'newitem'`.

If a root item already exists, clear() is called first to clear it before replacing it with newitem. Use this to install a custom item (derived from Fl_Tree_Item) as the root of the tree. This allows the derived class to implement custom drawing by overriding Fl_Tree_Item::draw_item_content().

Version
  1.3.3

## ◆ root_label()

void Fl_Tree::root_label | ( | const char * | new_label | ) |

Set the label for the root item to `'new_label'`.

Makes an internally managed copy of 'new_label'.

## ◆ scrollbar_size() [1/2]

int Fl_Tree::scrollbar_size | ( |  | ) | const

Gets the default size of scrollbars' troughs for this widget 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::scrollbar_size() is being used.

See also
  Fl::scrollbar_size(int)

## ◆ scrollbar_size() [2/2]

void Fl_Tree::scrollbar_size | ( | int | size | ) |

Sets the pixel size of the scrollbars' troughs to `'size'` for this widget, 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, and is the default behavior. Normally this is what you want.

Only use this method if you really need to override just THIS instance of the widget's scrollbar size. (This need 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] | size | Sets the scrollbar size in pixels. If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()

See also
  Fl::scrollbar_size()

## ◆ select() [1/2]

int Fl_Tree::select | ( | const char * | path,
|  | int | docallback = `1`
| ) |  |

Select the item specified by `'path'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

Items or submenus that themselves contain slashes ('/' or '\') should be escaped, e.g. select("Holidays/12\\/25\\/2010").

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 (e.g. "Flintstones/Fred")
  [in] | docallback | – A flag that determines if the callback() is invoked or not: 0 - the callback() is not invoked 1 - the callback() is invoked if item changed state (default), callback_reason() will be FL_TREE_REASON_SELECTED

Returns
  - 1 : OK: item's state was changed
  - 0 : OK: item was already selected, no change was made
  - -1 : ERROR: item was not found

## ◆ select() [2/2]

int Fl_Tree::select | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Select the specified `'item'`.

Use 'deselect()' to deselect it.

Invokes the callback depending on the value of optional parameter `docallback`.
Handles calling redraw() if anything changed.

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: 0 - the callback() is not invoked 1 - the callback() is invoked if item changed state, callback_reason() will be FL_TREE_REASON_SELECTED

Returns
  - 1 - item's state was changed
  - 0 - item was already selected, no change was made

## ◆ select_all()

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.
Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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 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: 0 - the callback() is not invoked 1 - the callback() is invoked for each item that changed state (default), callback_reason() will be FL_TREE_REASON_SELECTED

Returns
  Count of how many items were actually changed to the selected state.

## ◆ select_only()

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 `'selitem'` is 0, first() is used.
Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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

Parameters

  [in] | selitem | The 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 (default), 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.

## ◆ select_toggle()

void Fl_Tree::select_toggle | ( | Fl_Tree_Item * | item,
|  | int | docallback = `1`
| ) |  |

Toggle the select state of the specified `'item'`.

Invokes the callback depending on the value of optional parameter `'docallback'`.
Handles calling redraw() if anything changed.

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: 0 - the callback() is not invoked 1 - the callback() is invoked (default), callback_reason() will be either FL_TREE_REASON_SELECTED or FL_TREE_REASON_DESELECTED

## ◆ selectbox() [1/2]

Fl_Boxtype Fl_Tree::selectbox | ( |  | ) | const

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()

## ◆ selectbox() [2/2]

void Fl_Tree::selectbox | ( | Fl_Boxtype | val | ) |

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()

## ◆ selectmode() [1/2]

Fl_Tree_Select Fl_Tree::selectmode | ( |  | ) | const

Gets the tree's current selection mode.

See Fl_Tree_Select for possible values.

## ◆ selectmode() [2/2]

void Fl_Tree::selectmode | ( | Fl_Tree_Select | val | ) |

Sets the tree's selection mode.

See Fl_Tree_Select for possible values.

## ◆ set_item_focus()

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 it is visible).

Parameters

  [in] | item | The item that should take focus. If NULL, none will have focus.

## ◆ show_item() [1/2]

void Fl_Tree::show_item | ( | Fl_Tree_Item * | item | ) |

Adjust the vertical scrollbar to show `'item'` at the top of the display IF it is currently off-screen (for instance show_item_top()).

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

Parameters

  [in] | item | The item to be shown. If NULL, first() is used.

See also
  show_item_top(), show_item_middle(), show_item_bottom()

## ◆ show_item() [2/2]

void Fl_Tree::show_item | ( | Fl_Tree_Item * | item,
|  | int | yoff
| ) |  |

Adjust the vertical scrollbar 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] | item | The item to be shown. If NULL, first() is used.
  [in] | yoff | The pixel offset from the top for the displayed position.

See also
  show_item_top(), show_item_middle(), show_item_bottom()

## ◆ 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] | item | The item to be shown. If NULL, first() is used.

## ◆ show_item_middle()

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] | item | The item to be shown. If NULL, first() is used.

## ◆ show_item_top()

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] | item | The item to be shown. If NULL, first() is used.

## ◆ show_self()

void Fl_Tree::show_self | ( |  | ) |

Print the tree as 'ascii art' to stdout.

Used mainly for debugging.

Todo:
  should be const

Version
  1.3.0

## ◆ showcollapse() [1/2]

int Fl_Tree::showcollapse | ( |  | ) | const

Returns 1 if the collapse icon is enabled, 0 if not.

See also
  showcollapse(int)

## ◆ showcollapse() [2/2]

void Fl_Tree::showcollapse | ( | int | val | ) |

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] | val | 1: shows collapse icons (default), 0: hides collapse icons.

## ◆ showroot()

void Fl_Tree::showroot | ( | int | val | ) |

Set if the root item should be shown or not.

Parameters

  [in] | val | 1 – show the root item (default) 0 – hide the root item.

## ◆ sortorder()

Fl_Tree_Sort Fl_Tree::sortorder | ( |  | ) | const

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

See Fl_Tree_Sort for possible values.

## ◆ usericon() [1/2]

Fl_Image * Fl_Tree::usericon | ( |  | ) | const

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.

## ◆ usericon() [2/2]

void Fl_Tree::usericon | ( | Fl_Image * | val | ) |

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.

## ◆ vposition() [1/2]

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.

See also
  vposition(int), hposition(), hposition(int)

## ◆ vposition() [2/2]

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.

Parameters

  [in] | pos | The vertical position (in pixels) to scroll the tree to.

See also
  vposition(), hposition(), hposition(int)

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

- Fl_Tree.H
- Fl_Tree.cxx

FL_Up
#define FL_Up
The up arrow key.
Definition: Enumerations.H:481
Fl_Tree::insert
Fl_Tree_Item * insert(Fl_Tree_Item *item, const char *name, int pos)
Insert a new item 'name' into 'item's children at position 'pos'.
Definition: Fl_Tree.cxx:1104
Fl_Tree::find_item
Fl_Tree_Item * find_item(const char *path)
Non-const version of Fl_Tree::find_item(const char *path) const.
Definition: Fl_Tree.cxx:1179
Fl_Tree::item_labelfont
Fl_Font item_labelfont() const
Get the default font face used for creating new items.
Definition: Fl_Tree.cxx:2204
FL_TREE_REASON_SELECTED
@ FL_TREE_REASON_SELECTED
an item was selected
Definition: Fl_Tree.H:313
Fl_Tree::item_labelfgcolor
Fl_Color item_labelfgcolor(void) const
Get the default label foreground color used for creating new items.
Definition: Fl_Tree.cxx:2216
Fl_Tree::next_selected_item
Fl_Tree_Item * next_selected_item(Fl_Tree_Item *item=0, int dir=FL_Down)
Returns the next selected item above or below 'item', depending on 'dir'.
Definition: Fl_Tree.cxx:1615
Fl_Tree::first_selected_item
Fl_Tree_Item * first_selected_item()
Returns the first selected item in the tree.
Definition: Fl_Tree.cxx:1476
Fl_Tree::next
Fl_Tree_Item * next(Fl_Tree_Item *item=0)
Return the next item after 'item', or 0 if no more items.
Definition: Fl_Tree.cxx:1391
Fl_Tree_Select
Fl_Tree_Select
Definition: Fl_Tree_Prefs.H:67
FL_TREE_REASON_RESELECTED
@ FL_TREE_REASON_RESELECTED
an item was re-selected (e.g. double-clicked)
Definition: Fl_Tree.H:316
Fl_Tree::first_visible_item
Fl_Tree_Item * first_visible_item()
Returns the first open(), visible item in the tree, or 0 if none.
Definition: Fl_Tree.cxx:1369
FL_COURIER
const Fl_Font FL_COURIER
Courier normal.
Definition: Enumerations.H:883
Fl_Tree_Item
Tree widget item.
Definition: Fl_Tree_Item.H:67
Fl_Tree::prev
Fl_Tree_Item * prev(Fl_Tree_Item *item=0)
Return the previous item before 'item', or 0 if no more items.
Definition: Fl_Tree.cxx:1409
FL_TREE_REASON_CLOSED
@ FL_TREE_REASON_CLOSED
an item was closed
Definition: Fl_Tree.H:319
Fl_Tree::item_pathname
int item_pathname(char *pathname, int pathnamelen, const Fl_Tree_Item *item) const
Return 'pathname' of size 'pathnamelen' for the specified 'item'.
Definition: Fl_Tree.cxx:1211
Fl_Tree_Item::children
int children() const
Return the number of children this item has.
Definition: Fl_Tree_Item.H:232
Fl_Tree.H
This file contains the definitions of the Fl_Tree class.
FL_Down
#define FL_Down
The down arrow key.
Definition: Enumerations.H:483
Fl_Widget::w
int w() const
Gets the widget width.
Definition: Fl_Widget.H:294
Fl_Tree_Sort
Fl_Tree_Sort
Definition: Fl_Tree_Prefs.H:49
Fl_Tree::insert_above
Fl_Tree_Item * insert_above(Fl_Tree_Item *above, const char *name)
Inserts a new item 'name' above the specified Fl_Tree_Item 'above'.
Definition: Fl_Tree.cxx:1075
Fl_Tree::is_scrollbar
int is_scrollbar(Fl_Widget *w)
See if widget 'w' is one of the Fl_Tree widget's scrollbars.
Definition: Fl_Tree.cxx:2757
Fl_Tree_Item::label
void label(const char *val)
Set the label to 'name'.
Definition: Fl_Tree_Item.cxx:196
Fl_Tree::first
Fl_Tree_Item * first()
Returns the first item in the tree, or 0 if none.
Definition: Fl_Tree.cxx:1353
Fl_Tree::add
Fl_Tree_Item * add(const char *path, Fl_Tree_Item *newitem=0)
Adds a new item, given a menu style 'path'.
Definition: Fl_Tree.cxx:1013
Fl_Tree::callback_reason
void callback_reason(Fl_Tree_Reason reason)
Sets the reason for this callback.
Definition: Fl_Tree.cxx:2857
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition: Fl_Widget.H:101
Fl_Group::children
int children() const
Returns how many child widgets the group has.
Definition: Fl_Group.H:75
Fl_Tree::next_visible_item
Fl_Tree_Item * next_visible_item(Fl_Tree_Item *start, int dir)
Returns next open(), visible item above (dir==FL_Up) or below (dir==FL_Down) the specified 'item',...
Definition: Fl_Tree.cxx:1338
Fl_Tree_Item_Array
Manages an array of Fl_Tree_Item pointers.
Definition: Fl_Tree_Item_Array.H:47
Fl_Tree::Fl_Tree
Fl_Tree(int X, int Y, int W, int H, const char *L=0)
Constructor.
Definition: Fl_Tree.cxx:79
FL_TREE_REASON_OPENED
@ FL_TREE_REASON_OPENED
an item was opened
Definition: Fl_Tree.H:318
Fl_Tree_Connector
Fl_Tree_Connector
Definition: Fl_Tree_Prefs.H:58
Fl_Tree_Item::labelcolor
void labelcolor(Fl_Color val)
Set item's label text color. Alias for labelfgcolor(Fl_Color)).
Definition: Fl_Tree_Item.H:203
Fl_Tree::last
Fl_Tree_Item * last()
Returns the last item in the tree.
Definition: Fl_Tree.cxx:1426
Fl_Tree_Item::child
Fl_Tree_Item * child(int index)
Return the child item for the given 'index'.
Definition: Fl_Tree_Item.H:236
Fl_Group::child
Fl_Widget * child(int n) const
Returns array()[n].
Definition: Fl_Group.H:79
Fl_Tree_Item_Array::total
int total() const
Return the total items in the array, or 0 if empty.
Definition: Fl_Tree_Item_Array.H:72
FL_TREE_REASON_DESELECTED
@ FL_TREE_REASON_DESELECTED
an item was de-selected
Definition: Fl_Tree.H:314
Fl_Tree_Prefs
Tree widget's preferences.
Definition: Fl_Tree_Prefs.H:111
Fl_Tree::get_selected_items
int get_selected_items(Fl_Tree_Item_Array &ret_items)
Returns the currently selected items as an array of 'ret_items'.
Definition: Fl_Tree.cxx:1659
Fl_Tree::next_item
Fl_Tree_Item * next_item(Fl_Tree_Item *item, int dir=FL_Down, bool visible=false)
Returns next item after 'item' in direction 'dir' depending on 'visible'.
Definition: Fl_Tree.cxx:1567
Fl_Tree::last_selected_item
Fl_Tree_Item * last_selected_item()
Returns the last selected item in the tree.
Definition: Fl_Tree.cxx:1518
Fl_Tree::callback_item
void callback_item(Fl_Tree_Item *item)
Sets the item that was changed for this callback.
Definition: Fl_Tree.cxx:2843
Fl_Tree::last_visible_item
Fl_Tree_Item * last_visible_item()
Returns the last open(), visible item in the tree.
Definition: Fl_Tree.cxx:1447
Fl_Tree
Tree widget.
Definition: Fl_Tree.H:323
Fl_Tree_Item::labelfont
void labelfont(Fl_Font val)
Set item's label font face.
Definition: Fl_Tree_Item.H:177
- © 1998-2016 by Bill Spitzak and others.