Update docs for "item create", "item cget", "item configure", "dragimage visible" etc.

1 files changed, 117 insertions, 80 deletions

diff --git a/doc/treectrl.man b/doc/treectrl.man
index afe19bd..8aeb9f3 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.5 2004/07/26 17:16:52 treectrl Exp $}
+  $Id: treectrl.man,v 1.6 2004/07/30 21:21:01 treectrl Exp $}
 ][manpage_begin treectrl n 1.0]
 [moddesc {Tk Commands}]
 [titledesc {Create and manipulate hierarchical multicolumn widgets}]
@@ -119,9 +119,11 @@ during column resizing.
 
 [tkoption_def -defaultstyle defaultStyle DefaultStyle]
 Specifies a list of styles, one per column, to apply to each item created by
-the [cmd "item create"] command.
-Each element in the list should be a valid style name or an empty string to
-indicate no style should be applied to a specific column.
+the [cmd "item create"] command. The number of styles in the list can be
+different from the number of tree columns.
+Each list element should be a valid style name or an empty string to
+indicate no style should be applied to a specific column. The list of styles
+is updated if a style is deleted or if a column is moved.
 
 [tkoption_def -doublebuffer doubleBuffer DoubleBuffer]
 Specifies if double-buffering should be used to improve displaying.
@@ -148,10 +150,11 @@ Indentation is the screen distance an item is displayed more to
 the right than its father.
 
 [tkoption_def -itemheight itemHeight ItemHeight]
-Specifies the minimal height of an item
+Specifies a fixed height for every item
 in any of the forms acceptable to [fun Tk_GetPixels].
 The default is 0, which means that
-every item has exactly the height of it stallest element.
+every item has the height requested by the arrangement of elements
+in each column.
 
 [tkoption_def -linecolor lineColor LineColor]
 Specifies the color which should be used for drawing
@@ -415,9 +418,9 @@ The needed width is the maximum of the width of the column header
 and the width of the [emph widest] currently visible item.
 
 [call [arg pathName] [cmd {column width}] [arg column]]
-This command returns a decimal string giving the width
+This command returns a decimal string giving the width in pixels
 of the column specified by [arg column],
-even if the treectrl is configured to don't display the column headers
+even if the treectrl is configured to not display the column headers
 by means of the [option -showheader] option.
 [list_end]
 
@@ -586,9 +589,6 @@ The following dragimage options are supported:
 [opt_def [option -visible] [arg boolean]]
 Specifies a boolean value which determines
 whether the dragimage should currently be visible.
-This option should not be modified by means of the
-[cmd {dragimage configure}] widget command;
-instead use the [cmd {dragimage visible}] widget command.
 [list_end]
 
 [call [arg pathName] [cmd {dragimage offset}] [opt [arg {x y}]]]
@@ -599,13 +599,6 @@ relative to the item its shape is derived from.
 If two coordinates are specified,
 sets the dragimage offset to the given coordinates [arg x] and [arg y].
 
-[call [arg pathName] [cmd {dragimage visible}] [opt [arg boolean]]]
-If the additional argument specifies true, the dotted lines will become
-visible and the dragimage option [option -visible] becomes 1;
-if it specifies false, the dotted lines will be hidden
-and the dragimage option [option -visible] becomes 0.
-Returns 1 if the dragimage is currently visible,
-0 otherwise.
 [list_end]
 
 [call [arg pathName] [cmd element] [arg option] [opt [arg element]] \
@@ -744,6 +737,11 @@ in this column is considered, if an additional [arg element] is specified,
 the area of this [arg element] in [arg column] of the specified item is
 returned.
 
+[call [arg pathName] [cmd {item cget}] [arg itemDesc] [arg option]]
+Returns the current value of the configuration option for the item specified by
+[arg itemDesc] whose name is [arg option]. [arg Option] may have any of the
+values accepted by the [cmd "item create"] command when the item was created.
+
 [call [arg pathName] [cmd {item children}] [arg itemDesc]]
 Returns a list containing the numerical indexes of all children
 of the item specified by [arg itemDesc] in the correct order from
@@ -759,11 +757,47 @@ Every [arg option] must be known by the element's type
 The corresponding [arg value] will overwrite the value of the element for this
 one column in this item.
 
-[call [arg pathName] [cmd {item create}]]
-Creates a new item and returns its numerical indexes.
-The new item has set the states [const open] and [const enabled].
-If the treectrl widget has currently the focus,
-also the state [const focus] is set.
+[call [arg pathName] [cmd {item configure}] [arg itemDesc] [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
+If no [arg option] is specified, returns a list describing all of the available
+options for the item given by [arg itemDesc] (see [fun Tk_ConfigureInfo] for
+information on the format of this list). If [arg option] is specified with no
+value, then the command returns a list describing the one named option (this
+list will be identical to the corresponding sublist of the value returned if
+no [arg option] is specified). If one or more [arg option]-[arg value] pairs
+are specified, then the command modifies the given widget option(s) to have the
+given value(s); in this case the command returns an empty string. The options
+and values are the same as those permissible in the [cmd "item create"] command
+when the item was created.
+
+[call [arg pathName] [cmd {item create}] [opt [arg {option value ...}]]]
+Creates a new item and returns its unique identifier.
+The new item has the states [const open] and [const enabled] set by default.
+If the treectrl widget currently has the focus,
+the state [const focus] is also set. Each [arg option]-[arg value] pair sets one
+of the configuration options for the item. These same [arg option]-[arg value]
+pairs may be used in the [cmd "item configure"] command to change the item's
+configuration.
+[nl]
+The following options are supported by items:
+
+[list_begin opt]
+
+[opt_def [option -button] [arg boolean]]
+[arg Boolean] must have one of the forms accepted by [fun Tk_GetBoolean]. It
+indicates whether or not an expand/collapse button should be drawn next to this
+item, typically to indicate the item has children. The button will only be
+displayed if:
+a) the column specified by the widget option [option -treecolumn] is visible;
+and b) the widget option [option -showbuttons] is true
+
+[opt_def [option -visible] [arg boolean]]
+[arg Boolean] must have one of the forms accepted by [fun Tk_GetBoolean]. It
+indicates that the item should be displayed in the list. The item will only be
+displayed if:
+a) each ancestor is a descendant of the root item (not an orphan);
+and b) each ancestor's [option -visible] option is true 
+
+[list_end]
 
 [call [arg pathName] [cmd {item delete}] [arg first] [opt [arg last]]]
 Deletes the specified item(s).
@@ -774,7 +808,7 @@ specified, the item described by [arg first] is deleted.
 If both [arg first] and [arg last] are specified,
 they must decribe items with a common ancestor;
 then the range of items between [arg first] and [arg last] is deleted.
-[nl][nl]
+[nl]
 Deleting an item deletes any child items of the deleted item recursively.
 If the current [const active] item is deleted, the root item becomes the new active item.
 If the current selection [const anchor] item is deleted, the root item becomes the new anchor item.
@@ -796,11 +830,12 @@ The following forms of the command are supported:
 [list_begin definitions]
 [call [arg pathName] [cmd {item element actual}] [arg itemDesc] [arg column] \
      [arg element] [arg option]]
-This command returns the current value of the option named [arg option]
+This command returns the current value of the configuration option named [arg option]
 associated with [arg element] inside [arg column] of the item described by
-[arg itemDesc]; if it was already configured for the actual item, the
-return value is the same as if the [cmd {item element actual}] widget command
-was used; otherwise the option value of the underlynig element is returned.
+[arg itemDesc]. If [arg option] was configured using the
+[cmd "item element configure"] command, the
+return value is the same as if the [cmd {item element cget}] command
+was used. Otherwise the value of the configuration option of the underlying element is returned.
 [arg Option] may have any of the values accepted by the type of the
 specified element (see [sectref ELEMENTS] below)
 
@@ -839,12 +874,6 @@ If [arg child] is specified, it must described an item
 that is not an ancestor of [arg parent].
 Then it will become the new first child of [arg parent].
 
-[call [arg pathName] [cmd {item hasbutton}] [arg itemDesc] [opt [arg boolean]]]
-If [arg boolean] is not specified, returns 1 if to the left of
-the item described by [arg itemDesc] a button should be drawn, 0 otherwise.
-If [arg boolean] is specified, it must be a valid boolean value
-specifying if a button should be displayed to the left of this item. 
-
 [call [arg pathName] [cmd {item index}] [arg itemDesc]]
 Returns a list of two integers, which corresponds to the row 
 of the item described by [arg itemDesc],
@@ -922,8 +951,6 @@ instead the sorted items are returned as result of the command.
 [nl]
 
 By default ASCII sorting is used with the result returned in increasing order.
-The order can be modified by means of the [option -increasing] (the default)
-or [option -decreasing] flag.
 Any of the following options may be specified to control
 the sorting process of the previously specified column
 (unique abbreviations are accepted):
@@ -941,6 +968,9 @@ equal to, or greater than zero if the first item is to
 be considered less than, equal to, or greater than the second,
 respectively.
 
+[opt_def [option -decreasing]]
+Sort the items in decreasing order ("largest" items first).
+
 [opt_def [option -dictionary]]
 Use dictionary-style comparison. This is the same as [option -ascii]
 except (a) case is ignored except as a tie-breaker and (b) if two
@@ -949,6 +979,9 @@ not characters.  For example, in [option -dictionary] mode, [term bigBoy]
 sorts between [term bigbang] and [term bigboy], and [term x10y]
 sorts between [term x9y] and [term x11y].
 
+[opt_def [option -increasing]]
+Sort the items in increasing order ("smallest" items first). This is the default.
+
 [opt_def [option -integer]]
 Convert to integers and use integer comparison.
 
@@ -956,6 +989,15 @@ Convert to integers and use integer comparison.
 Convert to floating-point values and use floating comparison.
 [list_end]
 
+[call [arg pathName] [cmd {item state}] [arg command] [arg itemDesc] \
+     [opt [arg {arg ...}]]]
+This command is used to manipulate the states of an item.
+The exact behavior of the command depends on the [arg command] argument
+that follows the [cmd style] argument.
+The following forms of the command are supported:
+
+[list_begin definitions]
+
 [call [arg pathName] [cmd {item state get}] [arg itemDesc] \
      [opt [arg {stateName ...}]]]
 If no [arg stateName] is specified, returns a list containing
@@ -979,9 +1021,11 @@ in the range betwen [arg itemDesc] and [arg lastItem].
 [arg ItemDesc] may be the string [const all],
 then the state changes are made for all items of the treectrl widget.
 
+[list_end]
+
 [call [arg pathName] [cmd {item style}] [arg command] [arg itemDesc] \
      [opt [arg {arg ...}]]]
-This command is used to manipulate the style of the item.
+This command is used to manipulate the styles of an item.
 The exact behavior of the command depends on the [arg command] argument
 that follows the [cmd style] argument.
 The following forms of the command are supported:
@@ -994,11 +1038,15 @@ which is set for the item described by [arg itemDesc] in [arg column].
 
 [call [arg pathName] [cmd {item style map}] [arg itemDesc] [arg column] \
      [arg style] [arg map]]
-[arg Map] must be a list with an even number of elements,
-and each element must be the name of an element created by the
-[cmd {element create}] widget command.
-Replaces elements in the style of the item described by [arg itemDesc]
-in [arg column] based on the from-to pairs in [arg map].
+Like the [cmd "item style set"] command, this command may be used to assign a
+style to a specific column of an item. Unlike [cmd "item style set"], this
+command can transfer configuration values of elements in the current style
+to elements in the new style specified by [arg style].
+
+[arg Map] must be a list of [arg elementOld]-[arg elementNew] pairs, where
+[arg elementOld] is an element in the current style, and [arg elementNew] is
+an element in the style specified by [arg style]. Both [arg elementOld] and
+[arg elementNew] must be of the same type ([const bitmap], [const text] etc).
 
 [call [arg pathName] [cmd {item style set}] [arg itemDesc] [opt [arg column]] \
      [opt [arg style]] [opt [arg {column style ...}]]]
@@ -1024,14 +1072,6 @@ this command is provided as a convenience. Use the
 [cmd "item element configure"] command if you want to set the text of a
 specific text element.
 
-[call [arg pathName] [cmd {item visible}] [arg itemDesc] [opt [arg boolean]]]
-If [arg boolean] is not specified, returns 1 if the item
-described by [arg itemDesc] is currently visible, 0 otherwise.
-If [arg boolean] is specified, it must be a valid boolean value
-specifying if the item should be visible.
-The visibility of an item is independend from the state of its ancestors.
-So if the state of one of the ancestors is currently not opened,
-the item may be considered visible although it is not displayed on the screen.
 [list_end]
 
 [call [arg pathName] [cmd marquee] [arg option] [opt [arg {arg ...}]]]
@@ -1085,9 +1125,6 @@ The following marquee options are supported:
 Specifies a boolean value which determines
 whether the dotted line surrounding the region of the marquee
 should currently be visible.
-This option should not be modified by means of the
-[cmd {marquee configure}] widget command;
-instead use the [cmd {marquee visible}] widget command.
 [list_end]
 
 [call [arg pathName] [cmd {marquee coords}] [opt [arg {x1 y1 x2 y2}]]]
@@ -1115,13 +1152,6 @@ These lists start with the column number,
 followed by the elements of the style defined for the item in this column
 if there are any.
 
-[call [arg pathName] [cmd {marquee visible}] [opt [arg boolean]]]
-If the additional argument specifies true, the dotted line will become
-visible and the marquee option [option -visible] becomes 1;
-if it specifies false, the dotted line will be hidden
-and the marquee option [option -visible] becomes 0.
-Returns 1 if the dotted line surrounding the marquee is currently visible,
-0 otherwise.
 [list_end]
 
 [call [arg pathName] [cmd notify] [arg option] [opt [arg {arg ...}]]]
@@ -1507,7 +1537,6 @@ It can happen that the element's space is larger than its requested dimensions.
 These options may be used to position (or stretch) the slave within its cell.
 [arg Style]  is a string that contains zero or more of the characters
 [const n], [const s], [const e] or [const w].
-The string can contain other characters, but they are ignored.
 Each letter refers to a side (north, south,
 east, or west) in which direction the element will grow in.
 
@@ -1516,7 +1545,6 @@ If an element's area is smaller than its requested dimensions, this
 option may be used to allow shrinking of the element.
 [arg Style] is a string that contains zero or more of the characters
 [const x] or [const y].
-The string can contain other characters, but they are ignored.
 [const x] shrinks the element horizontally,
 [const y] shrinks it vertically.
 
@@ -1687,9 +1715,9 @@ Indicates whether or not a mouse click on the column header should
 change the sorting order of the tree.
 
 [opt_def [option -expand] [arg boolean]]
-Indicates whether or not any extra spaces should be distributed
+Indicates whether or not any extra horizontal space should be distributed
 to this column.
-This option will actually only work, if the column has no fix width defined
+This option will actually only work if the column has no fixed width defined
 by means of the [option -width] column option.
 
 [opt_def [option -font] [arg fontName]]
@@ -1758,16 +1786,26 @@ or top and bottom (for [option -textpady]) side of the text.
 of two values to specify padding for the two sides separately,
 it defaults to 0.
 
-[opt_def [option -width] [arg size]]
-Specifies the width of the column.
-
 [opt_def [option -visible] [arg boolean]]
 Indicates whether or not the column should be displayed.
 
+[opt_def [option -width] [arg size]]
+Specifies a fixed width for the column. If this value is zero, the column width
+is calculated as the maximum of:
+a) the width requested by items;
+b) the width requested the column header;
+c) and the column [option -minwidth].
+This calculated width is also affected by the [option -expand] option of all
+columns.
+
 [opt_def [option -widthhack] [arg boolean]]
-Indicates whether or not all items inside the column
-should have the same width
-(typically in a treectrl widget with horizontal orientation).
+Indicates whether or not all items should have the same width. This option only
+has effect when all of these conditions are met:
+a) the tree [option -orientation] option is [const vertical];
+b) only a single tree column is visible;
+c) the single visible tree column [option -width] option is zero;
+d) and the tree [option -wrap] option results in wrapping.
+
 [list_end]
 
 [section STATES]
@@ -2076,8 +2114,7 @@ Indicates the root item of the treectrl.
 The [arg itemDesc] may be followed by one or more [arg modifier]s.
 A modifier changes the item described by the [arg itemDesc] relative to
 the description upto this point.
-It may be specified in any of the following forms,
-all optionally followed by [const visible]:
+It may be specified in any of the following forms:
 
 [list_begin definitions]
 [lst_item [const above]]
@@ -2089,13 +2126,13 @@ Use the item one row below in this column.
 [lst_item [const bottom]]
 Use the item in the last row of this column.
 
-[lst_item "[const child] [arg n]"]
+[lst_item "[const child] [arg n] [opt [const visible]]"]
 Use the [arg n]th child of the item.
 
-[lst_item [const firstchild]]
+[lst_item "[const firstchild] [opt [const visible]]"]
 Use the first child of the item.
 
-[lst_item [const lastchild]]
+[lst_item "[const lastchild] [opt [const visible]]"]
 Use the last child of the item.
 
 [lst_item [const left]]
@@ -2104,22 +2141,22 @@ Use the item one column to the left in the same row.
 [lst_item [const leftmost]]
 Use the item of the first column in the same row.
 
-[lst_item [const next]]
+[lst_item "[const next] [opt [const visible]]"]
 Use the next item, which is the first existant (or visible) item of the
 following list: the first child, the next sibling or the next sibling of
 the nearest parent which has one.
 
-[lst_item [const nextsibling]]
+[lst_item "[const nextsibling] [opt [const visible]]"]
 Use the next sibling of the item.
 
 [lst_item [const parent]]
 Use the parent of the item.
 
-[lst_item [const prev]]
+[lst_item "[const prev] [opt [const visible]]"]
 Use the last child of the previous sibling,
 or the parent if there is no previos sibling.
 
-[lst_item [const prevsibling]]
+[lst_item "[const prevsibling] [opt [const visible]]"]
 Use the previous sibling of the item.
 
 [lst_item [const right]]
@@ -2128,7 +2165,7 @@ Use the item one column to the right in the same row.
 [lst_item [const rightmost]]
 Use the item of the last column in the same row.
 
-[lst_item "[const sibling] [arg n]"]
+[lst_item "[const sibling] [arg n] [opt [const visible]]"]
 Use the [arg n]th child of the item's parent.
 
 [lst_item [const top]]