Added some comments about the importance of order in per-state options. [BUG 1816723]

1 files changed, 14 insertions, 1 deletions

diff --git a/doc/treectrl.man b/doc/treectrl.man
index 1723088..a1ce326 100644
--- a/doc/treectrl.man
+++ b/doc/treectrl.man
@@ -3,7 +3,7 @@
   See the file "license.terms" for information on usage and redistribution
   of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 
-  $Id: treectrl.man,v 1.50 2007/02/06 22:27:35 treectrl Exp $}
+  $Id: treectrl.man,v 1.51 2007/10/23 23:04:33 treectrl Exp $}
 ][manpage_begin treectrl n 2.2.3]
 [moddesc {Tk Commands}]
 [titledesc {Create and manipulate hierarchical multicolumn widgets}]
@@ -2652,6 +2652,19 @@ In the example above, the [const rect] element is filled with blue when the tree
 has the focus and the item is selected. If the treectrl does not have the focus, the
 example specifies that gray should be used for selected items. Also note that if the
 item is not selected, no color is specified for the -fill option.
+[para]
+Each value-stateList pair is checked in order from left to right. The value
+associated with the first stateList that matches the current item state is
+used. So stateLists should be listed from most-specific to least-specific.
+[example_begin]
+$T element configure MyRectElement -fill {gray {selected} blue {selected focus}}
+[example_end]
+Written this way, gray will always be used for selected items since
+it appears first, and blue will never be used for selected items regardless
+of the focus.
+[para]
+A value followed by an empty stateList should always be last since it will be
+chosen regardless of the item's state.
 
 [section ELEMENTS]
 Elements are the smallest building blocks