o Added new 0xffffffff 'transparent' color behavior for the item's bg color;

  with this as the default color, Fl_Tree::color() can control the tree's background.
  Tests added to the test/tree application.

o test/tree.fl modified:
    o Added a 'Test Suggestions' button to document various tests
    o Added tests for new 'transparent' color behavior
    o Added test for STR#2832 to check if items can be drawn to the /right/ of child widgets

o Added new methods to Fl_Tree_Prefs:
    item_labelfont()     -- obsoletes labelfont()
    item_labelsize()     -- obsoletes labelsize()
    item_labelfgcolor()  -- obsoletes labelfgcolor()
    item_labelbgcolor()  -- obsoletes labelbgcolor()

o Added 'Fonts and Colors' section to Fl_Tree docs

o Fl_Tree_Item ABI feature added: using bitflags instead of chars
  to keep the class small, as it gets instanced a lot. (fast + LIGHT)



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

3 files changed, 167 insertions, 60 deletions

diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H
index 2a4b8cfa3..dfa75de90 100644
--- a/FL/Fl_Tree.H
+++ b/FL/Fl_Tree.H
@@ -80,6 +80,8 @@
 ///    tree.end();
 /// \endcode
 ///     
+/// \b FEATURES
+///
 ///     Items can be added with add(),
 ///     removed with remove(),
 ///     completely cleared with clear(),
@@ -95,7 +97,13 @@
 ///     and an item's pathname can be found with item_pathname().
 ///     The selected items' colors are controlled by selection_color() (inherited from Fl_Widget).
 ///
+/// \b 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().
+///
+/// \b CHILD WIDGETS
 ///
 ///     FLTK widgets (including custom widgets) can be assigned to tree items via
 ///     Fl_Tree_Item::widget().
@@ -110,6 +118,8 @@
 ///     adding the FL_TREE_ITEM_HEIGHT_FROM_WIDGET flag causes widget's height
 ///     to define the widget()'s height.
 ///
+/// \b 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(),
@@ -118,6 +128,27 @@
 ///     Various default preferences can be globally manipulated via Fl_Tree_Prefs, 
 ///     including colors, margins, icons, connection lines, etc. 
 ///
+/// \b FONTS AND COLORS
+///
+///     When adding new items to the tree, the new items get the
+///     defaults for fonts and colors from:
+///
+///	- 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')
+///
+///     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:
+///
+///	- Fl_Tree_Item::item_labelfont() -- The item's label font (default: FL_HELVETICA)
+///     - Fl_Tree_Item::item_labelsize() -- The item's label size (default: FL_NORMAL_SIZE)
+///     - Fl_Tree_Item::item_labelfgcolor() -- The item's label foreground color (default: FL_FOREGROUND_COLOR)
+///     - Fl_Tree_Item::item_labelbgcolor() -- The item's label background color (default: 0xffffffff, which tree uses as 'transparent')
+///
+/// \b 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. eg:
@@ -271,7 +302,7 @@ enum Fl_Tree_Reason {
   FL_TREE_REASON_DESELECTED,	///< an item was de-selected
 #if FLTK_ABI_VERSION >= 10302
   FL_TREE_REASON_RESELECTED,	///< an item was re-selected (e.g. double-clicked)
-#endif
+#endif /*FLTK_ABI_VERSION*/
   FL_TREE_REASON_OPENED,	///< an item was opened
   FL_TREE_REASON_CLOSED		///< an item was closed
 };
@@ -288,9 +319,9 @@ class FL_EXPORT Fl_Tree : public Fl_Group {
 #if FLTK_ABI_VERSION >= 10302
   // NEW: 
   Fl_Tree_Item *_lastselect;
-#else
+#else /*FLTK_ABI_VERSION*/
   // OLD: static data inside handle() method
-#endif
+#endif /*FLTK_ABI_VERSION*/
 
   void fix_scrollbar_order();
 
@@ -368,17 +399,18 @@ public:
   void set_item_focus(Fl_Tree_Item *item);
   int is_selected(Fl_Tree_Item *item) const;
   int is_selected(const char *path);
+
   /////////////////////////////////
   // Item attribute related methods
   /////////////////////////////////
+  Fl_Font     item_labelfont() const;
+  void        item_labelfont(Fl_Font val);
   Fl_Fontsize item_labelsize() const;
-  void item_labelsize(Fl_Fontsize val);
-  Fl_Font item_labelfont() const;
-  void item_labelfont(Fl_Font val);
-  Fl_Color item_labelfgcolor(void) const;
-  void item_labelfgcolor(Fl_Color val);
-  Fl_Color item_labelbgcolor(void) const;
-  void item_labelbgcolor(Fl_Color val);
+  void        item_labelsize(Fl_Fontsize val);
+  Fl_Color    item_labelfgcolor(void) const;
+  void        item_labelfgcolor(Fl_Color val);
+  Fl_Color    item_labelbgcolor(void) const;
+  void        item_labelbgcolor(Fl_Color val);
   Fl_Color connectorcolor() const;
   void connectorcolor(Fl_Color val);
   int marginleft() const;
@@ -388,7 +420,7 @@ public:
 #if FLTK_ABI_VERSION >= 10302
   int marginbottom() const;
   void marginbottom(int val);
-#endif
+#endif /*FLTK_ABI_VERSION*/
   int linespacing() const;
   void linespacing(int val);
   int openchild_marginbottom() const;
@@ -400,7 +432,7 @@ public:
 #if FLTK_ABI_VERSION >= 10302
   int widgetmarginleft() const;
   void widgetmarginleft(int val);
-#endif
+#endif /*FLTK_ABI_VERSION*/
   int connectorwidth() const;
   void connectorwidth(int val);
   Fl_Image* usericon() const;
@@ -427,8 +459,7 @@ public:
   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
-
+#endif /*FLTK_ABI_VERSION*/
   int displayed(Fl_Tree_Item *item);
   void show_item(Fl_Tree_Item *item, int yoff);
   void show_item(Fl_Tree_Item *item);
diff --git a/FL/Fl_Tree_Item.H b/FL/Fl_Tree_Item.H
index 83d6a4b42..b5dd7b985 100644
--- a/FL/Fl_Tree_Item.H
+++ b/FL/Fl_Tree_Item.H
@@ -56,11 +56,23 @@ class FL_EXPORT Fl_Tree_Item {
   Fl_Font                 _labelfont;		// label's font face
   Fl_Fontsize             _labelsize;		// label's font size
   Fl_Color                _labelfgcolor;	// label's fg color
-  Fl_Color                _labelbgcolor;	// label's bg color
+  Fl_Color                _labelbgcolor;	// label's bg color (0xffffffff is 'transparent')
+  enum {
+    OPEN                = 1<<0,		///> item is open
+    VISIBLE             = 1<<1,		///> item is visible
+    ACTIVE              = 1<<2,		///> item is active
+    SELECTED            = 1<<3,		///> item is selected
+  };
+#if FLTK_ABI_VERSION >= 10302
+  // NEW
+  unsigned short _flags;		// misc flags
+#else /*FLTK_ABI_VERSION*/
+  // OLD: this will go away after 1.3.x
   char                    _open;		// item is open?
   char                    _visible;		// item is visible?
   char                    _active;		// item activated?
   char                    _selected;		// item selected?
+#endif /*FLTK_ABI_VERSION*/
   int                     _xywh[4];		// xywh of this widget (if visible)
   int                     _collapse_xywh[4];	// xywh of collapse icon (if visible)
   int                     _label_xywh[4];	// xywh of label
@@ -131,10 +143,12 @@ public:
     return(_labelfgcolor); 
   }
   /// Set item's label background color.
+  /// A special case is made for color 0xffffffff which is treated as 'transparent'.
   void labelbgcolor(Fl_Color val) {
     _labelbgcolor = val; 
   }
   /// Return item's background text color.
+  /// If the color is 0xffffffff, it is 'transparent'.
   Fl_Color labelbgcolor() const {
     return(_labelbgcolor); 
   }
@@ -208,26 +222,26 @@ public:
   void close();
   /// See if the item is 'open'.
   int is_open() const {
-    return(_open?1:0);
+    return(is_flag(OPEN));
   }
   /// See if the item is 'closed'.
   int is_close() const {
-    return(_open?0:1);
+    return(is_flag(OPEN)?0:1);
   }
   /// Toggle the item's open/closed state.
   void open_toggle() {
-    _open?close():open();
+    is_open()?close():open();
   }
   /// Change the item's selection state to the optionally specified 'val'.
   /// If 'val' is not specified, the item will be selected.
   ///
   void select(int val=1) {
-    _selected = val;
+    set_flag(SELECTED, val);
   }
   /// Toggle the item's selection state.
   void select_toggle() {
     if ( is_selected() ) {
-      deselect();		// deselect if selected
+      deselect();	// deselect if selected
     } else {
       select();		// select if deselected
     }
@@ -249,7 +263,7 @@ public:
   }
   /// Disable the item's selection state.
   void deselect() {
-    _selected = 0;
+    set_flag(SELECTED, 0);
   }
   /// Deselect item and all its children.
   ///     Returns count of how many items were in the 'selected' state,
@@ -268,7 +282,7 @@ public:
   }
   /// See if the item is selected.
   char is_selected() const {
-    return(_selected);
+    return(is_flag(SELECTED));
   }
   /// Change the item's activation state to the optionally specified 'val'.
   ///
@@ -280,7 +294,7 @@ public:
   /// If 'val' is not specified, the item will be activated.
   ///
   void activate(int val=1) {
-    _active = val;
+    set_flag(ACTIVE,val);
     if ( _widget && val != (int)_widget->active() ) {
       if ( val ) {
 	_widget->activate();
@@ -298,15 +312,19 @@ public:
   }
   /// See if the item is activated.
   char is_activated() const {
-    return(_active);
+    return(is_flag(ACTIVE));
   }
   /// See if the item is activated.
   char is_active() const {
-    return(_active);
+    return(is_activated());
   }
-  /// See if the item is visible.
+  /// See if the item is visible. Alias for is_visible().
   int visible() const {
-    return(_visible ? 1 : 0);
+    return(is_visible());
+  }
+  /// See if the item is visible.
+  int is_visible() const {
+    return(is_flag(VISIBLE));
   }
   int visible_r() const;
 
@@ -329,6 +347,40 @@ public:
   int is_root() const {
     return(_parent==0?1:0);
   }
+
+  // Protected methods
+protected:
+#if FLTK_ABI_VERSION >= 10302
+  /// Set a flag to an on or off value. val is 0 or 1.
+  inline void set_flag(unsigned short flag,int val) {
+    if ( val ) _flags |= flag; else _flags &= ~flag;
+  }
+  /// See if flag set. Returns 0 or 1.
+  inline int is_flag(unsigned short val) const {
+    return(_flags & val ? 1 : 0);
+  }
+#else /*FLTK_ABI_VERSION*/
+  /// Set a flag to an on or off value. val is 0 or 1.
+  void set_flag(unsigned short flag,int val) {
+    switch (flag) {
+      case     OPEN: _open     = val; break;
+      case  VISIBLE: _visible  = val; break;
+      case   ACTIVE: _active   = val; break;
+      case SELECTED: _selected = val; break;
+    }
+  }
+  /// See if flag set. Returns 0 or 1.
+  int is_flag(unsigned short flag) const {
+    switch (flag) {
+      case     OPEN: return(_open ? 1 : 0);
+      case  VISIBLE: return(_visible ? 1 : 0);
+      case   ACTIVE: return(_active ? 1 : 0);
+      case SELECTED: return(_selected ? 1 : 0);
+      default:       return(0);
+    }
+  }
+#endif /*FLTK_ABI_VERSION*/
+
 };
 
 #endif /*FL_TREE_ITEM_H*/
diff --git a/FL/Fl_Tree_Prefs.H b/FL/Fl_Tree_Prefs.H
index 12dcafdbf..b87cc8521 100644
--- a/FL/Fl_Tree_Prefs.H
+++ b/FL/Fl_Tree_Prefs.H
@@ -91,7 +91,7 @@ enum Fl_Tree_Item_Draw_Mode {
   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
+#endif /*FLTK_ABI_VERSION*/
 
 /// \class Fl_Tree_Prefs
 ///
@@ -119,7 +119,7 @@ class FL_EXPORT Fl_Tree_Prefs {
   int _linespacing;			// vertical space between lines
   // Colors
   Fl_Color _labelfgcolor;		// label's foreground color
-  Fl_Color _labelbgcolor;		// background color
+  Fl_Color _labelbgcolor;		// label's background color
   Fl_Color _connectorcolor;		// connector dotted line color
   Fl_Tree_Connector _connectorstyle;	// connector line style
   Fl_Image *_openimage;			// the 'open' icon [+]
@@ -133,7 +133,7 @@ class FL_EXPORT Fl_Tree_Prefs {
 #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()
-#endif
+#endif /*FLTK_ABI_VERSION*/
 public:
   Fl_Tree_Prefs();
   
@@ -141,21 +141,61 @@ public:
   // Labels
   ////////////////////////////
   /// Return the label's font.
-  inline Fl_Font labelfont() const {
-    return(_labelfont);
-  }
+  inline Fl_Font item_labelfont() const { return(_labelfont); }
   /// Set the label's font to \p val.
-  inline void labelfont(Fl_Font val) {
-    _labelfont = val;
-  }
+  inline void item_labelfont(Fl_Font val) { _labelfont = val; }
   /// Return the label's size in pixels.
-  inline Fl_Fontsize labelsize() const {
-    return(_labelsize);
-  }
+  inline Fl_Fontsize item_labelsize() const { return(_labelsize); }
   /// Set the label's size in pixels to \p val.
-  inline void labelsize(Fl_Fontsize val) {
-    _labelsize = val;
+  inline void item_labelsize(Fl_Fontsize val) { _labelsize = val; }
+  /// Get the default label foreground color
+  inline Fl_Color item_labelfgcolor() const { return(_labelfgcolor); }
+  /// Set the default label foreground color
+  inline void item_labelfgcolor(Fl_Color val) { _labelfgcolor = val; }
+#if FLTK_ABI_VERSION >= 10302
+  /// Get the default label background color.
+  ///    This returns the Fl_Tree::color() unless item_labelbgcolor()
+  ///    has been set explicitly.
+  ///
+  inline Fl_Color item_labelbgcolor() const {
+    return _labelbgcolor;
+  }
+  /// Set the default label background color.
+  ///     Once set, overrides the default behavior of using Fl_Tree::color().
+  ///
+  inline void item_labelbgcolor(Fl_Color val) {
+    _labelbgcolor = val;
+  }
+#else /*FLTK_ABI_VERSION*/
+  /// Get the default label background color
+  inline Fl_Color item_labelbgcolor() const {
+    return(_labelbgcolor);
+  }
+  /// Set the default label background color
+  inline void item_labelbgcolor(Fl_Color val) {
+    _labelbgcolor = val;
   }
+#endif /*FLTK_ABI_VERSION*/
+
+  /////////////////
+  // Obsolete names - for 1.3.0 backwards compat
+  /////////////////
+  /// Obsolete: Return the label's font. Please use item_labelfont() instead.
+  inline Fl_Font labelfont() const { return(_labelfont); }
+  /// Obsolete: Set the label's font to \p val. Please use item_labelfont(Fl_Font) instead.
+  inline void labelfont(Fl_Font val) { _labelfont = val; }
+  /// Obsolete: Return the label's size in pixels. Please use item_labelsize() instead.
+  inline Fl_Fontsize labelsize() const { return(_labelsize); }
+  /// Obsolete: Set the label's size in pixels to \p val. Please use item_labelsize(Fl_Fontsize) instead.
+  inline void labelsize(Fl_Fontsize val) { _labelsize = val; }
+  /// Obsolete: Get the default label foreground color. Please use item_labelfgcolor() instead.
+  inline Fl_Color labelfgcolor() const { return(_labelfgcolor); }
+  /// Obsolete: Set the default label foreground color. Please use item_labelfgcolor(Fl_Color) instead.
+  inline void labelfgcolor(Fl_Color val) { _labelfgcolor = val; }
+  /// Obsolete: Get the default label background color. Please use item_labelbgcolor() instead.
+  inline Fl_Color labelbgcolor() const { return(item_labelbgcolor()); }
+  /// Obsolete: Set the default label background color. Please use item_labelbgcolor(Fl_Color) instead.
+  inline void labelbgcolor(Fl_Color val) { item_labelbgcolor(val); }
   
   ////////////////////////////
   // Margins
@@ -187,7 +227,7 @@ public:
   inline void marginbottom(int val) {
     _marginbottom = val;
   }
-#endif
+#endif /*FLTK_ABI_VERSION*/
   /// Get the margin below an open child in pixels
   inline int openchild_marginbottom() const {
     return(_openchild_marginbottom);
@@ -221,7 +261,7 @@ public:
   inline void widgetmarginleft(int val) {
     _widgetmarginleft = val;
   }
-#endif
+#endif /*FLTK_ABI_VERSION*/
   /// Get the line spacing value in pixels
   inline int linespacing() const {
     return(_linespacing);
@@ -234,22 +274,6 @@ public:
   ////////////////////////////
   // Colors and Styles
   ////////////////////////////
-  /// Get the default label foreground color
-  inline Fl_Color labelfgcolor() const {
-    return(_labelfgcolor);
-  }
-  /// Set the default label foreground color
-  inline void labelfgcolor(Fl_Color val) {
-    _labelfgcolor = val;
-  }
-  /// Get the default label background color
-  inline Fl_Color labelbgcolor() const {
-    return(_labelbgcolor);
-  }
-  /// Set the default label background color
-  inline void labelbgcolor(Fl_Color val) {
-    _labelbgcolor = val;
-  }
   /// Get the connector color used for tree connection lines.
   inline Fl_Color connectorcolor() const {
     return(_connectorcolor);
@@ -388,7 +412,7 @@ public:
   inline void item_draw_mode(Fl_Tree_Item_Draw_Mode val) {
     _itemdrawmode = val;
   }
-#endif
+#endif /*FLTK_ABI_VERSION*/
 };
 
 #endif /*FL_TREE_PREFS_H*/