From 6cadc456decb76816d72a783232fa7f11552d260 Mon Sep 17 00:00:00 2001 From: treectrl Date: Sat, 18 Nov 2006 04:40:10 +0000 Subject: Updates for 2.2. --- doc/What's New in TkTreeCtrl.html | 5290 ++++++++++++++++++++++++++++--------- doc/treectrl.html | 140 +- doc/treectrl.man | 134 +- doc/treectrl.n | 140 +- 4 files changed, 4213 insertions(+), 1491 deletions(-) diff --git a/doc/What's New in TkTreeCtrl.html b/doc/What's New in TkTreeCtrl.html index 9b9e04e..4fc90c5 100644 --- a/doc/What's New in TkTreeCtrl.html +++ b/doc/What's New in TkTreeCtrl.html @@ -1,7 +1,7 @@ - + @@ -10,6 +10,12 @@ + + + + + + @@ -25,6 +31,9 @@ + + + @@ -41,6 +50,12 @@ + + + + + + What's New in TkTreeCtrl @@ -55,6 +70,9 @@ + + +

What's New in TkTreeCtrl 2.2

@@ -64,6 +82,9 @@ + + +

TreeCtrl Configuration Options

@@ -80,6 +101,9 @@ + + + @@ -90,8 +114,14 @@ + + + + + + @@ -101,6 +131,9 @@ + + + @@ -110,6 +143,9 @@ + + + @@ -121,6 +157,9 @@ instead + + + @@ -130,6 +169,9 @@ instead + + + @@ -139,6 +181,9 @@ instead + + + @@ -148,10 +193,22 @@ instead + + + + + + + + + + + +
DeprecatedWhat to use instead
-defaultstyleThe -itemstyle option of a column.
@@ -163,6 +220,9 @@ instead + + +

TreeCtrl Command

@@ -180,6 +240,9 @@ instead + + + @@ -190,7 +253,13 @@ instead + + + + + + @@ -200,6 +269,9 @@ instead + + + @@ -210,6 +282,9 @@ Changed + + + @@ -220,6 +295,9 @@ changed + + + @@ -229,6 +307,9 @@ changed + + + @@ -238,6 +319,9 @@ changed + + + @@ -247,10 +331,28 @@ changed - + + + + + + + + + + + + +
Arguments/Result ChangedWhat changed
contentboxThe return value is an empty string if the content area is totally obscurred by column headers, borders, and/or locked columns. Typically this will only happen if the window is too small.The return value is an empty string if the +content area is totally obscurred by column headers, borders, and/or +locked columns. Typically this will only happen if the window is too +small.
+ + +

Column Configuration Options

@@ -260,6 +362,9 @@ changed + + + @@ -269,6 +374,9 @@ changed + + + @@ -278,6 +386,9 @@ changed + + + @@ -287,6 +398,9 @@ changed + + + + + + @@ -305,6 +422,9 @@ changed + + + @@ -315,6 +435,9 @@ name + + + @@ -324,6 +447,9 @@ name + + + @@ -333,6 +459,9 @@ name + + + @@ -342,6 +471,9 @@ name + + + @@ -351,6 +483,9 @@ name + + + @@ -360,6 +495,9 @@ name + + + @@ -369,6 +507,9 @@ name + + + @@ -378,6 +519,9 @@ name + + + @@ -387,6 +531,9 @@ name + + + @@ -396,6 +543,9 @@ name + + + @@ -405,6 +555,9 @@ name + + + @@ -414,6 +567,9 @@ name + + + @@ -435,16 +594,31 @@ horizontally. Valid values for this option are + + + + + + + + + + + + + + + @@ -454,6 +628,9 @@ newly-created items. This option replaces the treectrl option + + + @@ -463,6 +640,9 @@ newly-created items. This option replaces the treectrl option + + + @@ -542,6 +749,9 @@ will give column 0 twice the extra space as column 1. + + + @@ -551,6 +761,9 @@ will give column 0 twice the extra space as column 1. + + + @@ -560,6 +773,9 @@ will give column 0 twice the extra space as column 1. + + + @@ -569,6 +785,9 @@ will give column 0 twice the extra space as column 1. + + + @@ -578,6 +797,12 @@ will give column 0 twice the extra space as column 1. + + + + + + @@ -595,25 +820,24 @@ will give column 0 twice the extra space as column 1. -

Column Command

+

Column Command

-
Renamed
@@ -296,6 +410,9 @@ changed		New name
-tag-tags
NewComment
-lockThis option allows columns to stick to the left or right edge of the window. Locked columns can scroll vertically but not @@ -426,6 +582,9 @@ horizontally. Valid values for this option are + + +
-itemstyleSpecifies the name of a style to set in this column for newly-created items. This option replaces the treectrl option -defaultstyle.
-uniformThese two options operate the same as the grid geometry manager options of the same name. For example:
@@ -474,6 +654,12 @@ For example:
+ + + + + + @@ -490,6 +676,9 @@ For example:
+ + + will give columns 0 and 1 the same requested width, whichever is the larger of the two columns. And:
@@ -498,6 +687,12 @@ will give columns 0 and 1 the same requested width, whichever is the larger of t + + + + + + @@ -513,6 +708,9 @@ will give columns 0 and 1 the same requested width, whichever is the larger of t + + + will give column 0 twice the maximum of the requested widths of columns 0 and 1. And:
@@ -520,6 +718,12 @@ will give column 0 twice the maximum of the requested widths of columns 0 and 1. + + + + + + @@ -533,6 +737,9 @@ will give column 0 twice the maximum of the requested widths of columns 0 and 1. + + + will give column 0 twice the extra space as column 1.
-weight
+
- @@ -622,8 +846,8 @@ will give column 0 twice the extra space as column 1. - + @@ -631,16 +855,32 @@ will give column 0 twice the extra space as column 1. - + + + + + + + +will return the number of columns with either tag "a" or "b", but not both. + + @@ -649,25 +889,24 @@ will give column 0 twice the extra space as column 1. - + - + - @@ -676,11 +915,8 @@ will give column 0 twice the extra space as column 1. - + @@ -688,16 +924,15 @@ word "tail" in column descriptions. - + - @@ -705,8 +940,8 @@ word "tail" in column descriptions. + - @@ -715,25 +950,27 @@ word "tail" in column descriptions. - + - + - @@ -742,7 +979,7 @@ word "tail" in column descriptions. - + @@ -751,25 +988,24 @@ word "tail" in column descriptions. - + - + - @@ -778,16 +1014,8 @@ word "tail" in column descriptions. - - - - - - - - -
New
Arguments/Result +ChangedWhat +changed
column countTakes an optional column-description argument; the result is +the number of columns that match the column description. For example:
+ + 
.t column count visible
+will return the number of columns whose -visible option is true, and:
+ + 
.t column count {tag a^b}
- 		Comment
New
Commentcolumn tag addColumns can have -a list of tag names. Previously only a single tag was allowed. The tail column no -longer has the word "tail" as a tag, but it is still referred to by the -word "tail" in column descriptions.
column tag addcolumn tag expr
Columns can have +a list of tag names. Previously only a single tag was allowed. The tail column no +longer has the word "tail" as a tag, but it is still referred to by the +word "tail" in column descriptions.
column tag names
column tag exprcolumn tag remove
+ @@ -795,16 +1023,15 @@ word "tail" in column descriptions. -

Item Configuration Options

+ column tag names - @@ -812,8 +1039,8 @@ word "tail" in column descriptions. + - @@ -822,25 +1049,24 @@ word "tail" in column descriptions. - + - + - @@ -858,43 +1084,49 @@ word "tail" in column descriptions. - + + + + + + + + + + + +
Newcolumn tag removeComment
- -tags +

Item Configuration Options

- -Tags are textual labels applied to items to group them. Tags -do not affect the appearance or behaviour of items. Tags can be used in -item descriptions to operate on multiple items. More information can be -found in the man page. + - @@ -902,16 +1134,8 @@ found in the man page. + - - - - - - - - -
@@ -920,25 +1144,24 @@ found in the man page. -

Item Command

+ - + - @@ -947,7 +1170,7 @@ found in the man page. - + @@ -956,27 +1179,24 @@ found in the man page. - + - + - @@ -985,7 +1205,9 @@ changed - + + + @@ -994,18 +1216,21 @@ changed - + + - @@ -1023,26 +1248,35 @@ whose ancestors are all expanded etc). - + + + + + + + + + + + +
New
CommentArguments/Result -Changed
What -changed
-tagsitem count + +Tags are textual labels applied to items to group them. Tags +do not affect the appearance or behaviour of items. Tags can be used in +item descriptions to operate on multiple items. More information can be +found in the man page.New option -visible -added to return the number of items that are displayed (i.e., those -whose ancestors are all expanded etc).
- item create +

Item Command

- New option -tags -specifies an initial list of tags for created items. @@ -1051,8 +1285,8 @@ specifies an initial list of tags for created items. - + @@ -1060,16 +1294,15 @@ specifies an initial list of tags for created items. - + - @@ -1077,9 +1310,8 @@ specifies an initial list of tags for created items. + - -will return a list of ids for all items, and:
+ - - - - - - - - 
.t item id "$item children"
@@ -1129,7 +1348,7 @@ will return a list of ids for all items, and:
-will return the ids of every child of an item. + @@ -1138,25 +1357,24 @@ will return the ids of every child of an item. - + - + - @@ -1165,16 +1383,22 @@ will return the ids of every child of an item. - + - @@ -1183,7 +1407,7 @@ will return the ids of every child of an item. - + @@ -1192,26 +1416,24 @@ will return the ids of every child of an item. - + - + - @@ -1220,8 +1442,9 @@ an item. - + @@ -1229,19 +1452,15 @@ an item. - + - @@ -1249,8 +1468,8 @@ and mouse bindings. + - @@ -1259,25 +1478,25 @@ and mouse bindings. - + - + - 
.t item tag add all {a b c}
+ + + + 
.t item id all
@@ -1302,25 +1524,34 @@ and mouse bindings. -will add tags "a", "b" and "c" to every item.
+will return a list of ids for all items, and:
- + + + + + + + + + + + 
.t item id "$item children"
- @@ -1329,8 +1560,8 @@ will add tags "a", "b" and "c" to every item.
- +will return the ids of every child of an item. @@ -1338,16 +1569,15 @@ will add tags "a", "b" and "c" to every item.
- + - - - - - - - - - 
.t item tag expr $item a
@@ -1372,32 +1595,24 @@ will add tags "a", "b" and "c" to every item.
-returns 1 if an item has tag "a". Also:
+ - - - - - - - - 
.t item tag expr $item a||b
+ -returns 1 if  an item has tag "a" or "b". @@ -1415,16 +1630,13 @@ returns 1 if  an item has tag "a" or "b". - - - + - @@ -1433,8 +1645,7 @@ returns 1 if  an item has tag "a" or "b". - @@ -1443,39 +1654,25 @@ example:
- - - - - - - - 
.t item tag names $item
+ -returns the tag list for an item, and:
+ - - - - - - - - 
.t item tag names all
@@ -1484,8 +1681,8 @@ returns the tag list for an item, and:
-returns every tag assigned to any item. + @@ -1493,16 +1690,15 @@ returns every tag assigned to any item. - + - @@ -1510,8 +1706,11 @@ returns every tag assigned to any item. + - @@ -1520,32 +1719,24 @@ returns every tag assigned to any item. - - - - - - - - - 
.t item tag remove all {b c}
+ -will remove tags "b" and "c" from any items that have them. @@ -1554,7 +1745,7 @@ will remove tags "b" and "c" from any items that have them. - + @@ -1563,20 +1754,10 @@ will remove tags "b" and "c" from any items that have them. - - - - - - - - -
item id
Returns a list of item ids if the item description -matches multiple items. For example:
@@ -1088,39 +1320,26 @@ matches multiple items. For example:
- - - - - - - - 
.t item id all
+ 		Arguments/Result +ChangedWhat +changed
item countNewCommentTakes an optional item-description argument; the result is the number of items that match the item description. For example:
+ + 
.t item count visible
+will return the number of items that are displayed (i.e., those +whose ancestors are all expanded, -visible options are true, etc), and:
+ + 
.t item count {tag a^b}
+will return the number of items with either tag "a" or "b", but not both.
item descendants
Returns the ids of the children, grandchildren, etc of -an item.item create
New option -tags +specifies an initial list of tags for created items.item enabled
Gets and sets the enabled -state for items. All items are enabled when first created. Disabled -items cannot be selected, and are ignored by the default key-navigation -and mouse bindings.
item iditem tag addReturns a list of item ids if the item description +matches multiple items. For example:
- 		Add tags to items. For example:
@@ -1293,7 +1512,10 @@ and mouse bindings.
item tag expr
Evaluate a tag expression against items. For example:
@@ -1355,15 +1585,8 @@ will add tags "a", "b" and "c" to every item.
+
NewComment
item tag namesReturn a list of tag names assigned to items. For -example:
+ 		item descendantsReturns the ids of the children, grandchildren, etc of +an item.
item enabled
Gets and sets the enabled +state for items. All items are enabled when first created. Disabled +items cannot be selected, and are ignored by the default key-navigation +and mouse bindings.item tag removeRemove tags from items. For example:
+
item tag add
-

Text Element

-The new option -underline draws an underline under a single character of the displayed text.
+ Add tags to items. For example:
@@ -1584,21 +1765,25 @@ The new option -underline draws an under -

Window Element

+ + + + + + + + + + + 
.t item tag add all {a b c}
-Window elements can now be properly clipped so they don't draw over the -column header, borders, or outside the bounds of the item -columns they occupy. This is accomplished by making the window you want -to display a child of a borderless frame widget, and setting the new -clip option of the -window element to TRUE. So if your program displays a canvas widget in -a window element, you would change this code:
@@ -1606,8 +1791,8 @@ a window element, you would change this code:
+will add tags "a", "b" and "c" to every item.
-
set canvas [canvas .t.canvas ...]
.t item element configure $item $column myElement -window $canvas
@@ -1616,32 +1801,24 @@ a window element, you would change this code:
-to this:
+ -
set frame [frame .t.clip -borderwidth 0]
set canvas [canvas $frame.canvas ...]
.t item element configure $item $column myElement -window $frame -clip yes
+ -The -clip -option tells the window element to manage the geometry of both the -window -widget (i.e, -the frame) and its first child widget (i.e., the canvas). In this case, -the frame widget is kept sized and positioned so that it is never -out-of-bounds. You can see this in the "Big List" and "Firefox Privacy" -demos. -

Item Descriptions

@@ -1650,7 +1827,7 @@ demos. -New keywords were added to allow multiple items to be specified by an item description:
+ @@ -1659,34 +1836,24 @@ New keywords were added to allow multiple items to be specified by an list -specifies a list of other item descriptions: - - - - - - - - 
.t item id "list [list $a $b $c]"
+ Evaluate a tag expression against items. For example:
- @@ -1695,18 +1862,18 @@ specifies a list of other item descriptions: -
  • The keyword range -operates like the item -range command: - - - - - - - - 
    .t item id "range $first $last"
    + + + + + + + + + + + 
    .t item tag expr $item a
    @@ -1714,18 +1881,15 @@ range command: -
    • - +returns 1 if an item has tag "a". Also:
    -New modifiers were added to match multiple items: - + Return a list of tag names assigned to items. For +example:
    -New qualifiers were added to refine which items are matched:
    @@ -1836,8 +1979,18 @@ New qualifiers were added to refine which items are matched:
    - -
    -
    .t item id "all depth 2" ; # find all items that are children of the root's children
    .t item id "depth 2" ; # ditto
    -
    + + + + + + + + + + + 
    .t item tag names all
    - -
    -The keyword all -may now be followed by a list of qualifiers. For example:
    + + + + + + + + + + + 
    .t item tag remove all {b c}
    @@ -1977,30 +2115,24 @@ may now be followed by a list of qualifiers. For example:
    -
    .t item id "all !visible state myState" ; # find every item that is not displayed with user-defined state "myState"
    +will remove tags "b" and "c" from any items that have them. -A list of qualifiers may be used as the first part of an item -description. This gives the same result as  "all" followed by the -qualifiers. For example:
    -
    -
    .t item id "!visible state myState" ; # same as the previous example
    -
    + -

    Column Descriptions

    @@ -2009,49 +2141,41 @@ qualifiers. For example:
    -New keywords list and -range can be used to -match multiple columns.
    - - - - -New qualifiers state, -tag, !tail and !visible can be used -to restrict which columns are specified.
    - + + + + + + + + + + + + -The keyword all may be followed by a list of qualifiers.
    +

    Text Element

    -A list of qualifiers may used as the first part of a column -description. This gives the same result as  "all" followed by the -qualifiers. -

    Multi-item and multi-column commands

    +The new option -underline draws an underline under a single character of the displayed text.
    -Many commands can now operate on multiple items and/or columns by using -the improved item descriptions and column descriptions mentioned above. -For example: -
    -
    .t column configure "range 1 10" -tags {a b c}
    .t column delete "tag a"
    .t column id "tag {a || b}"
    .t item configure "depth 1" -button yes
    .t item element configure "root children" all elem1 -text "Hello"
    .t item id "visible"
    .t item image all all image1
    .t item style map "tag {a && !b}" "tag c" style2 {style1.elem1 style2.elem2}
    .t item style set all all style1
    .t item state forcolumn all all state1
    .t item state set "tag current" ~mouseover
    .t item remove "state selected"
    .t item span "range 1 10" "range 10 last" 2
    .t item text "root children" all "Hello"
    -
    -

    Demo Changes

    +

    Window Element

    @@ -2059,17 +2183,20 @@ For example: - +
    set frame [frame .t.clip -borderwidth 0]
    set canvas [canvas $frame.canvas ...]
    .t item element configure $item $column myElement -window $frame -clip yes
    -

    Bug Fixes

    @@ -2117,7 +2240,14 @@ option of window elements. -     - +New modifiers were added to match multiple items: + @@ -2234,7 +2373,20 @@ columns or items were hidden, or if the span of an item-column changed. - +
  • The modifier ancestors +operates like the item +ancestors command: + + + + + + + + + + + 
    .t item id "$item ancestors"
    @@ -2243,27 +2395,37 @@ columns or items were hidden, or if the span of an item-column changed.
    • - + - +
  • The modifier children +operates like the item +children command: + + + + + + + + + + + 
    .t item id "$item children"
    -
    • @@ -2272,8 +2434,8 @@ changed - + @@ -2281,16 +2443,28 @@ changed - @@ -2298,9 +2472,8 @@ changed + - @@ -2309,33 +2482,24 @@ columns to be deleted. - + - - - - - - - - -
    Arguments/Result -ChangedWhat -changed
    column delete
    +
  • The modifier descendants +operates like the item +descendants command: + + + + + + + + + + + 
    .t item id "$item descendants"
    -
    		• Added an optional second argument allowing a range of -columns to be deleted.
    +New qualifiers were added to refine which items are matched:
    -

    Bug Fixes

    @@ -2353,20 +2517,10 @@ columns to be deleted. -
  • The item sort -command -will be much faster in many cases. There was a silly error in the -pivot-finding code of quicksort which resulted in the slow-down.
    • - - - - - -
  • A column header will be redisplayed if an image in -the header is altered.
    • +
  • The qualifier depth matches items at a given depth in the heirarchy:
    • @@ -2375,8 +2529,7 @@ the header is altered. -
  • Fixed bus errors on some Unix systems due to alignment -problems.
    • + @@ -2385,7 +2538,8 @@ problems. - +
    +
    .t item id "all depth 2" ; # find all items that are children of the root's children
    .t item id "depth 2" ; # ditto
    @@ -2394,7 +2548,7 @@ problems. -

    Other Changes

    +
    @@ -2412,18 +2566,23 @@ problems. -
  • The Tk caret is now positioned over the active item when it -changes. The Tk caret is used for the Magnifier accessibility -application and IME on Windows, as well as XIM under Unix.
    • - - - - +
  • The qualifier !visible +matches items that are not displayed: + + + + + + + + + + + 
    .t item id "first !visible" ; # find the first item that is not displayed
    -
  • Improved the appearance of the column headers under OSX.
    • @@ -2431,8 +2590,8 @@ application and IME on Windows, as well as XIM under Unix. + -
  • Added <MouseWheel> support to OSX.
    • @@ -2441,30 +2600,36 @@ application and IME on Windows, as well as XIM under Unix. -
  • Changing the -visible option of an item could be slow if -any -items were selected. That is because non-visible items may not be part -of the selection. A change was made so that changes to the selection -caused by modifying the -visible option of an item do not occur until -the next display update.
    • +
  • The qualifier state +matches items that have certain states set (or not set if '!' is used): + + + + + + + + + + + 
    .t item id "first state {selected !open}" ; # find the first item that is selected and collapsed
    - +
    • -

    Demo Changes

    @@ -2473,7 +2638,19 @@ the next display update. - -
  • The screen-magnifier image now resizes with the "loupe" -window.
    • +
    - +The keyword all +may now be followed by a list of qualifiers. For example:
    -
    -

    What's New in TkTreeCtrl 2.1

    @@ -2531,91 +2703,105 @@ window. +
    .t item id "all !visible state myState" ; # find every item that is not displayed with user-defined state "myState"
    -This version should be backwards compatible with 2.0, except for a few -obscure changes.
    +A list of qualifiers may be used as the first part of an item +description. This gives the same result as  "all" followed by the +qualifiers. For example:
    -

    TreeCtrl Configuration Options

    +
    +
    .t item id "!visible state myState" ; # same as the previous example
    - + - +

    Column Descriptions

    - +New keywords list and +range can be used to +match multiple columns.
    - +New qualifiers state, +tag, !tail and !visible can be used +to restrict which columns are specified.
    - +The keyword all may be followed by a list of qualifiers.
    - +A list of qualifiers may used as the first part of a column +description. This gives the same result as  "all" followed by the +qualifiers. +

    Multi-item and multi-column commands

    - +Many commands can now operate on multiple items and/or columns by using +the improved item descriptions and column descriptions mentioned above. +For example: +
    +
    .t column configure "range 1 10" -tags {a b c}
    .t column delete "tag a"
    .t column id "tag {a || b}"
    .t item configure "depth 1" -button yes
    .t item count visible
    .t item element configure "root children" all elem1 -text "Hello"
    .t item id "visible"
    .t item image all all image1
    .t item style map "tag {a && !b}" "tag c" style2 {style1.elem1 style2.elem2}
    .t item style set all all style1
    .t item state forcolumn all all state1
    .t item state set "tag current" ~mouseover
    .t item remove "state selected"
    .t item span "range 1 10" "range 10 last" 2
    .t item text "root children" all "Hello"
    -
    + @@ -2623,7 +2809,7 @@ obscure changes.
    - + +
  • New demo "My Computer". Demonstrates disabled items used as +headers.
    • - @@ -2659,8 +2845,9 @@ obscure changes.
    - +
  • New demo "Column Locking". Demonstrates columns that do not +scroll horizontally.
    • @@ -2668,16 +2855,17 @@ obscure changes.
    - +
  • The "Big List" and "Firefox Privacy" demos were changed to +use the new -clip +option of window elements.
    • - @@ -2685,26 +2873,31 @@ obscure changes.
    + - +

    Misc Changes

    + +
  • If -itembackground colors are specified for the tail column, then they are drawn.
    • +
  • Memory usage is improved, especially for text elements.
    • + - @@ -2712,8 +2905,8 @@ obscure changes.
    +

    Bug Fixes

    - @@ -2722,33 +2915,27 @@ obscure changes.
    - - - - - - - - -
    NewComment
    -itemwidth
    +

    Demo Changes

    @@ -2632,25 +2818,25 @@ obscure changes.
    -
    -itemwidthequalDeprecates the column -widthhack option.
    -itemwidthmultipleDeprecates the column -stepwidth option.
    +