diff options
Diffstat (limited to 'doc/treectrl.man')
| -rw-r--r-- | doc/treectrl.man | 134 |
1 files changed, 64 insertions, 70 deletions
diff --git a/doc/treectrl.man b/doc/treectrl.man index 77fcbc7..ad4329f 100644 --- a/doc/treectrl.man +++ b/doc/treectrl.man @@ -3,11 +3,11 @@ 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.41 2006/11/03 22:31:05 treectrl Exp $} -][manpage_begin treectrl n 2.1.1] + $Id: treectrl.man,v 1.42 2006/11/18 04:40:10 treectrl Exp $} +][manpage_begin treectrl n 2.2] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] -[require treectrl 2.1.1] +[require treectrl 2.2] [description] [list_begin definitions] @@ -465,12 +465,12 @@ for the column specified by the [call [arg pathName] [cmd {column configure}] [arg columnDesc] \ [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]] This command is similar to the [cmd configure] widget command except -that it modifies options associated with the column specified by the +that it modifies options associated with the columns specified by the [sectref {COLUMN DESCRIPTION} {column description}] [arg columnDesc] instead of modifying options for the overall treectrl widget. [arg ColumnDesc] may be the string [const tail] to specify the tail column. -If [arg columnDesc] is the string [const all], at least one option-value pair -must be given; in this case all the columns are configured. +If [arg columnDesc] refers to more than one column, then at least one option-value pair +must be given. If no [arg option] is specified, the command returns a list describing all of the available options for [arg columnDesc] (see [fun Tk_ConfigureInfo] for information on the format of this list). @@ -495,11 +495,13 @@ or [const !=]. The return value of this command is 1 if the comparison evaluated to true, 0 otherwise. -[call [arg pathName] [cmd {column count}]] -Returns a decimal string giving the number of +[call [arg pathName] [cmd {column count}] [opt [arg columnDesc]]] +If no additional arguments are given, the result is a decimal string giving the number of columns created by the [cmd "column create"] widget command which haven't been -deleted by the [cmd "column delete"] widget command. The [const tail] column +deleted by the [cmd "column delete"] widget command; in this case the [const tail] column is not counted. +If [arg columnDesc] is given, then the result is the number of columns that +match that [sectref {COLUMN DESCRIPTION} {column description}]. [call [arg pathName] [cmd {column create}] [opt [arg {option value ...}]]] This command creates a new column in the treectrl widget. The new column is @@ -676,7 +678,8 @@ The following forms of the command are supported: [list_begin definitions] [call [arg pathName] [cmd {debug alloc}]] -Returns a string giving partial statistics on memory allocations. +Returns a string giving partial statistics on memory allocations, if the package +was built with TREECTRL_DEBUG defined. [call [arg pathName] [cmd {debug cget}] [arg option]] This command returns the current value of the debugging option @@ -755,12 +758,12 @@ Returns a string useful for debugging vertical scrolling. [list_end] [call [arg pathName] [cmd depth] [opt [arg itemDesc]]] -If the additional argument [arg itemDesc] is specified, -returns a decimal string giving the depth of -the item describing by [arg itemDesc], whereas depth is defined as -the number of steps you must go upward to reach to root item. -If no [arg itemDesc] is specified, the maximum depth of all +If the additional argument [arg itemDesc] is given, +then the result is a decimal string giving the depth of +the item described by [arg itemDesc]. +If no [arg itemDesc] is specified, then the maximum depth of all items in the treectrl widget is returned instead. +Depth is defined as the number of ancestors an item has. [call [arg pathName] [cmd dragimage] [arg option] [opt [arg {arg ...}]]] This command is used to manipulate the dragimage, @@ -964,20 +967,12 @@ of the item specified by [arg itemDesc] in the correct order from the first child to the last child. [call [arg pathName] [cmd {item collapse}] [arg itemDesc] [opt [option -recurse]]] -Switches off the [const open] state of the item(s) -described by [arg itemDesc]. -If the item has descendants, they are no longer displayed. -If the item is configured to have a button, -the button will now display the image or bitmap configured with the -widget options [option -buttonimage] or [option -buttonbitmap], -or a [emph +] sign if no image or bitmap is configured. -If the item is already closed, this command has no effect. -[arg ItemDesc] may also be the string [const all], -in which case all items of the treectrl widget are collapsed. -If [option -recurse] is specified, all descendants of [arg itemDesc] -will also be collapsed. -For every item, that actually will be collapsed, -two events are generated: +Switches off the [const open] state of the item(s) described by [arg itemDesc]. +If an item has descendants, then they are no longer displayed. +If an item is already closed, then this command has no effect on that item. +If [option -recurse] is specified, then all descendants of the items described +by [arg itemDesc] will also be collapsed. +For every item that actually will be collapsed, two events are generated: a [const <Collapse-before>] event before the item state is changed, and a [const <Collapse-after>] event after the item state was changed. @@ -995,7 +990,7 @@ This horrible command is now deprecated. Use [cmd {item element configure}] instead. For every column of the treectrl there may be specified one [arg list]. Each [arg list] should look like this: [example_begin] -{ {element option value...} {element option value...} ...} +{ {element option value ...} {element option value ...} ...} [example_end] Every [arg option] must be known by the element's type (see [sectref ELEMENTS] below). @@ -1027,14 +1022,13 @@ the meaning of each option): [list_end] -[call [arg pathName] [cmd {item count}] [opt [arg -visible]]] -Returns a decimal string giving the number of +[call [arg pathName] [cmd {item count}] [opt [arg itemDesc]]] +If no additional arguments are given, the result is a decimal string giving the number of items created by the [cmd "item create"] widget command which haven't been deleted by the [cmd "item delete"] widget command, plus 1 for the ever-present -root item. If the optional argument [arg -visible] is given, only the items -whose ancestors are expanded, and whose -visible option is true, get counted. -Additionally, for the root item, the treectrl option [option -showroot] must -be true for the root item to be counted. +root item. +If the optional argument [arg itemDesc] is given, then the result is the +number of items that match that [sectref {ITEM DESCRIPTION} {item description}]. [call [arg pathName] [cmd {item create}] [opt [arg {option value ...}]]] Creates some new items and optionally returns a list of unique identifiers for @@ -1053,7 +1047,8 @@ 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 treectrl option [option -treecolumn] is visible; -and b) the treectrl option [option -showbuttons] is true +and b) the treectrl option [option -showbuttons] is true; +and c) for the root item, the treectrl option [option -showrootbutton] is true. [opt_def [option -count] [arg numItems]] Specifies the number of items to create. Must be >= 0. Defaults to 1. @@ -1114,7 +1109,7 @@ in all cases the specification of the root item is ignored. For each call to this command, two events may be generated. If any of the deleted items are selected, then a [const <Selection>] event is generated just before the items are deleted. -If any items were actually deleted, then an [const <ItemDelete>] event event is generated just before the items +If any items are going to be deleted, then an [const <ItemDelete>] event event is generated just before the items are deleted. [call [arg pathName] [cmd {item descendants}] [arg itemDesc]] @@ -1195,21 +1190,16 @@ Returns 1 if the item described by [arg itemDesc] has the state [const enabled] switched on, 0 otherwise. If [arg boolean] is specified, then the [const enabled] state of every item described by the [sectref {ITEM DESCRIPTION} {item description}] [arg itemDesc] is set accordingly. +All items are enabled when first created. Disabled items cannot be selected, +and are ignored by the default key-navigation and mouse bindings. [call [arg pathName] [cmd {item expand}] [arg itemDesc] [opt [option -recurse]]] Switches on the [const open] state of the item(s) described by [arg itemDesc]. -If the item has descendants, they are now displayed. -If the item is configured to have a button, -the button will now display the image or bitmap configured with the -widget options [option -buttonimage] or [option -buttonbitmap], -or a [emph -] sign if no image or bitmap is configured. -If the item is already open, this command has no effect. -[arg ItemDesc] may also be the string [const all], -in which case all items of the treectrl widget are expanded. -If [option -recurse] is specified, all descendants of [arg itemDesc] -will also be expanded. -For every item, that actually will be expanded, -two events are generated: +If an item has descendants, then they are now displayed. +If an item is already open, then this command has no effect on that item. +If [option -recurse] is specified, then all descendants of the items described by +[arg itemDesc] will also be expanded. +For every item that actually will be expanded, two events are generated: an [const <Expand-before>] event before the item state is changed, and an [const <Expand-after>] event after the item state was changed. @@ -1527,13 +1517,11 @@ want to set or retrieve the value of the -text option for a specific text elemen [call [arg pathName] [cmd {item toggle}] [arg itemDesc] [opt [option -recurse]]] Changes the [const open] state of the item(s) described by [arg itemDesc]. -If the state is currently switched off, -this command does the same as the [cmd {item expand}] widget command, +If the [const open] state is currently switched off, then +this command does the same as the [cmd {item expand}] widget command; otherwise the same as the [cmd {item collapse}] widget command. -[arg ItemDesc] may also be the string [const all], -in which case the state of all items of the treectrl widget are toggled. -If [option -recurse] is specified, the state of all descendants of -[arg itemDesc] will also be toggled. +If [option -recurse] is specified, then the [const open] state of all descendants of +the items described by [arg itemDesc] will also be toggled. [list_end] @@ -1605,15 +1593,19 @@ If two coordinates are specified, sets the corner to the given coordinates [arg x] and [arg y]. [call [arg pathName] [cmd {marquee identify}]] -Returns a list with information about the items inside the marquee. -The list has as elements a list itself -for every item which is displayed inside the marquee. -The first element of these lists is the numerical item id, -followed by another list with information about every column of the -item inside the marque. -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. +Returns a list with information about any items intersecting the marquee. +The format of the returned list is: +[example_begin] +{ + {item {column element element ...} {column element element ...} ...} + {item {column element element ...} {column element element ...} ...} + ... +} +[example_end] +There may be zero sublists following an item id if the marquee is in the +button/line area of an item. There may be zero element names following a +column id if the item-column has no style or if the marquee does not +intersect any elements in that column. [list_end] @@ -2276,8 +2268,10 @@ determines this). The value may have any of the forms acceptable to [fun Tk_GetPixels]. [opt_def [option -button] [arg boolean]] -Indicates whether or not a mouse click on the column header should -change the sorting order of the tree. +Indicates whether or not the column header should be treated like a pushbutton. +When this option is true, the default bindings track <Button-1> events +in the header and generate a <Header-invoke> event when a <ButtonRelease-1> +event occurs in the header. See [sectref {DYNAMIC EVENTS}]. [opt_def [option -expand] [arg boolean]] Indicates whether or not any extra horizontal space should be distributed @@ -2336,7 +2330,7 @@ This option has no effect if the [option -width] option is set. [opt_def [option -resize] [arg boolean]] Specifies a boolean value that indicates whether the user should be allowed to -resize the column by dragging the right edge of the column's header. Default is true. +resize the column by dragging the edge of the column's header. Default is true. [opt_def [option -squeeze] [arg boolean]] Specifies a boolean value that indicates whether or not the column should @@ -2445,7 +2439,7 @@ This keyword cannot be followed by any modifiers unless a single column is matched. You may run into trouble if [arg tagExpr] looks like a column id or other keyword; also, [arg tagExpr] must look like a single list element since column descriptions are properly-formed lists. To be safe you may want to -use the [const tag] keyword followed by [arg tagExpr]. +use the [const tag] qualifier followed by [arg tagExpr]. [lst_item "[const all] [arg QUALIFIERS]"] Indicates every column, including the tail column if the command allows it, @@ -2929,7 +2923,7 @@ This keyword cannot be followed by any modifiers unless a single item is matched. You may run into trouble if [arg tagExpr] looks like an item id or other keyword; also, [arg tagExpr] must look like a single list element since item descriptions are properly-formed lists. To be safe you may want to -use the [const tag] keyword followed by [arg tagExpr]. +use the [const tag] qualifier followed by [arg tagExpr]. [lst_item [const active]] Indicates the item that is currently active, i.e. normally |