Author:        Peter Spjuth <[email protected]>
    State:         Final
    Type:          Project
    Vote:          Done
    Vote-Summary:  Accepted 5/0/0
    Votes-For:     BG, SL, JN, FV, KW
    Votes-Against: none
    Votes-Present: none
    Created:       19-Sep-2019
    Post-History:
    Tcl-Version:   8.7
    Keywords:      Tk, treeview
    Tk-Branch:     pspjuth-treeview

---

Abstract

This TIP proposes a set of new features for the Ttk treeview widget.

Rationale

Each time I have tried to use the Treeview widget it fell short of some feature or another and I had to resort to other means.

This aims to fill in the most common missing pieces.

Specification

The following features are added to the treeview widget.

Locked horizontal scrolling

Adds the ability to lock the first display column(s) from horizontal scrolling.

A new option -titlecolumns n is added, requesting columns to be locked. The tree column counts, even if -show tree is not specified. This is to follow the semantics of #N-indexing of columns. Thus for value N of this option, column #N is the first one that is scrollable.

Locked vertical scrolling

Adds the ability to lock the first item(s) from vertical scrolling.

A new option -titleitems n is added, requesting items to be locked.

Any individual item's visual appearance is not affected by this, just if it is shown or not. Thus if a hierarchy crosses the titleitem boundary it looks weird but works. If striped rows are used and the title items have default colors, it looks weird but works. Both those usages fall under "Don't do that then".

Cell selection

Adds the ability to select individual cells as well as full rows.

Cell selection is independent of item selection.

Cells are identified with a two element list with item id and column id.

A new subcommand cellselection is added, mirroring the present selection. In addition the cellselection commands get a version with two arguments for selecting/modifying a rectangular range. Only cells in displayed columns are allowed for rectangular selection.

Since for selection the itemList can also be a single item (by nature of how lists work for simple values), this is also allowed for a cellList since a two cell list can be clearly distinguished from the two element list that is one cell.

Any change to -columns clears the cell selection to avoid ambiguous state.

A new option -selecttype type is added to direct default bindings to use either item selection or cell selection. It takes values item or cell.

The identify subcommand is updated with the cell option.

The bbox subcommand receives a new optional argument column allowing to obtain the bounding box of a cell.

Default bindings are updated to use these features.

The <<TreeviewSelect>> virtual event triggers on any selection change including cellselection.

Striped rows

A new option -striped bool is added. This makes every other item to be drawn with the -stripedbackground color, if that option is set by the theme or tags. Built in themes are updated to put something fitting at that color.

Column separators

A new column option -separator bool is added. This controls if a column separator is drawn to the right of the column. Default is 0. Built in themes are updated to define the separators.

A new style option -columnseparatorwidth width is added. Default is 1.

Image anchor for tree

A new item option -imageanchor anchor is added. This controls the placement of the image relative to the text in an item's tree column. Default is "w". For tags, -imageanchor works like -image, i.e. if not set in the item, it can be set by tags.

Item height

A new item option -height height is added. This controls the height of the item, in multiples of -rowheight. Default is 1.

Item hiding

A new item option -hidden bool is added. If true, the item and any of its decendants are hidden. Default is 0.

Automatic -rowheight.

If the style does not set -rowheight, it is filled in based on current font and layout for an item. An Item and a Cell layout is measured with the style's settings, and the resulting height is used as default.

Cell tags.

To control appearance of individual cells, tags can be set on cells as well as items. The set of tags is shared between items and cells, so things like tag configure are not affected by this change.

Cell tags are distinct from item tags and they do not interfere except visually. Cell tags take precedence over item tags when drawing.

A new subcommand tag cell add is added, mirroring the present tag add but operating on cells.

A new subcommand tag cell remove is added, mirroring the present tag remove but operating on cells.

A new subcommand tag cell has is added, mirroring the present tag has but operating on cells.

Cell tags are, like cell values, locked to a column number. Changes to -columns or -displaycolumns do not affect cell tags.

Mouse events bound to a tag will trigger if the pointer is over a cell with that tag.

Cell Images.

Through cell tags, -image and -imageanchor can be present on a cell. Cells will draw accordingly.

For items, and item tags, -image and -imageanchor are specifically about the tree column. They do not propagate to other cell images.

Rejected alternatives

Striped rows

An earlier spec implemented -striped as an alternate state. This did not work well, since options are resolved in a certain order. Style defaults, tags, then Style maps. Since alternate was part of the style maps, it overrode any background in tags. The striped background should have less priority than tags, and be at the level of Style defaults. Thus it was moved to a -stripedbackground option.

Implementation

Started on branch pspjuth-treeview

Copyright

This document has been placed in the public domain.