diff options
| author | treectrl <treectrl> | 2006-10-27 04:37:11 (GMT) |
|---|---|---|
| committer | treectrl <treectrl> | 2006-10-27 04:37:11 (GMT) |
| commit | c183847037e396cbab17a5fef3199a83c1736dc2 (patch) | |
| tree | 6f9f92b47f295b72947693d7ea5cf7f47beafe86 /doc | |
| parent | 0d20c257e1157bc065fe0f700bb82addff4315d5 (diff) | |
| download | tktreectrl-c183847037e396cbab17a5fef3199a83c1736dc2.zip tktreectrl-c183847037e396cbab17a5fef3199a83c1736dc2.tar.gz tktreectrl-c183847037e396cbab17a5fef3199a83c1736dc2.tar.bz2 | |
Added column options -uniform and -weight.
Misc rewrites.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/treectrl.html | 197 | ||||
| -rw-r--r-- | doc/treectrl.man | 185 | ||||
| -rw-r--r-- | doc/treectrl.n | 188 |
3 files changed, 305 insertions, 265 deletions
diff --git a/doc/treectrl.html b/doc/treectrl.html index 3bc7ea8..32655e9 100644 --- a/doc/treectrl.html +++ b/doc/treectrl.html @@ -1,10 +1,10 @@ -<! -- Copyright (c) 2002-2003 Christian Krone. -- -- See the file "license.terms" for information on usage and redistribution -- of this file, and for a DISCLAIMER OF ALL WARRANTIES. -- -- $Id: treectrl.html,v 1.37 2006/10/18 03:47:48 treectrl Exp $ +<! -- Copyright (c) 2002-2003 Christian Krone. -- -- See the file "license.terms" for information on usage and redistribution -- of this file, and for a DISCLAIMER OF ALL WARRANTIES. -- -- $Id: treectrl.html,v 1.38 2006/10/27 04:37:11 treectrl Exp $ --><html><head> <title>treectrl - Tk Commands </title> </head> <! -- Generated from file 'doc/treectrl.man' by tcllib/doctools with format 'html' --> -<! -- CVS: $Id: treectrl.html,v 1.37 2006/10/18 03:47:48 treectrl Exp $ treectrl.n +<! -- CVS: $Id: treectrl.html,v 1.38 2006/10/27 04:37:11 treectrl Exp $ treectrl.n --> <body> @@ -434,11 +434,9 @@ not request any size at all. Database Name: <strong>indent</strong><br> Database Class: <strong>Indent</strong><br> <dd> -Specifies the amount of indentation +Specifies the screen distance an item is indented relative to its parent item in any of the forms acceptable to <strong>Tk_GetPixels</strong>. -The default is 19 pixel. -Indentation is the screen distance an item is displayed more to -the right than its father. +The default is 19 pixels. <br><br> <dt>Command-Line Switch: <strong>-itemheight</strong><br> @@ -552,9 +550,11 @@ during row resizing. Database Name: <strong>scrollMargin</strong><br> Database Class: <strong>ScrollMargin</strong><br> <dd> -The interpretation of this option is left to Tcl scripts -that implement scrolling: -the widget implementation ignores this option entirely. +Specifies a positive screen distance +in any of the forms acceptable to <strong>Tk_GetPixels</strong>. +This option is used by the default bindings to determine how close to the +edges of the contentbox the mouse pointer must be before scrolling occurs. +Specifying a positive value is useful when items may be drag-and-dropped. Defaults to 0. <br><br> @@ -682,14 +682,13 @@ be wider than the window (-orient horizontal). Database Name: <strong>xScrollDelay</strong><br> Database Class: <strong>ScrollDelay</strong><br> <dd> -Specifies the amount of time before the default binding should handle -repeating mouse motion events in horizontal direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly horizontal scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. <br><br> <dt>Command-Line Switch: <strong>-xscrollincrement</strong><br> @@ -704,21 +703,21 @@ multiple of <strong>-xscrollincrement</strong>; furthermore, the units for scro (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be <strong>-xscrollincrement</strong>. If the value of this option is less than or equal to zero, then horizontal scrolling -is unconstrained. +snaps to the left of an item, or part of an item if items are wider than the +contentbox. <br><br> <dt>Command-Line Switch: <strong>-yscrolldelay</strong><br> Database Name: <strong>yScrollDelay</strong><br> Database Class: <strong>ScrollDelay</strong><br> <dd> -Specifies the amount of time before the default binding should handle -repeating mouse motion events in vertical direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly vertical scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. <br><br> <dt>Command-Line Switch: <strong>-yscrollincrement</strong><br> @@ -733,7 +732,8 @@ multiple of <strong>-yscrollincrement</strong>; furthermore, the units for scro (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be <strong>-yscrollincrement</strong>. If the value of this option is less than or equal to zero, then vertical scrolling -is unconstrained. +snaps to the top of an item, or part of an item if items are taller than the +contentbox. </dl> <h2><a name="item_and_column_tags">ITEM AND COLUMN TAGS</a></h2> @@ -901,8 +901,7 @@ of the new column. <dt><a name="14"><i class='arg'>pathName</i> <b class='cmd'>column delete</b> <i class='arg'>first</i> ?<i class='arg'>last</i>?</a><dd> Deletes the specified column(s). <i class='arg'>First</i> and <i class='arg'>last</i> must be valid -<a href="#column_description">column descriptions</a>. If <i class='arg'>first</i> -is specified as <strong>all</strong>, then all columns are deleted. If both <i class='arg'>first</i> +<a href="#column_description">column descriptions</a>. If both <i class='arg'>first</i> and <i class='arg'>last</i> are specified, then they may refer to a single column only. The <strong>tail</strong> column cannot be deleted and it is an error to specify it. The order of <i class='arg'>first</i> and <i class='arg'>last</i> doesn't matter, and <i class='arg'>first</i> may @@ -1186,10 +1185,7 @@ debugging options <strong>-enable</strong> and <strong>-display</strong> are swi <dt><a name="36"><i class='arg'>pathName</i> <b class='cmd'>debug dinfo</b></a><dd> -For every of the treectrl widget -a line with some internal values info about all items -is printed to stdout. -The command returns the empty string. +Returns a string describing item layout. <br><br> <dt><a name="37"><i class='arg'>pathName</i> <b class='cmd'>debug expose</b> <i class='arg'>x1</i> <i class='arg'>y1</i> <i class='arg'>x2</i> <i class='arg'>y2</i></a><dd> @@ -1357,7 +1353,7 @@ which specifies the state to use. <br><br> <dt><a name="53"><i class='arg'>pathName</i> <b class='cmd'>element type</b> <i class='arg'>element</i></a><dd> -Returns the type of the elements given by <i class='arg'>element</i>, +Returns the type of the element given by <i class='arg'>element</i>, such as <strong>rect</strong> or <strong>text</strong>. </dl> @@ -1368,39 +1364,38 @@ Use <b class='cmd'>item expand</b> instead. <br><br> <dt><a name="55"><i class='arg'>pathName</i> <b class='cmd'>identify</b> <i class='arg'>x</i> <i class='arg'>y</i></a><dd> -Returns a list containing some diagnostics about what -is displayed at the given windows coordinates <i class='arg'>x</i> and <i class='arg'>y</i>. -The resulting list may be empty, -if nothing is displayed at the given coordinates, -otherwise the first list element is <strong>header</strong> or <strong>item</strong>. -<br><br> - -If the coordinates are in the header area -and thus the first element of the result is <strong>header</strong>, -the number of the column or the string <strong>tail</strong> -is the second element in the resulting list; -if the x coordinate is near the left or right end of the header, -a third element <strong>left</strong> or <strong>right</strong> is added respectively. -<br><br> - -If the coordinates are below the header area -and thus the first element of the result is <strong>item</strong>, -the numerical id of the item -is the second element in the resulting list. -If the x coordinate doesn't fall into the column -displaying the hierarchical structure, -the elements <strong>column</strong> and the column number are added. -If the x coordinate is within the column -displaying the hierarchical structure, -the following elements are added to the resulting list: -<strong>line</strong> and the numerical id of the item the line comes from, -if the x coordinate is above an item connecting line; -<strong>button</strong>, if the x coordinate is above a button; -<strong>column</strong>, the column number, <strong>elem</strong>, and the element name, -if the x coordinate is above an element of the item; -<strong>column</strong> and the column number, -if the x coordinate is to the right of the elements; -nothing otherwise. +Returns a list describing what +is displayed at the given window coordinates <i class='arg'>x</i> and <i class='arg'>y</i>. +If the coordinates are outside the window, over the borders, or over any +whitespace in the window, then the result is an empty string; +otherwise the first word of the result is <strong>header</strong> or <strong>item</strong>. +<br><br> + +If the coordinates are over a column header, then +the first word of the result is <strong>header</strong>, followed by +the unique id of the column (or the string <strong>tail</strong>). +If the x coordinate is near the left or right end of a column, then +a third word <strong>left</strong> or <strong>right</strong> is appended to the result. +<br><br> + +If the coordinates are over an item, then the first word of the result +is <strong>item</strong> followed by the unique id of that item. +If the coordinates are not over the area for displaying buttons and lines, +then <strong>column</strong> and a unique column id are the +3rd and 4th words of the result. If the coordinates are over an element within +that column, then <strong>element</strong> and an element name are the 5th and 6th +words of the result. +<br><br> + +If the coordinates are over a button, then the first word of the result is +<strong>item</strong>, followed by the unique id of that item, followed by the word +<strong>button</strong>. +<br><br> +If the coordinates are over a line descending from an ancestor of an item +(but not the parent of that item), then the first word of the result is +<strong>item</strong>, followed by the unique id of that item, followed by the word +<strong>line</strong>, followed by the unique id of the item the line is coming +from. This is used to collapse the ancestor when the line is clicked on. <br><br> <dt><a name="56"><i class='arg'>pathName</i> <b class='cmd'>index</b> <i class='arg'>itemDesc</i></a><dd> @@ -1428,10 +1423,10 @@ root item if <i class='arg'>itemDesc</i> is a descendant of the root item. <dt><a name="59"><i class='arg'>pathName</i> <b class='cmd'>item bbox</b> <i class='arg'>itemDesc</i> ?<i class='arg'>column</i>? ?<i class='arg'>element</i>?</a><dd> Returns a list with four elements giving the bounding box -for the item described by <i class='arg'>itemDesc</i>. +of the item described by <i class='arg'>itemDesc</i>. If no further argument is specified, the bbox spans the area of the item -over all columns. If a <i class='arg'>column</i> is specified, only the area of the item -in this column is considered, if an additional <i class='arg'>element</i> is specified, +over all non-locked columns. If a <i class='arg'>column</i> is specified, only the area of the item +in this column is considered. If an additional <i class='arg'>element</i> is specified, the area of this <i class='arg'>element</i> in <i class='arg'>column</i> of the specified item is returned. @@ -1636,9 +1631,8 @@ great-grandchildren etc, of the item. <br><br> <dt><a name="70"><i class='arg'>pathName</i> <b class='cmd'>item dump</b> <i class='arg'>itemDesc</i></a><dd> -Returns a list with six elements in the form -<strong>index</strong> <em>index</em> <strong>indexVis</strong> <em>indexVis</em> -<strong>neededHeight</strong> <em>neededHeight</em>. +Returns a list with 4 words in the form +<strong>index</strong> <em>index</em> <strong>indexVis</strong> <em>indexVis</em>. <br><br> <dt><a name="71"><i class='arg'>pathName</i> <b class='cmd'>item element</b> <i class='arg'>command</i> <i class='arg'>itemDesc</i> <i class='arg'>column</i> <i class='arg'>element</i> ?<i class='arg'>arg ...</i>?</a><dd> @@ -1694,7 +1688,8 @@ For example: $C3 $E1 -text "apples and oranges" </pre></td></tr></table></p> Each of the <a href="#column_description">column description</a> arguments -may refer to multiple columns. +to this command may refer to multiple columns if at least one +<i class='arg'>option</i>-<i class='arg'>value</i> pair is given. <br><br> <dt><a name="75"><i class='arg'>pathName</i> <b class='cmd'>item element perstate</b> <i class='arg'>itemDesc</i> <i class='arg'>column</i> <i class='arg'>element</i> <i class='arg'>option</i> ?<i class='arg'>stateList</i>?</a><dd> @@ -1711,7 +1706,8 @@ and dynamic, see <a href="#states">STATES</a>) is used in place of the current s Returns 1 if the item described by <i class='arg'>itemDesc</i> has the state <strong>enabled</strong> switched on, 0 otherwise. If <i class='arg'>boolean</i> is specified, -the <strong>enabled</strong> state is set accordingly. +then the <strong>enabled</strong> state of every item described by the +<a href="#item_description">item description</a> <i class='arg'>itemDesc</i> is set accordingly. <br><br> <dt><a name="77"><i class='arg'>pathName</i> <b class='cmd'>item expand</b> <i class='arg'>itemDesc</i> ?<strong>-recurse</strong>?</a><dd> @@ -1745,8 +1741,8 @@ Then it will become the new first child of <i class='arg'>parent</i>. <dt><a name="79"><i class='arg'>pathName</i> <b class='cmd'>item id</b> <i class='arg'>itemDesc</i></a><dd> This command resolves the <a href="#item_description">item description</a> -<i class='arg'>itemDesc</i> into a list of unique item identifiers. If the item(s) described by -<i class='arg'>itemDesc</i> don't exist, this command returns an empty list. +<i class='arg'>itemDesc</i> into a list of unique item identifiers. If <i class='arg'>itemDesc</i> +doesn't refer to any existing items, then this command returns an empty list. <br><br> <dt><a name="80"><i class='arg'>pathName</i> <b class='cmd'>item image</b> <i class='arg'>itemDesc</i> ?<i class='arg'>column</i>? ?<i class='arg'>image</i>? ?<i class='arg'>column image ...</i>?</a><dd> @@ -2826,8 +2822,8 @@ This command shifts the view in the window left or right according to <i class='arg'>What</i> must be either <strong>units</strong> or <strong>pages</strong> or an abbreviation of one of these. If <i class='arg'>what</i> is <strong>units</strong>, the view adjusts left or right in units -of the <strong>-xscrollincrement</strong> option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. +determined by the <strong>-xscrollincrement</strong> option (which may be zero, +see the description of that option). If <i class='arg'>what</i> is <strong>pages</strong> then the view adjusts in units of nine-tenths the window's width. If <i class='arg'>number</i> is negative then information farther to the left @@ -2870,8 +2866,8 @@ This command adjusts the view in the window up or down according to <i class='arg'>Number</i> must be an integer. <i class='arg'>What</i> must be either <strong>units</strong> or <strong>pages</strong>. If <i class='arg'>what</i> is <strong>units</strong>, the view adjusts up or down in units -of the <strong>-yscrollincrement</strong> option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. +of the <strong>-yscrollincrement</strong> option (which may be zero, +see the description of that option). If <i class='arg'>what</i> is <strong>pages</strong> then the view adjusts in units of nine-tenths the window's height. If <i class='arg'>number</i> is negative then higher information becomes @@ -2895,7 +2891,7 @@ See <a href="#column_description">COLUMN DESCRIPTION</a> below. There is always one special column, the <strong>tail</strong> 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 <strong>tail</strong>, which cannot be modified. +it can only be specified by the keyword <strong>tail</strong>. <p> When a column configuration option is specified as <a href="#per-state_options">per-state</a>, @@ -3098,19 +3094,37 @@ of two values to specify padding for top and bottom separately; it defaults to 0. <br><br> +<dt><strong><strong>-uniform</strong></strong> <i class='arg'>group</i><dd> +When a non-empty value is supplied, this option places the column in a +<em>uniform group</em> with other columns that have the same value for +<strong>-uniform</strong>. The space for columns belonging to a uniform group is +allocated so that their sizes are always in strict proportion to their +<strong>-weight</strong> values. +This option is based on the grid geometry manager. + +<br><br> <dt><strong><strong>-visible</strong></strong> <i class='arg'>boolean</i><dd> Indicates whether or not the column should be displayed. <br><br> +<dt><strong><strong>-weight</strong></strong> <i class='arg'>integer</i><dd> +Sets the relative weight for apportioning any extra space among columns. +A weight of zero (0) indicates the column will not deviate from its requested +size. A column whose weight is two will grow at twice the rate as a column of +weight one when extra space is allocated to columns. +This option is based on the grid geometry manager. + +<br><br> <dt><strong><strong>-width</strong></strong> <i class='arg'>size</i><dd> Specifies a fixed width for the column. If this value is an empty string, -the column width is calculated as the maximum of: +then the column width is calculated as the maximum of: a) the width requested by items; b) the width requested by the column's header; and c) the column's <strong>-minwidth</strong> option. -This calculated width is also affected by the <strong>-expand</strong> option and the -<strong>-squeeze</strong> option. In any case, the calculated width will not be greater -than the <strong>-maxwidth</strong> option, if specified. +This calculated width is also affected by the <strong>-expand</strong>, +<strong>-squeeze</strong>, <strong>-uniform</strong> and <strong>-weight</strong> options. In any case, +the calculated width will not be greater than the <strong>-maxwidth</strong> option, +if specified. <br><br> <dt><strong><strong>-widthhack</strong></strong> <i class='arg'>boolean</i><dd> @@ -3205,8 +3219,8 @@ Use the column to the left matching <i class='arg'>QUALIFIERS</i>. </dl> -The word <i class='arg'>QUALIFIERS</i> above represents a list of zero or more of the -following terms that changes which item is chosen: +The word <i class='arg'>QUALIFIERS</i> above represents a sequence of zero or more of the +following terms that changes which column is chosen: <dl> <dt><strong>state</strong> <i class='arg'>stateList</i><dd> @@ -3669,7 +3683,7 @@ or <strong>0</strong> to specify the ever-present root item. See also the <strong>-itemprefix</strong> option. <br><br> -<dt><i class='arg'>tagExpr</i><dd> +<dt><i class='arg'>tagExpr</i> <i class='arg'>QUALIFIERS</i><dd> <i class='arg'>TagExpr</i> is a tag expression (see <a href="#item_and_column_tags">ITEM AND COLUMN TAGS</a>) against which every item's tags are tested for a match. This keyword cannot be followed by any modifiers unless a single item is @@ -3726,7 +3740,7 @@ options. You can memorize <strong>rnc</strong> as an abbreviation of "row 'n' column". <br><br> -<dt><strong>range</strong> <i class='arg'>first last</i><dd> +<dt><strong>range</strong> <i class='arg'>first last</i> <i class='arg'>QUALIFIERS</i><dd> <i class='arg'>First</i> and <i class='arg'>last</i> specify a range of items. This keyword cannot be followed by any modifiers. @@ -3840,7 +3854,7 @@ Use the <i class='arg'>n</i>th child of the item's parent. Use the item in the first row of this column. </dl> -The word <i class='arg'>QUALIFIERS</i> above represents a list of zero or more of the +The word <i class='arg'>QUALIFIERS</i> above represents a series of zero or more of the following terms that changes which item is chosen: <dl> @@ -3882,6 +3896,7 @@ To get the every hidden item with tag "a" or "b": <p><table><tr><td bgcolor=black> </td><td><pre class='sample'> $T item id "all !visible tag a||b" $T item id "tag a||b !visible" +$T item id "a||b !visible" </pre></td></tr></table></p> <h2><a name="events_and_script_substitutions">EVENTS AND SCRIPT SUBSTITUTIONS</a></h2> diff --git a/doc/treectrl.man b/doc/treectrl.man index d169927..71efb7e 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.38 2006/10/18 03:47:48 treectrl Exp $} + $Id: treectrl.man,v 1.39 2006/10/27 04:37:11 treectrl Exp $} ][manpage_begin treectrl n 2.1.1] [moddesc {Tk Commands}] [titledesc {Create and manipulate hierarchical multicolumn widgets}] @@ -170,11 +170,9 @@ If this option is less than or equal to zero then the window will not request any size at all. [tkoption_def -indent indent Indent] -Specifies the amount of indentation +Specifies the screen distance an item is indented relative to its parent item in any of the forms acceptable to [fun Tk_GetPixels]. -The default is 19 pixel. -Indentation is the screen distance an item is displayed more to -the right than its father. +The default is 19 pixels. [tkoption_def -itemheight itemHeight ItemHeight] Specifies a fixed height for every item @@ -244,9 +242,11 @@ This line can be used to give the user a visual feedback during row resizing. [tkoption_def -scrollmargin scrollMargin ScrollMargin] -The interpretation of this option is left to Tcl scripts -that implement scrolling: -the widget implementation ignores this option entirely. +Specifies a positive screen distance +in any of the forms acceptable to [fun Tk_GetPixels]. +This option is used by the default bindings to determine how close to the +edges of the contentbox the mouse pointer must be before scrolling occurs. +Specifying a positive value is useful when items may be drag-and-dropped. Defaults to 0. [tkoption_def -selectmode selectMode SelectMode] @@ -326,14 +326,13 @@ taller than the window (-orient vertical) or no horizontal group of items will be wider than the window (-orient horizontal). [tkoption_def -xscrolldelay xScrollDelay ScrollDelay] -Specifies the amount of time before the default binding should handle -repeating mouse motion events in horizontal direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly horizontal scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. [tkoption_def -xscrollincrement xScrollIncrement ScrollIncrement] Specifies an increment for horizontal scrolling, in any of the usual forms @@ -344,17 +343,17 @@ multiple of [option -xscrollincrement]; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be [option -xscrollincrement]. If the value of this option is less than or equal to zero, then horizontal scrolling -is unconstrained. +snaps to the left of an item, or part of an item if items are wider than the +contentbox. [tkoption_def -yscrolldelay yScrollDelay ScrollDelay] -Specifies the amount of time before the default binding should handle -repeating mouse motion events in vertical direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly vertical scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. [tkoption_def -yscrollincrement yScrollIncrement ScrollIncrement] Specifies an increment for vertical scrolling, in any of the usual forms @@ -365,7 +364,8 @@ multiple of [option -yscrollincrement]; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be [option -yscrollincrement]. If the value of this option is less than or equal to zero, then vertical scrolling -is unconstrained. +snaps to the top of an item, or part of an item if items are taller than the +contentbox. [list_end] [section {ITEM AND COLUMN TAGS}] @@ -509,8 +509,7 @@ of the new column. [call [arg pathName] [cmd {column delete}] [arg first] [opt [arg last]]] Deletes the specified column(s). [arg First] and [arg last] must be valid -[sectref {COLUMN DESCRIPTION} {column descriptions}]. If [arg first] -is specified as [const all], then all columns are deleted. If both [arg first] +[sectref {COLUMN DESCRIPTION} {column descriptions}]. If both [arg first] and [arg last] are specified, then they may refer to a single column only. The [const tail] column cannot be deleted and it is an error to specify it. The order of [arg first] and [arg last] doesn't matter, and [arg first] may @@ -744,10 +743,7 @@ debugging options [option -enable] and [option -display] are switched on. [list_end] [call [arg pathName] [cmd {debug dinfo}]] -For every of the treectrl widget -a line with some internal values info about all items -is printed to stdout. -The command returns the empty string. +Returns a string describing item layout. [call [arg pathName] [cmd {debug expose}] [arg x1] [arg y1] [arg x2] [arg y2]] Causes the area of the window bounded by the given window-coords to be @@ -888,7 +884,7 @@ option named [arg option] for [arg element] for a certain state. which specifies the state to use. [call [arg pathName] [cmd {element type}] [arg element]] -Returns the type of the elements given by [arg element], +Returns the type of the element given by [arg element], such as [const rect] or [const text]. [list_end] @@ -897,39 +893,38 @@ such as [const rect] or [const text]. Use [cmd {item expand}] instead. [call [arg pathName] [cmd identify] [arg x] [arg y]] -Returns a list containing some diagnostics about what -is displayed at the given windows coordinates [arg x] and [arg y]. -The resulting list may be empty, -if nothing is displayed at the given coordinates, -otherwise the first list element is [const header] or [const item]. +Returns a list describing what +is displayed at the given window coordinates [arg x] and [arg y]. +If the coordinates are outside the window, over the borders, or over any +whitespace in the window, then the result is an empty string; +otherwise the first word of the result is [const header] or [const item]. [nl] -If the coordinates are in the header area -and thus the first element of the result is [const header], -the number of the column or the string [const tail] -is the second element in the resulting list; -if the x coordinate is near the left or right end of the header, -a third element [const left] or [const right] is added respectively. +If the coordinates are over a column header, then +the first word of the result is [const header], followed by +the unique id of the column (or the string [const tail]). +If the x coordinate is near the left or right end of a column, then +a third word [const left] or [const right] is appended to the result. [nl] -If the coordinates are below the header area -and thus the first element of the result is [const item], -the numerical id of the item -is the second element in the resulting list. -If the x coordinate doesn't fall into the column -displaying the hierarchical structure, -the elements [const column] and the column number are added. -If the x coordinate is within the column -displaying the hierarchical structure, -the following elements are added to the resulting list: -[const line] and the numerical id of the item the line comes from, -if the x coordinate is above an item connecting line; -[const button], if the x coordinate is above a button; -[const column], the column number, [const elem], and the element name, -if the x coordinate is above an element of the item; -[const column] and the column number, -if the x coordinate is to the right of the elements; -nothing otherwise. +If the coordinates are over an item, then the first word of the result +is [const item] followed by the unique id of that item. +If the coordinates are not over the area for displaying buttons and lines, +then [const column] and a unique column id are the +3rd and 4th words of the result. If the coordinates are over an element within +that column, then [const element] and an element name are the 5th and 6th +words of the result. +[nl] + +If the coordinates are over a button, then the first word of the result is +[const item], followed by the unique id of that item, followed by the word +[const button]. +[nl] +If the coordinates are over a line descending from an ancestor of an item +(but not the parent of that item), then the first word of the result is +[const item], followed by the unique id of that item, followed by the word +[const line], followed by the unique id of the item the line is coming +from. This is used to collapse the ancestor when the line is clicked on. [call [arg pathName] [cmd index] [arg itemDesc]] Deprecated. Use [cmd {item id}] instead. @@ -950,10 +945,10 @@ root item if [arg itemDesc] is a descendant of the root item. [call [arg pathName] [cmd {item bbox}] [arg itemDesc] [opt [arg column]] \ [opt [arg element]]] Returns a list with four elements giving the bounding box -for the item described by [arg itemDesc]. +of the item described by [arg itemDesc]. If no further argument is specified, the bbox spans the area of the item -over all columns. If a [arg column] is specified, only the area of the item -in this column is considered, if an additional [arg element] is specified, +over all non-locked columns. If a [arg column] is specified, only the area of the item +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. @@ -1127,9 +1122,8 @@ of the item specified by [arg itemDesc], i.e. the children, grandchildren, great-grandchildren etc, of the item. [call [arg pathName] [cmd {item dump}] [arg itemDesc]] -Returns a list with six elements in the form -[const index] [emph index] [const indexVis] [emph indexVis] -[const neededHeight] [emph neededHeight]. +Returns a list with 4 words in the form +[const index] [emph index] [const indexVis] [emph indexVis]. [call [arg pathName] [cmd {item element}] [arg command] [arg itemDesc] \ [arg column] [arg element] [opt [arg {arg ...}]]] @@ -1182,7 +1176,8 @@ For example: $C3 $E1 -text "apples and oranges" [example_end] Each of the [sectref {COLUMN DESCRIPTION} {column description}] arguments -may refer to multiple columns. +to this command may refer to multiple columns if at least one +[arg option]-[arg value] pair is given. [call [arg pathName] [cmd {item element perstate}] [arg itemDesc] [arg column] \ [arg element] [arg option] [opt [arg stateList]]] @@ -1197,7 +1192,8 @@ and dynamic, see [sectref STATES]) is used in place of the current state for [call [arg pathName] [cmd {item enabled}] [arg itemDesc] [opt [arg boolean]]] Returns 1 if the item described by [arg itemDesc] has the state [const enabled] switched on, 0 otherwise. If [arg boolean] is specified, -the [const enabled] state is set accordingly. +then the [const enabled] state of every item described by the +[sectref {ITEM DESCRIPTION} {item description}] [arg itemDesc] is set accordingly. [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]. @@ -1225,8 +1221,8 @@ Then it will become the new first child of [arg parent]. [call [arg pathName] [cmd {item id}] [arg itemDesc]] This command resolves the [sectref {ITEM DESCRIPTION} {item description}] -[arg itemDesc] into a list of unique item identifiers. If the item(s) described by -[arg itemDesc] don't exist, this command returns an empty list. +[arg itemDesc] into a list of unique item identifiers. If [arg itemDesc] +doesn't refer to any existing items, then this command returns an empty list. [call [arg pathName] [cmd {item image}] [arg itemDesc] [opt [arg column]] \ [opt [arg image]] [opt [arg {column image ...}]]] @@ -2154,8 +2150,8 @@ This command shifts the view in the window left or right according to [arg What] must be either [const units] or [const pages] or an abbreviation of one of these. If [arg what] is [const units], the view adjusts left or right in units -of the [option -xscrollincrement] option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. +determined by the [option -xscrollincrement] option (which may be zero, +see the description of that option). If [arg what] is [const pages] then the view adjusts in units of nine-tenths the window's width. If [arg number] is negative then information farther to the left @@ -2191,8 +2187,8 @@ This command adjusts the view in the window up or down according to [arg Number] must be an integer. [arg What] must be either [const units] or [const pages]. If [arg what] is [const units], the view adjusts up or down in units -of the [option -yscrollincrement] option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. +of the [option -yscrollincrement] option (which may be zero, +see the description of that option). If [arg what] is [const pages] then the view adjusts in units of nine-tenths the window's height. If [arg number] is negative then higher information becomes @@ -2215,7 +2211,7 @@ See [sectref {COLUMN DESCRIPTION}] below. There is always one special column, the [const tail] 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 [const tail], which cannot be modified. +it can only be specified by the keyword [const tail]. [para] When a column configuration option is specified as [sectref {PER-STATE OPTIONS} per-state], @@ -2387,18 +2383,34 @@ leave on the top and bottom of the text. of two values to specify padding for top and bottom separately; it defaults to 0. +[opt_def [option -uniform] [arg group]] +When a non-empty value is supplied, this option places the column in a +[emph "uniform group"] with other columns that have the same value for +[option -uniform]. The space for columns belonging to a uniform group is +allocated so that their sizes are always in strict proportion to their +[option -weight] values. +This option is based on the grid geometry manager. + [opt_def [option -visible] [arg boolean]] Indicates whether or not the column should be displayed. +[opt_def [option -weight] [arg integer]] +Sets the relative weight for apportioning any extra space among columns. +A weight of zero (0) indicates the column will not deviate from its requested +size. A column whose weight is two will grow at twice the rate as a column of +weight one when extra space is allocated to columns. +This option is based on the grid geometry manager. + [opt_def [option -width] [arg size]] Specifies a fixed width for the column. If this value is an empty string, -the column width is calculated as the maximum of: +then the column width is calculated as the maximum of: a) the width requested by items; b) the width requested by the column's header; and c) the column's [option -minwidth] option. -This calculated width is also affected by the [option -expand] option and the -[option -squeeze] option. In any case, the calculated width will not be greater -than the [option -maxwidth] option, if specified. +This calculated width is also affected by the [option -expand], +[option -squeeze], [option -uniform] and [option -weight] options. In any case, +the calculated width will not be greater than the [option -maxwidth] option, +if specified. [opt_def [option -widthhack] [arg boolean]] Deprecated. Use the treectrl's [option -itemwidthequal] option instead. @@ -2480,8 +2492,8 @@ Use the column to the left matching [arg QUALIFIERS]. [list_end] -The word [arg QUALIFIERS] above represents a list of zero or more of the -following terms that changes which item is chosen: +The word [arg QUALIFIERS] above represents a sequence of zero or more of the +following terms that changes which column is chosen: [list_begin definitions] [lst_item "[const state] [arg stateList]"] @@ -2893,7 +2905,7 @@ the return value of a prior call of the [cmd {item create}] widget command, or [const 0] to specify the ever-present root item. See also the [option -itemprefix] option. -[lst_item [arg tagExpr]] +[lst_item "[arg tagExpr] [arg QUALIFIERS]"] [arg TagExpr] is a tag expression (see [sectref {ITEM AND COLUMN TAGS}]) against which every item's tags are tested for a match. This keyword cannot be followed by any modifiers unless a single item is @@ -2941,7 +2953,7 @@ the on-screen arrangement of items as determined by the -orient and -wrap options. You can memorize [const rnc] as an abbreviation of "row 'n' column". -[lst_item "[const range] [arg {first last}]"] +[lst_item "[const range] [arg {first last}] [arg QUALIFIERS]"] [arg First] and [arg last] specify a range of items. This keyword cannot be followed by any modifiers. @@ -3034,7 +3046,7 @@ Use the [arg n]th child of the item's parent. Use the item in the first row of this column. [list_end] -The word [arg QUALIFIERS] above represents a list of zero or more of the +The word [arg QUALIFIERS] above represents a series of zero or more of the following terms that changes which item is chosen: [list_begin definitions] @@ -3073,6 +3085,7 @@ To get the every hidden item with tag "a" or "b": [example_begin] $T item id "all !visible tag a||b" $T item id "tag a||b !visible" +$T item id "a||b !visible" [example_end] [section {EVENTS AND SCRIPT SUBSTITUTIONS}] diff --git a/doc/treectrl.n b/doc/treectrl.n index 9b804d5..a918323 100644 --- a/doc/treectrl.n +++ b/doc/treectrl.n @@ -6,7 +6,7 @@ '\" 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.54 2006/10/18 03:47:48 treectrl Exp $ +'\" $Id: treectrl.n,v 1.55 2006/10/27 04:37:11 treectrl Exp $ .so man.macros .TH "treectrl" n 2.1.1 treectrl "Tk Commands" .BS @@ -615,11 +615,9 @@ Database Class: \fBIndent\fR .fi .IP -Specifies the amount of indentation +Specifies the screen distance an item is indented relative to its parent item in any of the forms acceptable to \fBTk_GetPixels\fR. -The default is 19 pixel. -Indentation is the screen distance an item is displayed more to -the right than its father. +The default is 19 pixels. .LP .nf .ta 6c @@ -766,9 +764,11 @@ Database Class: \fBScrollMargin\fR .fi .IP -The interpretation of this option is left to Tcl scripts -that implement scrolling: -the widget implementation ignores this option entirely. +Specifies a positive screen distance +in any of the forms acceptable to \fBTk_GetPixels\fR. +This option is used by the default bindings to determine how close to the +edges of the contentbox the mouse pointer must be before scrolling occurs. +Specifying a positive value is useful when items may be drag-and-dropped. Defaults to 0. .LP .nf @@ -928,14 +928,13 @@ Database Class: \fBScrollDelay\fR .fi .IP -Specifies the amount of time before the default binding should handle -repeating mouse motion events in horizontal direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly horizontal scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. .LP .nf .ta 6c @@ -953,7 +952,8 @@ multiple of \fB-xscrollincrement\fR; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be \fB-xscrollincrement\fR. If the value of this option is less than or equal to zero, then horizontal scrolling -is unconstrained. +snaps to the left of an item, or part of an item if items are wider than the +contentbox. .LP .nf .ta 6c @@ -963,14 +963,13 @@ Database Class: \fBScrollDelay\fR .fi .IP -Specifies the amount of time before the default binding should handle -repeating mouse motion events in vertical direction with button 1 pressed. -The value should be a list of 1 or 2 integers. -The first integer specifies the timespan in microseconds -before the active item should be changed to get nearer to the -current mouse position. If there are two integers specified, the first is only -used for the first motion event, any repeating motion events are handled -after the seconds amount of miliseconds is elapsed. +This option controls how quickly vertical scrolling occurs while dragging +the mouse with button 1 pressed. +The value should be a list of 1 or 2 integers interpreted as microseconds. +If 2 values are specified, then the first value determines the intial delay +after the first scroll, and the second value determines the delay for all +scrolling after the first. If only 1 value is specified, each scroll takes +place after that delay. .LP .nf .ta 6c @@ -988,7 +987,8 @@ multiple of \fB-yscrollincrement\fR; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be \fB-yscrollincrement\fR. If the value of this option is less than or equal to zero, then vertical scrolling -is unconstrained. +snaps to the top of an item, or part of an item if items are taller than the +contentbox. .SH "ITEM AND COLUMN TAGS" Columns and items may have any number of tags associated with them. A tag is just a string of characters, and it may take any form, @@ -1125,8 +1125,7 @@ of the new column. .TP \fIpathName\fR \fBcolumn delete\fR \fIfirst\fR ?\fIlast\fR? Deletes the specified column(s). \fIFirst\fR and \fIlast\fR must be valid -\fBcolumn descriptions\fR. If \fIfirst\fR -is specified as \fBall\fR, then all columns are deleted. If both \fIfirst\fR +\fBcolumn descriptions\fR. If both \fIfirst\fR and \fIlast\fR are specified, then they may refer to a single column only. The \fBtail\fR column cannot be deleted and it is an error to specify it. The order of \fIfirst\fR and \fIlast\fR doesn't matter, and \fIfirst\fR may @@ -1353,10 +1352,7 @@ debugging options \fB-enable\fR and \fB-display\fR are switched on. .RE .TP \fIpathName\fR \fBdebug dinfo\fR -For every of the treectrl widget -a line with some internal values info about all items -is printed to stdout. -The command returns the empty string. +Returns a string describing item layout. .TP \fIpathName\fR \fBdebug expose\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR Causes the area of the window bounded by the given window-coords to be @@ -1490,7 +1486,7 @@ option named \fIoption\fR for \fIelement\fR for a certain state. which specifies the state to use. .TP \fIpathName\fR \fBelement type\fR \fIelement\fR -Returns the type of the elements given by \fIelement\fR, +Returns the type of the element given by \fIelement\fR, such as \fBrect\fR or \fBtext\fR. .RE .TP @@ -1498,37 +1494,35 @@ such as \fBrect\fR or \fBtext\fR. Use \fBitem expand\fR instead. .TP \fIpathName\fR \fBidentify\fR \fIx\fR \fIy\fR -Returns a list containing some diagnostics about what -is displayed at the given windows coordinates \fIx\fR and \fIy\fR. -The resulting list may be empty, -if nothing is displayed at the given coordinates, -otherwise the first list element is \fBheader\fR or \fBitem\fR. -.sp -If the coordinates are in the header area -and thus the first element of the result is \fBheader\fR, -the number of the column or the string \fBtail\fR -is the second element in the resulting list; -if the x coordinate is near the left or right end of the header, -a third element \fBleft\fR or \fBright\fR is added respectively. -.sp -If the coordinates are below the header area -and thus the first element of the result is \fBitem\fR, -the numerical id of the item -is the second element in the resulting list. -If the x coordinate doesn't fall into the column -displaying the hierarchical structure, -the elements \fBcolumn\fR and the column number are added. -If the x coordinate is within the column -displaying the hierarchical structure, -the following elements are added to the resulting list: -\fBline\fR and the numerical id of the item the line comes from, -if the x coordinate is above an item connecting line; -\fBbutton\fR, if the x coordinate is above a button; -\fBcolumn\fR, the column number, \fBelem\fR, and the element name, -if the x coordinate is above an element of the item; -\fBcolumn\fR and the column number, -if the x coordinate is to the right of the elements; -nothing otherwise. +Returns a list describing what +is displayed at the given window coordinates \fIx\fR and \fIy\fR. +If the coordinates are outside the window, over the borders, or over any +whitespace in the window, then the result is an empty string; +otherwise the first word of the result is \fBheader\fR or \fBitem\fR. +.sp +If the coordinates are over a column header, then +the first word of the result is \fBheader\fR, followed by +the unique id of the column (or the string \fBtail\fR). +If the x coordinate is near the left or right end of a column, then +a third word \fBleft\fR or \fBright\fR is appended to the result. +.sp +If the coordinates are over an item, then the first word of the result +is \fBitem\fR followed by the unique id of that item. +If the coordinates are not over the area for displaying buttons and lines, +then \fBcolumn\fR and a unique column id are the +3rd and 4th words of the result. If the coordinates are over an element within +that column, then \fBelement\fR and an element name are the 5th and 6th +words of the result. +.sp +If the coordinates are over a button, then the first word of the result is +\fBitem\fR, followed by the unique id of that item, followed by the word +\fBbutton\fR. +.sp +If the coordinates are over a line descending from an ancestor of an item +(but not the parent of that item), then the first word of the result is +\fBitem\fR, followed by the unique id of that item, followed by the word +\fBline\fR, followed by the unique id of the item the line is coming +from. This is used to collapse the ancestor when the line is clicked on. .TP \fIpathName\fR \fBindex\fR \fIitemDesc\fR Deprecated. Use \fBitem id\fR instead. @@ -1548,10 +1542,10 @@ root item if \fIitemDesc\fR is a descendant of the root item. .TP \fIpathName\fR \fBitem bbox\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIelement\fR? Returns a list with four elements giving the bounding box -for the item described by \fIitemDesc\fR. +of the item described by \fIitemDesc\fR. If no further argument is specified, the bbox spans the area of the item -over all columns. If a \fIcolumn\fR is specified, only the area of the item -in this column is considered, if an additional \fIelement\fR is specified, +over all non-locked columns. If a \fIcolumn\fR is specified, only the area of the item +in this column is considered. If an additional \fIelement\fR is specified, the area of this \fIelement\fR in \fIcolumn\fR of the specified item is returned. .TP @@ -1726,9 +1720,8 @@ of the item specified by \fIitemDesc\fR, i.e. the children, grandchildren, great-grandchildren etc, of the item. .TP \fIpathName\fR \fBitem dump\fR \fIitemDesc\fR -Returns a list with six elements in the form -\fBindex\fR \fIindex\fR \fBindexVis\fR \fIindexVis\fR -\fBneededHeight\fR \fIneededHeight\fR. +Returns a list with 4 words in the form +\fBindex\fR \fIindex\fR \fBindexVis\fR \fIindexVis\fR. .TP \fIpathName\fR \fBitem element\fR \fIcommand\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR ?\fIarg ...\fR? This command is used to manipulate elements of the item. @@ -1778,7 +1771,8 @@ For example: .fi Each of the \fBcolumn description\fR arguments -may refer to multiple columns. +to this command may refer to multiple columns if at least one +\fIoption\fR-\fIvalue\fR pair is given. .TP \fIpathName\fR \fBitem element perstate\fR \fIitemDesc\fR \fIcolumn\fR \fIelement\fR \fIoption\fR ?\fIstateList\fR? This command returns the current value of the \fBper-state\fR @@ -1791,7 +1785,8 @@ and dynamic, see \fBSTATES\fR) is used in place of the current state for \fIpathName\fR \fBitem enabled\fR \fIitemDesc\fR ?\fIboolean\fR? Returns 1 if the item described by \fIitemDesc\fR has the state \fBenabled\fR switched on, 0 otherwise. If \fIboolean\fR is specified, -the \fBenabled\fR state is set accordingly. +then the \fBenabled\fR state of every item described by the +\fBitem description\fR \fIitemDesc\fR is set accordingly. .TP \fIpathName\fR \fBitem expand\fR \fIitemDesc\fR ?\fB-recurse\fR? Switches on the \fBopen\fR state of the item(s) described by \fIitemDesc\fR. @@ -1819,8 +1814,8 @@ Then it will become the new first child of \fIparent\fR. .TP \fIpathName\fR \fBitem id\fR \fIitemDesc\fR This command resolves the \fBitem description\fR -\fIitemDesc\fR into a list of unique item identifiers. If the item(s) described by -\fIitemDesc\fR don't exist, this command returns an empty list. +\fIitemDesc\fR into a list of unique item identifiers. If \fIitemDesc\fR +doesn't refer to any existing items, then this command returns an empty list. .TP \fIpathName\fR \fBitem image\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIimage\fR? ?\fIcolumn image ...\fR? This command sets or retrieves the value of the \fBper-state\fR @@ -2702,8 +2697,8 @@ This command shifts the view in the window left or right according to \fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation of one of these. If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units -of the \fB-xscrollincrement\fR option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. +determined by the \fB-xscrollincrement\fR option (which may be zero, +see the description of that option). If \fIwhat\fR is \fBpages\fR then the view adjusts in units of nine-tenths the window's width. If \fInumber\fR is negative then information farther to the left @@ -2739,8 +2734,8 @@ This command adjusts the view in the window up or down according to \fINumber\fR must be an integer. \fIWhat\fR must be either \fBunits\fR or \fBpages\fR. If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units -of the \fB-yscrollincrement\fR option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. +of the \fB-yscrollincrement\fR option (which may be zero, +see the description of that option). If \fIwhat\fR is \fBpages\fR then the view adjusts in units of nine-tenths the window's height. If \fInumber\fR is negative then higher information becomes @@ -2759,7 +2754,7 @@ See \fBCOLUMN DESCRIPTION\fR below. 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 can only be specified by the keyword \fBtail\fR. .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. @@ -2928,18 +2923,34 @@ leave on the top and bottom of the text. of two values to specify padding for top and bottom separately; it defaults to 0. .TP +\fB\fB-uniform\fR\fR \fIgroup\fR +When a non-empty value is supplied, this option places the column in a +\fIuniform group\fR with other columns that have the same value for +\fB-uniform\fR. The space for columns belonging to a uniform group is +allocated so that their sizes are always in strict proportion to their +\fB-weight\fR values. +This option is based on the grid geometry manager. +.TP \fB\fB-visible\fR\fR \fIboolean\fR Indicates whether or not the column should be displayed. .TP +\fB\fB-weight\fR\fR \fIinteger\fR +Sets the relative weight for apportioning any extra space among columns. +A weight of zero (0) indicates the column will not deviate from its requested +size. A column whose weight is two will grow at twice the rate as a column of +weight one when extra space is allocated to columns. +This option is based on the grid geometry manager. +.TP \fB\fB-width\fR\fR \fIsize\fR Specifies a fixed width for the column. If this value is an empty string, -the column width is calculated as the maximum of: +then the column width is calculated as the maximum of: a) the width requested by items; b) the width requested by the column's header; and c) the column's \fB-minwidth\fR option. -This calculated width is also affected by the \fB-expand\fR option and the -\fB-squeeze\fR option. In any case, the calculated width will not be greater -than the \fB-maxwidth\fR option, if specified. +This calculated width is also affected by the \fB-expand\fR, +\fB-squeeze\fR, \fB-uniform\fR and \fB-weight\fR options. In any case, +the calculated width will not be greater than the \fB-maxwidth\fR option, +if specified. .TP \fB\fB-widthhack\fR\fR \fIboolean\fR Deprecated. Use the treectrl's \fB-itemwidthequal\fR option instead. @@ -3011,8 +3022,8 @@ Use the column to the right matching \fIQUALIFIERS\fR. .TP \fBprev\fR \fIQUALIFIERS\fR Use the column to the left matching \fIQUALIFIERS\fR. -The word \fIQUALIFIERS\fR above represents a list of zero or more of the -following terms that changes which item is chosen: +The word \fIQUALIFIERS\fR above represents a sequence of zero or more of the +following terms that changes which column is chosen: .TP \fBstate\fR \fIstateList\fR \fIStateList\fR is a list of column state names. @@ -3394,7 +3405,7 @@ the return value of a prior call of the \fBitem create\fR widget command, or \fB0\fR to specify the ever-present root item. See also the \fB-itemprefix\fR option. .TP -\fItagExpr\fR +\fItagExpr\fR \fIQUALIFIERS\fR \fITagExpr\fR is a tag expression (see \fBITEM AND COLUMN TAGS\fR) against which every item's tags are tested for a match. This keyword cannot be followed by any modifiers unless a single item is @@ -3443,7 +3454,7 @@ the on-screen arrangement of items as determined by the -orient and -wrap options. You can memorize \fBrnc\fR as an abbreviation of "row 'n' column". .TP -\fBrange\fR \fIfirst last\fR +\fBrange\fR \fIfirst last\fR \fIQUALIFIERS\fR \fIFirst\fR and \fIlast\fR specify a range of items. This keyword cannot be followed by any modifiers. .TP @@ -3530,7 +3541,7 @@ Use the \fIn\fRth child of the item's parent. .TP \fBtop\fR Use the item in the first row of this column. -The word \fIQUALIFIERS\fR above represents a list of zero or more of the +The word \fIQUALIFIERS\fR above represents a series of zero or more of the following terms that changes which item is chosen: .TP \fBstate\fR \fIstateList\fR @@ -3570,6 +3581,7 @@ To get the every hidden item with tag "a" or "b": $T item id "all !visible tag a||b" $T item id "tag a||b !visible" +$T item id "a||b !visible" .fi .SH "EVENTS AND SCRIPT SUBSTITUTIONS" |