New | Comment |
---|---|
header create |
Creates a new row of column headers. The result is a unique ID for that header-row. |
header delete |
Deletes one or more header-rows. The top header-row, created when a treectrl is created, cannot be deleted. |
header cget header configure |
These commands work on both entire header-rows and individual columns within header-rows. The column configure command may also be used to configure column headers in the top header-row. |
header bbox header compare header count header element header id header image header span header state header style header text header tag |
These commands have the same syntax as the item subcommands of the same name. Header-rows are actually implemented as items. The header image and header text commands will change either the first image or text element in a custom style assigned to a column header, or the -image and -text options of a column header when no custom style is assigned. The header state command operates on header states, which are distinct from item states. See the updated section called STATES in the manual. |
header dragcget header dragconfigure |
Same as the column dragcget and column dragconfigure commands. The visual feedback when dragging column headers has changed. As a result, the following options are deprecated and have no effect:
|
Option | Comment |
---|---|
All
these options related to column headers are no longer a part of a
column itself. Instead, these options were moved to the new
column header API. These options can still be accessed using column cget and column configure, but only for the top row of column headers. To access these options in header-rows other than the top row, use the header cget and header configure command. |
Arguments Changed | Comment |
---|---|
element create element cget |
The new option -statedomain accepts a value of item or header. The default value is item.
This option is used to distinguish between elements used in items and
elements used in column headers, since items and headers have a
different
set of state flags. The value of this option cannot be changed. |
New | Comment |
---|---|
item state define item state linkage item state names item state undefine |
All the old subcommands of the widget state command are now in the updated item state
command. This was done because items and headers have a different
set of states. Defining new header states is done using the new header state command. |
Arguments Changed | Comment |
---|---|
style create style cget |
The new option -statedomain accepts a value of item or header. The default value is item.
This option is used to distinguish between styles used in items and
styles used in column headers, since items and headers have a different
set of state flags. The value of this option cannot be changed. |
style layout |
A new style layout option was added called -center. The -center option allows one or more elements to be centered within a style. |
Arguments/Result Changed | Comment |
---|---|
bbox |
Three new areas are defined, header.left, header.none, and header.right,
to get the bounds of the different groups of locked/unlocked column
headers. The words after "header." are each possible value of the
column option -lock. |
identify |
To make the result of this
command easier to use, especially with the new column header code, a
new option was added that sets the elements of an array variable rather
than returning the result as a list..t identify -array id $x $yThe above call will alter the array variable named "id" with info about what is under the given coordinates. |
New | Comment |
---|---|
-headerfont |
This
is the font used for drawing text in column headers. The default
value is TkHeadingFont where that font is defined (usually on Tk 8.5+),
otherwise it is the default listbox font. On Mac OS X,
TkHeadingFont is the small system font used for drawing text in the
fixed-height headers. This new option results in a different default look to column text on X11, where TkHeadingFont is a bold font. |
-headerfg -headerforeground |
This is the foreground text
color used when drawing text in column headers. On Gtk+, the
system theme may override this color. |
.t element create MyHeaderElement text -statedomain header
.t style create MyHeaderStyle -statedomain header
New | Comment |
---|---|
-buttony |
This
option allows you to specify the distance from the top of an item that
the expand/collapse button is drawn. When the value of this
option is unspecified, the button is centered vertically in the item. |
New | Comment |
---|---|
-gridleftcolor -gridrightcolor |
So-called "grid lines". These
two options specify a color or gradient to draw on the left and/or
right edge of the column. The lines are drawn overtop an item's
style and down in the whitespace region below any items. |
Usage Changed | How it changed |
-itembackground |
Item background colors can be a Tk color or a gradient name. Item background colors are now drawn below items in the whitespace region even when item wrapping is being used. Previously item background colors were not drawn below items when wrapping was used. |
-textcolor |
This is now a per-state option, just like the -background option, which may be incompatible.
If you previously specified a Tk color name with a space in it, such as
"light blue", then you will need to make the value a proper list:$T column configure $C -textcolor [list "light blue"]When this option is unspecified (the default), the system theme can specify the color. Currently that behavior is only used with the Gtk+ build of treectrl. |
New | Comment |
---|---|
buttonstate |
The value of this option can be active, normal or pressed.
This is used to change the appearance of the expand/collapse
buttons. On Gtk+ the buttons change appearance when the mouse
pointer is over them and when they are clicked. On Mac OS X the
buttons change appearance when they are clicked. On MS Windows
the buttons change appearance when the mouse pointer is over them, but
only when the Explorer theme is used (see the new theme setwindowtheme command). |
Arguments Changed | What changed |
create |
New option -enabled. |
collapse expand toggle |
A new option -animate
was added to support animated disclosure triangles on Gtk+ and Mac OS
X. The library scripts pass the -animate option when clicking on
a button, but not when toggling items using the keyboard. |
New | Comment |
---|---|
-fill |
Specifies the fill color for the
selection rectangle. The value can be a Tk color or a gradient
name or an empty string (the default). When this option isn't an
empty string the dotted outline is not drawn. By specifying the
name of a semi-transparent gradient a modern-looking selection
rectangle can be achieved. |
-outline |
Specifies the outline color for
the selection rectangle. The value can be a Tk color, a gradient name, or an empty
string which is the default. When this option isn't an empty
string the dotted outline is not drawn. |
Behavior Changed | What changed |
---|---|
-union |
Previously, nesting -union elements had undefined behavior. Now it is ok to include an element with -union layout in another element's -union list. |
New | Comment |
---|---|
-bgimage |
This is a synonym for the -backgroundimage option. |
-bgimageanchor | Controls
the alignment of the -backgroundimage. The value is a standard Tk
anchor position such as "nw", "se" or "center", etc. The image is
aligned to the content area when the image doesn't scroll, otherwise
the image is aligned to the canvas. The default is "nw". |
-bgimageopaque |
A boolean that indicates whether
or not the -backgroundimage is partially transparent. This is
needed because there is no way to tell in Tk whether an image contains
transparency. The default is true, so if you use a transparent
-backgroundimage you must set this to false. |
-bgimagescroll |
Controls whether the
-backgroundimage scrolls along with the items or remains locked in
place. The value can be an emptry string for no scrolling, "x"
for horizontal scrolling only, "y" for vertical scrolling only, or "xy"
(the default) for scrolling in both directions. |
-bgimagetile |
Controls whether the
-backgroundimage is tiled along the x and y axes. The value can
be "", "x", "y" or "xy" (the default). |
-buttontracking |
On Mac OS X and Gtk+ the
expand/collapse buttons don't toggle when they are clicked, only when
the mouse button is released over them, like regular pushbuttons.
The value of this option is a boolean; when true the buttons toggle
when the mouse button is released, when false the buttons toggle when
clicked. The default is true on Mac OS X and Gtk+, false on Win32 and X11. |
-canvaspadx -canvaspady |
These options allow whitespace
margins around the edges of the canvas. This is useful for 2D
views where you don't want the items to butt against the window
borders. The value of each option is a list of one or two screen
distances specifying the width of the left/right margins and the height
of the top/bottom margins respectively. |
-itemgapx -itemgapy |
These options allow whitespace gaps between adjacent items.
This is useful for 2D views such as an icon view in a file browser or
an image thumbnail list. The value of each option is a screen
distance defaulting to zero. |
-xscrollsmoothing -yscrollsmoothing |
When these options are set to
true and the xview or yview commands are called to scroll by "units",
scrolling occurs according to the -xscrollincrement or
-yscrollincrement options, and all other scrolling is done as if the
-xscrollincrement or -yscrollincrement options were set to 1. The
effect is that when dragging the scrollbar thumb scrolling is very
smooth, but when clicking the scrollbar buttons scrolling is done in
coarser increments. |
Usage Changed | How it changed |
-columnresizemode |
The default value is "realtime", it used to be "proxy". |
-showlines |
The default value is false on Mac OS X and Gtk+, true on Win32 and X11. |
-usetheme |
The default value is now true. Complete reversal from previous versions, head for the hills. |
New | Comment |
---|---|
gradient | Linear
gradients! There are a number of issues when using gradients, see
the demos and the relevant sections in the manual page for more info. |
theme |
The theme platform command returns the API used to draw themed parts of the treectrl.
$T theme setwindowtheme "Explorer"
...on Windows 7 the disclosure triangles of the Explorer file browser will be used rather than +/- buttons. |
Ignored | Comment |
---|---|
-doublebuffer | This option no longer has any effect but was left in to avoid incompatibilities. Instead, the amount of double-buffering is chosen depending on the platform. Modern platforms such as Mac OS X double-buffer each toplevel whereas older platforms such as Windows XP do not. |
New | Comment |
---|---|
-lmargin1 | Specifies how much the first line of text should be
indented. |
-lmargin2 | Specifies how much the 2nd or greater lines should be indented when a line of text wraps. |
Arguments/Result Changed | What changed |
---|---|
see | OLD: $T see $item NEW: $T see $item ?$column? ?-center xy? You can specify a particular column to scroll into view horizontally. The -center option will center the item/column in the window instead of performing the minimal amount of scrolling to bring it into view at the edge of the window. |
New | Comment |
---|---|
-wrap | When this option is true an item will be the first in a
horizontal (when the treectrl option -orient=horizontal)
or a vertical (when the treectrl option -orient=vertical)
range of items. See the new "iMovie (Wrap)" demo. |
New | Comment |
---|---|
-showrootchildbuttons | Similar to -showrootlines,
this boolean option controls the display of expand/collapse buttons
next to child items of the root item. |
Issues regarding the incompatibility of 8.4 built TkTreeCtrl working in 8.5 were resolved. The Mac OS X API issues noted for 2.2.4 remain (they relate to difficult to reconcile core drawing changes).
A Windows DLL manifest is now embedded to address native theme drawing issues.
Under Mac OSX some internal changes to Tk 8.4.15 and Tk 8.4.17 result in incompatibilities:
New | Comment |
---|---|
-columntagexpr -itemtagexpr |
These boolean options can be used to turn off tag expressions in column descriptions and item descriptions. When the value of these options is false the characters (', ')', '&', '|', '^' and '!' have no special significance when using tags in column/item descriptions. This is useful for applications which may have arbitrary tags applied to columns or items. |
New | Comment |
---|---|
-itemjustify | This option allows item styles to be justified separately from the image/text in the column header. If the value of this option is unspecified (the default), then item styles are justified according to the -justify option of the column. |
Usage Changed | How it changed |
---|---|
-button | The value of this option can now be the word auto (or any abbreviation) in which case a button is drawn only when the item has at least one child item with its item option -visible set to true. |
.t item id "root child end-1" ; # get the second-to-last child of the root item
Deprecated | What to use instead |
---|---|
-defaultstyle | The -itemstyle option of a column. |
Arguments/Result Changed | What changed |
---|---|
contentbox | 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. |
selection get | Accepts 2 optional arguments to allow in-place lindex and lrange queries of
the selection. For example:.t selection get 0 ; # the first selected item |
New | Comment |
bbox | Returns the bounding box of different areas of the
window. For example:.t bboxwill return the bounds of the window, and: .t bbox headerwill return the bounds of the column headers, and: .t bbox contentwill return the same result as the [contentbox] command, and: .t bbox leftwill return the bounds of the left-locked and right-locked columns. |
Renamed |
New name |
---|---|
-tag | -tags |
New | Comment |
-lock | This option allows columns to stick to the left or right edge of the window. Locked columns can scroll vertically but not horizontally. Valid values for this option are none (the default), left or right. |
-itemstyle | Specifies the name of a style to set in this column for newly-created items. This option replaces the treectrl option -defaultstyle. |
-uniform | These two options
operate the same as the grid geometry manager options of the same name.
For example:.t column configure 0 -uniform awill give columns 0 and 1 the same requested width, whichever is the larger of the two columns. And: .t column configure 0 -uniform a -weight 2will give column 0 twice the maximum of the requested widths of columns 0 and 1. And: .t column configure 0 -expand yes -weight 2will give column 0 twice the extra space as column 1. |
-weight |
Arguments/Result Changed | What changed |
---|---|
column count | Takes an optional column-description argument; the
result is
the number of columns that match the column description. For example:.t column count visiblewill return the number of columns whose -visible option is true, and: .t column count {tag a^b}will return the number of columns with either tag "a" or "b", but not both. |
New | Comment |
column tag add | 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 expr | |
column tag names | |
column tag remove |
New | Comment |
---|---|
-tags | 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. |
Arguments/Result Changed | What changed |
---|---|
item count | Takes an optional item-description argument; the result
is the number of items that match the item description. For example:.t item count visiblewill 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 create | New option -tags specifies an initial list of tags for created items. |
item id | Returns a list of item ids if the item description
matches multiple items. For example:.t item id allwill return a list of ids for all items, and: .t item id "$item children"will return the ids of every child of an item. |
New | Comment |
item descendants | Returns 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 add | Add tags to items. For example:.t item tag add all {a b c}will add tags "a", "b" and "c" to every item. |
item tag expr | Evaluate a tag expression against items. For example:.t item tag expr $item areturns 1 if an item has tag "a". Also: .t item tag expr $item a||breturns 1 if an item has tag "a" or "b". |
item tag names | Return a list of tag names assigned to items. For
example:.t item tag names $itemreturns the tag list for an item, and: .t item tag names allreturns every tag assigned to any item. |
item tag remove | Remove tags from items. For example:.t item tag remove all {b c}will remove tags "b" and "c" from any items that have them. |
set canvas [canvas .t.canvas ...]to this:
.t item element configure $item $column myElement -window $canvas
set frame [frame .t.clip -borderwidth 0]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.
set canvas [canvas $frame.canvas ...]
.t item element configure $item $column myElement -window $frame -clip yes
.t item id "list [list $a $b $c]"
.t item id "range $first $last"
.t item id "$item ancestors"
.t item id "$item children"
.t item id "$item descendants"
.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 id "first !visible" ; # find the first item that is not displayed
.t item id "first state {selected !open}" ; # find the first item that is selected and collapsed
.t item id "$item children tag {a && !b}" ; # find children of $item that have tag "a" but not tag "b"
.t item id "all !visible state myState" ; # find every item that is not displayed with user-defined state "myState"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
.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"
Arguments/Result Changed | What changed |
---|---|
column delete |
Added an optional second argument allowing a range of columns to be deleted. |
New | Comment |
---|---|
-itemwidth | |
-itemwidthequal | Deprecates the column -widthhack option. |
-itemwidthmultiple | Deprecates the column -stepwidth option. |
Deprecated | What to use instead |
---|---|
-stepwidth | treectrl's -itemwidthmultiple option |
-widthhack | treectrl's -itemwidthequal option |
New | Comment |
---|---|
element perstate | Like [item element perstate]. |
New | Comment |
---|---|
-height | Overrides the treectrl's -itemheight option |
Deprecated | What to use instead |
---|---|
item element actual | item element perstate |
item complex | item element configure |
Behaviour Changed | What changed |
item bbox | No longer returns an error if no style had been assigned to the column. |
item state forcolumn | No longer returns an error if no style had been assigned to the column. |
item style set | Does nothing when replacing a style with the same
style.
Previously the old style was freed before assigning the new style,
losing the element config info if the old and new styles were the same. Potential incompatibility |
Arguments/Result Changed | What changed |
item create | Added options: -count -height, -nextsibling, -open, -parent, -prevsibling, and -returnid. Multiple items may be created with one call using the -count option. |
item element configure | Multiple elements in multiple columns may be configured with a single call. Use '+' to separate elements, and ',' to separate columns. See the docs. |
item style set | When no column is specified, returns a list of one
style name
per column. Previously, the list would have less values than the number
of columns if no styles had ever been assigned to the rightmost
column(s). Potential incompatibility |
item text | When no column is specified, returns a list of one string per column. |
New | Comment |
item image | Partner to the [item text] command. |
item element perstate | Not really new, just renamed from [item element actual]
to
better describe what it does. Accepts a new optional argument which
specifies the state to use when determining the value of the per-state
option. The following options no longer return a default value if the per-state option itself does not have a value specified:
|
item span | A style may now be displayed over multiple adjacent
columns. |
New | Comment |
---|---|
notify unbind |
Let's you unbind all scripts from an object with one call. |
Replaced | What to use instead |
---|---|
-openbuttonimage | -buttonimage |
-closedbuttonimage | -buttonimage |
-openbuttonbitmap | -buttonbitmap |
-closedbuttonbitmap | -buttonbitmap |
Usage Changed | How it changed |
-backgroundmode | The values "index" and "visindex" are deprecated. The value "order" should be used instead of "index", and "ordervisible" should be used instead of "visindex". This brings agreement with the new "item order" command which replaces the "item index" command. |
-treecolumn | This used to be any integer value which may or may not have corresponded to an actual column. Now the value must be a valid column description, or an empty string to indicate no column should display buttons/lines. |
New | |
-backgroundimage | |
-columnprefix | |
-columnresizemode | |
-itemprefix | |
-minitemheight | |
-usetheme |
Deprecated | What to use instead |
---|---|
compare | item compare |
index | item id |
numcolumns | column count |
numitems | item count |
range | item range |
Removed | What to use instead |
---|---|
-relief |
-state |
-sunken | -state |
Renamed |
New name |
-arrowpad | -arrowpadx |
Usage Changed | How it changed |
-background | This is now a per-state option. See COLUMNS in the help file for valid state names. |
New |
|
-arrowbitmap |
|
-arrowimage | |
-arrowpady | |
-maxwidth | |
-resize | |
-state | |
-textlines |
Deprecated | What to use instead |
---|---|
column index | column id |
Arguments/Result Changed | What changed |
column configure |
A column description of "all" is allowed if at least
one
option-value pair is given. |
column create | The result is a unique identifier. Previously the result was an index in the list of columns. |
column delete | A column description of "all" is allowed. |
New | Comment |
column compare | |
column count | replaces "numcolumns" |
column dragconfigure | |
column dragcget | |
column id | replaces "column index" |
column list | |
column order |
Removed | What to use instead |
---|---|
item index | item order |
New | Comment |
item compare | replaces "compare" |
item count | replaces "numitems" |
item id | replaces "index" |
item order | replaces "item index" |
item range | replaces "range" |
Arguments/Result Changed | What changed |
---|---|
notify generate |
Added optional percentsCommand argument |
notify install | Old syntax (supported but deprecated):notify install event eventName notify install detail eventName detailNew syntax: notify install <eventName> notify install <eventName-detail> |
notify linkage | Old syntax (supported but deprecated):notify linkage eventName notify linkage eventName detail notify linkage <eventName> notify linkage <eventName-detail> |
notify uninstall | see notify install above |
Usage Changed | How it changed |
---|---|
-iexpand | Two new flags "x' and "y" are allowed. Previously, only
the
-ipadx and -ipady padding could be expanded by this option. The new xy
flags expand the display area of the element, not the padding. To
update your code, you will probably want to change this:$T style layout $S $E -iexpand we $T style layout $S $E -iexpand x |
New |
|
-height | |
-maxheight | |
-maxwidth | |
-minheight | |
-minwidth | |
-sticky | |
-width |