o Added FL_TREE_ITEM_HEIGHT_FROM_WIDGET option to item_draw_mode()

  to allow widgets to control the size of items in the tree
  (instead of vice versa).

o Added item_draw_mode(int) to allow for easier bitflag maintenance,
  since enums don't seem to be typesafe yet.

o Tree demo modified to demonstrate this feature.
  An important feature for adding large widgets to tree items.
  Will probably add an example, 'tree-of-tables' to demo this usage.

o Small doc fixes.

o Had to rename FL_TREE_ITEM_DRAW_WIDGET_ONLY to FL_TREE_ITEM_DRAW_DEFAULT.
  Its meaning for the bit fields changed when new bit fields were added.
  (The prev name just didn't make sense in the new context. Since it was
  just a few svn commits old and an unreleased ABI feature, it shouldn't
  affect anyone not in R&D)



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

3 files changed, 35 insertions, 20 deletions

diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H
index e934963a0..a53560f8b 100644
--- a/FL/Fl_Tree.H
+++ b/FL/Fl_Tree.H
@@ -52,9 +52,9 @@
 ///                  |--- Fl_Tree_Sort (enum)           // Sort behavior
 /// \endcode
 ///
-///     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.
+///     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.
@@ -100,13 +100,23 @@
 ///     FLTK widgets (including custom widgets) can be assigned to tree items via
 ///     Fl_Tree_Item::widget().
 ///
-///     Icons for individual items can be changed with
-///     Fl_Tree_Item::openicon(), 
-///     Fl_Tree_Item::closeicon(),
-///     Fl_Tree_Item::usericon().
+///     When a 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: 
+///     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.
+///
+///     The tree's open/close icons can be redefined with
+///     Fl_Tree::openicon(), Fl_Tree::closeicon(). User icons
+///     can either be changed globally with Fl_Tree::usericon(),
+///     or on a per-item basis with Fl_Tree_Item::usericon().
 ///
 ///     Various default preferences can be globally manipulated via Fl_Tree_Prefs, 
-///     including colors, margins, icons, connection lines. 
+///     including colors, margins, icons, connection lines, etc. 
 ///
 ///     The tree's callback() will be invoked when items change state or are open/closed.
 ///     when() controls when mouse/keyboard events invoke the callback.
@@ -125,7 +135,7 @@
 ///   }
 /// \endcode
 ///
-///     To get the item's full menu pathname, you can use Fl_Tree_Item::item_pathname(), eg:
+///     To get the item's full menu pathname, you can use Fl_Tree::item_pathname(), eg:
 ///
 /// \code
 ///   char pathname[256] = "???";
@@ -415,6 +425,7 @@ public:
   void item_reselect_mode(Fl_Tree_Item_Reselect_Mode mode);
   Fl_Tree_Item_Draw_Mode item_draw_mode() const;
   void item_draw_mode(Fl_Tree_Item_Draw_Mode mode);
+  void item_draw_mode(int mode);
 #endif
 
   int displayed(Fl_Tree_Item *item);
diff --git a/FL/Fl_Tree_Item.H b/FL/Fl_Tree_Item.H
index ff6e5c50a..83d6a4b42 100644
--- a/FL/Fl_Tree_Item.H
+++ b/FL/Fl_Tree_Item.H
@@ -232,7 +232,7 @@ public:
       select();		// select if deselected
     }
   }
-  /// Select self and all children
+  /// Select item and all its children.
   ///     Returns count of how many items were in the 'deselected' state,
   ///     ie. how many items were "changed".
   ///
@@ -251,7 +251,7 @@ public:
   void deselect() {
     _selected = 0;
   }
-  /// Deselect self and all children
+  /// Deselect item and all its children.
   ///     Returns count of how many items were in the 'selected' state,
   ///     ie. how many items were "changed".
   ///
@@ -310,11 +310,11 @@ public:
   }
   int visible_r() const;
 
-  /// Set the user icon's image. '0' will disable.
+  /// Set the item's user icon to an Fl_Image. '0' will disable.
   void usericon(Fl_Image *val) {
     _usericon = val;
   }
-  /// Get the user icon. Returns '0' if disabled.
+  /// Get the item's user icon as an Fl_Image. Returns '0' if disabled.
   Fl_Image *usericon() const {
     return(_usericon);
   }
diff --git a/FL/Fl_Tree_Prefs.H b/FL/Fl_Tree_Prefs.H
index f396b80ce..12dcafdbf 100644
--- a/FL/Fl_Tree_Prefs.H
+++ b/FL/Fl_Tree_Prefs.H
@@ -73,19 +73,23 @@ enum Fl_Tree_Select {
 
 #if FLTK_ABI_VERSION >= 10302
 /// \enum Fl_Tree_Item_Reselect_Mode
-/// Defines the ways an item can be (re) selected.
+/// Defines the ways an item can be (re) selected
+/// via item_reselect_mode().
 ///
 enum Fl_Tree_Item_Reselect_Mode {
-  FL_TREE_SELECTABLE_ONCE=0,	///< item can only be selected once (default)
-  FL_TREE_SELECTABLE_ALWAYS, 	///< enables FL_TREE_REASON_RESELECTED events for callbacks
+  FL_TREE_SELECTABLE_ONCE=0,	///< Item can only be selected once (default)
+  FL_TREE_SELECTABLE_ALWAYS, 	///< Enables FL_TREE_REASON_RESELECTED events for callbacks
 };
 
 /// \enum Fl_Tree_Item_Draw_Mode
-/// Controls how item's labels and widget()s are drawn in the tree.
+/// Bit flags that control how item's labels and widget()s are drawn in the tree
+/// via item_draw_mode().
 ///
 enum Fl_Tree_Item_Draw_Mode {
-  FL_TREE_ITEM_DRAW_WIDGET_ONLY=0,	///< if widget() defined, draw it in place of the label (default)
-  FL_TREE_ITEM_DRAW_LABEL_AND_WIDGET=1	///< if widget() defined, draw it to right of label
+  FL_TREE_ITEM_DRAW_DEFAULT=0,		///< If widget() defined, draw in place of label,
+                                        ///< and widget() tracks item height (default)
+  FL_TREE_ITEM_DRAW_LABEL_AND_WIDGET=1,	///< If widget() defined, include label to the left of the widget
+  FL_TREE_ITEM_HEIGHT_FROM_WIDGET=2	///< If widget() defined, widget()'s height controls item's height
 };
 #endif
 
@@ -128,7 +132,7 @@ class FL_EXPORT Fl_Tree_Prefs {
   Fl_Tree_Select _selectmode;		// selection mode
 #if FLTK_ABI_VERSION >= 10302
   Fl_Tree_Item_Reselect_Mode _itemreselectmode;	// controls item selection callback() behavior
-  Fl_Tree_Item_Draw_Mode     _itemdrawmode;	// controls how items draw label, widget()
+  Fl_Tree_Item_Draw_Mode     _itemdrawmode;	// controls how items draw label + widget()
 #endif
 public:
   Fl_Tree_Prefs();