FLTK 1.3.2
Fl_Tree_Item Class Reference

Tree 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)
 Add a new child to this item with the name 'new_label', with defaults from 'prefs'. 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...
 
int calc_item_height (const Fl_Tree_Prefs &prefs) const
 Return the item's 'visible' height. 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...
 
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_Widget *tree, Fl_Tree_Item *itemfocus, const Fl_Tree_Prefs &prefs, int lastchild=1)
 Draw this item and its children.
 
int event_on_collapse_icon (const Fl_Tree_Prefs &prefs) const
 Was the event on the 'collapse' button?
 
int event_on_label (const Fl_Tree_Prefs &prefs) const
 Was event on the label()?
 
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 (char **arr) const
 Find child item by descending array of names. More...
 
Fl_Tree_Itemfind_child_item (char **arr)
 Find child item by descending array of names. More...
 
const Fl_Tree_Itemfind_clicked (const Fl_Tree_Prefs &prefs) const
 Find the item that the last event was over. More...
 
Fl_Tree_Itemfind_clicked (const Fl_Tree_Prefs &prefs)
 Non-const version of the above. More...
 
const Fl_Tree_Itemfind_item (char **arr) const
 Find item by descending array of names. More...
 
Fl_Tree_Itemfind_item (char **arr)
 Find item by descending array of names. More...
 
 Fl_Tree_Item (const Fl_Tree_Prefs &prefs)
 Constructor. More...
 
 Fl_Tree_Item (const Fl_Tree_Item *o)
 Copy constructor.
 
int h () const
 
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 into current item's children at a specified position. More...
 
Fl_Tree_Iteminsert_above (const Fl_Tree_Prefs &prefs, const char *new_label)
 Insert a new item above this item. More...
 
char is_activated () const
 See if the item is activated.
 
char is_active () const
 See if the item 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. Makes a copy of the name.
 
const char * label () const
 Return the label.
 
void labelbgcolor (Fl_Color val)
 Set item's label background color. More...
 
Fl_Color labelbgcolor () const
 Return item's background text color. More...
 
void labelcolor (Fl_Color val)
 Set item's label text color.
 
Fl_Color labelcolor () const
 Return item's label text color.
 
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.
 
Fl_Tree_Itemnext ()
 Return the next item in the tree. More...
 
Fl_Tree_Itemnext_displayed (Fl_Tree_Prefs &prefs)
 Return the next visible item. More...
 
Fl_Tree_Itemnext_sibling ()
 Return this item's next sibling. 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...
 
Fl_Tree_Itemprev ()
 Return the previous item in the tree. More...
 
Fl_Tree_Itemprev_displayed (Fl_Tree_Prefs &prefs)
 Return the previous visible item. More...
 
Fl_Tree_Itemprev_sibling ()
 Return this item's previous sibling. More...
 
int remove_child (Fl_Tree_Item *item)
 Remove child by item. More...
 
int remove_child (const char *new_label)
 Remove immediate child (and its children) by its label 'name'. 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. More...
 
int swap_children (Fl_Tree_Item *a, Fl_Tree_Item *b)
 Swap two of our children, given item pointers. 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 usericon (Fl_Image *val)
 Set the item's user icon to an Fl_Image. '0' will disable.
 
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
 Returns if item and all its parents are visible. More...
 
int w () const
 
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
 
int y () const
 

Protected Member Functions

void draw_horizontal_connector (int x1, int x2, int y, const Fl_Tree_Prefs &prefs)
 Internal: Horizontal connector line based on preference settings.
 
void draw_vertical_connector (int x, int y1, int y2, const Fl_Tree_Prefs &prefs)
 Internal: Vertical connector line based on preference settings.
 
void hide_widgets ()
 Internal: Hide the FLTK widget() for this item and all children. More...
 
int is_flag (unsigned short flag) const
 See if flag set. Returns 0 or 1.
 
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 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.

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'.

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 the item has a widget() 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 
)

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

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

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.
int Fl_Tree_Item::calc_item_height ( const Fl_Tree_Prefs prefs) const

Return the item's 'visible' height.

Doesn't include linespacing(); prevents affecting eg. height of widget().

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

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

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

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.

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

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.
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 ( char **  arr) const

Find child item by descending array of names.

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

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

Find child item by descending array of names.

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

Returns
item, or 0 if not found
const Fl_Tree_Item * Fl_Tree_Item::find_clicked ( const Fl_Tree_Prefs prefs) const

Find the item that the last event was over.

Returns the item if it is visible, and mouse is over it. Works even if widget deactivated. Use event_on_collapse_icon() to determine if collapse button was pressed.

Returns
const visible item under the event if found, or 0 if none.
Fl_Tree_Item * Fl_Tree_Item::find_clicked ( const Fl_Tree_Prefs prefs)

Non-const version of the above.

Find the item that the last event was over.

Returns the item if it is visible, and mouse is over it. Works even if widget deactivated. Use event_on_collapse_icon() to determine if collapse button was pressed.

Returns
the visible item under the event if found, or 0 if none.
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
item, or 0 if not found
Fl_Tree_Item * Fl_Tree_Item::find_item ( char **  names)

Find item by descending array of names.

Includes self in search. Only Fl_Tree should need this method.

Returns
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 into current item's children at a specified position.

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 above this item.

Returns
the new item inserted, or 0 if an error occurred.
void Fl_Tree_Item::labelbgcolor ( Fl_Color  val)
inline

Set item's label background color.

A special case is made for color 0xffffffff which is treated as 'transparent'.

Fl_Color Fl_Tree_Item::labelbgcolor ( ) const
inline

Return item's background text color.

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

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)

Return the next 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 visible to the user.

Returns
the next visible item below us, or 0 if there's no more items.
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 moving deeper into the tree, effectively skipping over this item's children/descendents.

Returns
item's next sibling, or 0 if none.
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.

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)

Return the previous 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 visible to the user.

Returns
the previous visible item above us, or 0 if there's no more items.
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 moving deeper into the tree.

Returns
This item's previous sibling, or 0 if none.
int Fl_Tree_Item::remove_child ( Fl_Tree_Item item)

Remove child by item.

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'.

Returns
0 if removed, -1 if not found.
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.

Use this eg. for sorting.

This method is FAST, and does not involve lookups.

No range checking is done on either index value.

Returns
  • 0 : OK
  • -1 : failed: 'a' or 'b' is not our immediate child
int Fl_Tree_Item::swap_children ( Fl_Tree_Item a,
Fl_Tree_Item b 
)

Swap two of our children, given item pointers.

Use this eg. for sorting.

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

Returns
  • 0 : OK
  • -1 : failed: 'a' or 'b' is not our immediate child
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.

int Fl_Tree_Item::visible_r ( ) const

Returns if item and all its parents are visible.

Also takes into consideration if any parent is close()ed.

Returns
1 – item and its parents are visible/open() 0 – item (or parents) invisible or close()ed.

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