Replaced -XXXbuttonXXX with -buttonbitmap, -buttonimage.

New -minitemheight and -usetheme treectrl options.
New -arrowpadx, -arrowpady, -arrowbitmap, -arrowimage, -state, -textlines column options.
Removed -relief and -sunken column options.
Added PER-STATE OPTIONS section.
New "window" element type.
New <ItemDelete> event.

1 files changed, 165 insertions, 79 deletions

diff --git a/doc/treectrl.n b/doc/treectrl.n
index d3a3ad3..0ed1b33 100644
--- a/doc/treectrl.n
+++ b/doc/treectrl.n
@@ -6,14 +6,14 @@
 '\"   See the file "license.terms" for information on usage and redistribution
 '\"   of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\"   $Id: treectrl.n,v 1.28 2005/03/29 21:20:42 treectrl Exp $
+'\"   $Id: treectrl.n,v 1.29 2005/05/11 03:31:33 treectrl Exp $
 .so man.macros
-.TH "treectrl" n 1.1  "Tk Commands"
+.TH "treectrl" n 1.2  "Tk Commands"
 .BS
 .SH "NAME"
 treectrl \- Create and manipulate hierarchical multicolumn widgets
 .SH "SYNOPSIS"
-package require \fBtreectrl  1.1\fR
+package require \fBtreectrl  1.2\fR
 .sp
 \fBtreectrl\fR \fIpathName\fR ?\fIoptions\fR?\fR
 .sp
@@ -384,6 +384,18 @@ for \fBvisindex\fR only the visible items are counted.
 .LP
 .nf
 .ta 6c
+Command-Line Switch:	\fB-buttonbitmap\fR
+Database Name:	\fBbuttonBitmap\fR
+Database Class:	\fBButtonBitmap\fR
+.fi
+.IP
+Specifies the bitmap to be used as the expand/collapse button to the left of
+an item. This is a per-state option (see \fBPER-STATE OPTIONS\fR). If
+a bitmap is specified for a certain item state, it overrides the effects of
+-usetheme.
+.LP
+.nf
+.ta 6c
 Command-Line Switch:	\fB-buttoncolor\fR
 Database Name:	\fBbuttonColor\fR
 Database Class:	\fBButtonColor\fR
@@ -394,6 +406,18 @@ and the plus or minus sign of the button to the left of an item.
 .LP
 .nf
 .ta 6c
+Command-Line Switch:	\fB-buttonimage\fR
+Database Name:	\fBbuttonImage\fR
+Database Class:	\fBButtonImage\fR
+.fi
+.IP
+Specifies the image to be used as the expand/collapse button to the left of
+an item. This is a per-state option (see \fBPER-STATE OPTIONS\fR).
+If an image is specified for a certain item state, it overrides the effects of
+-buttonbitmap and -usetheme.
+.LP
+.nf
+.ta 6c
 Command-Line Switch:	\fB-buttonsize\fR
 Database Name:	\fBbuttonSize\fR
 Database Class:	\fBButtonSize\fR
@@ -415,26 +439,6 @@ in any of the forms acceptable to \fBTk_GetPixels\fR.
 .LP
 .nf
 .ta 6c
-Command-Line Switch:	\fB-closedbuttonbitmap\fR
-Database Name:	\fBclosedButtonBitmap\fR
-Database Class:	\fBClosedButtonBitmap\fR
-.fi
-.IP
-Specifies the bitmap to be used as the button to the left of a closed item
-in any of the forms acceptable to \fBTk_GetPixels\fR.
-.LP
-.nf
-.ta 6c
-Command-Line Switch:	\fB-closedbuttonimage\fR
-Database Name:	\fBclosedButtonImage\fR
-Database Class:	\fBClosedButtonImage\fR
-.fi
-.IP
-Specifies the image to be used as the button to the left of a closed item
-in any of the forms acceptable to \fBTk_GetImage\fR.
-.LP
-.nf
-.ta 6c
 Command-Line Switch:	\fB-columnproxy\fR
 Database Name:	\fBcolumnProxy\fR
 Database Class:	\fBColumnProxy\fR
@@ -515,10 +519,11 @@ Database Class:	\fBItemHeight\fR
 .fi
 .IP
 Specifies a fixed height for every item
-in any of the forms acceptable to \fBTk_GetPixels\fR.
+in any of the forms acceptable to \fBTk_GetPixels\fR. If non-zero, this
+option overrides the requested height of an item and the -minitemheight option.
 The default is 0, which means that
 every item has the height requested by the arrangement of elements
-in each column.
+in each column. Items are never shorter than the maximum height of a button.
 .LP
 .nf
 .ta 6c
@@ -552,23 +557,17 @@ in any of the forms acceptable to \fBTk_GetPixels\fR.
 .LP
 .nf
 .ta 6c
-Command-Line Switch:	\fB-openbuttonbitmap\fR
-Database Name:	\fBopenButtonBitmap\fR
-Database Class:	\fBOpenButtonBitmap\fR
+Command-Line Switch:	\fB-minitemheight\fR
+Database Name:	\fBminItemHeight\fR
+Database Class:	\fBMinItemHeight\fR
 .fi
 .IP
-Specifies the bitmap to be used as the button to the left of an opened item
-in any of the forms acceptable to \fBTk_GetBitmap\fR.
-.LP
-.nf
-.ta 6c
-Command-Line Switch:	\fB-openbuttonimage\fR
-Database Name:	\fBopenButtonImage\fR
-Database Class:	\fBOpenButtonImage\fR
-.fi
-.IP
-Specifies the image to be used as the button to the left of an opened item
-in any of the forms acceptable to \fBTk_GetImage\fR.
+Specifies a minimum height for every item
+in any of the forms acceptable to \fBTk_GetPixels\fR.
+The default is 0, which means that
+every item has the height requested by the arrangement of elements
+in each column. This option has no effect if the -itemheight option is specified.
+Items are never shorter than the maximum height of a button.
 .LP
 .nf
 .ta 6c
@@ -678,6 +677,17 @@ Default is 0 meaning that the first column displays the tree.
 .LP
 .nf
 .ta 6c
+Command-Line Switch:	\fB-usetheme\fR
+Database Name:	\fBuseTheme\fR
+Database Class:	\fBUseTheme\fR
+.fi
+.IP
+Specifies a boolean value that determines whether this widget should draw
+parts of itself using a platform-specific theme manager.
+The default is false.
+.LP
+.nf
+.ta 6c
 Command-Line Switch:	\fB-width\fR
 Database Name:	\fBwidth\fR
 Database Class:	\fBWidth\fR
@@ -2125,8 +2135,11 @@ There is always one special column, the \fBtail\fR column, which fills
 all space to the right of the last ordinary column.
 This column has no number;
 it can only be specified by its tag \fBtail\fR, which cannot be modified.
-It is explicitely mentioned for a widget command,
-if its \fIcolumn\fR argument can also specify the tail column.
+.PP
+When a column configuration option is specified as \fBper-state\fR, the state
+names are \fBnormal\fR, \fBactive\fR, \fBpressed\fR or \fBup\fR, i.e.
+do not use item state names. See \fBPER-STATE OPTIONS\fR
+for more info.
 .PP
 The following options are supported for columns:
 .TP
@@ -2136,6 +2149,15 @@ to the right of the column title.
 \fIDirection\fR must have one of the values
 \fBnone\fR (the default), \fBup\fR, or \fBdown\fR.
 .TP
+\fB\fB-arrowbitmap\fR\fR \fIbitmap\fR
+Specifies as a per-state option the bitmap to use to draw the arrow if
+this columns -arrow option is not \fBnone\fR.
+.TP
+\fB\fB-arrowimage\fR\fR \fIimage\fR
+Specifies as a per-state option the image to use to draw the arrow if
+this columns -arrow option is not \fBnone\fR. If an image is specified for
+a certain state, it overrides the -arrowbitmap option.
+.TP
 \fB\fB-arrowside\fR\fR \fIside\fR
 Indicates on which side an arrow should be drawn, if at all.
 \fISide\fR must be either \fBleft\fR or \fBright\fR (the default).
@@ -2145,11 +2167,18 @@ Indicates onto which side an arrow should be packed,
 if there is more space available for drawing the arrow then needed.
 \fISide\fR must be either \fBleft\fR (the default) or \fBright\fR.
 .TP
-\fB\fB-arrowpad\fR\fR \fIamount\fR
+\fB\fB-arrowpadx\fR\fR \fIamount\fR
 \fIAmount\fR specifies how much padding to
 leave on the left and right side of the arrow.
 \fIAmount\fR may be a list
-of two values to specify padding for left and right separately,
+of two values to specify padding for left and right separately;
+it defaults to 6.
+.TP
+\fB\fB-arrowpady\fR\fR \fIamount\fR
+\fIAmount\fR specifies how much padding to
+leave on the top and bottom of the arrow.
+\fIAmount\fR may be a list
+of two values to specify padding for top and bottom separately;
 it defaults to 0.
 .TP
 \fB\fB-bitmap\fR\fR \fIbitmap\fR
@@ -2157,7 +2186,8 @@ Specifies the bitmap to display in the element
 to the left of the column title.
 .TP
 \fB\fB-background\fR\fR \fIcolor\fR
-Specifies the color to use for the background of the column header.
+Specifies as a per-state option the color to use for the background of the
+column header.
 .TP
 \fB\fB-borderwidth\fR\fR \fIsize\fR
 Specifies a non-negative value indicating the width
@@ -2185,13 +2215,17 @@ to the left of the column title.
 This option overrides the \fB-bitmap\fR column option.
 .TP
 \fB\fB-imagepadx\fR\fR \fIamount\fR
+\fIAmount\fR specifies how much padding to
+leave on the left and right side of the image.
+\fIAmount\fR may be a list
+of two values to specify padding for left and right separately;
+it defaults to 6.
 .TP
 \fB\fB-imagepady\fR\fR \fIamount\fR
 \fIAmount\fR specifies how much padding to
-leave on the left and right (for \fB-imagepadx\fR)
-or top and bottom (for \fB-imagepady\fR) side of the image.
+leave on the top and bottom of the image.
 \fIAmount\fR may be a list
-of two values to specify padding for the two sides separately,
+of two values to specify padding for top and bottom separately;
 it defaults to 0.
 .TP
 \fB\fB-itembackground\fR\fR \fIcolorList\fR
@@ -2207,12 +2241,6 @@ Must be one of \fBleft\fR (the default), \fBcenter\fR, or \fBright\fR.
 Specifies the minimum size, in screen units,
 that will be permitted for this column.
 .TP
-\fB\fB-relief\fR\fR \fIrelief\fR
-Specifies the 3-D effect desired for the column header containing the title.
-Acceptable values are the typical relief values,
-but the value seems to be ignored anyway;
-better use the \fB-sunken\fR column option instead.
-.TP
 \fB\fB-squeeze\fR\fR \fIboolean\fR
 Specifies a boolean value that indicates whether or not the column should
 shrink when the content width of the treectrl is less than the total needed width
@@ -2221,16 +2249,17 @@ smaller than its needed width. The column will not get smaller than the value
 of its \fB-minwidth\fR option, if specified. This option has no effect if the
 \fB-width\fR option is set.
 .TP
+\fB\fB-state\fR\fR \fIstate\fR
+Specifies one of three states for the column header: \fBnormal\fR, \fBactive\fR,
+or \fBpressed\fR. The active state is used when the mouse is over the header.
+The pressed state is used when the mouse button is pressed in the header.
+.TP
 \fB\fB-stepwidth\fR\fR \fIsize\fR
 Specifies a sort of tabbed alignment for columns that displays
 more than one item next to each other
 (typically in a treectrl widget with horizontal orientation).
 Every item will get an x-coordinate which is a multiple of \fIsize\fR.
 .TP
-\fB\fB-sunken\fR\fR \fIboolean\fR
-Indicates whether or not the column header containing the column title
-will be displayed with a sunken relief.
-.TP
 \fB\fB-tag\fR\fR \fItag\fR
 Defines a unique name for the columns which can be used in subsequent calls
 of the treectrl widget commands, wherever a column must be specified.
@@ -2242,14 +2271,24 @@ Specifies a text to be displayed inside the column title.
 Specifies a color, which should be used as foreground color
 to display the column title.
 .TP
+\fB\fB-textlines\fR\fR \fIcount\fR
+Specifies the maximum number of lines of text to display in the column title.
+If this value is zero, the number of lines displayed is determined by any newline
+characters and the effects of wrapping when the column width is less than
+needed. The default is 1.
+.TP
 \fB\fB-textpadx\fR\fR \fIamount\fR
+\fIAmount\fR specifies how much padding to
+leave on the left and right side of the text.
+\fIAmount\fR may be a list
+of two values to specify padding for left and right separately;
+it defaults to 6.
 .TP
 \fB\fB-textpady\fR\fR \fIamount\fR
 \fIAmount\fR specifies how much padding to
-leave on the left and right (for \fB-textpadx\fR)
-or top and bottom (for \fB-textpady\fR) side of the text.
+leave on the top and bottom of the text.
 \fIAmount\fR may be a list
-of two values to specify padding for the two sides separately,
+of two values to specify padding for top and bottom separately;
 it defaults to 0.
 .TP
 \fB\fB-visible\fR\fR \fIboolean\fR
@@ -2303,7 +2342,7 @@ the descendants of the item are not displayed
 - the item is collapsed.
 For a new item this state is switched on.
 It can be modified by means of the widget commands
-\fBexpand\fR, \fBcollapse\fR, or \fBtoggle\fR.
+\fBitem expand\fR, \fBitem collapse\fR, or \fBitem toggle\fR.
 .TP
 \fBselected\fR
 This state is set for every item, which is included in the selection.
@@ -2323,17 +2362,45 @@ Some widget commands expect a \fIstatePattern\fR argument,
 which should be a non empty list of \fIstateDesc\fRs.
 The pattern matches, if for every element of the list
 the \fIstateDesc\fR describes the same state as the item currently has.
+.SH "PER-STATE OPTIONS"
+The visual appearance of an item can change depending on the state the item
+is in, such as being the active item, being included in the selection, being
+collapsed, or some combination of those or other states. When a configuration
+option is described as \fBper-state\fR, it means the option describes a
+value which varies depending on the state of the item. If a per-state option is
+specified as a single value, the value is used for all states. Otherwise
+the per-state option must be specified as an even-numbered list. For example,
+to use the font "Times 12 bold" in a \fBtext\fR element regardless of the
+item state you can write:
+.nf
+$T element configure MyTextElement -font {{Times 12 bold}}
+.fi
+However, to use a different font when the item is selected you could write:
+.nf
+$T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
+.fi
+In the second example above the -font option reads "value stateList value stateList".
+If \fIstateList\fR is an empty list, the preceding \fIvalue\fR is used regardless
+of the item state. A non-empty stateList specifies a list of states which must be
+set for the item in order to use the preceding value. Each stateList can also
+include state names preceded by a ! sign, indicating the state must *not* be
+set for the item. For example:
+.nf
+$T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}
+.fi
+In the example above, the \fBrect\fR element is filled with blue when the treectrl
+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.
 .SH "ELEMENTS"
-Elements are the smallest building block
+Elements are the smallest building blocks
 which are handled by a treectrl widget.
 One or more elements together can be combined to a style,
 which can be considered as a blueprint for an item.
-They can also be used to create an item directly
-by means of the \fBitem complex\fR widget command.
 An element can be of type \fBbitmap\fR, \fBborder\fR, \fBimage\fR,
-\fBrect\fR, or \fBtext\fR.
-For each element type there is a section below describing all options
-which can modify the behaviour of an element of this type.
+\fBrect\fR, \fBtext\fR or \fBwindow\fR.
+For each element type there is a section below describing the options
+which can modify an element of that type.
 .PP
 There are some options which can be configured to get different values
 dependent on the state of the item in which their element is included.
@@ -2345,28 +2412,28 @@ For acceptable values of \fIstatePattern\fR
 see the section \fBSTATES\fR above.
 The last \fIstatePattern\fR can be empty,
 implementing a sort of \fIotherwise clause\fR.
-The options with this behaviour are called \fIper state options\fR.
+The options with this behaviour are called \fIper-state options\fR.
 .SH "BITMAP ELEMENT"
 An element of type \fBbitmap\fR can be used to display a bitmap in an item.
 The following options are supported for bitmap elements:
 .TP
 \fB\fB-background\fR\fR \fIcolor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color to use for each of the bitmap's '0' valued pixels.
 .TP
 \fB\fB-bitmap\fR\fR \fIbitmap\fR
-Specifies as a per state option
+Specifies as a per-state option
 the bitmap to display in the element.
 .TP
 \fB\fB-foreground\fR\fR \fIcolor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color to use for each of the bitmap's '1' valued pixels.
 .SH "BORDER ELEMENT"
 An element of type \fBborder\fR can be used to add a border to an item.
 The following options are supported for border elements:
 .TP
 \fB\fB-background\fR\fR \fIcolor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color to use for the background of the border.
 .TP
 \fB\fB-filled\fR\fR \fIboolean\fR
@@ -2378,7 +2445,7 @@ background color of the tree is visible between the borders.
 Specifies the height of the area of the border.
 .TP
 \fB\fB-relief\fR\fR \fIreliefList\fR
-Specifies as a per state option
+Specifies as a per-state option
 relief of the border.
 For acceptable values see the description of the
 \fB-relief\fR option in the \fBoptions\fR manual page.
@@ -2396,7 +2463,7 @@ The following options are supported for image elements:
 Specifies the height of the image.
 .TP
 \fB\fB-image\fR\fR \fIimage\fR
-Specifies as a per state option
+Specifies as a per-state option
 the image to display in the element.
 .TP
 \fB\fB-width\fR\fR \fIsize\fR
@@ -2406,7 +2473,7 @@ An element of type \fBrect\fR can be used to display a rectangle in an item.
 The following options are supported for rectangle elements:
 .TP
 \fB\fB-fill\fR\fR \fIfillColor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color to be used to fill rectangle's area.
 \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
 If \fIcolor\fR is an empty string (the default), then
@@ -2424,7 +2491,7 @@ will not be drawn.
 The default is the empty string, which causes the outline to be drawn completely.
 .TP
 \fB\fB-outline\fR\fR \fIoutlineColor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color that should be used to draw the outline of the rectangle.
 \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
 If \fIcolor\fR is specified as an empty string (the default),
@@ -2457,7 +2524,7 @@ Specifies the datatype which should be used to convert the value of the
 \fBdouble\fR, \fBinteger\fR, \fBlong\fR, \fBstring\fR, or \fBtime\fR.
 .TP
 \fB\fB-fill\fR\fR \fIcolor\fR
-Specifies as a per state option
+Specifies as a per-state option
 the color to be used as foreground color of the text.
 \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
 If \fIcolor\fR is an empty string (the default), then
@@ -2473,7 +2540,7 @@ for all other datatypes it should be
 a valid format element of the \fBformat\fR command.
 .TP
 \fB\fB-font\fR\fR \fIfontName\fR
-Specifies as a per state option
+Specifies as a per-state option
 the font to use for the text.
 \fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR.
 If this option isn't specified, it defaults to the font configured for
@@ -2505,6 +2572,18 @@ Specifies the width of the area of the text.
 \fIMode\fR specifies how to handle lines that are wider than the
 text's area.
 Acceptable values are \fBchar\fR or \fBword\fR.
+.SH "WINDOW ELEMENT"
+An element of type \fBwindow\fR can be used to display a Tk window in an item.
+The following options are supported for window elements:
+.TP
+\fB\fB-window\fR\fR \fIpathName\fR
+Specifies the window to associate with this element. The window specified by
+\fIpathName\fR must either be a child of the treectrl widget or a child of
+some ancestor of the treectrl widget. \fIPathName\fR may not refer to a
+top-level window. This option cannot be specified by
+the \fBelement create\fR or \fBelement configure\fR commands, only by the
+\fBitem element configure\fR command; i.e., the element must be associated
+with a particular item.
 .SH "ITEM DESCRIPTION"
 Many of the widget commands for a treectrl take as one argument an
 indicator of which item of the treectrl to operate on.  These
@@ -2674,6 +2753,13 @@ Generated after an item is expanded.
 \fB%I\fR The item id
 .RE
 .TP
+\fB<ItemDelete>\fR
+Generated when items are about to be deleted by the \fBitem delete\fR command.
+.RS
+.TP
+\fB%i\fR List of items ids being deleted.
+.RE
+.TP
 \fB<Scroll-x>\fR
 Generated whenever the view in the treectrl changes in such a way that a
 horizontal scrollbar should be redisplayed.