these options can also be specified for the widget's header at row and cell
level, with the aid of the header rowconfigure
(or
header
configrowlist
, or header configrows
) and
header
cellconfigure
(or header configcelllist
, or
header
configcells
) subcommands. Likewise, the
-stripebackground
and
-stripeforeground
options can also be specified at
column level. For this reason, a particular cell can have up to four
values for one and the same color or font option. If these values
conflict, then the option specified at the highest priority level is
used. The decreasing priority order is cell, row, column,
widget.-listvariable
option, or at least do not
add new items to the variable specified as its value, because adding
new items to that list will result in inserting those list elements
into the widget without respecting the tree's internal structure.-treecolumn
option is
left-aligned so the tree structure can be displayed as expected.insertchild(ren)
or insertchildlist
subcommand rather
than insert
or
insertlist
for inserting
new items into the widget's body.-editable
option at both cell and column level. If the cell-level option was set
explicitly then its value determines the editability of the cell's
content. Otherwise the value of the column-level option is used to
decide whether the cell can be edited interactively. From this rule
it follows that you can enable interactive cell editing for a whole column
by setting its -editable
option to true. To
exclude some of the column's cells from interactive editing, just set their
-editable
option to false.editcell
subcommand, which is
invoked implicitly by clicking with the left mouse button into an editable
cell (see the -editselectedonly
option for details) or
using keyboard navigation to move from one editable cell into
another. If the selection type is cell
and the
location cursor is in an editable cell, then the interactive editing of the
active element can also be started by pressing Return
or
KP_Enter
. Per default, the editcell
subcommand creates a temporary entry widget and embeds it into the cell
whose index was passed to it as argument. You can, however, use the
-editwindow
column or
cell configuration option to specify another
widget instead of an entry, like a Tk core text, spinbox, checkbutton, or
menubutton widget, or a tile entry, spinbox, combobox, checkbutton, or
menubutton, or one of the 19 currently supported widgets from the packages
BWidget, Iwidgets, combobox (by Bryan Oakley), ctext, and Mentry
(or Mentry_tile). Before specifying a widget from one of these
library packages as the value of the -editwindow
column
or cell configuration option, you must register it for interactive cell
editing by invoking the corresponding tablelist::add*
command. The above-mentioned Tk core and tile widgets are
automatically registered for cell editing.-formatcommand
option of the cell's
column. However, if the value of the -editstartcommand
configuration option
is a nonempty string, then the text displayed in the cell is passed to that
command as its last argument (following the tablelist's path name as well
as the cell's row and column indices), the resulting script is evaluated in
the global scope, and the return value becomes the edit window's
content. From within this script you can invoke the cancelediting
subcommand, which destroys
the temporary embedded widget and cancels the editing of its content.
The main goal of this script is, however, to enable you to define
validations for the editing process. This can be done either with the
aid of the options for entry validation, supported by Tk versions 8.3 and
higher (see the entry reference page), or by using the widget
callback package Wcb, available for Tk
versions 8.0 and higher. The Iwidgets package (available for Tk
versions 8.0 or higher) provides its own validation facilities, which can
equally be used if the edit window is a widget belonging to that
extension. In either case, you will need the path name of the
temporary embedded widget or that of its entry or entry-like component; use
the editwinpath
and
entrypath
subcommands to get
these path names. Another purpose of the command indicated by the
-editstartcommand
option is to enable you to prepare
the edit window in various other ways. For example, if the latter is
a combobox widget then you can set its -editable
option
to false or (for a tile combobox) set its state to
readonly
, and you will have to populate its listbox
component. In the same script, you can change some of the embedded
widget's visual attributes (like its background, selection background, or
selection foreground color). (Notice that this can also be done with
the aid of the Tk option database.)Control-i
inserts a tab, Control-j
inserts a newline, and if the edit window is a text or ctext widget then
Return
and KP_Enter
insert a newline character,
too. Tab
and Shift-Tab
are used for
navigation between the editable cells, just like Alt-Left
,
Alt-Right
, Alt-Up
, Alt-Down
,
Alt-Prior
, Alt-Next
, Alt-Home
, and
Alt-End
(as well as Control-Home
and
Control-End
, except in the case of a text or ctext
widget). On Mac OS Classic and Mac OS X/11+ Aqua the
Command
key is used instead of Alt
. The
editing can be aborted with the Escape
key (or by invoking the
cancelediting
subcommand)
and terminated normally with Return
or KP_Enter
(together with Control
for a text or ctext widget). The
bindings for the keys used for normal termination of the editing just
invoke the finishediting
subcommand; the latter can also be called explicitly to terminate the
editing programmatically. Normal termination is also triggered by
clicking with the left mouse button anywhere in the tablelist's body,
outside the cell just being edited, or moving into another editable cell by
using keyboard navigation. If the editing was started with the left
mouse button, the edit window is a Tk or tile checkbutton, and the value of
the -instanttoggle
option
is true, then the normal termination of the editing will take place
automatically, without any user interaction. Similarly, if the edit
window is one of the four combobox widgets supported by Tablelist or a
menubutton widget, and the value of the -autofinishediting
option is true, then
selecting a combobox or menu entry will automatically terminate the editing
session. Finally, if the value of the -editendonfocusout
option is true then
normal termination is also triggered when the tablelist widget loses the
focus.-editendcommand
configuration option is a nonempty string, then the edit window's final
text is passed to that command as its last argument (following the
tablelist's path name as well as the cell's row and column indices), the
resulting script is evaluated in the global scope, and the return value
becomes the cell's new internal content after destroying the temporary
embedded widget. The main goal of this script is to enable you to do
a final validation of the edit window's content. From within this
script you can invoke the rejectinput
subcommand, which prevents the
script's return value from becoming the cell's new content; this subcommand
also prevents the destruction of the temporary embedded widget.
Another purpose of the command indicated by the
-editendcommand
option is to convert the edit window's
text to the cell's new internal content, which is necessary if, due
to the -formatcommand
column configuration option, the cell's internal value is different from
its external representation. See the description of the
-forceeditendcommand
option for more about the invocation of the command mentioned above.-customdragsource
opton was set to true
or its body component was registered as a drag source for mouse button 1
via the tkdnd::drag_source register
or the
BWidget DragSite::register
command.tkdnd::drop_target
register
command. Similarly, you can register the
body component of a tablelist widget as a drop target for the drag & drop
framework included in BWidget, with the aid of the
DropSite::register
command. (Notice that for
BWidget it is necessary to register the tablelist's body rather than
the widget itself.)autoscrolltarget
subcommand, you can
make sure that when the mouse pointer leaves the area obtained by removing
a few pixels from the scrollable part of the tablelist's body on each side,
an automatic scrolling away from the mouse is started, which continues
until it gets canceled by the stopautoscroll
subcommand, or the mouse
pointer re-enters that area, or no more scrolling in that direction is
possible.$tbl
with the aid of the
showtargetmark
,
hidetargetmark
,
targetmarkpos
, and
targetmarkpath
subcommands.https://sourceforge.net/projects/tkdnd/files/
package require tkdnd 2.7 tkdnd::drop_target register $tbl DND_Text bind $tbl <<DropEnter>> { onTblDropEnterOrPos %W %e %X %Y %a %b } bind $tbl <<DropPosition>> { onTblDropEnterOrPos %W %e %X %Y %a %b } bind $tbl <<DropLeave>> { %W hidetargetmark } bind $tbl <<Drop>> { onTblDrop %W %A %D } proc onTblDropEnterOrPos {tbl event rootX rootY actions buttons} { # Scroll the target if the mouse is about to leave its scrollable part set x [expr {$rootX - [winfo rootx $tbl]}] set y [expr {$rootY - [winfo rooty $tbl]}] $tbl autoscrolltarget $event $x $y global place row foreach {place row} [$tbl targetmarkpos $y] {} if {some_optional_excluding_condition} { $tbl hidetargetmark return refuse_drop } else { $tbl showtargetmark $place $row return copy ;# for example } } proc onTblDrop {tbl action data} { # Cancel the automatic scrolling of the target $tbl stopautoscroll handleTblDrop $tbl $data return $action }
DropSite::*
commands used in
the following example are described in the "DropSite" reference page
included in the BWidget distribution. When using this drag & drop
framework, you will have to register not only the tablelist's body, but
also its target indicator as drop sites, to make sure that the target
mark won't get hidden by moving the mouse cursor over it with mouse
button 1 down:
package require BWidget foreach w [list [$tbl bodypath] [$tbl targetmarkpath]] { DropSite::register $w -dropovercmd tblDropOverCmd -dropcmd tblDropCmd \ -droptypes ... } proc tblDropOverCmd {dropTarget dragSrc event rootX rootY op dataType data} { # Scroll the target if the mouse is about to leave its scrollable part set tbl [tablelist::getTablelistPath $dropTarget] set x [expr {$rootX - [winfo rooty $tbl]}] set y [expr {$rootY - [winfo rooty $tbl]}] $tbl autoscrolltarget $event $x $y # $event may be "enter", "motion", or "leave" if {[string equal $event "leave"]} { set newWidget [winfo containing -displayof $dropTarget $rootX $rootY] if {![string equal $newWidget [$tbl targetmarkpath]] && ![string equal $newWidget [$tbl bodypath]]} { $tbl hidetargetmark return 2 ;# refuse the drop and re-invoke the callback on motion events } } global place row foreach {place row} [$tbl targetmarkpos $y] {} if {some_optional_excluding_condition} { $tbl hidetargetmark DropSite::setcursor dot return 2 ;# refuse the drop and re-invoke the callback on motion events } else { $tbl showtargetmark $place $row DropSite::setcursor based_arrow_down return 3 ;# accept the drop and re-invoke the callback on motion events } } proc tblDropCmd {dropTarget dragSrc rootX rootY op dataType data} { # Cancel the automatic scrolling of the target set tbl [tablelist::getTablelistPath $dropTarget] $tbl stopautoscroll handleTblDrop $tbl $data return 1 ;# accept the drop }
-horizontal
or -vertical
to the
targetmarkpos
invocation. When passing the -vertical
option,
you will have to extend the if
statement following
that subcommand invocation as follows:
if {$row < 0 || some_optional_excluding_condition} {
handleTblDrop
procedure,
implemented as follows:
proc handleTblDrop {tbl data} { $tbl hidetargetmark global place row if {[string equal $place "before"]} if {$row < [$tbl size]} { # Insert a sibling of the item indicated by $row, built from $data # (For a flat tablelist replace the following 2 lines with # "set key [$tbl insert $row ...]") set key [$tbl insertchild [$tbl parentkey $row] \ [$tbl childindex $row] ...] } else { # Append a top-level item built from $data # (For a flat tablelist replace the following line with # "set key [$tbl insert end ...]") set key [$tbl insertchild root end ...] } } else { ;# "inside" # Insert a child of the item indicated by $row, built from $data # Alternatively, update the item indicated by $row, using $data set key [$tbl insertchild $row end ...] $tbl expand $row -partly } . . . }
event
generate
command to send them to the tablelist widget in
question (whose path name will be the value of the %W
substitution in event scripts). When using Tk 8.5 or above, most of
these virtual events are generated with their -data
option set to an appropriate event-specific value. Binding scripts
can access this user data as the value of the %d
substitution. Unfortunately, the -data
option
to event generate
was not supported by Tk
versions earlier than 8.5. For these Tk versions, the
event generate
command will be invoked without
the -data
option.| Virtual Event | Description | User Data (for Tk 8.5 or Later) |
|---|---|---|
<<TablelistActivate>> |
Generated by the default bindings whenever the active row or cell changes in the tablelist widget due to user interaction. | Not used. |
<<TablelistCellRestored>> |
Generated by the cancelediting subcommand. |
A list consisting of the numerical row and column indices of the cell whose content is being edited. |
<<TablelistCellUpdated>> |
Generated by the finishediting subcommand if the
editing session has effectively changed the cell's content. |
A list consisting of the numerical row and column indices of the cell whose content is being edited. |
<<TablelistColHiddenStateChanged>> |
Generated whenever the hidden state of one or more columns is
toggled by using the columnconfigure , configcolumnlist ,
configcolumns , or
togglecolumnhide
subcommand. |
A list consisting of the numerical indices of the columns whose hidden state changed. |
<<TablelistColumnMoved>> |
Generated by the default bindings whenever a column is moved interactively to a new position. | A list of length 4, whose first two elements are identical to the
two arguments passed to the movecolumn subcommand invoked for moving
the source column to the target position, and the last two elements
are the corresponding column names, retrieved with the aid of
the columncget ...
-name subcommand. |
<<TablelistColumnResized>> |
Generated by the default bindings whenever a column is resized interactively. | The numerical index of the column that was resized. |
<<TablelistColumnSorted>> |
Generated by the tablelist::sortByColumn
command. |
A list consisting of the numerical column index and the sort
order (decreasing or
increasing ). |
<<TablelistColumnsSorted>> |
Generated by the tablelist::addToSortColumns
command. |
A list consisting of the two lists passed to the
sortbycolumnlist
subcommand, invoked to perform the multi-column sorting. |
<<TablelistHeaderHeightChanged>> |
Generated whenever the (requested) height of the tablelist's header changes. Used by the scrollarea widget of the Scrollutil package. | The (requested) height of the tablelist's header. |
<<TablelistRowHiddenStateChanged>> |
Generated whenever the hidden state of one or more rows is
toggled by using the rowconfigure , configrowlist , configrows , or togglerowhide subcommand. |
A list consisting of the numerical indices of the rows whose hidden state changed. |
<<TablelistRowMoved>> |
Generated by the default bindings whenever a row is moved interactively to a new position. | A list of length 3, whose elements are derived from the arguments
passed to the second form of the move subcommand invoked for moving the source
row to the target position. The first list element will be the
full key corresponding to the first argument, the second one will be
root or the full key corresponding to the second
argument, and the third list element will be identical to the third
argument passed to the move subcommand. |
<<TablelistSelect>> ,
<<ListboxSelect>> |
Generated by the default bindings whenever the selection changes in the tablelist widget due to user interaction. | Not used. |
<<TablelistSelectionLost>> |
Sent to the tablelist widget whenever it loses ownership of the PRIMARY selection. | Not used. |
<<TablelistTitleColsWidthChanged>> |
Generated whenever the total width of the non-hidden title columns changes. Used by the scrollarea widget of the Scrollutil package. | The total width of the non-hidden title columns. |
<<TablelistViewUpdated>> |
Generated whenever the tablelist widget has finished updating its view (which, for performance reasons, is performed at idle time). | Not used. |
<<TablelistThemeDefaultsChanged>>
and sends
it (without any user data) to the main window (!) after invoking the
tablelist::setThemeDefaults
command when handling the virtual events
<<ThemeChanged>>
,
<<LightAqua>>
, and
<<DarkAqua>>
. To handle it, use the
binding tag TablelistMain
, which is assigned by
Tablelist_tile to the main window.number |
Specifies the item as a numerical index, where 0
corresponds to the first item in the tablelist's body. |
knumber |
Specifies the item by its full key, composed of the prefix
k and the sequence number associated with the
item. You can use the getkeys widget command to get this sequence
number, or the getfullkeys widget command to retrieve
the full key. In addition, the insert , insertlist , insertchildren , and
insertchildlist
subcommands return the list of full keys associated with the items
just inserted. |
active |
Indicates the item containing the element that has the location
cursor. Depending on the selection type, this item as a whole
or just its element having the location cursor will be displayed
according to the value of the -activestyle configuration option when
the tablelist has the keyboard focus. This item is specified
with the activate widget
command or as the row containing the element specified with the
activatecell widget
command. |
anchor |
Indicates the anchor point for the row selection, which is set
with the selection
anchor widget command, or the row containing the
anchor point for the cell selection, which is set with the
cellselection
anchor widget command. |
end |
Indicates the end of the tablelist. For most commands this
refers to the last item in the tablelist, but for a few commands such
as index , insert , insertlist , and showtargetmark before , as well
as for the target of the move
command it refers to the item just after the last one. |
last |
Indicates the last item of the tablelist. |
top |
Indicates the topmost body item visible in the tablelist window. |
bottom |
Indicates the bottommost body item visible in the tablelist window. |
@x,y |
Indicates the body item that covers the point in the tablelist
window specified by x and y
(in pixel coordinates). If no item covers that point, then the
closest item to that point is used. The coordinates
x and y are expected to be
relative to the tablelist window itself (not its body
component). |
name |
Specifies the row by the value of its -name configuration option.
name must be different from all the above row
indices, and should be unique (if several rows have the same name
then this value is considered to indicate the first matching
row). |
index
, firstIndex
,
lastIndex
, sourceIndex
, and
targetIndex
always contain row indices in one of the
above forms.root
,
denoting the invisible root node of a tablelist used as a tree widget, or a
regular row index in one of the above forms, specifying a particular item
of the tablelist.nodeIndex
, parentNodeIndex
, and
targetParentNodeIndex
always contain node indices.number |
Specifies the column as a numerical index, where 0
corresponds to the first column in the tablelist. |
active |
Indicates the column containing the element that has the location
cursor. If the selection type is cell then
this element will be displayed according to the value of the
-activestyle
configuration option when the tablelist has the keyboard focus.
This element is specified with the activatecell widget command. |
anchor |
Indicates the column containing the anchor point for the cell
selection, which is set with the cellselection anchor widget
command. |
end |
Indicates the last column of the tablelist, except for the
commands insertcolumns and insertcolumnlist , as well as for
the target of the movecolumn command, in which cases it
refers to the column just after the last one. |
last |
Indicates the last column of the tablelist. |
left |
Indicates the leftmost column visible in the tablelist window. |
right |
Indicates the rightmost column visible in the tablelist window. |
@x,y |
Indicates the column that covers the point in the tablelist
window specified by x and y
(in pixel coordinates). If no column covers that point, then
the closest column to that point is used. The coordinates
x and y are expected to be
relative to the tablelist window itself (not its body
component). |
name |
Specifies the column by the value of its -name configuration option.
name must be different from all the above column
indices, and should be unique (if several columns have the same name
then this value is considered to indicate the first matching
column). |
columnIndex
, firstColumn
,
lastColumn
, sourceColumn
, and
targetColumn
always contain column indices in one of
the above forms.row,col |
Indicates the cell having the row index row
and column index col .
row may be a number, a full key (of the form
knumber ), active ,
anchor , end (where the latter
indicates the last row in the tablelist), last ,
top , bottom , or a row
name. col may be a number,
active , anchor ,
end , last ,
left , right , or a column
name. |
active |
Indicates the element that has the location cursor. If the
selection type is cell then this element will be
displayed according to the value of the -activestyle configuration option when
the tablelist has the keyboard focus. This element is specified
with the activatecell
widget command. |
anchor |
Indicates the anchor point for the cell selection, which is set
with the cellselection
anchor widget command. |
end |
Indicates the last cell in the last row of the tablelist. |
last |
Indicates the last cell in the last row of the tablelist (same as
end ). |
@x,y |
Indicates the body cell that covers the point in the tablelist
window specified by x and y
(in pixel coordinates). If no body cell covers that point, then
the closest body cell to that point is used. The coordinates
x and y are expected to be
relative to the tablelist window itself (not its body
component). |
cellIndex
, firstCell
, and
lastCell
always contain cell indices in one of the
above forms.header
tablelist widget command take one or more
header row indices as arguments. A header row index specifies a
particular item of the tablelist's header component, in any of the
following ways:number |
Specifies the header item as a numerical index, where
0 corresponds to the first item in the tablelist's
header. |
hknumber |
Specifies the header item by its full key, composed of the prefix
hk and the sequence number associated with the
item. You can use the header getkeys widget command to
get this sequence number, or the header getfullkeys widget
command to retrieve the full key. In addition, the
header insert
and header
insertlist subcommands return the list of full
keys associated with the header items just inserted. |
end |
Indicates the end of the tablelist's header. For most
commands this refers to the last item in the header component, but
for a few commands such as header
index , header
insert , and header insertlist it refers to
the header item just after the last one. |
last |
Indicates the last header item of the tablelist. |
@x,y |
Indicates the header item that covers the point in the tablelist
window specified by x and y
(in pixel coordinates). If no header item covers that point,
then the closest header item to that point is used. The
coordinates x and y are
expected to be relative to the tablelist window itself (not its
header component). |
name |
Specifies the header row by the value of its -name configuration option.
name must be different from all the above header
row indices, and should be unique (if several header rows have the
same name then this value is considered to indicate the first
matching header row). |
headerIndex
, firstHeaderIndex
, and
lastHeaderIndex
always contain header row indices in
one of the above forms.header
tablelist widget command take one or more
header cell indices as arguments. A header cell index specifies a
particular cell of the tablelist's header component, in any of the
following ways:headerRow,col |
Indicates the cell having the header row index
headerRow and column index
col . headerRow may be a
number, a full key (of the form hknumber ),
end (where the latter indicates the last header
row in the tablelist), last , or a header row
name. col may be a number,
active , anchor ,
end , last ,
left , right , or a column
name. |
end |
Indicates the last cell in the last row of the tablelist's header. |
last |
Indicates the last cell in the last row of the tablelist's header
(same as end ). |
@x,y |
Indicates the header cell that covers the point in the tablelist
window specified by x and y
(in pixel coordinates). If no header cell covers that point,
then the closest header cell to that point is used. The
coordinates x and y are
expected to be relative to the tablelist window itself (not its body
component). |
headerCellIndex
, firstHeaderCell
,
and lastHeaderCell
always contain header cell indices
in one of the above forms.tablelist::tablelist
command creates a new Tcl
command whose name is pathName
. This command
may be used to invoke various operations on the widget. It has the
following general form:
pathName option ?arg arg ...?
option
and the arg
s determine
the exact behavior of the command. The following commands are
possible for tablelist widgets:pathName activate
index
index
if the tablelist's state
is not
disabled
. If index
is
outside the range of items in the tablelist or it refers to a
non-viewable item then the closest viewable
item is activated. The active item is drawn as specified by the
-activestyle
configuration option when the widget has the input focus and the
selection type is row
. Its index may be
retrieved with the index active
. Returns an
empty string.pathName
activatecell cellIndex
cellIndex
if the tablelist's state
is not
disabled
. If cellIndex
is
outside the range of elements in the tablelist or it refers to a
non-viewable element, then the closest
viewable element is activated. The active element is drawn as
specified by the -activestyle
configuration option when
the widget has the input focus and the selection type is
cell
. Its index may be retrieved with the
cell index active
. Returns an empty
string.pathName
applysorting itemList
itemList
according to the
parameters of the most recent sort
, sortbycolumn
, or sortbycolumnlist
invocation and
returns a new list in sorted order. The
itemList
argument is supposed to be a well-formed
list of lists, where the length of each sublist is expected to be no
less than the number of columns of the tablelist widget. If the
items haven't been sorted at all, or the sort information was reset by
invoking resetsortinfo
, then no sorting takes
place and the return value will be identical to
itemList
.-expandcommand
configuration option,
for a tablelist row whose children have not yet been inserted into the
widget. The most efficient way to insert the child items in the
correct order is to add them to a list, sort this list via
applysorting
, and then insert the items of the
sorted list by invoking the insertchildlist
subcommand.pathName attrib
?name? ?value name value ...?
name
is specified, the command returns a list of
pairs, each of which contains the name and the value of an attribute
for pathName
. If name
is
specified with no value
, then the command returns
the value of the one named attribute, or an empty string if no
corresponding value exists (you can use the hasattrib
subcommand to distinguish this
case from the one that the value of an existing attribute is an
empty string). If one or more
name
-value
pairs are specified,
then the command sets the given widget attribute(s) to the given
value(s); in this case the return value is an empty string.
name
may be an arbitrary string.pathName
autoscrolltarget event x y
<<DropEnter>>
and
<<DropPosition>>
and its arguments are
as follows: event is the value of the %e
field, while x and y were obtained by transforming the
root coordinates given by the %X
and
%Y
fields to coordinates relative to the tablelist
window. In the second (BWidget) case it is assumed that the
command was invoked from within the command specified as the value of
the -dropovercmd
option of
DropSite::register
and its arguments are as
follows: event is the value of the 3rd argument passed to that
command, while x and y were obtained by transforming the
root coordinates passed to that commad as its 4th and 5th
arguments.stopautoscroll
subcommand, or the
mouse pointer re-enters that area, or no more scrolling in that
direction is possible. The scrollable part of the tablelist's
body is the body itself or the area to the right of the title columns
if the value of the -titlecolumns
option is positive.pathName bbox
index
index
. The first two elements of
the list give the x and y coordinates of the upper-left corner of the
screen area covered by the row (specified in pixels relative to the
widget) and the last two elements give the width and height of the
area, in pixels. If no part of the row given by
index
is visible on the screen, or if
index
refers to a non-existent row, then the result
is an empty string; if the row is partially visible, the result gives
the full area of the row, including any parts that are not
visible.pathName
bodypath
pathName
bodytag
TablelistBody
in the list of binding
tags of the tablelist descendants mentioned above, and is designed to
be used when defining individual binding scripts for tablelist
widgets. The main advantage of using this tag instead of the path
name of the tablelist's body is that it enables you to write event
handling scripts that are valid not only for the tablelist's body but
also for the separators, multi-line cells, and embedded images.$tbl
as a drag source for mouse button 1 in such a way
that the drag works also for the separators, multi-line cells, and
embedded images, you can proceed like in the following code
samples:package require tkdnd 2.7 bind [$tbl bodytag] <Button-1> { registerDragSrc %W } proc registerDragSrc w { # $w can be the tablelist's body, a separator, a message widget # displaying a multi-line element, or a label widget displaying an # image. Register this widget as a drag source for mouse button 1 tkdnd::drag_source register $w DND_Text 1 bind $w <<DragInitCmd>> { onTblDragInit %W } bind $w <<DragEndCmd>> { onTblDragEnd %W %A } } proc onTblDragInit w { set tbl [tablelist::getTablelistPath $w] . . . } proc onTblDragEnd {w action} { if {![string equal $action "refuse_drop"]} { ;# drop accepted set tbl [tablelist::getTablelistPath $w] . . . } } # Make sure to register the tablelist's body explicitly as a drag source: registerDragSrc [$tbl bodypath]
package require BWidget bind [$tbl bodytag] <Button-1> { registerDragSrc %W } proc registerDragSrc w { # $w can be the tablelist's body, a separator, a message widget # displaying a multi-line element, or a label widget displaying an # image. Register this widget as a drag source for mouse button 1 DragSite::register $w -dragevent 1 \ -draginitcmd tblDragInitCmd -dragendcmd tblDragEndCmd } proc tblDragInitCmd {dragSrc rootX rootY top} { set tbl [tablelist::getTablelistPath $dragSrc] . . . } proc tblDragEndCmd {dragSrc dropTarget op dataType data result} { if {$result != 0} { ;# drop accepted set tbl [tablelist::getTablelistPath $dragSrc] . . . } } # Make sure to register the tablelist's body explicitly as a drag source: registerDragSrc [$tbl bodypath]
registerDragSrc
explicitly for the tablelist's body,
because the widget registered as a drag source by its invocation on a
<Button-1>
event can be different from the body
component, and the default bindings need the information whether
the tablelist's body was registered as a drag source.pathName
canceledediting
1
if the most recent interactive
cell editing was canceled (by the user or programmatically, with the
aid of the cancelediting
subcommand) and
0
otherwise.-editendcommand
configuration option,
you can find out whether the editing session was canceled or terminated
normally. Remember that this Tcl command will be invoked in both
cases mentioned above if the -forceeditendcommand
option was
set to true.pathName
cancelediting
editcell
subcommand, destroys the temporary
widget embedded into the cell, and restores the original cell
content. This command enables you to cancel the interactive cell
editing from within the Tcl command specified by the -editstartcommand
configuration
option if that pre-edit callback encounters an error when preparing the
text to be inserted into the edit window. The command is also
invoked implicitly by pressing the Escape
key when a cell
is being edited. The return value is an empty string.
Before returning this value, the command restores the original value of
the tablelist widget's -exportselection
option and
generates the virtual event
<<TablelistCellRestored>>
. For Tk
versions 8.5 and higher, this virtual event is generated with its
-data
option set to a list consisting of the
numerical row and column indices of the cell whose content is being
edited. If no cell was being edited when the command was invoked
then an empty string is returned without generating a virtual
event.pathName cellattrib
cellIndex ?name? ?value name value
...?
cellIndex
. If no name
is
specified, the command returns a list of pairs, each of which contains
the name and the value of an attribute for the cell. If
name
is specified with no
value
, then the command returns the value of the
one named cell attribute, or an empty string if no corresponding value
exists (you can use the hascellattrib
subcommand to distinguish
this case from the one that the value of an existing cell
attribute is an empty string). If one or more
name
-value
pairs are specified,
then the command sets the given cell attribute(s) to the given
value(s); in this case the return value is an empty string.
name
may be an arbitrary string.pathName cellbbox
cellIndex
cellIndex
. The first two
elements of the list give the x and y coordinates of the upper-left
corner of the screen area covered by the cell (specified in pixels
relative to the widget) and the last two elements give the width and
height of the area, in pixels. If no part of the cell given by
cellIndex
is visible on the screen, or if
cellIndex
refers to a non-existent cell, then the
result is an empty string; if the cell is partially visible, the result
gives the full area of the cell, including any parts that are not
visible.pathName cellcget
cellIndex option
option
for the cell specified by
cellIndex
. option
may
have any of the values accepted by the cellconfigure
command.pathName
cellconfigure cellIndex ?option? value
option value ...?
cellIndex
. If no option
is specified, the command returns a list describing all of the
available options for the cell (see
Tk_ConfigureInfo
for information on the format of
this list). If option
is specified with no
value
, then the command returns a list describing
the one named option (this list will be identical to the corresponding
sublist of the value returned if no option
is
specified). If one or more
option
-value
pairs are
specified, then the command modifies the given cell option(s) to have
the given value(s); in this case the return value is an empty
string. option
may have any of the values
described in the CELL CONFIGURATION OPTIONS IN
THE TABLELIST BODY section.pathName cellindex
cellIndex
cellIndex
, in the form
row,col
, where
row
and col
are integers.pathName
cellselection option args
option
:pathName cellselection anchor
cellIndex
cellIndex
. If
cellIndex
refers to a nonexistent or
non-viewable element, then the closest
viewable element is used. The cell selection anchor is the
end of the cell selection that is fixed while dragging out a cell
selection with the mouse if the selection type is
cell
. The cell index
anchor
may be used to refer to the anchor
element.pathName cellselection clear
firstCell lastCell
pathName cellselection clear
cellIndexList
firstCell
and lastCell
(inclusive) or corresponding to
the cell indices specified by the list
cellIndexList
are selected, they are
deselected. The selection state is not changed for elements
outside the range given in the first form of the command or
different from those specified by the cell index list given in its
second form.pathName cellselection includes
cellIndex
1
if the element indicated by
cellIndex
is currently selected, 0
if it isn't.pathName cellselection set
firstCell lastCell
pathName cellselection set
cellIndexList
firstCell
and
lastCell
, inclusive, or corresponding to the
indices specified by the list cellIndexList
,
without affecting the selection state of any other elements.
An element is viewed as selectable if and only if the value of the
-selectable
option of
the row containing it is true.state
is disabled
and
option
is different from
includes
then the command just returns an empty
string, without performing any of the above actions.pathName cget
option
option
, which may have any of the values accepted
by the tablelist::tablelist
command.pathName childcount
nodeIndex
nodeIndex
. If this argument is specified as
root
then the return value will be the number of
top-level items of the tablelist widget.pathName childindex
index
index
in the list of children of its parent
node.pathName childkeys
nodeIndex
nodeIndex
. If this argument is
specified as root
then the return value will be the
list of full keys of the top-level items contained in the tablelist
widget.pathName collapse
indexList ?-fully|-partly?
-fully
(which is the default) indicates
that the command will be performed recursively, i.e., all of the
descendants of the nodes specified by indexList
will be collapsed, so that a subsequent invocation of the non-recursive
version of the expand(all)
subcommand will only display their children but no further descendants
of them. The -partly
option (which is used by
the default bindings) restricts the operation to just one hierarchy
level, implying that by a subsequent invocation of the non-recursive
version of the expand(all)
subcommand exactly the
same descendants will be displayed again that were visible prior to
collapsing the rows.-collapsecommand
option (if any) is
automatically concatenated with the path name of the tablelist widget
and the row index, and the resulting script is evaluated in the global
scope.-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.pathName
collapseall ?-fully|-partly?
-fully
(which is the default) indicates
that the command will be performed recursively, i.e., all of the
descendants of the top-level nodes will be collapsed, so that a
subsequent invocation of the non-recursive version of the
expandall
subcommand will
only display their children but no further descendants of them.
The -partly
option restricts the operation to just
one hierarchy level, implying that by a subsequent invocation of the
non-recursive version of the expandall
subcommand
exactly the same items will be displayed again that were visible prior
to collapsing the top-level ones.-collapsecommand
option (if any) is
automatically concatenated with the path name of the tablelist widget
and the row index, and the resulting script is evaluated in the global
scope.-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.pathName
columnattrib columnIndex ?name? ?value
name value ...?
columnIndex
. If no name
is specified, the command returns a list of pairs, each of which
contains the name and the value of an attribute for the column.
If name
is specified with no
value
, then the command returns the value of the
one named column attribute, or an empty string if no corresponding
value exists (you can use the hascolumnattrib
subcommand to
distinguish this case from the one that the value of an existing
column attribute is an empty string). If one or more
name
-value
pairs are specified,
then the command sets the given column attribute(s) to the given
value(s); in this case the return value is an empty string.
name
may be an arbitrary string.pathName columncget
columnIndex option
option
for the column specified by
columnIndex
. option
may
have any of the values accepted by the columnconfigure
command.pathName
columnconfigure columnIndex ?option? ?value
option value ...?
columnIndex
. If no
option
is specified, the command returns a list
describing all of the available options for the column (see
Tk_ConfigureInfo
for information on the format of
this list). If option
is specified with no
value
, then the command returns a list describing
the one named option (this list will be identical to the corresponding
sublist of the value returned if no option
is
specified). If one or more
option
-value
pairs are
specified, then the command modifies the given column option(s) to have
the given value(s); in this case the return value is an empty
string. option
may have any of the values
described in the COLUMN CONFIGURATION
OPTIONS section.pathName
columncount
pathName
columnindex columnIndex
columnIndex
.columnIndex
is end
then the return value is the numerical index
of the last column (not the number of columns). This behavior is
different from that of the index
subcommand, which (for compatibility with
the Tk core listbox) for the argument end
returns
the number of items (not the index of the last item).pathName
columnwidth columnIndex
?-requested|-stretched|-total?
columnIndex
. If the optional argument is
-requested
(which is the default) then the return
value is the number of pixels corresponding to the column width
specified by the -columns
widget or -width
column
configuration option (possibly overridden by interactive column
resizing); if the column width was specified as 0
(and was
not changed by interactive column resizing) then the return value is
the actual number of pixels corresponding to the widest viewable element of the column, including its
header. With the -stretched
option, the
command returns the column width obtained by increasing the value
described above by the number of additional pixels that might have been
added to the requested column width by a stretch operation (see the
-stretch
widget and
-stretchable
column
configuration options). Finally, if the optional argument is
-total
then the return value is the stretched
column width increased by the number of pixels corresponding to the
left and right margins within the column; this value equals the width
of the header label if the tablelist widget is mapped. Note that
the width of the left and right margins within the column equals the
width of the 0
character in the widget's font.pathName
configcelllist cellConfigSpecList
cellConfigSpecList
, the command modifies the
given option of the given cell to have the given value. The
argument cellConfigSpecList
must be a list of the
form
cellIndex option value cellIndex option value ...
option
may have any of the values
described in the CELL CONFIGURATION OPTIONS IN
THE TABLELIST BODY section. The return value is an empty
string.eval [list pathName configcells] cellConfigSpecList
pathName
configcells ?cellIndex option value
cellIndex option value ...?
cellIndex
, option
,
and value
, the command modifies the given option of
the given cell to have the given value. Each
option
may have any of the values described in the
CELL CONFIGURATION OPTIONS IN THE TABLELIST
BODY section. The return value is an empty string.pathName
configcolumnlist columnConfigSpecList
columnConfigSpecList
, the command modifies the
given option of the given column to have the given value. The
argument columnConfigSpecList
must be a list of
the form
columnIndex option value columnIndex option value ...
option
may have any of the values
described in the COLUMN CONFIGURATION
OPTIONS section. The return value is an empty string.eval [list pathName configcolumns] columnConfigSpecList
pathName
configcolumns ?columnIndex option value
columnIndex option value ...?
columnIndex
,
option
, and value
, the command
modifies the given option of the given column to have the given
value. Each option
may have any of the values
described in the COLUMN CONFIGURATION
OPTIONS section. The return value is an empty string.pathName
configrowlist rowConfigSpecList
rowConfigSpecList
, the command modifies the given
option of the given row to have the given value. The argument
rowConfigSpecList
must be a list of the form
index option value index option value ...
option
may have any of the values
described in the ROW CONFIGURATION OPTIONS IN
THE TABLELIST BODY section. The return value is an empty
string.eval [list pathName configrows] rowConfigSpecList
pathName configrows
?index option value index option
value ...?
index
, option
, and
value
, the command modifies the given option of the
given row to have the given value. Each
option
may have any of the values described in the
ROW CONFIGURATION OPTIONS IN THE TABLELIST
BODY section. The return value is an empty string.pathName configure
?option? ?value option value
...?
option
is specified, the command returns a
list describing all of the available options for
pathName
(see Tk_ConfigureInfo
for information on the format of this list). If
option
is specified with no
value
, then the command returns a list describing
the one named option (this list will be identical to the corresponding
sublist of the value returned if no option
is
specified). If one or more
option
-value
pairs are
specified, then the command modifies the given widget option(s) to have
the given value(s); in this case the return value is an empty
string. option
may have any of the values
accepted by the tablelist::tablelist
command.pathName containing
y
-1
. The coordinate y
is
expected to be relative to the tablelist window itself (not its body
component).pathName
containingcell x y
-1
. The coordinates x
and
y
are expected to be relative to the tablelist
window itself (not its body component).pathName
containingcolumn x
-1
. The coordinate x
is
expected to be relative to the tablelist window itself (not its body
component).pathName
cornerlabelpath
cornerpath
subcommand. When using
Tablelist_tile, the return value will be a ttk::label widget of the
same style as the header labels. The global visual options set
for the header labels are automatically applied to this (ttk::)label
widget, too.pathName
cornerpath ?-ne|-sw?
-ne
(which is the default) stands for
north-east and -sw
stands for south-west.-ne
then the command returns the path name of the
north-east corner frame, which is designed to be shown to the
right of the tablelist widget's top-right corner when managing the
vertical scrollbar on Mac OS X/11+ or X11 (see Remark 1 below).
This corner frame contains a label or ttk::label widget, depending on
whether the package Tablelist or Tablelist_tile is being used (see the
cornerlabelpath
subcommand). The height of this corner frame is automatically
kept in sync with that of the tablelist's header component, and the
height of the above-mentioned (ttk::)label widget is automatically kept
in sync with that of the header labels. Whenever the (requested)
height of the tablelist's header (and thus that of the north-east
corner frame) changes, the
<<TablelistHeaderHeightChanged>>
virtual event is generated, with its -data
option
set to the (requested) height of the header for Tk versions 8.5 and
higher.-sw
then the return value is the path name of the south-west corner
frame, which is designed to be shown just below the tablelist's
lower-left corner when managing the horizontal scrollbar if the value
of the -titlecolumns
option is positive (see Remark 2 below). The width of this corner
frame is automatically kept in sync with the total width of the
non-hidden title columns. When using Tablelist_tile, the
south-west corner frame will be a ttk::frame widget.labels.
Whenever the total width of the non-hidden title columns (and thus the
requested width of the south-west corner frame) changes, the
<<TablelistTitleColsWidthChanged>>
virtual event is generated, with its -data
option
set to the total width of the non-hidden title columns for Tk versions
8.5 and higher.# Add some entries to the Tk option database option add *ScrollArea.borderWidth 1 option add *ScrollArea.relief sunken option add *ScrollArea.Tablelist.borderWidth 0 option add *ScrollArea.Tablelist.highlightThickness 0 . . . # Create the tablelist and the scrollbars as # children of a frame of the class ScrollArea set frm [(ttk::)frame ... -class ScrollArea] set tbl $frm.tbl set vsb $frm.vsb set hsb $frm.hsb tablelist::tablelist $tbl ... \ -xscrollcommand [list $hsb set] -yscrollcommand [list $vsb set] (ttk::)scrollbar $vsb -orient vertical -command [list $tbl yview] (ttk::)scrollbar $hsb -orient horizontal -command [list $tbl xview] . . . # Manage the widgets within the frame grid $tbl -row 0 -rowspan 2 -column 0 -sticky news if {[string compare [tk windowingsystem] "win32"] == 0} { grid $vsb -row 0 -rowspan 2 -column 1 -sticky ns } else { grid [$tbl cornerpath] -row 0 -column 1 -sticky ew grid $vsb -row 1 -column 1 -sticky ns } grid $hsb -row 2 -column 0 -sticky ew grid rowconfigure $frm 1 -weight 1 grid columnconfigure $frm 0 -weight 1 # Manage the frame pack $frm -expand yes -fill both -padx 10 -pady 10
-titlecolumns
option
is positive. In the above example, this can be achieved by
modifying its second half as follows:
. . . # Manage the widgets within the frame grid $tbl -row 0 -rowspan 2 -column 0 -columnspan 2 -sticky news if {[string compare [tk windowingsystem] "win32"] == 0} { grid $vsb -row 0 -rowspan 2 -column 2 -sticky ns } else { grid [$tbl cornerpath] -row 0 -column 2 -sticky ew grid $vsb -row 1 -column 2 -sticky ns } grid [$tbl cornerpath -sw] -row 2 -column 0 -sticky ns grid $hsb -row 2 -column 1 -sticky ew grid rowconfigure $frm 1 -weight 1 grid columnconfigure $frm 1 -weight 1 # Manage the frame pack $frm -expand yes -fill both -padx 10 -pady 10For a tablelist widget having two header rows and one title column, the scrollbars of the modified example will appear like in the screenshot below (on Windows this is only valid for the horizontal scrollbar):
package require scrollutil(_tile) . . . # Create the tablelist within a scrollarea set sa [scrollutil::scrollarea ...] set tbl $sa.tbl tablelist::tablelist $tbl ... $sa setwidget $tbl . . . # Manage the scrollarea pack $sa -expand yes -fill both -padx 10 -pady 10
pathName curcellselection
?-all|-nonhidden|-viewable?
row,col
, where row
and
col
are numbers) of all of the elements in the
tablelist that are currently selected. If there are no such
elements in the tablelist then an empty string is returned.-all
means: no restriction. The
value -nonhidden
filters out the elements whose row
or column has its -hide
option set to true.
Finally, the value -viewable
restricts the set of
currently selected elements to the viewable
ones.pathName
curselection
?-all|-nonhidden|-viewable?
-all
means: no restriction.
The value -nonhidden
filters out the items whose
row has its -hide
option
set to true. Finally, the value -viewable
restricts the set of currently (partly) selected items to the viewable ones.pathName delete
firstIndex lastIndex
pathName delete indexList
state
is not
disabled
. In the first form of the command,
firstIndex
and lastIndex
are
indices specifying the first and last items in the range to
delete. The command's second form accepts a list
indexList
of indices specifying the items to be
deleted. In both cases, all descendants of the specified items
will be deleted, too. The return value is an empty string.pathName delete 0
end
returns imediately without raising an error,
although in this case both indices are invalid.pathName
deletecolumns firstColumn lastColumn
pathName deletecolumns
columnIndexList
state
is not
disabled
. In the first form of the command,
firstColumn
and lastColumn
are
indices specifying the first and last columns in the range to
delete. The command's second form accepts a list
columnIndexList
of indices specifying the columns
to be deleted. Returns an empty string.pathName
deletecolumns 0 end
returns imediately
without raising an error, although in this case both column indices are
invalid.pathName depth
nodeIndex
nodeIndex
to the root
node. The latter's depth is 0, that of the top-level rows is 1,
and so on.pathName
descendantcount nodeIndex
nodeIndex
. If this argument is specified as
root
then the return value will be the number of
items of the tablelist widget.pathName dicttoitem
dictionary
dictionary
. The values corresponding to
those keys in the specified dictionary that are valid column indices in
any of the forms described in the COLUMN
INDICES section, will be interpreted as the elements of the
resulting tablelist item. The keys that are no valid column
indices, are silently ignored. If the number of distinct
numerical equivalents of the keys that are valid column indices (see
the columnindex
subcommand) is less than the number of columns, then the elements
corresponding to the missing column indices will be set to empty
strings.-name forename
and
-name surname
,
respectively, and you pass the dictionary {forename
Joe surname Black}
to the
dicttoitem
subcommand, then the return value will
be the list {Joe Black {}}
. If the user swaps
the first two columns then, for the same dictionary, the subcommand
will return the list {Black Joe {}}
.dict
command, which is the case when using Tcl
version 8.5 or later, or one of the alternative, Tcl-only dict
implementations.pathName dumptofile
fileName
fileName
. Before writing the data to the
file, the subcommand expands all rows of the tablelist by
invoking expandall
-fully
. You can later load the file's content with the
aid of the loadfromfile
subcommand.expandall
subcommand can take quite a long time
(several seconds or even minutes), it is recommended to enclose the
invocation of dumptofile
between setbusycursor
and restorecursor
.pathName
dumptostring
expandall
-fully
. You can later load the return string with the
aid of the loadfromstring
subcommand.expandall
subcommand can take quite a long time
(several seconds or even minutes), it is recommended to enclose the
invocation of dumptostring
between
setbusycursor
and
restorecursor
.pathName editcell
cellIndex
state
is not
disabled
and the cell is viewable and editable. Returns an empty
string. Before returning this value, the command sets the
tablelist widget's -exportselection
option to
0
, thus making sure that the widget won't lose the
selection while the cell's content is being edited. (Note that on
termination of the editing session, the option's original value will be
restored.) See the INTERACTIVE CELL
EDITING section for details on editablity and on the editing
process.pathName
editinfo
knumber
) associated with the item containing
the tablelist element that is being edited. The second and third
elements are the cell's row and column indices. If currently no
cell is being edited then the return value is the list {""
-1 -1}
.pathName
editwinpath
editcell
subcommand. If no cell is
currently being edited then the return value is an empty string.
This subcommand enables you to access the edit window from within the
commands specified by the -editstartcommand
and
-editendcommand
configuration options.pathName
editwintag
entrypath
subcommand). This binding tag precedes the tag TablelistEdit
in the list of binding
tags of the edit window components mentioned above, and is designed to
be used when defining individual binding scripts for controlling the
interactive cell editing.Return
key during cell editing in the tablelist
widget .tbl
with that of the Tab
key:
bind [.tbl editwintag] <Return> "[bind TablelistEdit <Tab>]; break"
-window
option of the cell indicated by cellIndex
to a
procedure that creates a frame with a checkbutton child having its
-variable
option set to a global variable whose
name is private to Tablelist and is initialized with the cell's
internal value (which should be the boolean 0
or
1
). Any change in the checkbutton's check state will
automatically set the cell's internal value to the corresponding
boolean value 0
or 1
. If the optional
command
argument is a nonempty string then the
checkbutton's -command
option will be set to a
script that concatenates this argument with the path name of the
tablelist widget and the cell's current row and column indices (which
can be different from the ones at the checkbutton's creation time) and
then invokes the resulting script at idle time, thus making sure that
at the time of its invocation the cell's internal value will already be
updated to reflect the checkbutton's check state.windowpath
subcommand
will return the path name of the embedded window, which is a frame; to
get the checkbutton's path name, append .ckbtn
to
the frame's one.cget -variable
, and set this variable to the
cell's internal value.pathName
embedcheckbuttons columnIndex
?command?
embedcheckbutton
for all body cells
of the column specified by columnIndex
.pathName
embedttkcheckbutton cellIndex
?command?
embedcheckbutton
, with the only
difference that the frame embedded into the cell will contain a
ttk::checkbutton child.pathName
embedttkcheckbuttons columnIndex
?command?
embedttkcheckbutton
for all body
cells of the column specified by columnIndex
.pathName
entrypath
editcell
subcommand. If no cell is currently being edited or the editing
is taking place with the aid of a Tk or tile checkbutton, Tk or tile
menubutton, or mentry widget, then the return value is an empty string;
otherwise it is the path name of a Tk or tile entry, text or ctext, Tk
or tile spinbox, or BWidget Entry widget, which can be the edit window
itself or one of its descendants. This subcommand enables you to
access the entry or entry-like component of the temporary embedded
widget from within the commands specified by the -editstartcommand
and
-editendcommand
configuration options.pathName expand
indexList ?-fully|-partly?
-fully
(which is the default) indicates
that the command will be performed recursively, i.e., all of the
descendants of the nodes specified by indexList
will be displayed. The -partly
option (which
is used by the default bindings) restricts the operation to just one
hierarchy level, indicating that only the children of the specified
nodes will be displayed, without changing the expanded/collapsed state
of the child nodes.-expandcommand
option (if any) is
automatically concatenated with the path name of the tablelist widget
and the row index, and the resulting script is evaluated in the global
scope. This enables you to insert a tree node's children on
demand, just before expanding it.-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.pathName expandall
?-fully|-partly?
-fully
(which is the default) indicates
that the command will be performed recursively, i.e., all of the
descendants of the top-level nodes will be displayed. The
-partly
option restricts the operation to just one
hierarchy level, indicating that only the children of the top-level
nodes will be displayed, without changing the expanded/collapsed state
of the child nodes.-expandcommand
option (if any) is
automatically concatenated with the path name of the tablelist widget
and the row index, and the resulting script is evaluated in the global
scope. This enables you to insert a tree node's children on
demand, just before expanding it.-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.pathName
expandedkeys
pathName fillcolumn
columnIndex ?-text|-image|-window?
value
cellconfigure
subcommand for all body cells of the specified column, with
-text
(the default), -image
, or
-window
, as well as value
as
arguments.pathName
findcolumnname name
-name
column configuration
option) equals name
. If no column has the
specified name then the return value is -1
.pathName
findrowname name ?-descend? ?-parent
nodeIndex?
nodeIndex
whose name (given by the
-name
row configuration
option) equals name
. The
-descend
option extends the search to all
descendants of the tree node given by the -parent
option. The default is to restrict the search to the parent
node's children only. The default parent is
root
. When searching for the given name, the
items will be visited in the order of their row indices. If none
of the relevant rows has the specified name then the return value is
-1
.pathName
finishediting
editcell
subcommand by destroying the
temporary widget embedded into the cell and updating the cell's
content. The exact steps involved are as follows: First,
the widget's final text is compared to its original one. If they
are equal then the edit window is destroyed and the cell's original
content is restored. If the two strings are different and the
value of the -editendcommand
configuration option
is a nonempty string, then the widget's final text is passed to that
command as its last argument (following the tablelist's path name as
well as the cell's row and column indices), the resulting script is
evaluated in the global scope, and the return value becomes the cell's
new content after destroying the edit window. However, if from
within this script the rejectinput
subcommand was invoked then
the cell's value is not changed and the embedded widget remains
displayed in the cell; in this case the command returns the boolean
value 0
. In all the other cases, the return value is
1
. Before returning the value 1
, the
command restores the original value of the tablelist widget's
-exportselection
option, and generates the virtual
event <<TablelistCellUpdated>>
if the
editing session has effectively changed the cell's content. For
Tk versions 8.5 and higher, this virtual event is generated with its
-data
option set to a list consisting of the
numerical row and column indices of the cell whose content is being
edited. If no cell was being edited when the command was invoked
then the same value 1
is returned but no virtual event is
generated. Likewise, if the widget's state is
disabled
then the subcommand returns the value
1
immediately, without terminating the editing and
generating any virtual event.Return
or KP_Enter
(together with
Control
if the edit window is a text or ctext widget) when
editing a cell, or by clicking with the left mouse button anywhere in
the tablelist's body, outside the cell just being edited, or moving
into another editable cell by using keyboard navigation. If the
editing was started with the left mouse button, the edit window is a Tk
or tile checkbutton, and the value of the -instanttoggle
option is true, then
this subcommand will be invoked automatically, without any user
interaction. Similarly, if the edit window is one of the four
combobox widgets supported by Tablelist or a menubutton widget, and the
value of the -autofinishediting
option is true,
then selecting a combobox or menu entry will automatically invoke this
subcommand and thus terminate the editing session. Finally, if
the value of the -editendonfocusout
option is true
then this subcommand will also be invoked automatically when the
tablelist widget loses the focus.-editendonfocusout
option was set
to true).pathName
formatinfo
-formatcommand
column configuration
option. It returns a three-element list containing information
about the body or header cell whose content is being formatted with the
aid of that command. The first element of the list is the full
key (of the form knumber
or
hknumber
) associated with the body or header
item containing the tablelist element that is being formatted.
The second and third list elements are the cell's row (or header row)
and column indices.-formatcommand
column configuration option
as [list formatCommand
pathName]
, like in the following example:
.tbl columnconfigure 1 -formatcommand [list formatValue .tbl] proc formatValue {tbl val} { # Get information about the cell whose content is being formatted foreach {key row col} [$tbl formatinfo] {} # Return a string depending on $val and $row (or $key) . . . }
pathName get firstIndex
lastIndex
?-all|-nonhidden|-viewable?
pathName get indexList
firstIndex
and lastIndex
,
inclusive. The optional argument can be used to restrict the
items when building the result list. The default value
-all
means: no restriction. The value
-nonhidden
filters out the items whose row has its
-hide
option set to
true. Finally, the value -viewable
restricts
the items to the viewable ones.indexList
: if the
latter contains exactly one index then the return value is the
tablelist item indicated by that index (or an empty string if the index
refers to a non-existent item); otherwise the command returns the list
of all of the tablelist items corresponding to the indices specified by
indexList
.pathName getcells
firstCell lastCell
?-all|-nonhidden|-viewable?
pathName getcells cellIndexList
firstCell
and lastCell
,
inclusive. The optional argument can be used to restrict the
elements when building the result list. The default value
-all
means: no restriction. The value
-nonhidden
filters out the elements whose row or
column has its -hide
option set to true.
Finally, the value -viewable
restricts the elements
to the viewable ones.cellIndexList
: if
the latter contains exactly one cell index then the return value is the
tablelist element indicated by that cell index; otherwise the command
returns the list of all of the tablelist elements corresponding to the
cell indices specified by cellIndexList
.pathName getcolumns
firstColumn lastColumn
pathName getcolumns
columnIndexList
firstColumn
and
lastColumn
, inclusive, and consists of all of the
tablelist body elements contained in that column. The value
returned by the second form depends on the number of elements in the
list columnIndexList
: if the latter contains
exactly one column index then the return value is a list consisting of
all of the tablelist body elements contained in the column indicated by
that column index; otherwise the command returns a list whose elements
are lists themselves, where each of the sublists corresponds to exactly
one column index in columnIndexList
and consists of
all of the tablelist body elements contained in that column.pathName
getformatted firstIndex lastIndex
?-all|-nonhidden|-viewable?
pathName getformatted indexList
firstIndex
and
lastIndex
, inclusive. The optional argument
can be used to restrict the items when building the result list.
The default value -all
means: no restriction.
The value -nonhidden
filters out the items whose
row has its -hide
option
set to true. Finally, the value -viewable
restricts the items to the viewable
ones.indexList
: if the
latter contains exactly one index then the return value is the
formatted tablelist item indicated by that index (or an empty string if
the index refers to a non-existent item); otherwise the command returns
the list of all of the formatted tablelist items corresponding to the
indices specified by indexList
.pathName
getformattedcells firstCell lastCell
?-all|-nonhidden|-viewable?
pathName getformattedcells
cellIndexList
firstCell
and
lastCell
, inclusive. The optional argument
can be used to restrict the elements when building the result
list. The default value -all
means: no
restriction. The value -nonhidden
filters out
the elements whose row or column has its -hide
option set to true. Finally, the value
-viewable
restricts the elements to the viewable ones.cellIndexList
: if
the latter contains exactly one cell index then the return value is the
formatted tablelist element indicated by that cell index; otherwise the
command returns the list of all of the formatted tablelist elements
corresponding to the cell indices specified by
cellIndexList
.pathName
getformattedcolumns firstColumn
lastColumn
pathName getformattedcolumns
columnIndexList
firstColumn
and
lastColumn
, inclusive, and consists of all of the
formatted tablelist body elements
contained in that column. The value returned by the second form
depends on the number of elements in the list
columnIndexList
: if the latter contains exactly one
column index then the return value is a list consisting of all of the
formatted tablelist body elements contained in the column indicated by
that column index; otherwise the command returns a list whose elements
are lists themselves, where each of the sublists corresponds to exactly
one column index in columnIndexList
and consists of
all of the formatted tablelist body elements contained in that
column.pathName
getfullkeys firstIndex lastIndex
?-all|-nonhidden|-viewable?
pathName getfullkeys indexList
firstIndex
and lastIndex
,
inclusive. The optional argument can be used to restrict the
items when building the result list. The default value
-all
means: no restriction. The value
-nonhidden
filters out the items whose row has its
-hide
option set to
true. Finally, the value -viewable
restricts
the items to the viewable ones.indexList
: if the
latter contains exactly one index then the return value is the full key
associated with the tablelist item indicated by that index (or an empty
string if the index refers to a non-existent item); otherwise the
command returns the list of all of the full keys associated with the
tablelist items corresponding to the indices specified by
indexList
.k
to these internal item IDs.pathName getkeys
firstIndex lastIndex
?-all|-nonhidden|-viewable?
pathName getkeys indexList
firstIndex
and lastIndex
,
inclusive. The optional argument can be used to restrict the
items when building the result list. The default value
-all
means: no restriction. The value
-nonhidden
filters out the items whose row has its
-hide
option set to
true. Finally, the value -viewable
restricts
the items to the viewable ones.indexList
: if the
latter contains exactly one index then the return value is the sequence
number associated with the tablelist item indicated by that index (or
an empty string if the index refers to a non-existent item); otherwise
the command returns the list of all of the sequence numbers associated
with the tablelist items corresponding to the indices specified by
indexList
.pathName hasattrib
name
1
if the attribute name
exists and 0
otherwise.pathName
hascellattrib cellIndex name
1
if the attribute name
for the cell given by cellIndex
exists and
0
otherwise.pathName
hascolumnattrib columnIndex name
1
if the attribute name
for the column given by columnIndex
exists and
0
otherwise.pathName
hasrowattrib index name
1
if the attribute name
for the row given by index
exists and
0
otherwise.pathName header
option ?arg arg ...?
pathName
headerpath
pathName
headertag
TablelistHeader
in the list of binding tags of the tablelist descendants mentioned
above, and is designed to be used when defining individual binding
scripts for tablelist widgets. The main advantage of using this
tag instead of the path name of the text widget containing the header
items is that it enables you to write event handling scripts that are
valid not only for the above-mentioned text widget but also for the
multi-line cells and embedded images contained in it.pathName
hidetargetmark
showtargetmark
command. No error is generated if the target indicator is not
visible at the time the command is invoked.pathName
imagelabelpath cellIndex
cellIndex
, as
specified with the -image
option of the cellconfigure
subcommand. If no
image is currently embedded into the cell then the return value is an
empty string.bind [.tbl bodytag] <Button-1> {printClickedImage %W %x %y}
proc printClickedImage {w x y} { foreach {tbl x y} [tablelist::convEventFields $w $x $y] {} set cellIdx [$tbl containingcell $x $y] scan $cellIdx "%d,%d" row col if {$row >= 0 && $col >= 0 && [string compare $w [$tbl imagelabelpath $cellIdx]] == 0} { puts "clicked the image of cell $cellIdx" } }
pathName index
index
index
. For compatibility with the Tk core
listbox, if index
is end
then
the return value is the number of items in the tablelist (not the index
of the last item). To get the numerical index of the last item,
you can pass the word last
as
index
argument.pathName insert
index ?item item ...?
index
if the tablelist's
state
is not
disabled
. If index
equals
the number of items or is specified as end
then the
new items are added to the end of the widget's list. Tabulator
characters are displayed as \t
(i.e., a backslash followed
by a t
) but are inserted unchanged into the internal
list. Newline characters will force line breaks, i.e., will give
rise to multi-line elements (which are displayed in embedded message
widgets, created on demand). The return value is the list of full
keys associated with the items just inserted.insertchildren
or insertchildlist
subcommand.pathName
insertchildlist parentNodeIndex childIndex
itemList
itemList
in the
widget's internal list of children of the node specified by
parentNodeIndex
just before the item given by
childIndex
if the tablelist's state
is not
disabled
. childIndex
must
be a number, last
(specifying the parent's last
child), or end
; if it equals the number of children
of the node given by parentNodeIndex
or is
specified as end
then the new items are added to
the end of the parent's list of children. Tabulator characters
are displayed as \t
(i.e., a backslash followed by a
t
) but are inserted unchanged into the internal
list. Newline characters will force line breaks, i.e., will give
rise to multi-line elements (which are displayed in embedded message
widgets, created on demand). The return value is the list of full
keys associated with the items just inserted.eval [list pathName insertchildren parentNodeIndex childIndex] itemList
-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.insertchildren
.pathName
insertchildren parentNodeIndex childIndex
?item item ...?
parentNodeIndex
just before the item given by childIndex
if the
tablelist's state
is not
disabled
. childIndex
must
be a number, last
(specifying the parent's last
child), or end
; if it equals the number of children
of the node given by parentNodeIndex
or is
specified as end
then the new items are added to
the end of the parent's list of children. Tabulator characters
are displayed as \t
(i.e., a backslash followed by a
t
) but are inserted unchanged into the internal
list. Newline characters will force line breaks, i.e., will give
rise to multi-line elements (which are displayed in embedded message
widgets, created on demand). The return value is the list of full
keys associated with the items just inserted.-elide
text widget tag option for collapsing a
row), this subcommand is not supported for Tk versions earlier than
8.3.insertchildren
as
insertchild
. This comes in handy when using
this subcommand to insert just one child item.pathName
insertcolumnlist columnIndex
columnList
columnList
just before the column given by
columnIndex
if the tablelist's state
is not
disabled
. If columnIndex
equals the number of columns or is specified as end
then the new columns are added to the end of the column list. The
argument columnList
must be a list containing the
width, title, and optional alignment specifications for the new
columns, in the same form as in the case of the -columns
configuration option. The
return value is an empty string. The elements of the new columns
are initially empty strings; the easiest way to change these values is
to use the fillcolumn
subcommand or the -text
column configuration option.eval [list pathName insertcolumns columnIndex] columnList
pathName
insertcolumns columnIndex ?width title
?alignment? width title ?alignment?
...?
columnIndex
if the tablelist's state
is not
disabled
. If columnIndex
equals the number of columns or is specified as end
then the new columns are added to the end of the column list. The
arguments following the column index have the same meanings as in the
case of the -columns
configuration option. The return value is an empty string.
The elements of the new columns are initially empty strings; the
easiest way to change these values is to use the fillcolumn
subcommand or the
-text
column configuration
option.pathName insertlist
index itemList
itemList
in the
widget's internal list just before the item given by
index
if the tablelist's state
is not
disabled
. If index
equals
the number of items or is specified as end
then the
new items are added to the end of the widget's list. Tabulator
characters are displayed as \t
(i.e., a backslash followed
by a t
) but are inserted unchanged into the internal
list. Newline characters will force line breaks, i.e., will give
rise to multi-line elements (which are displayed in embedded message
widgets, created on demand). The return value is the list of full
keys associated with the items just inserted.eval [list pathName insert index] itemList
insert
.insertchildlist
or insertchildren
subcommand.pathName
iselemsnipped cellIndex fullTextName
1
if the text displayed in the cell
specified by cellIndex
is snipped and
0
otherwise. In both cases, the full (unsnipped)
cell text is stored in the variable having the name given by
fullTextName
; this full text can be the cell's
content or the string obtained from the latter by using the
-formatcommand
option of the cell's column. The most common invocation of this
command occurs within the procedure specified as the value of the
-tooltipaddcommand
configuration option.pathName isexpanded
index
1
if the row indicated by
index
is expanded and 0
otherwise.pathName
istitlesnipped columnIndex
fullTextName
1
if the text displayed in the
header label specified by columnIndex
is snipped
and 0
otherwise. In both cases, the full (unsnipped)
label text is stored in the variable having the name given by
fullTextName
. The most common invocation of
this command occurs within the procedure specified as the value of the
-tooltipaddcommand
configuration option.pathName isviewable
index
1
if the row indicated by
index
is viewable and 0
otherwise. A tablelist row is called viewable if the value of its
-hide
option is false and
all its ancestors are (partly) expanded. Likewise, a tablelist
cell is called viewable if its row is viewable and the value of its
column's -hide
option is
false.pathName
itemlistvar
upvar
command, like in the following example:
upvar #0 [.tbl itemlistvar] itemList
itemList
will be the internal list associated with the body of the tablelist
widget .tbl
. Each element of the list corresponds to
one item, and it is in turn a list whose elements correspond to the
elements of that item, except that it has one additional element,
holding the item's full key.itemlistvar
command provides an efficient way for accessing this internal list,
instead of retrieving the items with the get
subcommand or using the -listvariable
option (these methods
consume significantly more memory). It can be useful in
situations where the elements of a tablelist widget are to be accessed
for creating text files, HTML output, XML data, database commands,
etc. This should, however, be a strictly readonly access;
otherwise the results will be unpredictable!pathName itemtodict
item ?excludedColumnIndexList?
item
. The optional argument
excludedColumnIndexList
(which must be a valid
list) specifies those column indices (in any of the forms described in
the COLUMN INDICES section) that are to be
ignored when building the dictionary. The dictionary's keys will
be column numbers or names, and the values will be the corresponding
elements of the given item. For each column number
col
, if the corresponding column name (returned
by pathName columncget col -name
)
is a nonempty string then this name will be used as dictionary key,
otherwise the numerical column index col
. In
both cases, if the optional argument
excludedColumnIndexList
contains a column index
whose numerical equivalent (returned by the columnindex
subcommand) equals
col
, then this column will be silently ignored,
i.e., the mapping from the key to the corresponding tablelist element
will not be inserted into the dictionary.-name forename
and
-name surname
,
respectively, and you pass the item
{Joe Black "Young Man in Coffee Shop"}
itemtodict
subcommand, then the return
value will be the dictionary
{forename Joe surname Black 2 {Young Man in Coffee Shop}}
{2}
, or {end}
,
or {last}
as additional argument to the
itemtodict
subcommand, then the return value will
be the dictionary
{forename Joe surname Black}
dict
command, which is the case when using Tcl
version 8.5 or later, or one of the alternative, Tcl-only dict
implementations.pathName labelpath
columnIndex
columnIndex
.pathName
labels
pathName
labeltag
tablelist::getTablelistColumn
and tablelist::getTablelistPath
.pathName
labelwindowpath columnIndex
-labelwindow
column configuration
option. If that option was not set or was set to an empty string
then the return value will be an empty string.pathName
loadfromfile fileName
?-fully|-partly?
fileName
. This
file must have have been created with the aid of the dumptofile
subcommand.lsearch
options), this subcommand is not supported
for Tk versions earlier than 8.4.header
insertlist
and then examines the body items
contained in the file. If all of them were direct children of the
original (source) tablelist's root
node, then the
subcommand inserts them as top-level items via insertlist
. Otherwise:-partly
(which is the default), then the
subcommand inserts those body items that in the original tablelist
were direct children of the root
node as
top-level items, via insertchildlist
, and sets the
widget's -populatecommand
and
-expandcommand
options to ::tablelist::populateCmd
and
::tablelist::expandCmd
, respectively, thus making sure
that the items can later be expanded both programmatically and
interactively. These procedures, which are implemented in the
Tablelist distribution file tablelistWidget.tcl
,
make use of documented tablelist subcommands only and are richly
commented. They work as expected regardless of whether the
current sort column(s) and/or sort order(s) are still the same as
the ones retrieved from the file. On the other hand, the
number and position of the columns must remain unchanged (to this
end, the subcommand also sets the widget's -movablecolumns
option to
0
).-fully
, then the subcommand inserts all the
body items under the corresponding parent nodes via
insertchild
, and
after that it collapses all rows of the tablelist by invoking
collapseall
-fully
.-partly
option is the recommended way to
use it, being that it inserts the top-level items only, which makes the
widget much more responsive than one having all its items effectively
inserted.loadfromfile
with the -fully
option between setbusycursor
and restorecursor
.pathName
loadfromstring string
?-fully|-partly?
string
, which must have have been returned
by the dumptostring
subcommand.lsearch
options), this subcommand is not supported
for Tk versions earlier than 8.4.loadfromfile
subcommand (just replace
"file" with "string" where appropriate).pathName move
sourceIndex targetIndex
pathName move sourceIndex
targetParentNodeIndex targetChildIndex
sourceIndex
just before the one given by
targetIndex
if the tablelist's state
is not
disabled
. If targetIndex
equals the number of items or is specified as end
then the source item is moved after the last one. The item
specified by targetIndex
must have the same parent
as the one given by sourceIndex
, or else it must be
the item just below the last descendant of the source node's
parent.sourceIndex
just before the node having the parent
indicated by targetParentNodeIndex
and the index
targetChildIndex
in the parent's list of children
if the tablelist's state
is
not disabled
.
targetChildIndex
must be a number,
last
(specifying the target parent's last child),
or end
; if it equals the number of children of the
target parent node or is specified as end
then the
source item is moved after the target parent node's last child.pathName movecolumn
sourceColumn targetColumn
sourceColumn
just
before the one given by targetColumn
if the
tablelist's state
is not
disabled
. If targetColumn
equals the number of columns or is specified as end
then the source column is moved after the last one. Returns an
empty string.pathName nearest
y
y
is expected to be relative to the tablelist
window itself (not its body component).pathName
nearestcell x y
x
and
y
are expected to be relative to the tablelist
window itself (not its body component).pathName
nearestcolumn x
x
is expected to
be relative to the tablelist window itself (not its body
component).pathName noderow
parentNodeIndex childIndex
parentNodeIndex
and the index
childIndex
in the parent's list of children.
childIndex
must be a number,
last
(specifying the parent's last child), or
end
; if it equals the number of children of the
parent node or is specified as end
then the return
value will be the row index of the item following the parent node's
last descendant.pathName parentkey
nodeIndex
nodeIndex
. If this argument is specified as
root
then the return value will be an empty
string. If nodeIndex
identifies a top-level
item then the subcommand will return root
.
For all other items the return value will be a full key of the form
knumber
.pathName
refreshsorting ?parentNodeIndex?
parentNodeIndex
according to the parameters of the
most recent sort
,
sortbycolumn
, or
sortbycolumnlist
invocation. If the items haven't been sorted at all, or the sort
information was reset by invoking resetsortinfo
, then no sorting takes
place. The optional argument parentNodeIndex
defaults to root
, meaning that all the items are to
be sorted per default. The return value is an empty string.pathName
rejectinput
-editendcommand
configuration option, then this subcommand prevents the termination of
the interactive editing of the content of the cell whose index was
passed to the editcell
subcommand. It invokes the seecell
subcommand to make sure the
respective cell becomes visible (in case it was scrolled out of view),
and sets the focus to the temporary widget embedded into the
cell. This command enables you to reject the widget's text during
the final validation of the string intended to become the new cell
content. The return value is an empty string.pathName
resetsortinfo
sortcolumn
and sortorder
will return -1
and
an empty string, respectively. Similarly, subsequent invocations
of sortcolumnlist
and
sortorderlist
will
return an empty string. This command also removes any existing
up- or down-arrows displayed by an earlier invocation of
sortbycolumn
or
sortbycolumnlist
. The return
value is an empty string.pathName
restorecursor
-cursor
configuration option to the
value that it had before invoking the setbusycursor
subcommand and returns
the boolean value 1
. If there was no previous
setbusycursor
invocation or this is not the first
restorecursor
invocation since the most recent call
to setbusycursor
, then the command returns the
value 0
, without attempting to restore the cursor.pathName rowattrib
index ?name? ?value name value
...?
index
. If no name
is
specified, the command returns a list of pairs, each of which contains
the name and the value of an attribute for the row. If
name
is specified with no
value
, then the command returns the value of the
one named row attribute, or an empty string if no corresponding value
exists (you can use the hasrowattrib
subcommand to distinguish
this case from the one that the value of an existing row
attribute is an empty string). If one or more
name
-value
pairs are specified,
then the command sets the given row attribute(s) to the given value(s);
in this case the return value is an empty string.
name
may be an arbitrary string.pathName rowcget
index option
option
for the row specified by
index
. option
may have
any of the values accepted by the rowconfigure
command.pathName
rowconfigure index ?option? ?value
option value ...?
index
. If no option
is
specified, the command returns a list describing all of the available
options for the row (see Tk_ConfigureInfo
for
information on the format of this list). If
option
is specified with no
value
, then the command returns a list describing
the one named option (this list will be identical to the corresponding
sublist of the value returned if no option
is
specified). If one or more
option
-value
pairs are
specified, then the command modifies the given row option(s) to have
the given value(s); in this case the return value is an empty
string. option
may have any of the values
described in the ROW CONFIGURATION OPTIONS IN
THE TABLELIST BODY section.pathName scan
option args
option
:pathName scan mark x
y
x
and y
and the
current view in the tablelist window; used in conjunction with
later scan dragto
commands. Typically this command is associated with a mouse
button press in the body component of the widget. It returns
an empty string. The coordinates x
and
y
are expected to be relative to the tablelist
window itself (not its body component).pathName scan dragto x
y
x
and y
arguments to the
last scan mark
command for
the widget. It then adjusts the view (the vertical one only
in the body component) by 10 times the difference in
coordinates. This command is typically associated with mouse
motion events in the body component of the widget, to produce the
effect of dragging the table at high speed through the
window. The return value is an empty string. The
coordinates x
and y
are
expected to be relative to the tablelist window itself (not its
body component).pathName
searchcolumn columnIndex pattern
?options?
columnIndex
to see if one of them matches
pattern
. If a match is found, the row index
of the first matching element is returned as result (unless the option
-all
is specified). If not, the return value
is -1
. One or more of the following options may be
specified to control the search:-all |
Changes the result to be the list of all matching row
indices, which will be in numeric order (or in reverse numeric
order when used with the -backwards
option). |
-backwards |
The search will proceed backward through the given column's elements in the tablelist's body. |
-check command |
Specifies an additional condition to be fulfilled by the
matching elements. If an element of the specified column
matches the given pattern and command is a nonempty
string, then the latter is automatically concatenated with the
path name of the tablelist widget, the element's row index, the
numerical equivalent of columnIndex , as well
as the element itself or its formatted version (depending on the presence
of the -formatted option), the resulting
script is evaluated in the global scope, and the return value
(which must be a boolean) will determine whether the element in
question will still be viewed as matching or not. The
default command is an empty string. This option
enables you to pass arbitrary additional matching criteria to the
searching process. |
-descend |
Search the elements of the specified column in all
descendants of the tree node given by the
-parent option. The elements will be
visited in the order of their row indices (or in reverse order of
their row indices when used with the
-backwards option). The default is to
restrict the search to the parent node's children only. |
-exact |
The matching element(s) must be identical to the literal
string pattern . |
-formatted |
Examine the formatted versions of the elements rather than the internal cell values. |
-glob |
Treat pattern as a glob-style pattern and
match it against the elements using the same rules as the
string match command. |
-nocase |
Causes comparisons to be handled in a case-insensitive
manner. Has no effect if combined with the
-numeric option. |
-not |
This option negates the sense of the match, returning the row
index of the first non-matching element (or, in the presence of
the -all option, the list of row indices of
all non-matching elements) of the given column. |
-numeric |
The elements are to be compared to
pattern as integer or floating-point values,
using the == comparison operator. This
option is only meaningful when used with
-exact . |
-parent
nodeIndex |
This option restricts the search to the children (or
descendants, when used with -descend ) of the
tree node given by nodeIndex . The
default parent is root . |
-regexp |
Treat pattern as a regular expression and
match it against the elements using the rules described in the
re_syntax reference page. |
-start index |
The elements of the specified column are to be searched
(forwards or backwards) starting at the row given by
index . This option makes it easy to
provide incremental search. |
-exact
, -glob
, and
-regexp
are omitted then the matching style
defaults to -glob
. If more than one of them
is specified, the last matching style given takes precedence.-descend
option) of a row whose children
have not been inserted yet, the command specified as the value of the
-populatecommand
option (if any) is automatically concatenated with the path name of the
tablelist widget and the row index, and the resulting script is
evaluated in the global scope. This enables you to insert the
children on demand, just before searching them for the specified
pattern.pathName see
index
index
is visible. If the item is already
visible then the command has no effect; if the item is near one edge of
the window then the tablelist scrolls to bring the item into view at
the edge; otherwise the tablelist scrolls to center the item.pathName seecell
cellIndex
cellIndex
is visible. If the cell is already
visible then the command has no effect; if the cell is near one edge of
the window then the tablelist scrolls to bring the cell into view at
the edge; otherwise the tablelist scrolls to center the cell. If
the value of the -titlecolumns
option is positive then
the centering of the cell is only done vertically; the horizontal
scrolling (which in this case is performed column-wise) will just bring
the cell into view next to the title columns or at the right edge of
the window.pathName seecolumn
columnIndex
columnIndex
is visible. If the column is
already visible then the command has no effect; if the column is near
one edge of the window then the tablelist scrolls horizontally to bring
the column into view at the edge; otherwise the tablelist scrolls
horizontally to center the column. If the value of the
-titlecolumns
option is
positive then the horizontal scrolling (which in this case is performed
column-wise) will just bring the column into view next to the title
columns or at the right edge of the window.pathName selection
option args
option
:pathName selection anchor
index
index
. If index
refers to a nonexistent or non-viewable
item, then the closest viewable item is used. The selection
anchor is the end of the selection that is fixed while dragging out
a selection with the mouse if the selection type is
row
. The index anchor
may be used to refer to the anchor item.pathName selection clear
firstIndex lastIndex
pathName selection clear
indexList
firstIndex
and
lastIndex
(inclusive) or corresponding to the
indices specified by the list indexList
contain
at least one selected cell, they are deselected. The
selection state is not changed for items outside the range given in
the first form of the command or different from those specified by
the index list given in its second form.pathName selection includes
index
1
if the item indicated by
index
contains at least one selected cell,
0
if it doesn't.pathName selection set
firstIndex lastIndex
pathName selection set
indexList
firstIndex
and lastIndex
,
inclusive, or corresponding to the indices specified by the list
indexList
, without affecting the selection
state of any other items.state
is disabled
and
option
is different from
includes
then the command just returns an empty
string, without performing any of the above actions.pathName
separatorpath ?columnIndex?
-titlecolumns
option is positive and an
empty string otherwise. If the optional argument is present, then
the command returns the path name of the separator attached to the
right edge of the header label indicated by
columnIndex
if the value of the -showseparators
configuration option
is true and an empty string otherwise.pathName
separators
-titlecolumns
option is positive then
the first element of the list will be the path name of the special
separator displayed to mark the end of the title columns. Whether
the path names of the other separators are included in the list,
depends on the value of the -showseparators
configuration
option.pathName
setbusycursor
-cursor
configuration option and then sets this option to the name of a
windowing system-specific busy cursor (watch
or
wait
). Since this subcommand is designed to
be invoked just before starting an operation that can take a long time
to complete, it also makes sure that the new cursor will immediately
get visible, by calling update
idletasks
. In the rare but possible case that, as a
side effect of this invocation, the tablelist widget gets destroyed by
some application-specific action scheduled for execution at idle time,
the command returns the boolean value 0
, otherwise the
value 1
.pathName
showtargetmark before|inside
index
index
. If the subcommand's name is followed
by before
and index
equals the
number of items or is specified as end
then the
horizontal gap will be shown just after the tablelist's last
row. If the subcommand is used with the
inside
option then the index
end
is interpreted as indicating the widget's last
item.pathName size
pathName sort
?-increasing|-decreasing?
-increasing
. Uses the value of the
-sortcommand
widget
configuration option as comparison command.
sort
also removes any existing up- or down-arrows
displayed by an earlier invocation of sortbycolumn
or sortbycolumnlist
. After
sorting the items, the command conditionally adjusts the vertical view
as follows: (a) if interactive cell editing is in progress then the
cell being edited is brought into view; (b) else, if exactly one item
is selected then the view is shifted to bring that item into view; (c)
else, if the tablelist's body is the most recent window to have the
input focus among all the windows in the same toplevel as the widget
itself then the currently active item is brought into view.pathName
sortbycolumn columnIndex
?-increasing|-decreasing?
columnIndex
, in increasing or decreasing order, as
specified by the optional argument. The default is
-increasing
. The sorting process is
controlled by the values of the -sortmode
and -sortcommand
options for the given
column. If both the value of the -showarrow
configuration option and that of
the -showarrow
option
for the specified column are true then an up- or down-arrow indicating
the sort order will be placed into the column's label. The shape
of the arrow depends on the command's optional argument and on the
value of the -incrarrowtype
configuration
option. If the label's text is right-aligned then the arrow will
be displayed on the left side of the label, otherwise on its right
side, with the exception of Windows Vista, 7, 8, and 10+, where the
arrow will be shown horizontally centered in the header label and
attached to its top edge. After sorting the items, the vertical
view is adjusted in the same way as in the case of the
sort
subcommand.-showlinenumbers
option hasn't
been set to true.pathName
sortbycolumnlist columnIndexList
?sortOrderList?
columnIndexList
argument, which must be a list
of distinct column indices. Only those elements of this list are
considered significant that identify columns whose -showlinenumbers
option hasn't
been set to true.columnIndexList
,
then based on the one given by the last but one significant element,
and so on. The order of each sort operation is taken from the
optional argument sortOrderList
, whose elements
must be (abbreviations of) increasing
or
decreasing
. If this argument was not
specified or contains less elements than
columnIndexList
then the missing sort orders are
assumed to be increasing
. Each sorting
process is controlled by the values of the -sortmode
and -sortcommand
options for the
respective column. If the column's index was specified among the
first 9 significant elements of columnIndexList
and
both the value of the -showarrow
configuration option and that of
the -showarrow
option
for that column are true then an up- or down-arrow indicating the sort
order will be placed into the column's label. The shape of the
arrow depends on the respective sort order and on the value of the
-incrarrowtype
configuration option. If the label's text is right-aligned then
the arrow will be displayed on the left side of the label, otherwise on
its right side, with the exception of Windows Vista, 7, 8, and 10+,
where the arrow will be shown horizontally centered in the header label
and attached to its top edge. If more than one sort arrows are to
be displayed then the first 9 sort ranks (1
for the first
significant element of columnIndexList
,
2
for the second one, and so on) will also be shown to the
right of the arrows. After sorting the items, the vertical view
is adjusted in the same way as in the case of the sort
subcommand.pathName
sortcolumn
sortbycolumn
or sortbycolumnlist
command, or
-1
if they were last sorted with the sort
command or haven't been sorted at all, or
the sort information was reset by invoking resetsortinfo
. If called from
within the command specified as the value of the
-sortcommand
widget or
column configuration option, then the
return value of this subcommand refers to the sorting in progress
rather than the most recent one.pathName
sortcolumnlist
sortbycolumnlist
or
sortbycolumn
command
(in the second case the list will contain exactly one element), or an
empty string if they were last sorted with the sort
command or haven't been sorted at all, or
the sort information was reset by invoking resetsortinfo
. If called from
within the command specified as the value of the
-sortcommand
widget or
column configuration option, then the
return value of this subcommand refers to the sorting in progress
rather than the most recent one.pathName
sortorder
increasing
or
decreasing
) from the last sorting performed by the
sort
, sortbycolumn
, or sortbycolumnlist
command, or an
empty string if the items haven't been sorted at all, or the sort
information was reset by invoking resetsortinfo
. If called from
within the command specified as the value of the
-sortcommand
widget or
column configuration option, then the
return value of this subcommand refers to the sorting in progress
rather than the most recent one.pathName
sortorderlist
increasing
or decreasing
) from
the last invocation of the sortbycolumnlist
or
sortbycolumn
command
(in the second case the list will contain exactly one element), or an
empty string if the items were last sorted with the sort
command or haven't been sorted at all, or
the sort information was reset by invoking resetsortinfo
. If called from
within the command specified as the value of the
-sortcommand
widget or
column configuration option, then the
return value of this subcommand refers to the sorting in progress
rather than the most recent one.pathName
stopautoscroll
autoscrolltarget
subcommand.<<Drop>>
virtual event. In the
second (BWidget) case it is should be invoked from within the command
specified as the value of the -dropcmd
option of
DropSite::register
.pathName
targetmarkpath
pathName
targetmarkpos y
?-any|-horizontal|-vertical?
showtargetmark
subcommand in order to display the drop target indicator corresponding
to that y-coordinate. The first list element will be the string
before
or inside
, and the
second one a numerical row index. These list elements depend on
the relative position of y
within the containing
row (if any), as well as on the optional second argument: The
default option -any
allows both
before
and inside
as first
element of the result list, while the options
-horizontal
and -vertical
restrict the value of the first list element to
before
and inside
,
respectively. If the option -vertical
was
specified and no item of the tablelist's body contains the given
y-position, then the return value is the list
{inside -1}
. The coordinate
y
is expected to be relative to the tablelist
window itself (not its body component).pathName
togglecolumnhide firstColumn lastColumn
pathName togglecolumnhide
columnIndexList
-hide
option for one or more columns of the
tablelist widget. In the first form of the command,
firstColumn
and lastColumn
are
indices specifying the first and last columns in the range whose
visibility is to be toggled. The command's second form accepts a
list columnIndexList
of indices specifying the
columns whose visibility is to be toggled. Returns an empty
string. After toggling the hidden state of the specified columns,
the <<TablelistColHiddenStateChanged>>
virtual event is generated. For Tk versions 8.5 and higher, this
virtual event is generated with its -data
option
set to a list consisting of the numerical column indices of the columns
whose -hide
option was toggled. The main
advantage of using this command instead of invoking columnconfigure
for each of the
specified columns is that it causes only one redisplay of the widget's
content, thus being significantly faster.pathName
togglerowhide firstIndex lastIndex
pathName togglerowhide indexList
-hide
option for one or more rows of the
tablelist widget's body. In the first form of the command,
firstIndex
and lastIndex
are
indices specifying the first and last rows in the range whose
visibility is to be toggled. The command's second form accepts a
list indexList
of indices specifying the rows whose
visibility is to be toggled. Returns an empty string. After
toggling the hidden state of the specified rows, the
<<TablelistRowHiddenStateChanged>>
virtual event is generated. For Tk versions 8.5 and higher, this
virtual event is generated with its -data
option
set to a list consisting of the numerical row indices of the rows whose
-hide
option was toggled. Just like the
-hide
row configuration option, this subcommand is
not supported for Tk versions earlier than 8.3.pathName
toplevelkey index
index
is a top-level
one then the subcommand returns the full key of that item.
Otherwise the return value is the full key of the unique top-level item
having the given item among its descendants.pathName
unsetattrib name
name
. Returns an
empty string.pathName
unsetcellattrib cellIndex name
name
for the cell given by
cellIndex
. Returns an empty string.pathName
unsetcolumnattrib columnIndex name
name
for the column given
by columnIndex
. Returns an empty string.pathName
unsetrowattrib index name
name
for the row given by
index
. Returns an empty string.pathName
viewablerowcount ?firstIndex
lastIndex?
firstIndex
and
lastIndex
. If these optional indices are not
specified then firstIndex
defaults to
0
and lastIndex
defaults to one less
the total number of body items, i.e., the index range comprises all
rows of the tablelist's body.pathName windowpath
cellIndex
cellIndex
, created with the -window
option of the cellconfigure
subcommand. If no
window is currently embedded into the cell then the return value is an
empty string.pathName xview
?args?
pathName xview
0
and 1
; together
they describe the horizontal span that is visible in the
window. For example, if the first element is 0.2
and the second element is 0.6
, 20% of the tablelist's
scrollable text is off-screen to the left, the middle 40% is
visible in the window, and 40% of the scrollable text is off-screen
to the right. These are the same values passed to scrollbars
via the -xscrollcommand
option.pathName xview
units
-titlecolumns
option is positive
then this command adjusts the view in the window so that the column
whose offset from the end of the title column area equals
units
non-hidden columns is displayed next to
the title columns. Otherwise the command adjusts the view in
the window so that the character position given by
units
is displayed at the left edge of the
window. Character positions are defined by the width of the
character 0
.pathName xview moveto
fraction
fraction
of the total width of the scrollable
tablelist text is off-screen to the left.
fraction
must be a fraction between
0
and 1
.pathName xview scroll number
what
number
and
what
. number
must be
an integer or a float; if it is a float then it is converted to an
integer, rounded away from 0
.
what
must be either units
or pages
or an abbreviation of one of
these. If what
is
units
, the view adjusts left or right by
number
non-hidden columns or character units
(the width of the 0
character) on the display,
depending on the value of the -titlecolumns
option; if
what
is pages
then the view
adjusts by number
screenfuls. If
number
is negative then columns or characters
farther to the left become visible; if it is positive then columns
or characters farther to the right become visible.pathName yview
?args?
pathName yview
0
and 1
. The
first element gives the position of the viewable tablelist item at the top of the window,
relative to the tablelist as a whole (0.5
means it is
halfway through the tablelist, for example). The second
element gives the position of the viewable tablelist item just
after the last one in the window, relative to the tablelist as a
whole. These are the same values passed to scrollbars via the
-yscrollcommand
option.pathName yview
units
units
viewable
rows is displayed at the top of the window.pathName yview moveto
fraction
fraction
appears at the top of the
window. fraction
is a fraction between
0
and 1
; 0
indicates the
first viewable item in the tablelist, 0.33
indicates
the viewable item one-third the way through the tablelist, and so
on.pathName yview scroll number
what
number
and what
.
number
must be an integer or a float; if it is
a float then it is converted to an integer, rounded away from
0
. what
must be either
units
or pages
or an
abbreviation of one of these. If what
is
units
, the view adjusts up or down by
number
viewable rows;
if it is pages
then the view adjusts by
number
screenfuls. If
number
is negative then items farther to the
top become visible; if it is positive then items farther to the
bottom become visible.header
tablelist command,
used to invoke various operations on the header items, has the following
general form:
pathName header option ?arg arg ...?
option
and the arg
s determine
the exact behavior of the command. The following subcommands are
supported for the tablelist header:pathName header bbox
headerIndex
bbox
command
for the tablelist body.pathName header
cellattrib headerCellIndex ?name? ?value
name value ...?
cellattrib
command for the tablelist
body.pathName header
cellbbox headerCellIndex
cellbbox
command for the tablelist body.pathName header
cellcget headerCellIndex option
cellcget
command for the tablelist body. option
may
have any of the values accepted by the header cellconfigure
subcommand.pathName header
cellconfigure headerCellIndex ?option? value
option value ...?
cellconfigure
command for the tablelist
body. Each option
may have any of the values
described in the CELL CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
cellindex headerCellIndex
cellindex
command for the tablelist
body.pathName header
configcelllist headerCellConfigSpecList
configcelllist
command for the
tablelist body. The argument
headerCellConfigSpecList
must be a list of the
form
headerCellIndex option value headerCellIndex option value ...
option
may have any of the values
described in the CELL CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
configcells ?headerCellIndex option value
headerCellIndex option value ...?
configcells
command for the tablelist
body. Each option
may have any of the values
described in the CELL CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
configrowlist headerRowConfigSpecList
configrowlist
command for the
tablelist body. The argument
headerRowConfigSpecList
must be a list of the
form
headerIndex option value headerIndex option value ...
option
may have any of the values
described in the ROW CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
configrows ?headerIndex option value
headerIndex option value ...?
configrows
command for the tablelist
body. Each option
may have any of the values
described in the ROW CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
containing y
containing
command for the tablelist
body.pathName header
containingcell x y
containingcell
command for the
tablelist body.pathName header
delete firstHeaderIndex lastHeaderIndex
pathName header delete
headerIndexList
delete
command for the tablelist body.pathName
header embedcheckbutton headerCellIndex
?command?
embedcheckbutton
command for the
tablelist body.pathName
header embedcheckbuttons columnIndex
?command?
embedcheckbuttons
command for the
tablelist body. Logically equivalent to invoking
header
embedcheckbutton
for all header cells of the
column specified by columnIndex
.pathName
header embedttkcheckbutton headerCellIndex
?command?
embedttkcheckbutton
command for
the tablelist body.pathName
header embedttkcheckbuttons columnIndex
?command?
embedttkcheckbutton
command for
the tablelist body. Logically equivalent to invoking
header
embedttkcheckbutton
for all header cells of the
column specified by columnIndex
.pathName header
fillcolumn columnIndex
?-text|-image|-window? value
fillcolumn
command for the tablelist
body. Logically equivalent to invoking the
header
cellconfigure
subcommand for all header cells of
the specified column, with -text
(the default),
-image
, or -window
, as well as
value
as arguments.pathName header
findrowname name
findrowname
command for the tablelist
body. Returns the header row index of the first header item whose
name equals name
.pathName header get
firstHeaderIndex lastHeaderIndex
pathName header get
headerIndexList
get
command
for the tablelist body.pathName header
getcells firstHeaderCell lastHeaderCell
pathName header getcells
headerCellIndexList
getcells
command for the tablelist body.pathName header
getcolumns firstColumn lastColumn
pathName header getcolumns
columnIndexList
getcolumns
command for the tablelist
body.pathName header
getformatted firstHeaderIndex
lastHeaderIndex
pathName header getformatted
headerIndexList
getformatted
command for the tablelist
body.pathName
header getformattedcells firstHeaderCell
lastHeaderCell
pathName header getformattedcells
headerCellIndexList
getformattedcells
command for the
tablelist body.pathName
header getformattedcolumns firstColumn
lastColumn
pathName header getformattedcolumns
columnIndexList
getformattedcolumns
command for
the tablelist body.pathName header
getfullkeys firstHeaderIndex
lastHeaderIndex
pathName header getfullkeys
headerIndexList
getfullkeys
command for the tablelist
body. Remember that the full keys of the header items start with
hk
.pathName header
getkeys firstHeaderIndex lastHeaderIndex
pathName header getkeys
headerIndexList
getkeys
command for the tablelist body.pathName header
hascellattrib headerCellIndex name
hascellattrib
command for the tablelist
body.pathName header
hasrowattrib headerIndex name
hasrowattrib
command for the tablelist
body.pathName header
imagelabelpath headerCellIndex
imagelabelpath
command for the
tablelist body.pathName header index
headerIndex
index
command for the tablelist body.pathName header
insert headerIndex ?item item ...?
insert
command for the tablelist body.pathName header
insertlist headerIndex itemList
insertlist
command for the tablelist
body.pathName header
iselemsnipped headerCellIndex
fullTextName
iselemsnipped
command for the tablelist
body.pathName header
itemlistvar
itemlistvar
command for the tablelist
body.pathName header
nearest y
nearest
command for the tablelist body.pathName header
nearestcell x y
nearestcell
command for the tablelist
body.pathName header
rowattrib headerIndex ?name? ?value
name value ...?
rowattrib
command for the tablelist
body.pathName header
rowcget index option
rowcget
command for the tablelist body. option
may
have any of the values accepted by the header rowconfigure
subcommand.pathName header
rowconfigure headerIndex ?option? ?value
option value ...?
rowconfigure
command for the tablelist
body. Each option
may have any of the values
described in the ROW CONFIGURATION OPTIONS
IN THE TABLELIST HEADER section.pathName header
size
size
command
for the tablelist body.pathName header
unsetcellattrib headerCellIndex name
unsetcellattrib
command for the
tablelist body.pathName header
unsetrowattrib headerIndex name
unsetrowattrib
command for the
tablelist body.pathName header
windowpath headerCellIndex
windowpath
command for the tablelist
body.Text
is replaced with a new binding tag
called TablelistBody
. The latter has all the
events of the Listbox
widget class, and several of
its binding scripts are obtained from those of
Listbox
by replacing the event fields
%W
, %x
, and
%y
with the path name of the tablelist widget and the
x and y coordinates relative to the latter. These values are
assigned to the help variables tablelist::W
,
tablelist::x
, and tablelist::y
by
invoking the helper command tablelist::convEventFields
as follows:
foreach {tablelist::W tablelist::x tablelist::y} \ [tablelist::convEventFields %W %x %y] {}
tablelist
namespace in order to avoid any
conflicts with global variables.%x
and
%y
fields; in this case another helper command
tablelist::getTablelistPath
is used to set the help variable tablelist::W
to the
path name of the tablelist widget:
set tablelist::W [tablelist::getTablelistPath %W]
TablelistBody
replaces the class
name (Frame
or TSeparator
) of the
separator widgets, too. It also replaces the binding tag
Message
of the message widgets used to display
multi-line elements, as well as the binding tag Label
of the label widgets used to display embedded images. This makes sure
that the default handling of the mouse events on the column separators,
multi-line cells, and embedded images is the same as in the rest of the
tablelist's body..tbl
prints the index of the cell where mouse button
1 was clicked:
bind [.tbl bodytag] <Button-1> {printClickedCell %W %x %y}
proc printClickedCell {w x y} { foreach {tbl x y} [tablelist::convEventFields $w $x $y] {} puts "clicked on cell [$tbl containingcell $x $y]"
bodytag
subcommand instead of
just with the path name of the tablelist's body we make sure to have the
same event handling for the separators, multi-line cells, and embedded
images as for the rest of the tablelist's body.TablelistBody
ensure that the body component of a
tablelist has the same behavior as a Tk core listbox widget. Whether
this is strictly valid, is controlled by the boolean variable
tablelist::strictTk
. For improved
user-friendliness and compatibility with other frameworks, this variable
has the default value 0
, which enables a few
Tablelist-specific extensions and changes:tablelist::strictTk
is true then
all default bindings associated with the binding tag
TablelistBody
give rise to exactly the same
behavior as the default bindings associated with the binding tag
Listbox
.tablelist::strictTk
is false
then, in all selection modes, the selection state of individual
tablelist items or elements (depending on the selection type) can be
toggled with the aid of Control-Button-1
,
Control-space
, and Control-Select
(see
below).row
: If the selection type is
row
(which is the default) then everything described in
the "DEFAULT BINDINGS" section of the listbox manual entry applies
to the body component of a tablelist, too. The only difference is
that the word "element" in that manual page has to be replaced with "item"
when applying the description to the body of a tablelist widget. In
addition:tablelist::strictTk
is false
(which is the default) then pressing button 1 with the
Control
key down toggles the selection state of the item
under the mouse. If the selection mode is
extended
then additional actions apply, as
described in the listbox manual entry. If the selection
mode is single
or browse
and
the selection state of the item changes from unselected to selected
then any other selected items will be deselected, just as if button 1
had been pressed without the Control
key down.tablelist::strictTk
is
false, then Control-space
and Control-Select
toggle the selection state of the active item just as if button 1 had
been pressed over this item with the Control
key
down.cell
: If the selection type is
cell
then everything described in the "DEFAULT
BINDINGS" section of the listbox manual entry applies to the body
component of a tablelist, too, with the following extensions and
changes:Tab
or Shift-Tab
is pressed, the
location cursor (active element) moves to the next/previous
element. If the selection mode is browse
or
extended
then the new active element is also
selected and all other elements are deselected. In
extended
mode the new active element becomes the
selection anchor.
Notice that these bindings replace the common inter-widget
navigation via Tab
and Shift-Tab
with
inter-cell navigation. Just like in the case of the text
widget, Control-Tab
and Control-Shift-Tab
are intended to be used for widget-to-widget keyboard
navigation. Unfortunately, this won't always work because some
window managers intercept the latter key sequences and use them for
their own purposes (like inter-workplace navigation). For this
reason, Tablelist supports the additional key sequences
Meta-Tab
and Meta-Shift-Tab
as replacements
for Control-Tab
and Control-Shift-Tab
,
respectively.
Left
or Right
key is
pressed, the location cursor (active element) moves to the
previous/next element of the active row. If the selection mode is
browse
or extended
then the new
active element is also selected and all other elements are
deselected. In extended
mode the new active
element becomes the selection anchor.extended
mode,
Shift-Left
and Shift-Right
move the location
cursor (active element) to the previous/next element of the active row
and also extend the selection to that element in a fashion similar to
dragging with mouse button 1.Home
or End
key is
pressed, the location cursor (active element) moves to the first/last
element of the active row, the new active element is selected, and all
other elements are deselected.extended
mode,
Shift-Home
and Shift-End
extend the selection
to the first/last element of the active row. In
multiple
mode, Shift-Home
and
Shift-End
move the location cursor to the first/last
element of the active row.Return
and KP_Enter
start the interactive
editing of the active element.tablelist::strictTk
is false
(which is the default) then pressing button 1 with the
Control
key down toggles the selection state of the
element under the mouse. If the selection mode is
extended
then additional actions apply, as
described in the listbox manual entry. If the selection
mode is single
or browse
and
the selection state of the element changes from unselected to selected
then any other selected elements will be deselected, just as if button
1 had been pressed without the Control
key down.tablelist::strictTk
is
false, then Control-space
and Control-Select
toggle the selection state of the active element just as if button 1
had been pressed over this element with the Control
key
down.TablelistBody
are valid on the windowing systems
x11
and win32
:Control-a
behaves the same as
Control-slash
, i.e., it selects everything in the
widget's body, except in single
and
browse
modes, in which case it selects the active
item or element (depending on the selection type) and deselects
everything else.
REMARK 1: The default widget bindings in current Tk
versions on Windows already support Control-a
as an
alternative to Control-slash
. In Tablelist this is
now valid on X11, too.
REMARK 2: On Mac OS X/11+, the default widget
bindings in current Tk versions use the key sequence
Command-a
instead of
Control-slash
.
Shift-Control-A
behaves the same as
Control-backslash
, i.e., it deselects everything in the
widget, except in browse
mode where it has no
effect.
REMARK 1: This shortcut comes in handy on Windows
when using, e.g., a French or German keyboard, because in this case
Tk fails to recognize the Control-backslash
key sequence
(for which one has to press Control
, AltGr
,
and a third key: _
on a French and ß
on a German keyboard). Moreover, on many keyboards it is quite
difficult (if not even impossible) to generate the
Control-backslash
key sequence, fact which makes the
support for this alternative shortcut even more useful on both X11
and Windows.
REMARK 2: On Mac OS X/11+, the default widget
bindings in current Tk versions use the key sequence
Option-Command-a
instead of
Control-backslash
.
<<ListboxSelect>>
. Instead of this
event (which is supported for compatibility reasons), the virtual event
<<TablelistSelect>>
can be used to be made
aware of any changes to tablelist selection. Both events will be
generated independently of the selection type. A binding script for
one of these events can use the curselection
and curcellselection
subcommands to retrieve
the indices of the selected rows and cells, respectively.<<TablelistActivate>>
. A binding
script for this event can access the active item or element by using the
word active
(which is a valid row and cell index) or its
canonical equivalent given by [pathName index active]
and
[pathName cellindex
active]
, respectively.TablelistBody
is only valid if the
selection mode is single
or
multiple
:
If mouse button 1 is clicked on an item and then dragged outside that item, and the value of the
-movablerows
configuration option is true, then the mouse cursor takes on the shape specified by the-movecursor
option, indicating that the item in question is being moved to another position. The new item position (if any) is visualized with the aid of a gap placed before the target row or a bar placed inside the latter (depending on the current mouse position), indicating whether the source item would be moved before this row or become a child of it. This local drag & drop operation ends when mouse button 1 is released, and can be canceled by pressing theEscape
key. In both cases, the mouse cursor is reset to its original value, specified by the-cursor
configuration option. After releasing mouse button 1 in the presence of a valid target, the source item is moved before the target row or just before the latter's first child, and the virtual event<<TablelistRowMoved>>
is generated. For Tk versions 8.5 and higher, this virtual event is generated with its-data
option set to a list of length 3, whose elements are derived from the arguments passed to the second form of themove
subcommand invoked for moving the source row to its new position. The first list element will be the full key corresponding to the first argument, the second one will beroot
or the full key corresponding to the second argument, and the third list element will be identical to the third argument passed to themove