diff options
Diffstat (limited to 'doc/treectrl.html')
| -rw-r--r-- | doc/treectrl.html | 140 |
1 files changed, 67 insertions, 73 deletions
diff --git a/doc/treectrl.html b/doc/treectrl.html index 88b53c4..d7281e8 100644 --- a/doc/treectrl.html +++ b/doc/treectrl.html @@ -1,14 +1,14 @@ -<! -- 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.40 2006/11/03 22:31:04 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.41 2006/11/18 04:40:10 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.40 2006/11/03 22:31:04 treectrl Exp $ treectrl.n +<! -- CVS: $Id: treectrl.html,v 1.41 2006/11/18 04:40:10 treectrl Exp $ treectrl.n --> <body> -<h1> treectrl(n) 2.1.1 treectrl "Tk Commands"</h1> +<h1> treectrl(n) 2.2 treectrl "Tk Commands"</h1> <h2><a name="name">NAME</a></h2> <p> <p> treectrl - Create and manipulate hierarchical multicolumn widgets @@ -44,7 +44,7 @@ <a href="#keywords">KEYWORDS</a><br> <h2><a name="synopsis">SYNOPSIS</a></h2> <p> -package require <b>treectrl 2.1.1</b><br> +package require <b>treectrl 2.2</b><br> <br><table border=1 width=100% cellspacing=0 cellpadding=0><tr bgcolor=lightyellow><td bgcolor=lightyellow><table 0 width=100% cellspacing=0 cellpadding=0><tr valign=top ><td ><a href="#1"><b class='cmd'>treectrl</b> <i class='arg'>pathName</i> ?<i class='arg'>options</i>?</a></td></tr> <tr valign=top ><td ><a href="#2"><i class='arg'>pathName</i> <b class='cmd'>activate</b> <i class='arg'>itemDesc</i></a></td></tr> <tr valign=top ><td ><a href="#3"><i class='arg'>pathName</i> <b class='cmd'>canvasx</b> <i class='arg'>screenx</i></a></td></tr> @@ -56,7 +56,7 @@ package require <b>treectrl 2.1.1</b><br> <tr valign=top ><td ><a href="#9"><i class='arg'>pathName</i> <b class='cmd'>column cget</b> <i class='arg'>columnDesc</i> <i class='arg'>option</i></a></td></tr> <tr valign=top ><td ><a href="#10"><i class='arg'>pathName</i> <b class='cmd'>column configure</b> <i class='arg'>columnDesc</i> ?<i class='arg'>option</i>? ?<i class='arg'>value</i>? ?<i class='arg'>option value ...</i>?</a></td></tr> <tr valign=top ><td ><a href="#11"><i class='arg'>pathName</i> <b class='cmd'>column compare</b> <i class='arg'>column1</i> <i class='arg'>op</i> <i class='arg'>column2</i></a></td></tr> -<tr valign=top ><td ><a href="#12"><i class='arg'>pathName</i> <b class='cmd'>column count</b></a></td></tr> +<tr valign=top ><td ><a href="#12"><i class='arg'>pathName</i> <b class='cmd'>column count</b> ?<i class='arg'>columnDesc</i>?</a></td></tr> <tr valign=top ><td ><a href="#13"><i class='arg'>pathName</i> <b class='cmd'>column create</b> ?<i class='arg'>option value ...</i>?</a></td></tr> <tr valign=top ><td ><a href="#14"><i class='arg'>pathName</i> <b class='cmd'>column delete</b> <i class='arg'>first</i> ?<i class='arg'>last</i>?</a></td></tr> <tr valign=top ><td ><a href="#15"><i class='arg'>pathName</i> <b class='cmd'>column dragcget</b> <i class='arg'>option</i></a></td></tr> @@ -110,7 +110,7 @@ package require <b>treectrl 2.1.1</b><br> <tr valign=top ><td ><a href="#63"><i class='arg'>pathName</i> <b class='cmd'>item compare</b> <i class='arg'>itemDesc1</i> <i class='arg'>op</i> <i class='arg'>itemDesc2</i></a></td></tr> <tr valign=top ><td ><a href="#64"><i class='arg'>pathName</i> <b class='cmd'>item complex</b> <i class='arg'>itemDesc</i> ?<i class='arg'>list...</i>?</a></td></tr> <tr valign=top ><td ><a href="#65"><i class='arg'>pathName</i> <b class='cmd'>item configure</b> <i class='arg'>itemDesc</i> ?<i class='arg'>option</i>? ?<i class='arg'>value</i>? ?<i class='arg'>option value ...</i>?</a></td></tr> -<tr valign=top ><td ><a href="#66"><i class='arg'>pathName</i> <b class='cmd'>item count</b> ?<i class='arg'>-visible</i>?</a></td></tr> +<tr valign=top ><td ><a href="#66"><i class='arg'>pathName</i> <b class='cmd'>item count</b> ?<i class='arg'>itemDesc</i>?</a></td></tr> <tr valign=top ><td ><a href="#67"><i class='arg'>pathName</i> <b class='cmd'>item create</b> ?<i class='arg'>option value ...</i>?</a></td></tr> <tr valign=top ><td ><a href="#68"><i class='arg'>pathName</i> <b class='cmd'>item delete</b> <i class='arg'>first</i> ?<i class='arg'>last</i>?</a></td></tr> <tr valign=top ><td ><a href="#69"><i class='arg'>pathName</i> <b class='cmd'>item descendants</b> <i class='arg'>itemDesc</i></a></td></tr> @@ -849,12 +849,12 @@ for the column specified by the <dt><a name="10"><i class='arg'>pathName</i> <b class='cmd'>column configure</b> <i class='arg'>columnDesc</i> ?<i class='arg'>option</i>? ?<i class='arg'>value</i>? ?<i class='arg'>option value ...</i>?</a><dd> This command is similar to the <b class='cmd'>configure</b> 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 <a href="#column_description">column description</a> <i class='arg'>columnDesc</i> instead of modifying options for the overall treectrl widget. <i class='arg'>ColumnDesc</i> may be the string <strong>tail</strong> to specify the tail column. -If <i class='arg'>columnDesc</i> is the string <strong>all</strong>, at least one option-value pair -must be given; in this case all the columns are configured. +If <i class='arg'>columnDesc</i> refers to more than one column, then at least one option-value pair +must be given. If no <i class='arg'>option</i> is specified, the command returns a list describing all of the available options for <i class='arg'>columnDesc</i> (see <strong>Tk_ConfigureInfo</strong> for information on the format of this list). @@ -882,12 +882,14 @@ The return value of this command is 1 if the comparison evaluated to true, 0 otherwise. <br><br> -<dt><a name="12"><i class='arg'>pathName</i> <b class='cmd'>column count</b></a><dd> +<dt><a name="12"><i class='arg'>pathName</i> <b class='cmd'>column count</b> ?<i class='arg'>columnDesc</i>?</a><dd> -Returns a decimal string giving the number of +If no additional arguments are given, the result is a decimal string giving the number of columns created by the <b class='cmd'>column create</b> widget command which haven't been -deleted by the <b class='cmd'>column delete</b> widget command. The <strong>tail</strong> column +deleted by the <b class='cmd'>column delete</b> widget command; in this case the <strong>tail</strong> column is not counted. +If <i class='arg'>columnDesc</i> is given, then the result is the number of columns that +match that <a href="#column_description">column description</a>. <br><br> <dt><a name="13"><i class='arg'>pathName</i> <b class='cmd'>column create</b> ?<i class='arg'>option value ...</i>?</a><dd> @@ -1108,7 +1110,8 @@ The following forms of the command are supported: <dl> <dt><a name="33"><i class='arg'>pathName</i> <b class='cmd'>debug alloc</b></a><dd> -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. <br><br> <dt><a name="34"><i class='arg'>pathName</i> <b class='cmd'>debug cget</b> <i class='arg'>option</i></a><dd> @@ -1202,12 +1205,12 @@ Returns a string useful for debugging vertical scrolling. <dt><a name="39"><i class='arg'>pathName</i> <b class='cmd'>depth</b> ?<i class='arg'>itemDesc</i>?</a><dd> -If the additional argument <i class='arg'>itemDesc</i> is specified, -returns a decimal string giving the depth of -the item describing by <i class='arg'>itemDesc</i>, whereas depth is defined as -the number of steps you must go upward to reach to root item. -If no <i class='arg'>itemDesc</i> is specified, the maximum depth of all +If the additional argument <i class='arg'>itemDesc</i> is given, +then the result is a decimal string giving the depth of +the item described by <i class='arg'>itemDesc</i>. +If no <i class='arg'>itemDesc</i> 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. <br><br> <dt><a name="40"><i class='arg'>pathName</i> <b class='cmd'>dragimage</b> <i class='arg'>option</i> ?<i class='arg'>arg ...</i>?</a><dd> @@ -1448,20 +1451,12 @@ the first child to the last child. <br><br> <dt><a name="62"><i class='arg'>pathName</i> <b class='cmd'>item collapse</b> <i class='arg'>itemDesc</i> ?<strong>-recurse</strong>?</a><dd> -Switches off the <strong>open</strong> state of the item(s) -described by <i class='arg'>itemDesc</i>. -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 <strong>-buttonimage</strong> or <strong>-buttonbitmap</strong>, -or a <em>+</em> sign if no image or bitmap is configured. -If the item is already closed, this command has no effect. -<i class='arg'>ItemDesc</i> may also be the string <strong>all</strong>, -in which case all items of the treectrl widget are collapsed. -If <strong>-recurse</strong> is specified, all descendants of <i class='arg'>itemDesc</i> -will also be collapsed. -For every item, that actually will be collapsed, -two events are generated: +Switches off the <strong>open</strong> state of the item(s) described by <i class='arg'>itemDesc</i>. +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 <strong>-recurse</strong> is specified, then all descendants of the items described +by <i class='arg'>itemDesc</i> will also be collapsed. +For every item that actually will be collapsed, two events are generated: a <strong><Collapse-before></strong> event before the item state is changed, and a <strong><Collapse-after></strong> event after the item state was changed. @@ -1483,7 +1478,7 @@ This horrible command is now deprecated. Use <b class='cmd'>item element configu instead. For every column of the treectrl there may be specified one <i class='arg'>list</i>. Each <i class='arg'>list</i> should look like this: <p><table><tr><td bgcolor=black> </td><td><pre class='sample'> -{ {element option value...} {element option value...} ...} +{ {element option value ...} {element option value ...} ...} </pre></td></tr></table></p> Every <i class='arg'>option</i> must be known by the element's type (see <a href="#elements">ELEMENTS</a> below). @@ -1518,15 +1513,14 @@ the meaning of each option): </dl> -<dt><a name="66"><i class='arg'>pathName</i> <b class='cmd'>item count</b> ?<i class='arg'>-visible</i>?</a><dd> +<dt><a name="66"><i class='arg'>pathName</i> <b class='cmd'>item count</b> ?<i class='arg'>itemDesc</i>?</a><dd> -Returns a decimal string giving the number of +If no additional arguments are given, the result is a decimal string giving the number of items created by the <b class='cmd'>item create</b> widget command which haven't been deleted by the <b class='cmd'>item delete</b> widget command, plus 1 for the ever-present -root item. If the optional argument <i class='arg'>-visible</i> 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 <strong>-showroot</strong> must -be true for the root item to be counted. +root item. +If the optional argument <i class='arg'>itemDesc</i> is given, then the result is the +number of items that match that <a href="#item_description">item description</a>. <br><br> <dt><a name="67"><i class='arg'>pathName</i> <b class='cmd'>item create</b> ?<i class='arg'>option value ...</i>?</a><dd> @@ -1548,7 +1542,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 <strong>-treecolumn</strong> is visible; -and b) the treectrl option <strong>-showbuttons</strong> is true +and b) the treectrl option <strong>-showbuttons</strong> is true; +and c) for the root item, the treectrl option <strong>-showrootbutton</strong> is true. <br><br> <dt><strong><strong>-count</strong></strong> <i class='arg'>numItems</i><dd> @@ -1619,7 +1614,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 <strong><Selection></strong> event is generated just before the items are deleted. -If any items were actually deleted, then an <strong><ItemDelete></strong> event event is generated just before the items +If any items are going to be deleted, then an <strong><ItemDelete></strong> event event is generated just before the items are deleted. <br><br> @@ -1709,23 +1704,18 @@ 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, 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. +All items are enabled when first created. Disabled items cannot be selected, +and are ignored by the default key-navigation and mouse bindings. <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> Switches on the <strong>open</strong> state of the item(s) described by <i class='arg'>itemDesc</i>. -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 <strong>-buttonimage</strong> or <strong>-buttonbitmap</strong>, -or a <em>-</em> sign if no image or bitmap is configured. -If the item is already open, this command has no effect. -<i class='arg'>ItemDesc</i> may also be the string <strong>all</strong>, -in which case all items of the treectrl widget are expanded. -If <strong>-recurse</strong> is specified, all descendants of <i class='arg'>itemDesc</i> -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 <strong>-recurse</strong> is specified, then all descendants of the items described by +<i class='arg'>itemDesc</i> will also be expanded. +For every item that actually will be expanded, two events are generated: an <strong><Expand-before></strong> event before the item state is changed, and an <strong><Expand-after></strong> event after the item state was changed. @@ -2098,13 +2088,11 @@ want to set or retrieve the value of the -text option for a specific text elemen <dt><a name="108"><i class='arg'>pathName</i> <b class='cmd'>item toggle</b> <i class='arg'>itemDesc</i> ?<strong>-recurse</strong>?</a><dd> Changes the <strong>open</strong> state of the item(s) described by <i class='arg'>itemDesc</i>. -If the state is currently switched off, -this command does the same as the <b class='cmd'>item expand</b> widget command, +If the <strong>open</strong> state is currently switched off, then +this command does the same as the <b class='cmd'>item expand</b> widget command; otherwise the same as the <b class='cmd'>item collapse</b> widget command. -<i class='arg'>ItemDesc</i> may also be the string <strong>all</strong>, -in which case the state of all items of the treectrl widget are toggled. -If <strong>-recurse</strong> is specified, the state of all descendants of -<i class='arg'>itemDesc</i> will also be toggled. +If <strong>-recurse</strong> is specified, then the <strong>open</strong> state of all descendants of +the items described by <i class='arg'>itemDesc</i> will also be toggled. </dl> @@ -2188,15 +2176,19 @@ sets the corner to the given coordinates <i class='arg'>x</i> and <i class='arg' <br><br> <dt><a name="115"><i class='arg'>pathName</i> <b class='cmd'>marquee identify</b></a><dd> -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: +<p><table><tr><td bgcolor=black> </td><td><pre class='sample'> +{ + {item {column element element ...} {column element element ...} ...} + {item {column element element ...} {column element element ...} ...} + ... +} +</pre></td></tr></table></p> +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. </dl> @@ -2966,8 +2958,10 @@ The value may have any of the forms acceptable to <strong>Tk_GetPixels</strong>. <br><br> <dt><strong><strong>-button</strong></strong> <i class='arg'>boolean</i><dd> -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 <a href="#dynamic_events">DYNAMIC EVENTS</a>. <br><br> <dt><strong><strong>-expand</strong></strong> <i class='arg'>boolean</i><dd> @@ -3038,7 +3032,7 @@ This option has no effect if the <strong>-width</strong> option is set. <br><br> <dt><strong><strong>-resize</strong></strong> <i class='arg'>boolean</i><dd> 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. <br><br> <dt><strong><strong>-squeeze</strong></strong> <i class='arg'>boolean</i><dd> @@ -3164,7 +3158,7 @@ This keyword cannot be followed by any modifiers unless a single column is matched. You may run into trouble if <i class='arg'>tagExpr</i> looks like a column id or other keyword; also, <i class='arg'>tagExpr</i> must look like a single list element since column descriptions are properly-formed lists. To be safe you may want to -use the <strong>tag</strong> keyword followed by <i class='arg'>tagExpr</i>. +use the <strong>tag</strong> qualifier followed by <i class='arg'>tagExpr</i>. <br><br> <dt><strong>all</strong> <i class='arg'>QUALIFIERS</i><dd> @@ -3711,7 +3705,7 @@ This keyword cannot be followed by any modifiers unless a single item is matched. You may run into trouble if <i class='arg'>tagExpr</i> looks like an item id or other keyword; also, <i class='arg'>tagExpr</i> must look like a single list element since item descriptions are properly-formed lists. To be safe you may want to -use the <strong>tag</strong> keyword followed by <i class='arg'>tagExpr</i>. +use the <strong>tag</strong> qualifier followed by <i class='arg'>tagExpr</i>. <br><br> <dt><strong>active</strong><dd> |