Fl_Tree documentation fixes for html/pdf, doxygen 1.8.5

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@13008 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

2 files changed, 569 insertions, 569 deletions

diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H
index 119662887..63c06240a 100644
--- a/FL/Fl_Tree.H
+++ b/FL/Fl_Tree.H
@@ -36,280 +36,239 @@
 /// \brief This file contains the definitions of the Fl_Tree class
 ///
 
-/// \class Fl_Tree
-///
-/// \brief Tree widget.
-///
-///     \image html tree-simple.png "Fl_Tree example program"
-///     \image latex tree-simple.png "Fl_Tree example program" width=4cm
-///
-/// \code
-///     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
-/// \endcode
-///     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:
-/// \code
-///    #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();
-/// \endcode
-///     
-/// \par FEATURES
-///     Items can be added with add(),<BR>
-///     removed with remove(),<BR>
-///     completely cleared with clear(),<BR>
-///     inserted with insert() and insert_above(),<BR>
-///     selected/deselected with select() and deselect(),<BR>
-///     open/closed with open() and close(),<BR>
-///     positioned on the screen with show_item_top(), show_item_middle() and
-///     show_item_bottom(),<BR>
-///     item children can be swapped around with Fl_Tree_Item::swap_children(),<BR>
-///     items can be moved around with Fl_Tree_Item::move(),<BR>
-///     an item's children can be walked with Fl_Tree_Item::first() and Fl_Tree_Item::next(),
-///     an item's children can be indexed directly with Fl_Tree_Item::child()
-///     and Fl_Tree_Item::children(),<BR>
-///     items can be moved from one subtree to another with Fl_Tree_Item::deparent()
-///     and Fl_Tree_Item::reparent(),<BR>
-///     sorting can be controlled when items are add()ed via sortorder().<BR>
-///     You can walk the entire tree with first() and next().<BR>
-///     You can walk visible items with first_visible_item()
-///     and next_visible_item().<BR>
-///     You can walk selected items with first_selected_item() and
-///     next_selected_item().<BR>
-///     Items can be found by their pathname using find_item(const char*),
-///     and an item's pathname can be found with item_pathname().<BR>
-///     The selected items' colors are controlled by selection_color()
-///     (inherited from Fl_Widget).<BR>
-///     A hook is provided to allow you to redefine how item's labels are drawn
-///     via Fl_Tree::item_draw_callback().<BR>
-///
-/// \par 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().
-///
-/// \par CHILD WIDGETS
-///     FLTK widgets (including custom widgets) can be assigned to tree items via
-///     Fl_Tree_Item::widget().
-/// \par
-///     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.
-///
-/// \par 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().
-/// \par
-///     Various default preferences can be globally manipulated via Fl_Tree_Prefs, 
-///     including colors, margins, icons, connection lines, etc. 
-///
-/// \par FONTS AND COLORS
-///     When adding new items to the tree, the new items get the
-///     defaults for fonts and colors from:
-/// \par
-///	- 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')
-/// \par
-///     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:
-/// \par
-///	- 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)
-///
-/// \par 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.
-/// \par
-/// \code
-/// 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: [..]
-///   }
-/// \endcode
-///
-/// \par SIMPLE EXAMPLES
-///     To find all the selected items:
-/// \code
-/// for ( Fl_Tree_Item *i=first_selected_item(); i; i=next_selected_item(i) )
-///   printf("Item %s is selected\n", i->label());
-/// \endcode
-///     To get an item's full menu pathname, use Fl_Tree::item_pathname(), e.g.
-/// \code
-///   char pathname[256] = "???";
-///   tree->item_pathname(pathname, sizeof(pathname), item);		// eg. "Parent/Child/Item"
-/// \endcode
-/// \par
-///     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
-/// \par
-///     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
-/// \par
-///     To change the default label font and color when 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
-/// \par
-///     To change the font and color of all existing 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
-///
-/// \par DISPLAY DESCRIPTION
-///     The following image shows the tree's various visual elements
-///     and the methods that control them:
-/// \par
-///     \image html tree-elements.png
-///     \image latex tree-elements.png "Fl_Tree elements" width=6cm
-/// \par
-///     The following shows the protected dimension variables 'tree inner' (tix..)
-///     and 'tree outer' (tox..):
-///     \image html tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
-///     \image latex tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
-///
-/// \par KEYBOARD BINDINGS
-///     The following table lists keyboard bindings for navigating the tree:
-///
-///  <TABLE BORDER="1" SUMMARY="Fl_Tree keyboard bindings.">
-///    <CAPTION ALIGN=TOP>Fl_Tree keyboard bindings.</CAPTION>
-///  <TR>
-///    <TD WIDTH=25% ALIGN=CENTER><B>Keyboard</B></TD>
-///    <TD WIDTH=25% ALIGN=CENTER><B>FL_TREE_SELECT_MULTI</B></TD>
-///    <TD WIDTH=25% ALIGN=CENTER><B>FL_TREE_SELECT_SINGLE</B></TD>
-///    <TD WIDTH=25% ALIGN=CENTER><B>FL_TREE_SELECT_NONE</B></TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Ctrl-A</B> (Linux/Windows)<BR><B>Command-A</B> (Mac)</TD>
-///    <TD ALIGN=CENTER>Select all items.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Space </B></TD>
-///    <TD ALIGN=CENTER>Selects item.</TD>
-///    <TD ALIGN=CENTER>Selects item.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Ctrl-Space </B></TD>
-///    <TD ALIGN=CENTER>Toggle item.</TD>
-///    <TD ALIGN=CENTER>Toggle item.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Shift-Space </B></TD>
-///    <TD ALIGN=CENTER>Extends selection<BR>from last item.</TD>
-///    <TD ALIGN=CENTER>Selects item.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Enter,<BR>Ctrl-Enter,<BR>Shift-Enter </B></TD>
-///    <TD ALIGN=CENTER>Toggles open/close</TD>
-///    <TD ALIGN=CENTER>Toggles open/close</TD>
-///    <TD ALIGN=CENTER>Toggles open/close</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Right / Left</B></TD>
-///    <TD ALIGN=CENTER>Open/Close item.</TD>
-///    <TD ALIGN=CENTER>Open/Close item.</TD>
-///    <TD ALIGN=CENTER>Open/Close item.</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Up / Down</B></TD>
-///    <TD ALIGN=CENTER>Move focus box up/down.</TD>
-///    <TD ALIGN=CENTER>Move focus box up/down.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Shift-Up / Shift-Down</B></TD>
-///    <TD ALIGN=CENTER>Extend selection up/down.</TD>
-///    <TD ALIGN=CENTER>Move focus up/down.</TD>
-///    <TD ALIGN=CENTER>N/A</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>Home / End</B></TD>
-///    <TD ALIGN=CENTER>Move to top/bottom of tree.</TD>
-///    <TD ALIGN=CENTER>Move to top/bottom of tree.</TD>
-///    <TD ALIGN=CENTER>Move to top/bottom of tree.</TD>
-///
-///  </TR><TR>
-///    <TD ALIGN=CENTER><B>PageUp / PageDown</B></TD>
-///    <TD ALIGN=CENTER>Page up/down.</TD>
-///    <TD ALIGN=CENTER>Page up/down.</TD>
-///    <TD ALIGN=CENTER>Page up/down.</TD>
-///
-///  </TD></TR></TABLE>
-///
+/** \class Fl_Tree
+
+ \brief Tree widget.
+
+ \image html tree-simple.png "Fl_Tree example program"
+ \image latex tree-simple.png "Fl_Tree example program" width=4cm
+
+ \code
+ 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
+ \endcode
+
+ 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:
+ \par
+ \code
+ #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();
+ \endcode
+     
+ \par FEATURES
+ Items can be added with add(),<BR>
+ removed with remove(),<BR>
+ completely cleared with clear(),<BR>
+ inserted with insert() and insert_above(),<BR>
+ selected/deselected with select() and deselect(),<BR>
+ open/closed with open() and close(),<BR>
+ positioned on the screen with show_item_top(), show_item_middle() and
+ show_item_bottom(),<BR>
+ item children can be swapped around with Fl_Tree_Item::swap_children(),<BR>
+ items can be moved around with Fl_Tree_Item::move(),<BR>
+ an item's children can be walked with Fl_Tree_Item::first() and Fl_Tree_Item::next(),
+ an item's children can be indexed directly with Fl_Tree_Item::child()
+ and Fl_Tree_Item::children(),<BR>
+ items can be moved from one subtree to another with Fl_Tree_Item::deparent()
+ and Fl_Tree_Item::reparent(),<BR>
+ sorting can be controlled when items are add()ed via sortorder().<BR>
+ You can walk the entire tree with first() and next().<BR>
+ You can walk visible items with first_visible_item()
+ and next_visible_item().<BR>
+ You can walk selected items with first_selected_item() and
+ next_selected_item().<BR>
+ Items can be found by their pathname using find_item(const char*),
+ and an item's pathname can be found with item_pathname().<BR>
+ The selected items' colors are controlled by selection_color()
+ (inherited from Fl_Widget).<BR>
+ A hook is provided to allow you to redefine how item's labels are drawn
+ via Fl_Tree::item_draw_callback().<BR>
+
+ \par 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().
+
+ \par CHILD WIDGETS
+ FLTK widgets (including custom widgets) can be assigned to tree items via
+ Fl_Tree_Item::widget().
+ \par
+ 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.
+
+ \par 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().
+ \par
+ Various default preferences can be globally manipulated via Fl_Tree_Prefs, 
+ including colors, margins, icons, connection lines, etc. 
+
+ \par FONTS AND COLORS
+ When adding new items to the tree, the new items get the
+ defaults for fonts and colors from:
+ \par
+ - 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')
+ \par
+ 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:
+ \par
+ - 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)
+
+ \par 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.
+ \par
+ \code
+ 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: [..]
+   }
+   :
+ }
+ \endcode
+
+ \par SIMPLE EXAMPLES
+ To find all the selected items:
+ \par
+ \code
+ for ( Fl_Tree_Item *i=first_selected_item(); i; i=next_selected_item(i) )
+   printf("Item %s is selected\n", i->label());
+ \endcode
+ \par
+     To get an item's full menu pathname, use Fl_Tree::item_pathname(), e.g.
+ \par
+ \code
+ [..]
+ char pathname[256] = "???";
+ tree->item_pathname(pathname, sizeof(pathname), item);		// eg. "Parent/Child/Item"
+ [..]
+ \endcode
+ \par
+ To walk all the items of the tree from top to bottom:
+ \par
+ \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
+ \par
+ To recursively walk all the children of a particular item, 
+ define a function that uses recursion:
+ \par
+ \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
+ \par
+ To change the default label font and color when creating new items:
+ \par
+ \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
+ \par
+ To change the font and color of all existing items in the tree:
+ \par
+ \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
+
+ \par DISPLAY DESCRIPTION
+ The following image shows the tree's various visual elements
+ and the methods that control them:
+ \par
+ \image html tree-elements.png
+ \image latex tree-elements.png "Fl_Tree elements" width=6cm
+ \par
+ The following shows the protected dimension variables 'tree inner' (tix..)
+ and 'tree outer' (tox..):
+ \image html tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
+ \image latex tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
+
+ \par KEYBOARD BINDINGS
+ The following table lists keyboard bindings for navigating the tree:
+ \par
+ Keyboard                | FL_TREE_SELECT_MULTI        | FL_TREE_SELECT_SINGLE       | FL_TREE_SELECT_NONE         |
+ ------------------------|-----------------------------|-----------------------------|-----------------------------|
+ Ctrl-A (Linux/Windows)  | Select all items            | N/A                         | N/A                         |
+ 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           | Selects item                | N/A                         |
+ Enter                   | Toggles open/close          | Toggles open/close          | Toggles open/close          |
+ Ctrl-Enter              | Toggles open/close          | Toggles open/close          | Toggles open/close          |
+ 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                |
+
+*/
 
 /// \enum Fl_Tree_Reason
 /// The reason the callback was invoked.
diff --git a/src/Fl_Tree.cxx b/src/Fl_Tree.cxx
index 115683390..a658a38c7 100644
--- a/src/Fl_Tree.cxx
+++ b/src/Fl_Tree.cxx
@@ -630,11 +630,10 @@ void Fl_Tree::calc_dimensions() {
 /// 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 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.
@@ -800,24 +799,27 @@ void Fl_Tree::root(Fl_Tree_Item *newitem) {
   _root = newitem;
 }
 
-/// Adds a new item, given a menu style \p 'path'.
-/// Any parent nodes that don't already exist are created automatically.
-/// Adds the item based on the value of sortorder().
-/// If \p '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.
-/// \code
-///     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"
-/// \endcode
-/// \param[in] path The path to the item, e.g. "Flintstone/Fred".
-/// \param[in] item The new item to be added.
-///                 If NULL, a new item is created with
-///                 a name that is the last element in \p 'path'.
-/// \returns The new item added, or 0 on error.
-/// \version 1.3.3
-///
+/** Adds a new item, given a menu style \p 'path'.
+ Any parent nodes that don't already exist are created automatically.
+ Adds the item based on the value of sortorder().
+ If \p '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.
+ \par
+ \code
+ :
+ 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"
+ :
+ \endcode
+ \param[in] path The path to the item, e.g. "Flintstone/Fred".
+ \param[in] item The new item to be added.
+                 If NULL, a new item is created with
+                 a name that is the last element in \p 'path'.
+ \returns The new item added, or 0 on error.
+ \version 1.3.3
+*/
 Fl_Tree_Item* Fl_Tree::add(const char *path, Fl_Tree_Item *item) {
   // Tree has no root? make one
   if ( ! _root ) {
@@ -845,46 +847,52 @@ Fl_Tree_Item* Fl_Tree::add(Fl_Tree_Item *parent_item, const char *name) {
   return(parent_item->add(_prefs, name));
 }
 
-/// Inserts a new item \p 'name' above the specified Fl_Tree_Item \p 'above'.
-/// Example:
-/// \code
-/// 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
-/// \endcode
-///
-/// \param[in] above -- the item above which to insert the new item. Must not be NULL.
-/// \param[in] name -- the name of the new item
-/// \returns The new item added, or 0 if 'above' could not be found.
-/// \see insert()
-/// 
+/**
+ Inserts a new item \p 'name' above the specified Fl_Tree_Item \p 'above'.
+ Example:
+ \par
+ \code
+ :
+ 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
+ :
+ \endcode
+ 
+ \param[in] above -- the item above which to insert the new item. Must not be NULL.
+ \param[in] name -- the name of the new item
+ \returns The new item added, or 0 if 'above' could not be found.
+ \see insert()
+*/
 Fl_Tree_Item* Fl_Tree::insert_above(Fl_Tree_Item *above, const char *name) {
   return(above->insert_above(_prefs, name));
 }
 
-/// Insert a new item \p 'name' into \p 'item's children at position \p 'pos'.
-///
-/// Example:
-/// \code
-/// 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
-/// \endcode
-///
-/// \param[in] item The existing item to insert new child into. Must not be NULL.
-/// \param[in] name The label for the new item
-/// \param[in] pos The position of the new item in the child list
-/// \returns The new item added.
-/// \see insert_above()
-///
+/**
+ Insert a new item \p 'name' into \p 'item's children at position \p 'pos'.
+ Example:
+ \par
+ \code
+ :
+ 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
+ :
+ \endcode
+ \param[in] item The existing item to insert new child into. Must not be NULL.
+ \param[in] name The label for the new item
+ \param[in] pos The position of the new item in the child list
+ \returns The new item added.
+ \see insert_above()
+*/
 Fl_Tree_Item* Fl_Tree::insert(Fl_Tree_Item *item, const char *name, int pos) {
   return(item->insert(_prefs, name, pos));
 }
@@ -930,23 +938,26 @@ void Fl_Tree::clear_children(Fl_Tree_Item *item) {
   }
 } 
 
-/// 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.
-///
-/// \code
-///     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"
-/// \endcode
-///
-/// \param[in] path -- the tree item's pathname to be found (e.g. "Flintstones/Fred")
-/// \returns The item, or NULL if not found.
-/// \see item_pathname()
-///
+/**
+ 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.
+ \par
+ \code
+ :
+ 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"
+ :
+ \endcode
+
+ \param[in] path -- the tree item's pathname to be found (e.g. "Flintstones/Fred")
+ \returns The item, or NULL if not found.
+ \see item_pathname()
+*/
 const Fl_Tree_Item *Fl_Tree::find_item(const char *path) const {
   if ( ! _root ) return(NULL);
   char **arr = parse_path(path);
@@ -1067,41 +1078,47 @@ Fl_Tree_Item* Fl_Tree::item_clicked() {
   return(_callback_item);
 }
 
-/// Returns next open(), visible item above (\p dir==FL_Up)
-/// or below (\p dir==FL_Down) the specified \p 'item', or 0 if no more items.
-///
-/// If \p 'item' is 0, returns last() if \p 'dir' is FL_Up,
-/// or first() if \p dir is FL_Down.
-///
-/// \code
-/// // 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());
-/// \endcode
-/// \param[in] item The item above/below which we'll find the next visible item
-/// \param[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 \p item.
-/// \version 1.3.3
-///
+/**
+ Returns next open(), visible item above (\p dir==FL_Up)
+ or below (\p dir==FL_Down) the specified \p 'item', or 0 if no more items.
+
+ If \p 'item' is 0, returns last() if \p 'dir' is FL_Up,
+ or first() if \p dir is FL_Down.
+ \par
+ \code
+ :
+ // 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());
+ :
+ \endcode
+ \param[in] item The item above/below which we'll find the next visible item
+ \param[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 \p item.
+ \version 1.3.3
+*/
 Fl_Tree_Item *Fl_Tree::next_visible_item(Fl_Tree_Item *item, int dir) {
   return next_item(item, dir, true);
 }
 
-/// Returns the first item in the tree, or 0 if none.
-///
-/// Use this to walk the tree in the forward direction, e.g.
-/// \code
-/// for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) )
-///     printf("Item: %s\n", item->label());
-/// \endcode
-///
-/// \returns First item in tree, or 0 if none (tree empty).
-/// \see first(), next(), last(), prev()
-///
+/**
+ Returns the first item in the tree, or 0 if none.
+
+ Use this to walk the tree in the forward direction, e.g.
+ \par
+ \code
+ :
+ for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) )
+     printf("Item: %s\n", item->label());
+ :
+ \endcode
+ \returns First item in tree, or 0 if none (tree empty).
+ \see first(), next(), last(), prev()
+*/
 Fl_Tree_Item* Fl_Tree::first() {
   return(_root);				// first item always root
 }
@@ -1127,54 +1144,55 @@ Fl_Tree_Item* Fl_Tree::first_visible_item() {
   return(0);
 }
 
-/// Return the next item after \p 'item', or 0 if no more items.
-///
-/// Use this code to walk the entire tree:
-/// \code
-/// for ( Fl_Tree_Item *i = tree->first(); i; i = tree->next(i) )
-///     printf("Item: %s\n", i->label());
-/// \endcode
-///
-/// \param[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 first(), next(), last(), prev()
-///
+/**
+ Return the next item after \p 'item', or 0 if no more items.
+ Use this code to walk the entire tree:
+ \par
+ \code
+ :
+ for ( Fl_Tree_Item *i = tree->first(); i; i = tree->next(i) )
+     printf("Item: %s\n", i->label());
+ :
+ \endcode
+ \param[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 first(), next(), last(), prev()
+*/
 Fl_Tree_Item *Fl_Tree::next(Fl_Tree_Item *item) {
   if ( ! item ) return(0);
   return(item->next());
 }
 
-/// Return the previous item before \p 'item', or 0 if no more items.
-///
-/// This can be used to walk the tree in reverse, e.g.
-/// \code
-/// for ( Fl_Tree_Item *item = tree->first(); item; item = tree->prev(item) )
-///     printf("Item: %s\n", item->label());
-/// \endcode
-///
-/// \param[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 first(), next(), last(), prev()
-///
+/**
+ Return the previous item before \p 'item', or 0 if no more items.
+ This can be used to walk the tree in reverse, e.g.
+ \par
+ \code
+ :
+ for ( Fl_Tree_Item *item = tree->first(); item; item = tree->prev(item) )
+     printf("Item: %s\n", item->label());
+ :
+ \endcode
+ \param[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 first(), next(), last(), prev()
+*/
 Fl_Tree_Item *Fl_Tree::prev(Fl_Tree_Item *item) {
   if ( ! item ) return(0);
   return(item->prev());
 }
 
-/// Returns the last item in the tree.
-///
-/// This can be used to walk the tree in reverse, e.g.
-///
-/// \code
-/// for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() )
-///     printf("Item: %s\n", item->label());
-/// \endcode
-///
-/// \returns Last item in the tree, or 0 if none (tree empty).
-/// \see first(), next(), last(), prev()
-///
+/**
+ Returns the last item in the tree.
+ This can be used to walk the tree in reverse, e.g.
+ \par
+ \code
+ for ( Fl_Tree_Item *item = tree->last(); item; item = tree->prev() )
+     printf("Item: %s\n", item->label());
+ \endcode
+ \returns Last item in the tree, or 0 if none (tree empty).
+ \see first(), next(), last(), prev()
+*/
 Fl_Tree_Item* Fl_Tree::last() {
   if ( ! _root ) return(0);
   Fl_Tree_Item *item = _root;
@@ -1211,89 +1229,98 @@ Fl_Tree_Item* Fl_Tree::last_visible_item() {
   return(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.
-///
-/// \code
-/// // 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());
-/// \endcode
-///
-/// \returns The first selected item, or 0 if none.
-/// \see first_selected_item(), last_selected_item(), next_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.
+ \par
+ \code
+ :
+ // 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());
+ :
+ \endcode
+ \returns The first selected item, or 0 if none.
+ \see first_selected_item(), last_selected_item(), next_selected_item()
+*/
 Fl_Tree_Item *Fl_Tree::first_selected_item() {
   return(next_selected_item(0));
 }
 
 
-/// 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.
-///
-/// \code
-/// // 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());
-/// \endcode
-///
-/// \returns The last selected item, or 0 if none.
-/// \see first_selected_item(), last_selected_item(), next_selected_item()
-/// \version 1.3.3
-///     
+/**
+ 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.
+ \par
+ \code
+ :
+ // 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());
+ :
+ \endcode
+ \returns The last selected item, or 0 if none.
+ \see first_selected_item(), last_selected_item(), next_selected_item()
+ \version 1.3.3
+*/
 Fl_Tree_Item *Fl_Tree::last_selected_item() {
   return(next_selected_item(0, FL_Up));
 }
 
-/// Returns next item after \p 'item' in direction \p 'dir'
-/// depending on \p 'visible'.
-///
-/// Next item will be above (if dir==FL_Up) or below (if dir==FL_Down).
-/// If \p 'visible' is true, only items whose parents are open() will be returned.
-/// If \p 'visible' is false, even items whose parents are close()ed will be returned.
-///
-/// If \p item is 0, the return value will be the result of this truth table:
-/// <PRE>
-///                        visible=true           visible=false
-///                        -------------------    -------------
-///          dir=FL_Up:    last_visible_item()    last()
-///        dir=FL_Down:    first_visible_item()   first()
-/// </PRE>
-///
-/// \par Example use:
-/// \code
-/// // 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());
-/// \endcode
-///
-/// \param[in] item    The item to use to find the next item. If NULL, returns 0.
-/// \param[in] dir     Can be FL_Up or FL_Down (default=FL_Down or 'next')
-/// \param[in] visible true=return only open(), visible items,<br>
-///                    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 first(), last(), next(),<BR>
-///      first_visible_item(), last_visible_item(), next_visible_item(),<BR>
-///      first_selected_item(), last_selected_item(), next_selected_item()
-/// \version 1.3.3
-///  
+/**
+ Returns next item after \p 'item' in direction \p 'dir'
+ depending on \p 'visible'.
+
+ Next item will be above (if dir==FL_Up) or below (if dir==FL_Down).
+ If \p 'visible' is true, only items whose parents are open() will be returned.
+ If \p 'visible' is false, even items whose parents are close()ed will be returned.
+
+ If \p item is 0, the return value will be the result of this truth table:
+ <PRE>
+                        visible=true           visible=false
+                        -------------------    -------------
+          dir=FL_Up:    last_visible_item()    last()
+        dir=FL_Down:    first_visible_item()   first()
+ </PRE>
+
+ Example use:
+ \par
+ \code
+ :
+ // 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());
+ :
+ \endcode
+
+ \param[in] item    The item to use to find the next item. If NULL, returns 0.
+ \param[in] dir     Can be FL_Up or FL_Down (default=FL_Down or 'next')
+ \param[in] visible true=return only open(), visible items,<br>
+                    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 first(), last(), next(),<BR>
+      first_visible_item(), last_visible_item(), next_visible_item(),<BR>
+      first_selected_item(), last_selected_item(), next_selected_item()
+ \version 1.3.3
+*/
 Fl_Tree_Item *Fl_Tree::next_item(Fl_Tree_Item *item, int dir, bool visible) {
   if ( ! item ) {					// no start item?
     if ( visible ) {
@@ -1317,31 +1344,35 @@ Fl_Tree_Item *Fl_Tree::next_item(Fl_Tree_Item *item, int dir, bool visible) {
   return(0);		// unknown dir
 }
 
-/// Returns the next selected item above or below \p 'item', depending on \p 'dir'.
-/// If \p 'item' is 0, search starts at either first() or last(), depending on \p 'dir':
-/// first() if \p 'dir' is FL_Down (default), last() if \p 'dir' is FL_Up.
-///
-/// Use this to walk the tree looking for all the selected items, e.g.
-/// \code
-/// // 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());
-/// \endcode
-///
-/// \param[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)
-/// \param[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 first_selected_item(), last_selected_item(), next_selected_item()
-/// \version 1.3.3
-///
+/**
+ Returns the next selected item above or below \p 'item', depending on \p 'dir'.
+ If \p 'item' is 0, search starts at either first() or last(), depending on \p 'dir':
+ first() if \p 'dir' is FL_Down (default), last() if \p 'dir' is FL_Up.
+
+ Use this to walk the tree looking for all the selected items, e.g.
+ \par
+ \code
+ :
+ // 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());
+ :
+ \endcode
+
+ \param[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)
+ \param[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 first_selected_item(), last_selected_item(), next_selected_item()
+ \version 1.3.3
+*/
 Fl_Tree_Item *Fl_Tree::next_selected_item(Fl_Tree_Item *item, int dir) {
   switch (dir) {
     case FL_Down:
@@ -1366,25 +1397,28 @@ Fl_Tree_Item *Fl_Tree::next_selected_item(Fl_Tree_Item *item, int dir) {
   return(0);
 }
 
-/// Returns the currently selected items as an array of \p 'ret_items'.
-///
-/// Example:
-/// \code
-///   // 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..
-///   }
-/// \endcode
-///
-/// \param[out] ret_items The returned array of selected items.
-/// \returns The number of items in the returned array.
-/// \see first_selected_item(), next_selected_item()
-/// \version 1.3.3 ABI feature
-///
+/**
+ Returns the currently selected items as an array of \p 'ret_items'.
+
+ Example:
+ \par
+ \code
+   :
+   // 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..
+   }
+   :
+ \endcode
+ \param[out] ret_items The returned array of selected items.
+ \returns The number of items in the returned array.
+ \see first_selected_item(), next_selected_item()
+ \version 1.3.3 ABI feature
+*/
 int Fl_Tree::get_selected_items(Fl_Tree_Item_Array &ret_items) {
   ret_items.clear();
   for ( Fl_Tree_Item *i=first_selected_item(); i; i=next_selected_item(i) ) {
@@ -2439,19 +2473,23 @@ void Fl_Tree::hposition(int pos) {
   redraw();
 }
 
-/// See if widget \p 'w' is one of the Fl_Tree widget's scrollbars.
-/// Use this to skip over the scrollbars when walking the child() array. Example:
-/// \code
-/// 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..
-/// }
-/// \endcode
-/// \param[in] w Widget to test
-/// \returns 1 if \p w is a scrollbar, 0 if not.
-/// \todo should be const
-///
+/**
+ See if widget \p 'w' is one of the Fl_Tree widget's scrollbars.
+ Use this to skip over the scrollbars when walking the child() array. Example:
+ \par
+ \code
+ :
+ 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..
+ }
+ :
+ \endcode
+ \param[in] w Widget to test
+ \returns 1 if \p w is a scrollbar, 0 if not.
+ \todo should be const
+*/
 int Fl_Tree::is_scrollbar(Fl_Widget *w) {
   return( (w==_vscroll || w==_hscroll) ? 1 : 0 );
 }
@@ -2546,25 +2584,28 @@ void Fl_Tree::callback_reason(Fl_Tree_Reason reason) {
   _callback_reason = reason;
 }
 
-/// Gets the reason for this callback.
-///
-/// The callback() can use this value to see why it was called. Example:
-/// \code
-///     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..
-///         }
-///     }
-/// \endcode
-///
-/// \see item_reselect_mode() -- enables FL_TREE_REASON_RESELECTED events
-///
+/**
+ Gets the reason for this callback.
+
+ The callback() can use this value to see why it was called. Example:
+ \par
+ \code
+ :
+ 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..
+     }
+ }
+ :
+ \endcode
+ \see item_reselect_mode() -- enables FL_TREE_REASON_RESELECTED events
+*/
 Fl_Tree_Reason Fl_Tree::callback_reason() const {
   return(_callback_reason);
 }