FLTK 1.3.4
Fl_Tree_Item Class Reference

Tree widget item. More...

#include <Fl_Tree_Item.H>

Public Member Functions

void activate (int val=1)
 Change the item's activation state to the optionally specified 'val'. More...
 
Fl_Tree_Itemadd (const Fl_Tree_Prefs &prefs, const char *new_label, Fl_Tree_Item *newitem)
 Add 'item' as immediate child with 'new_label' and defaults from 'prefs'. More...
 
Fl_Tree_Itemadd (const Fl_Tree_Prefs &prefs, const char *new_label)
 Add a new child to this item with the name 'new_label' and defaults from 'prefs'. More...
 
Fl_Tree_Itemadd (const Fl_Tree_Prefs &prefs, char **arr, Fl_Tree_Item *newitem)
 Descend into path specified by 'arr' and add 'newitem' there. More...
 
Fl_Tree_Itemadd (const Fl_Tree_Prefs &prefs, char **arr)
 Descend into the path specified by 'arr', and add a new child there. More...
 
Fl_Tree_Itemchild (int index)
 Return the child item for the given 'index'.
 
const Fl_Tree_Itemchild (int t) const
 Return the const child item for the given 'index'. More...
 
int children () const
 Return the number of children this item has.
 
void clear_children ()
 Clear all the children for this item.
 
void close ()
 Close this item and all its children.
 
void deactivate ()
 Deactivate the item; the callback() won't be invoked when clicked. More...
 
Fl_Tree_Itemdeparent (int index)
 Deparent child at index position 'pos'. More...
 
int depth () const
 Returns how many levels deep this item is in the hierarchy. More...
 
void deselect ()
 Disable the item's selection state.
 
int deselect_all ()
 Deselect item and all its children. More...
 
void draw (int X, int &Y, int W, Fl_Tree_Item *itemfocus, int &tree_item_xmax, int lastchild=1, int render=1)
 Draw this item and its children. More...
 
virtual int draw_item_content (int render)
 Draw the item content. More...
 
int event_on_collapse_icon (const Fl_Tree_Prefs &prefs) const
 Was the event on the 'collapse' button of this item?
 
int event_on_label (const Fl_Tree_Prefs &prefs) const
 Was event on the label() of this item?
 
int find_child (const char *name)
 Return the index of the immediate child of this item that has the label 'name'. More...
 
int find_child (Fl_Tree_Item *item)
 Find the index number for the specified 'item' in the current item's list of children. More...
 
const Fl_Tree_Itemfind_child_item (const char *name) const
 Return the /immediate/ child of current item that has the label 'name'. More...
 
Fl_Tree_Itemfind_child_item (const char *name)
 Non-const version of Fl_Tree_Item::find_child_item(const char *name) const.
 
const Fl_Tree_Itemfind_child_item (char **arr) const
 Find child item by descending array 'arr' of names. More...
 
Fl_Tree_Itemfind_child_item (char **arr)
 Non-const version of Fl_Tree_Item::find_child_item(char **arr) const.
 
const Fl_Tree_Itemfind_clicked (const Fl_Tree_Prefs &prefs, int yonly=0) const
 Find the item that the last event was over. More...
 
Fl_Tree_Itemfind_clicked (const Fl_Tree_Prefs &prefs, int yonly=0)
 Non-const version of Fl_Tree_Item::find_clicked(const Fl_Tree_Prefs&,int) const.
 
const Fl_Tree_Itemfind_item (char **arr) const
 Find item by descending array of 'names'. More...
 
Fl_Tree_Itemfind_item (char **arr)
 Non-const version of Fl_Tree_Item::find_item(char **names) const.
 
 Fl_Tree_Item (const Fl_Tree_Prefs &prefs)
 Constructor. More...
 
 Fl_Tree_Item (Fl_Tree *tree)
 Constructor. More...
 
 Fl_Tree_Item (const Fl_Tree_Item *o)
 Copy constructor.
 
int h () const
 The item's height.
 
int has_children () const
 See if this item has children.
 
Fl_Tree_Iteminsert (const Fl_Tree_Prefs &prefs, const char *new_label, int pos=0)
 Insert a new item named 'new_label' into current item's children at a specified position 'pos'. More...
 
Fl_Tree_Iteminsert_above (const Fl_Tree_Prefs &prefs, const char *new_label)
 Insert a new item named 'new_label' above this item. More...
 
char is_activated () const
 See if the item is activated.
 
char is_active () const
 See if the item is activated. Alias for is_activated().
 
int is_close () const
 See if the item is 'closed'.
 
int is_open () const
 See if the item is 'open'.
 
int is_root () const
 Is this item the root of the tree?
 
char is_selected () const
 See if the item is selected.
 
int is_visible () const
 See if the item is visible.
 
void label (const char *val)
 Set the label to 'name'. More...
 
const char * label () const
 Return the label.
 
int label_h () const
 The item's label height. More...
 
int label_w () const
 The item's maximum label width to right edge of Fl_Tree's inner width within scrollbars. More...
 
int label_x () const
 The item's label x position relative to the window. More...
 
int label_y () const
 The item's label y position relative to the window. More...
 
void labelbgcolor (Fl_Color val)
 Set item's label background color. More...
 
Fl_Color labelbgcolor () const
 Return item's label background text color. More...
 
void labelcolor (Fl_Color val)
 Set item's label text color. Alias for labelfgcolor(Fl_Color)).
 
Fl_Color labelcolor () const
 Return item's label text color. Alias for labelfgcolor() const).
 
void labelfgcolor (Fl_Color val)
 Set item's label foreground text color.
 
Fl_Color labelfgcolor () const
 Return item's label foreground text color.
 
void labelfont (Fl_Font val)
 Set item's label font face.
 
Fl_Font labelfont () const
 Get item's label font face.
 
void labelsize (Fl_Fontsize val)
 Set item's label font size.
 
Fl_Fontsize labelsize () const
 Get item's label font size.
 
int move (int to, int from)
 Move the item 'from' to sibling position of 'to'. More...
 
int move (Fl_Tree_Item *item, int op=0, int pos=0)
 Move the current item above/below/into the specified 'item', where 'op' determines the type of move: More...
 
int move_above (Fl_Tree_Item *item)
 Move the current item above the specified 'item'. More...
 
int move_below (Fl_Tree_Item *item)
 Move the current item below the specified 'item'. More...
 
int move_into (Fl_Tree_Item *item, int pos=0)
 Parent the current item as a child of the specified 'item'. More...
 
Fl_Tree_Itemnext ()
 Return the next item in the tree. More...
 
Fl_Tree_Itemnext_displayed (Fl_Tree_Prefs &prefs)
 Same as next_visible(). More...
 
Fl_Tree_Itemnext_sibling ()
 Return this item's next sibling. More...
 
Fl_Tree_Itemnext_visible (Fl_Tree_Prefs &prefs)
 Return the next open(), visible() item. More...
 
void open ()
 Open this item and all its children.
 
void open_toggle ()
 Toggle the item's open/closed state.
 
Fl_Tree_Itemparent ()
 Return the parent for this item. Returns NULL if we are the root.
 
const Fl_Tree_Itemparent () const
 Return the const parent for this item. Returns NULL if we are the root.
 
void parent (Fl_Tree_Item *val)
 Set the parent for this item. More...
 
const Fl_Tree_Prefsprefs () const
 Return the parent tree's prefs. More...
 
Fl_Tree_Itemprev ()
 Return the previous item in the tree. More...
 
Fl_Tree_Itemprev_displayed (Fl_Tree_Prefs &prefs)
 Same as prev_visible(). More...
 
Fl_Tree_Itemprev_sibling ()
 Return this item's previous sibling. More...
 
Fl_Tree_Itemprev_visible (Fl_Tree_Prefs &prefs)
 Return the previous open(), visible() item. More...
 
int remove_child (Fl_Tree_Item *item)
 Remove 'item' from the current item's children. More...
 
int remove_child (const char *new_label)
 Remove immediate child (and its children) by its label 'name'. More...
 
int reparent (Fl_Tree_Item *newchild, int index)
 Reparent specified item as a child of ourself at position 'pos'. More...
 
Fl_Tree_Itemreplace (Fl_Tree_Item *new_item)
 Replace the current item with a new item. More...
 
Fl_Tree_Itemreplace_child (Fl_Tree_Item *olditem, Fl_Tree_Item *newitem)
 Replace existing child 'olditem' with 'newitem'. More...
 
void select (int val=1)
 Change the item's selection state to the optionally specified 'val'. More...
 
int select_all ()
 Select item and all its children. More...
 
void select_toggle ()
 Toggle the item's selection state.
 
void show_self (const char *indent="") const
 Print the tree as 'ascii art' to stdout. More...
 
void swap_children (int ax, int bx)
 Swap two of our children, given two child index values 'ax' and 'bx'. More...
 
int swap_children (Fl_Tree_Item *a, Fl_Tree_Item *b)
 Swap two of our immediate children, given item pointers. More...
 
const Fl_Treetree () const
 Return the tree for this item. More...
 
Fl_Treetree ()
 Return the tree for this item. More...
 
void update_prev_next (int index)
 Update our _prev_sibling and _next_sibling pointers to point to neighbors given index as being our current position in the parent's item array. More...
 
void user_data (void *data)
 Set a user-data value for the item.
 
void * user_data () const
 Retrieve the user-data value that has been assigned to the item.
 
void userdeicon (Fl_Image *val)
 Set the usericon to draw when the item is deactivated. More...
 
Fl_Imageuserdeicon () const
 Return the deactivated version of the user icon, if any. More...
 
void usericon (Fl_Image *val)
 Set the item's user icon to an Fl_Image. More...
 
Fl_Imageusericon () const
 Get the item's user icon as an Fl_Image. Returns '0' if disabled.
 
int visible () const
 See if the item is visible. Alias for is_visible().
 
int visible_r () const
 See if item and all its parents are open() and visible(). More...
 
int w () const
 The entire item's width to right edge of Fl_Tree's inner width within scrollbars. More...
 
void widget (Fl_Widget *val)
 Assign an FLTK widget to this item.
 
Fl_Widgetwidget () const
 Return FLTK widget assigned to this item.
 
int x () const
 The item's x position relative to the window.
 
int y () const
 The item's y position relative to the window.
 

Protected Member Functions

void _Init (const Fl_Tree_Prefs &prefs, Fl_Tree *tree)
 
int calc_item_height (const Fl_Tree_Prefs &prefs) const
 Return the item's 'visible' height. More...
 
void draw_horizontal_connector (int x1, int x2, int y, const Fl_Tree_Prefs &prefs)
 Internal: Horizontal connector line based on preference settings. More...
 
void draw_vertical_connector (int x, int y1, int y2, const Fl_Tree_Prefs &prefs)
 Internal: Vertical connector line based on preference settings. More...
 
Fl_Color drawbgcolor () const
 Returns the recommended background color used for drawing this item. More...
 
Fl_Color drawfgcolor () const
 Returns the recommended foreground color used for drawing this item. More...
 
void hide_widgets ()
 Internal: Hide the FLTK widget() for this item and all children. More...
 
int is_flag (unsigned short val) const
 See if flag set. Returns 0 or 1.
 
void recalc_tree ()
 Call this when our geometry is changed. More...
 
void set_flag (unsigned short flag, int val)
 Set a flag to an on or off value. val is 0 or 1.
 
void show_widgets ()
 Internal: Show the FLTK widget() for this item and all children. More...
 

Detailed Description

Tree widget item.

This class is a single tree item, and manages all of the item's attributes. Fl_Tree_Item is used by Fl_Tree, which is comprised of many instances of Fl_Tree_Item.

Fl_Tree_Item is hierarchical; it dynamically manages an Fl_Tree_Item_Array of children that are themselves instances of Fl_Tree_Item. Each item can have zero or more children. When an item has children, close() and open() can be used to hide or show them.

Items have their own attributes; font size, face, color. Items maintain their own hierarchy of children.

When you make changes to items, you'll need to tell the tree to redraw() for the changes to show up.

New 1.3.3 ABI feature: You can define custom items by either adding a custom widget to the item with Fl_Tree_Item::widget(), or override the draw_item_content() method if you want to just redefine how the label is drawn.

The following shows the Fl_Tree_Item's dimensions, useful when overriding the draw_item_content() method:

Fl_Tree_Item-dimensions.png
Fl_Tree_Item's internal dimensions.

Constructor & Destructor Documentation

Fl_Tree_Item::Fl_Tree_Item ( const Fl_Tree_Prefs prefs)

Constructor.

Makes a new instance of Fl_Tree_Item using defaults from 'prefs'.

Deprecated:
in 1.3.3 ABI – you must use Fl_Tree_Item(Fl_Tree*) for proper horizontal scrollbar behavior.
Fl_Tree_Item::Fl_Tree_Item ( Fl_Tree tree)

Constructor.

Makes a new instance of Fl_Tree_Item for 'tree'.

This must be used instead of the older, deprecated Fl_Tree_Item(Fl_Tree_Prefs) constructor for proper horizontal scrollbar calculation.

Version
1.3.3 ABI feature

Member Function Documentation

void Fl_Tree_Item::activate ( int  val = 1)
inline

Change the item's activation state to the optionally specified 'val'.

When deactivated, the item will be 'grayed out'; the callback() won't be invoked if the user clicks on the label. If a widget() is associated with the item, its activation state will be changed as well.

If 'val' is not specified, the item will be activated.

Fl_Tree_Item * Fl_Tree_Item::add ( const Fl_Tree_Prefs prefs,
const char *  new_label,
Fl_Tree_Item item 
)

Add 'item' as immediate child with 'new_label' and defaults from 'prefs'.

If 'item' is NULL, a new item is created. An internally managed copy is made of the label string. Adds the item based on the value of prefs.sortorder().

Returns
the item added
Version
1.3.3
Fl_Tree_Item * Fl_Tree_Item::add ( const Fl_Tree_Prefs prefs,
const char *  new_label 
)

Add a new child to this item with the name 'new_label' and defaults from 'prefs'.

An internally managed copy is made of the label string. Adds the item based on the value of prefs.sortorder().

Returns
the item added
Version
1.3.0 release
Fl_Tree_Item * Fl_Tree_Item::add ( const Fl_Tree_Prefs prefs,
char **  arr,
Fl_Tree_Item newitem 
)

Descend into path specified by 'arr' and add 'newitem' there.

Should be used only by Fl_Tree's internals. If item is NULL, a new item is created. Adds the item based on the value of prefs.sortorder().

Returns
the item added.
Version
1.3.3 ABI feature
Fl_Tree_Item * Fl_Tree_Item::add ( const Fl_Tree_Prefs prefs,
char **  arr 
)

Descend into the path specified by 'arr', and add a new child there.

Should be used only by Fl_Tree's internals. Adds the item based on the value of prefs.sortorder().

Returns
the item added.
Version
1.3.0 release
int Fl_Tree_Item::calc_item_height ( const Fl_Tree_Prefs prefs) const
protected

Return the item's 'visible' height.

Takes into account the item's:

const Fl_Tree_Item * Fl_Tree_Item::child ( int  t) const

Return the const child item for the given 'index'.

Return const child item for the specified 'index'.

void Fl_Tree_Item::deactivate ( )
inline

Deactivate the item; the callback() won't be invoked when clicked.

Same as activate(0)

Fl_Tree_Item * Fl_Tree_Item::deparent ( int  pos)

Deparent child at index position 'pos'.

This creates an "orphaned" item that is still allocated, but has no parent or siblings. Normally the caller would want to immediately reparent the orphan elsewhere.

A successfully orphaned item will have its parent() and prev_sibling()/next_sibling() set to NULL.

Returns
  • pointer to orphaned item on success
  • NULL on error (could not deparent the item)
int Fl_Tree_Item::depth ( ) const

Returns how many levels deep this item is in the hierarchy.

For instance; root has a depth of zero, and its immediate children would have a depth of 1, and so on. Use e.g. for determining the horizontal indent of this item during drawing.

int Fl_Tree_Item::deselect_all ( )
inline

Deselect item and all its children.

Returns count of how many items were in the 'selected' state, ie. how many items were "changed".

void Fl_Tree_Item::draw ( int  X,
int &  Y,
int  W,
Fl_Tree_Item itemfocus,
int &  tree_item_xmax,
int  lastchild = 1,
int  render = 1 
)

Draw this item and its children.

Parameters
[in]XHorizontal position for item being drawn
[in,out]YVertical position for item being drawn, returns new position for next item
[in]WRecommended width for item
[in]itemfocusThe tree's current focus item (if any)
[in,out]tree_item_xmaxThe tree's running xmax (right-most edge so far). Mainly used by parent tree when render==0 to calculate tree's max width.
[in]lastchildIs this item the last child in a subtree?
[in]renderWhether or not to render the item: 0: no rendering, just calculate size w/out drawing. 1: render item as well as size calc
Version
1.3.3 ABI feature: modified parameters
void Fl_Tree_Item::draw_horizontal_connector ( int  x1,
int  x2,
int  y,
const Fl_Tree_Prefs prefs 
)
protected

Internal: Horizontal connector line based on preference settings.

Parameters
[in]x1The left hand X position of the horizontal connector
[in]x2The right hand X position of the horizontal connector
[in]yThe vertical position of the horizontal connector
[in]prefsThe Fl_Tree prefs
int Fl_Tree_Item::draw_item_content ( int  render)
virtual

Draw the item content.

This method can be overridden to implement custom drawing by filling the label_[xywh]() area with content.

A minimal example of how to override draw_item_content() and draw just a normal item's background and label ourselves:

class MyTreeItem : public Fl_Tree_Item {
public:
MyTreeItem() { }
~MyTreeItem() { }
// DRAW OUR CUSTOM CONTENT FOR THE ITEM
int draw_item_content(int render) {
// Our item's dimensions + text content
int X=label_x(), Y=label_y(), W=label_w(), H=label_h();
const char *text = label() ? label() : "";
// Rendering? Do any drawing that's needed
if ( render ) {
// Draw bg -- a filled rectangle
// Draw label
fl_font(labelfont(), labelsize()); // use item's label font/size
fl_color(drawfgcolor()); // use recommended fg color
fl_draw(text, X,Y,W,H, FL_ALIGN_LEFT); // draw the item's label
}
// Rendered or not, we must calculate content's max X position
int lw=0, lh=0;
fl_measure(text, lw, lh); // get width of label text
return X + lw; // return X + label width
}
};

You can draw anything you want inside draw_item_content() using any of the fl_draw.H functions, as long as it's within the label's xywh area.

To add instances of your custom item to the tree, you can use:

// Example #1: using add()
MyTreeItem *bart = new MyTreeItem(..); // class derived from Fl_Tree_Item
tree->add("/Simpsons/Bart", bart); // Add item as /Simpsons/Bart

..or you can insert or replace existing items:

// Example #2: using replace()
MyTreeItem *marge = new MyTreeItem(..); // class derived from Fl_Tree_Item
item = tree->add("/Simpsons/Marge"); // create item
item->replace(mi); // replace it with our own
Parameters
[in]renderWhether we should render content (1), or just tally the geometry (0). Fl_Tree may want only to find the widest item in the tree for scrollbar calculations.
Returns
the right-most X coordinate, or 'xmax' of content we drew, i.e. the "scrollable" content. The tree uses the largest xmax to determine the maximum width of the tree's content (needed for e.g. computing the horizontal scrollbar's size).
Version
1.3.3 ABI feature
void Fl_Tree_Item::draw_vertical_connector ( int  x,
int  y1,
int  y2,
const Fl_Tree_Prefs prefs 
)
protected

Internal: Vertical connector line based on preference settings.

Parameters
[in]xThe x position of the vertical connector
[in]y1The top of the vertical connector
[in]y2The bottom of the vertical connector
[in]prefsThe Fl_Tree prefs
Fl_Color Fl_Tree_Item::drawbgcolor ( ) const
protected

Returns the recommended background color used for drawing this item.

See Also
draw_item_content()
Version
1.3.3 ABI
Fl_Color Fl_Tree_Item::drawfgcolor ( ) const
protected

Returns the recommended foreground color used for drawing this item.

See Also
draw_item_content()
Version
1.3.3 ABI ABI
int Fl_Tree_Item::find_child ( const char *  name)

Return the index of the immediate child of this item that has the label 'name'.

Returns
index of found item, or -1 if not found.
Version
1.3.0 release
int Fl_Tree_Item::find_child ( Fl_Tree_Item item)

Find the index number for the specified 'item' in the current item's list of children.

Returns
the index, or -1 if not found.
const Fl_Tree_Item * Fl_Tree_Item::find_child_item ( const char *  name) const

Return the /immediate/ child of current item that has the label 'name'.

Returns
const found item, or 0 if not found.
Version
1.3.3
const Fl_Tree_Item * Fl_Tree_Item::find_child_item ( char **  arr) const

Find child item by descending array 'arr' of names.

Does not include self in search. Only Fl_Tree should need this method.

Returns
item, or 0 if not found
Version
1.3.0 release
const Fl_Tree_Item * Fl_Tree_Item::find_clicked ( const Fl_Tree_Prefs prefs,
int  yonly = 0 
) const

Find the item that the last event was over.

If 'yonly' is 1, only check event's y value, don't care about x.

Parameters
[in]prefsThe parent tree's Fl_Tree_Prefs
[in]yonly– 0: check both event's X and Y values. – 1: only check event's Y value, don't care about X.
Returns
pointer to clicked item, or NULL if none found
Version
1.3.3 ABI feature
const Fl_Tree_Item * Fl_Tree_Item::find_item ( char **  names) const

Find item by descending array of 'names'.

Includes self in search. Only Fl_Tree should need this method. Use Fl_Tree::find_item() instead.

Returns
const item, or 0 if not found
void Fl_Tree_Item::hide_widgets ( )
protected

Internal: Hide the FLTK widget() for this item and all children.

Used by close() to hide widgets.

Fl_Tree_Item * Fl_Tree_Item::insert ( const Fl_Tree_Prefs prefs,
const char *  new_label,
int  pos = 0 
)

Insert a new item named 'new_label' into current item's children at a specified position 'pos'.

Returns
the new item inserted.
Fl_Tree_Item * Fl_Tree_Item::insert_above ( const Fl_Tree_Prefs prefs,
const char *  new_label 
)

Insert a new item named 'new_label' above this item.

Returns
the new item inserted, or 0 if an error occurred.
void Fl_Tree_Item::label ( const char *  name)

Set the label to 'name'.

Makes and manages an internal copy of 'name'.

int Fl_Tree_Item::label_h ( ) const
inline

The item's label height.

Version
1.3.3
int Fl_Tree_Item::label_w ( ) const
inline

The item's maximum label width to right edge of Fl_Tree's inner width within scrollbars.

Version
1.3.3
int Fl_Tree_Item::label_x ( ) const
inline

The item's label x position relative to the window.

Version
1.3.3
int Fl_Tree_Item::label_y ( ) const
inline

The item's label y position relative to the window.

Version
1.3.3
void Fl_Tree_Item::labelbgcolor ( Fl_Color  val)
inline

Set item's label background color.

A special case is made for color 0xffffffff which uses the parent tree's bg color.

Fl_Color Fl_Tree_Item::labelbgcolor ( ) const
inline

Return item's label background text color.

If the color is 0xffffffff, the default behavior is the parent tree's bg color will be used. (An overloaded draw_item_content() can override this behavior.)

int Fl_Tree_Item::move ( int  to,
int  from 
)

Move the item 'from' to sibling position of 'to'.

Returns
  • 0: Success
  • -1: range error (e.g. if 'to' or 'from' out of range).
  • (Other return values reserved for future use)
int Fl_Tree_Item::move ( Fl_Tree_Item item,
int  op = 0,
int  pos = 0 
)

Move the current item above/below/into the specified 'item', where 'op' determines the type of move:

  • 0: move above 'item' ('pos' ignored)
  • 1: move below 'item' ('pos' ignored)
  • 2: move into 'item' as a child (at optional position 'pos')
Returns
0 on success. a negative number on error:
  • -1: one of the items has no parent
  • -2: item's index could not be determined
  • -3: bad 'op'
  • -4: index range error
  • -5: could not deparent
  • -6: could not reparent at 'pos'
  • (Other return values reserved for future use.)
int Fl_Tree_Item::move_above ( Fl_Tree_Item item)

Move the current item above the specified 'item'.

This is the equivalent of calling move(item,0,0).

Returns
0 on success.
On error returns a negative value; see move(Fl_Tree_Item*,int,int) for possible error codes.
int Fl_Tree_Item::move_below ( Fl_Tree_Item item)

Move the current item below the specified 'item'.

This is the equivalent of calling move(item,1,0).

Returns
0 on success.
On error returns a negative value; see move(Fl_Tree_Item*,int,int) for possible error codes.
int Fl_Tree_Item::move_into ( Fl_Tree_Item item,
int  pos = 0 
)

Parent the current item as a child of the specified 'item'.

This is the equivalent of calling move(item,2,pos).

Returns
0 on success.
On error returns a negative value; see move(Fl_Tree_Item*,int,int) for possible error codes.
Fl_Tree_Item * Fl_Tree_Item::next ( )

Return the next item in the tree.

This method can be used to walk the tree forward. For an example of how to use this method, see Fl_Tree::first().

Returns
the next item in the tree, or 0 if there's no more items.
Fl_Tree_Item * Fl_Tree_Item::next_displayed ( Fl_Tree_Prefs prefs)

Same as next_visible().

Deprecated:
in 1.3.3 for confusing name, use next_visible() instead
Fl_Tree_Item * Fl_Tree_Item::next_sibling ( )

Return this item's next sibling.

Moves to the next item below us at the same level (sibling). Use this to move down the tree without changing depth(). effectively skipping over this item's children/descendents.

Returns
item's next sibling, or 0 if none.
Fl_Tree_Item * Fl_Tree_Item::next_visible ( Fl_Tree_Prefs prefs)

Return the next open(), visible() item.

(If this item has children and is closed, children are skipped)

This method can be used to walk the tree forward, skipping items that are not currently open/visible to the user.

Returns
the next open() visible() item below us, or 0 if there's no more items.
Version
1.3.3
void Fl_Tree_Item::parent ( Fl_Tree_Item val)
inline

Set the parent for this item.

Should only be used by Fl_Tree's internals.

const Fl_Tree_Prefs & Fl_Tree_Item::prefs ( ) const

Return the parent tree's prefs.

Returns
a reference to the parent tree's Fl_Tree_Prefs
Version
1.3.3 ABI feature
Fl_Tree_Item * Fl_Tree_Item::prev ( )

Return the previous item in the tree.

This method can be used to walk the tree backwards. For an example of how to use this method, see Fl_Tree::last().

Returns
the previous item in the tree, or 0 if there's no item above this one (hit the root).
Fl_Tree_Item * Fl_Tree_Item::prev_displayed ( Fl_Tree_Prefs prefs)

Same as prev_visible().

Deprecated:
in 1.3.3 for confusing name, use prev_visible()
Fl_Tree_Item * Fl_Tree_Item::prev_sibling ( )

Return this item's previous sibling.

Moves to the previous item above us at the same level (sibling). Use this to move up the tree without changing depth().

Returns
This item's previous sibling, or 0 if none.
Fl_Tree_Item * Fl_Tree_Item::prev_visible ( Fl_Tree_Prefs prefs)

Return the previous open(), visible() item.

(If this item above us has children and is closed, its children are skipped)

This method can be used to walk the tree backward, skipping items that are not currently open/visible to the user.

Returns
the previous open() visible() item above us, or 0 if there's no more items.
void Fl_Tree_Item::recalc_tree ( )
protected

Call this when our geometry is changed.

(Font size, label contents, etc) Schedules tree to recalculate itself, as changes to us may affect tree widget's scrollbar visibility and tab sizes.

Version
1.3.3 ABI
int Fl_Tree_Item::remove_child ( Fl_Tree_Item item)

Remove 'item' from the current item's children.

Returns
0 if removed, -1 if item not an immediate child.
int Fl_Tree_Item::remove_child ( const char *  name)

Remove immediate child (and its children) by its label 'name'.

If more than one item matches 'name', only the first matching item is removed.

Parameters
[in]nameThe label name of the immediate child to remove
Returns
0 if removed, -1 if not found.
Version
1.3.3
int Fl_Tree_Item::reparent ( Fl_Tree_Item newchild,
int  pos 
)

Reparent specified item as a child of ourself at position 'pos'.

Typically 'newchild' was recently orphaned with deparent().

Returns
  • 0: on success
  • -1: on error (e.g. if 'pos' out of range) with no changes made.
Fl_Tree_Item * Fl_Tree_Item::replace ( Fl_Tree_Item newitem)

Replace the current item with a new item.

The current item is destroyed if successful. No checks are made to see if an item with the same name exists.

This method can be used to, for example, install 'custom' items into the tree derived from Fl_Tree_Item; see draw_item_content().

Parameters
[in]newitemThe new item to replace the current item
Returns
newitem on success, NULL if could not be replaced.
See Also
Fl_Tree_Item::draw_item_content(), Fl_Tree::root(Fl_Tree_Item*)
Version
1.3.3 ABI feature
Fl_Tree_Item * Fl_Tree_Item::replace_child ( Fl_Tree_Item olditem,
Fl_Tree_Item newitem 
)

Replace existing child 'olditem' with 'newitem'.

The 'olditem' is destroyed if successful. Can be used to put custom items (derived from Fl_Tree_Item) into the tree. No checks are made to see if an item with the same name exists.

Parameters
[in]olditemThe item to be found and replaced
[in]newitemThe new item to take the place of 'olditem'
Returns
newitem on success and 'olditem' is destroyed. NULL on error if 'olditem' was not found as an immediate child.
See Also
replace(), Fl_Tree_Item::draw()
Version
1.3.3 ABI feature
void Fl_Tree_Item::select ( int  val = 1)
inline

Change the item's selection state to the optionally specified 'val'.

If 'val' is not specified, the item will be selected.

int Fl_Tree_Item::select_all ( )
inline

Select item and all its children.

Returns count of how many items were in the 'deselected' state, ie. how many items were "changed".

void Fl_Tree_Item::show_self ( const char *  indent = "") const

Print the tree as 'ascii art' to stdout.

Used mainly for debugging.

void Fl_Tree_Item::show_widgets ( )
protected

Internal: Show the FLTK widget() for this item and all children.

Used by open() to re-show widgets that were hidden by a previous close()

void Fl_Tree_Item::swap_children ( int  ax,
int  bx 
)

Swap two of our children, given two child index values 'ax' and 'bx'.

Use e.g. for sorting.
This method is FAST, and does not involve lookups.
No range checking is done on either index value.

Parameters
[in]ax,bxthe index of the items to swap
int Fl_Tree_Item::swap_children ( Fl_Tree_Item a,
Fl_Tree_Item b 
)

Swap two of our immediate children, given item pointers.

Use e.g. for sorting.

This method is SLOW because it involves linear lookups.
For speed, use swap_children(int,int) instead.

Parameters
[in]a,bThe item ptrs of the two items to swap. Both must be immediate children of the current item.
Returns
  • 0 : OK
  • -1 : failed: item 'a' or 'b' is not our child.
const Fl_Tree* Fl_Tree_Item::tree ( ) const
inline

Return the tree for this item.

Version
1.3.3 (ABI feature)
Fl_Tree* Fl_Tree_Item::tree ( )
inline

Return the tree for this item.

Version
1.3.4 (ABI feature)
void Fl_Tree_Item::update_prev_next ( int  index)

Update our _prev_sibling and _next_sibling pointers to point to neighbors given index as being our current position in the parent's item array.

Call this whenever items in the array are added/removed/moved/swapped/etc.

Parameters
[in]indexOur index# in the parent.
Special case if index=-1: become an orphan; null out all parent/sibling associations.
void Fl_Tree_Item::userdeicon ( Fl_Image val)
inline

Set the usericon to draw when the item is deactivated.

Use '0' to disable. No internal copy is made; caller must manage icon's memory.

To create a typical 'grayed out' version of your usericon image, you can do the following:

// Create tree + usericon for items
Fl_Tree *tree = new Fl_Tree(..);
Fl_Image *usr_icon = new Fl_Pixmap(..); // your usericon
Fl_Image *de_icon = usr_icon->copy(); // make a copy, and..
de_icon->inactive(); // make it 'grayed out'
...
for ( .. ) { // item loop..
item = tree->add("..."); // create new item
item->usericon(usr_icon); // assign usericon to items
item->userdeicon(de_icon); // assign userdeicon to items
..
}

In the above example, the app should 'delete' the two icons when they're no longer needed (e.g. after the tree is destroyed)

Version
1.3.4
Fl_Image* Fl_Tree_Item::userdeicon ( ) const
inline

Return the deactivated version of the user icon, if any.

Returns 0 if none.

void Fl_Tree_Item::usericon ( Fl_Image val)
inline

Set the item's user icon to an Fl_Image.

Use '0' to disable. No internal copy is made, caller must manage icon's memory.

Note, if you expect your items to be deactivated(), use userdeicon(Fl_Image*) to set up a 'grayed out' version of your icon to be used for display.

See Also
userdeicon(Fl_Image*)
int Fl_Tree_Item::visible_r ( ) const

See if item and all its parents are open() and visible().

Returns
1 – item and its parents are open() and visible() 0 – item (or one of its parents) are invisible or close()ed.
int Fl_Tree_Item::w ( ) const
inline

The entire item's width to right edge of Fl_Tree's inner width within scrollbars.


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