From 7faf6694227a4640be8dc6642dcf65f350eea1fb Mon Sep 17 00:00:00 2001
From: Greg Ercolano <erco@seriss.com>
Date: Tue, 1 Feb 2011 14:13:18 +0000
Subject: [PATCH] Documentation fixups, code examples added.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8352 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 FL/Fl_Tree.H | 50 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 4 deletions(-)

diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H
index 82185d56a..c6ddfb5da 100644
--- a/FL/Fl_Tree.H
+++ b/FL/Fl_Tree.H
@@ -54,10 +54,8 @@
 ///                  |--- Fl_Tree_Sort (enum)           // Sort behavior
 /// \endcode
 ///
-///     An expandable tree widget.
-///
-///     Similar to Fl_Browser, Fl_Tree is browser of Fl_Tree_Item's, which can be
-///     in a parented hierarchy. Subtrees can be expanded or closed. Items can be
+///     Similar to Fl_Browser, Fl_Tree is a browser of Fl_Tree_Item's, which is arranged
+///     in a parented hierarchy, or 'tree'. Subtrees can be expanded or closed. Items can be
 ///     added, deleted, inserted, sorted and re-ordered.
 ///
 ///     The tree items may also contain other FLTK widgets, like buttons, input fields,
@@ -116,6 +114,50 @@
 ///     when() controls when mouse/keyboard events invoke the callback.
 ///     callback_item() and callback_reason() can be used to determine the cause of the callback.
 ///
+///     To walk all the items of the tree from top to bottom:
+/// \code
+/// // 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());
+/// }
+/// \endcode
+///
+///     To recursively walk all the children of a particular item, 
+///     define a function that uses recursion:
+///     \code
+/// // 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
+///     }
+/// }
+///     \endcode
+///
+///     To change the default label font and color for creating new items:
+/// \code
+///  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");
+///  [..]
+/// \endcode
+///
+///     To change the font and color of all items in the tree:
+/// \code
+/// // 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);
+/// }
+/// \endcode
+///
+///     The following image shows the tree's various visual elements
+///     and the methods that control them:
+///     
 ///     \image html tree-elements.png
 ///     \image latex tree-elements.png "Fl_Tree dimensions" width=6cm
 ///