1. Documentation for ::Tk::Tabular
2. Description
A Table widget for Tk using the text widget.
Tabular provides the following features:
- Columns auto-size to cell contents.
- Cells have any number or combination of text/tags, images and windows.
- Column alignment eg: left, right, center and numeric.
- Column sizing uses tabs for fast, dynamic resizing.
- Handles large data sets (eg. 100K+ rows).
- Support for variable (array or list), or command (eg. for sqlite).
- Tree mode operations.
- Implemented in pure Tcl (version >= 8.3).
Implementation:
Table columns/rows number from 0 where row 0 is the title row.
Uses text widgets with tab chars delimiting cells.
A line holds one row of cells, each of which starts with \t\t and
ends with \t. Cell data thus may not contain \t, \n or \r.
Easy internal variable data access eg. "upvar [.n icfg winvar] v"
NOTE: see "Oldclock" if using Tcl 8.5+.
Dependancies:
There are no dependancies other than Tk 8.3 and the files included, ie:
- solid.xpm (or write perms in appdir) for cell borders.
- either the package Mod Modlite.tcl in appdir.
- Combo (ie. with -type Choice) without Mod falls back to entry/spinbox.
TODO:
Fix column width calculation on very wide columns.
Fix bug where an image/window can not be first index in a cell.
Add general "tag bind" to handle keyinput other than "current" (ie. at mouse).
Tcl/BSD Copyright 2007 - Peter MacDonald - http://pdqi.com
3. Synopsis
4. Commands
Following are the extern definitions for commands in this module.
4.1 proc activate {w cell1 {cell2 {}} args}
Make given cell(s) active and visible.
OPTIONS:
{ -istitle 0 "Is title row" }
{ -see True "Make viewable" }
extern activate {w cell1 {cell2 {}} args} {. . . . {opts -istitle -see}}
4.2 proc bbox {w cell {leading False}}
Return bounding box of cell
4.3 proc cget {w opt}
Get a config option.
4.4 proc clear w
Erase the contents of table.
4.5 proc conf {w args}
Modify config options.
4.6 proc coords {w cell}
Get char indices for cell at idx.
Returned data includes tabs.
4.7 proc edit {w {cell active.first} {op start}}
Activate cell and begin editing.
extern edit {w {cell active.first} {op start}} {. tkwin . {choice start done donenext escape get}}
4.8 proc find {w string args}
Search for string in body and activate cell.
OPTIONS:
{ -back False "Search backward" }
{ -case True "Search is case sensitive" }
{ -col {} "Search only in given column (.==active)" }
{ -noact False "Do not activate the match" }
{ -type exact "Type of search" -type {Choice exact glob regexp} }
{ -word False "Match only whole word" }
extern find {w string args} {. . . {topts -back . -case . -col . -noact . -type {Choice exact glob regexp} -word .}}
4.9 proc get {w cell args}
Get text string for cell given by index.
OPTIONS:
{ -tree False "Do not trim off col0 space prefix for -tree" }
{ -type text "Type to get" -type {choice text image window} }
{ -skip 0 "Number of images/windows to skip" }
extern get {w cell args} {. . . {topts -tree . -type {choice text image window} -skip .}}
4.10 proc icfg {w args}
Change internal config.
4.11 proc index {w cell {intitle False}}
Return index spec in COL,ROW form.
For example: @X,Y .winname etc.
If not in COL,ROW form, try matching TITLE,N using col title string.
Otherwise, use the Text widget index command on the body
and convert the resulting index position into COL,ROW.
extern index {w cell {intitle False}} {. tkwin . Bool}
4.12 proc new {w args}
Widget creation.
OPTIONS:
{ -bd 0 "Border size for widget" }
{ -cols 1 "Number of columns in table" }
{ -colwidth 30 "Minimum width of columns" -type int }
{ -fillcmd {} "Command for dynamically filling a null-row" -type {cmd w ww row numcols} }
{ -height 10 "Height of widget in chars" -type int }
{ -icfg {} "Internal name/value config options" }
{ -opencmd {} "Command to call when sub-tree is opened" }
{ -relief {} "Relief for widget" }
{ -rows 0 "Number of empty rows to preallocate" }
{ -showtitle True "Show title row above columns" }
{ -style {} "Style to apply" }
{ -tagcmd {} "Command to markup/modify cells when mapped" -type {cmd w ww i1 i2 col row node} }
{ -tree False "Use tree mode" }
{ -variable {} "Variable of data for table" }
{ -width 80 "Width of widget in chars" -type int }
{ -xscrollcommand {} "Horizontal scroll command" }
{ -yscrollcommand {} "Vertical scroll command" }
{ --check True "Type checking enabled on cell edits" }
{ --dynamic True "Update widget view on scroll for large tables" }
{ --editcmd {} "Command to create custom edit widget" -type {cmd w ww type} }
{ --fields {} "Fields info" }
{ --fields {} "Use given field names instead of extracting var" }
{ --showkey False "Display key when using -variable" }
{ --sortable True "Dynamic sorting by clicking on column titles" }
{ --sortby {} "Field to sort by" }
{ --sortdown False "Sort in decreasing order" }
{ --speed False "Favor speed over data size" }
{ --syncvar False "Map array-variable changes to modify calls" }
{ --time False "Report timing stats for query" }
{ --updatecmd {} "Callback for updates" -type {cmd w col row value num} }
extern new {w args} {. . {topts -bd . -cols . -colwidth int -fillcmd {cmd w ww row numcols} -height int -icfg . -opencmd . -relief . -rows . -showtitle . -style . -tagcmd {cmd w ww i1 i2 col row node} -tree . -variable . -width int -xscrollcommand . -yscrollcommand . --check . --dynamic . --editcmd {cmd w ww type} --fields . --fields . --showkey . --sortable . --sortby . --sortdown . --speed . --syncvar . --time . --updatecmd {cmd w col row value num}}}
4.13 proc readonly {w {cell {}} {ro { }}}
Get or set cells readonly state of cell.
4.14 proc redraw {w args}
Schedule redraw of cells in visible viewport.
Called automatically on scrolling of text window or manual updates.
This is sets up column tab widths.
OPTIONS:
{ -flush False "Forget cached maxwidths from previous redraws" }
extern redraw {w args} {. . {opts -flush}}
4.15 proc see {w cell {redraw 1}}
Arrange for the given cell to be made visible.
4.16 proc sub {w {target {}} {cmd {}} args}
Invoke sub-command on component (body or title).
extern sub {w {target {}} {cmd {}} args} {. tkwin {Choice body title}}
4.17 proc update {w cell value args}
Set or change text, image or window in cell.
OPTIONS:
{ -check True "Invoke text type checking if available" }
{ -delete False "Delete window/image value" }
{ -end False "Add to end rather than start (if not updating)" }
{ -iopts {} "Options for inline image/window" }
{ -raw False "Do not skip tree prefix space" }
{ -skip 0 "Number to matching items to skip in dump" }
{ -tags {} "Additional tags to add to item" }
{ -type text "Type of item" -type {Choice text image window}}
{ -update True "Replace rather than appending value" }
{ -withtag {} "Limit update to item marked with user tag" }
extern update {w cell value args} {. . . . {topts -check . -delete . -end . -iopts . -raw . -skip . -tags . -type {Choice text image window} -update . -withtag .}}
4.18 proc xview {w args}
Manage x viewport.
4.19 proc yview {w args}
Manage y viewport.
5. Sub-commands for: col
5.1 proc col::align {w {col {}} {align { }} {titles False}}
Get or set column alignments eg: l, r, c n, n.X.
If col==-1, sets default alignment.
If col=={} return list of all aligns.
The .X suffix for numerics specifies what portion (.1 to .9) of the
number that is normally before the decimal: the default is .5.
5.2 proc col::delete {w {col end} args}
Delete one or more columns.
OPTIONS:
{ -count 1 "Number of columns to delete" -type "int -min 1 -max 20"}
{ -titles True "Delete titles cols from col instead of end" }
extern delete {w {col end} args} {. . . {topts -count {int -min 1 -max 20} -titles .}}
5.3 proc col::get {w col {start 1} {end end}}
Return list text values for a col.
5.4 proc col::hide {w {col {}} {hide {}} args}
Set or get columns hidden state.
OPTIONS:
{ -count 1 "Number of cols to hide" }
extern hide {w {col {}} {hide {}} args} {. . . . {opts -count}}
5.5 proc col::index {w col {istitle 0}}
Translate column name to an it's index number.
5.6 proc col::insert {w args}
Insert 1 or more columns.
OPTIONS:
{ -at end "Place to insert column" }
{ -count 1 "Number of columns to insert" }
{ -default {} "Default value for cells in row" }
{ -titles True "Insert titles columns instead of appending" }
{ -values {} "Data list of cells for col" }
extern insert {w args} {. . {opts -at -count -default -titles -values}}
5.7 proc col::readonly {w {col {}} {ro {}}}
Set or get cols readonly state.
5.8 proc col::sort {w col}
Sort by given column.
5.9 proc col::tag {w col {tags { }}}
Set or query tags for given column.
5.10 proc col::width {w {col {}} {width { }}}
Set minimum width for a column.
6. Sub-commands for: row
6.1 proc row::align {w row {aligns { }}}
Set or get per row columns alignments.
If row=={} return list of all aligns custom.
The .X part specifies what portion (.1 to .9) the leading
numeric is usually before the decimal where .5 is the default.
6.2 proc row::autofill {w {force False}}
Force loading of deferred data now.
6.3 proc row::delete {w {row end} args}
delete 1 or more rows.
OPTIONS:
{ -count 1 "Number of rows to delete" }
{ -update True "Do update of -variable" }
extern delete {w {row end} args} {. . . {opts -count -update}}
6.4 proc row::get {w row {start 0} {end end}}
Return list text values for all or part of row.
6.5 proc row::hide {w {row {}} {hide {}} args}
Set row hidden state or get list of all hidden rows.
OPTIONS:
{ -count 1 "Number of rows to hide" }
extern hide {w {row {}} {hide {}} args} {. . . . {opts -count}}
6.6 proc row::index {w row}
Translate row name to an row index number.
6.7 proc row::insert {w args}
Insert row of values.
OPTIONS:
{ -at end "Place to insert new row" }
{ -parent {} "Tree node child add" }
{ -count 1 "Number of columns to insert"}
{ -default {} "Default value for cells" }
{ -update True "Do update of -variable" }
{ -values {} "List of data value" }
extern insert {w args} {. . {opts -at -parent -count -default -update -values}}
6.8 proc row::markup {w line1 {line2 {}}}
Add markup (tags) to line.
Invokes -tagcmd and/or -fillcmd as required.
When line2=={}, returns node name of line.
6.9 proc row::node {w row {row2 {}}}
Return the #NNN node id for the given row.
6.10 proc row::offsets {w row {embeds 0}}
Return list of text indexes for cell end chars in row.
The text index is the char 1 after the final tab char per cell.
Used as follows:
set n 0; set lst {}
foreach i [$t row offset 1] {
lappend lst [$t.body get 1.$n+2c 1.$i-1c]; set n $i
}
If $embeds==1, then also return list of images/windows.
6.11 proc row::readonly {w {row {}} {ro {}}}
Set or get rows readonly state.
6.12 proc row::update {w row list args}
Update entire text data values for row.
OPTIONS:
{ -update True "Update data variable" }
extern update {w row list args} {. . . . {opts -update}}
7. Sub-commands for: tag
7.1 proc tag::add {w tag cell1 {cell2 {}} args}
Add tag to cells.
7.2 proc tag::conf {w tag args}
Configure tag for body; same as [sub body tag conf].
7.3 proc tag::nextrange {w tag cell1 {cell2 {}}}
Return next range of cells with tag.
7.4 proc tag::prevrange {w tag cell1 {cell2 {}}}
Return previous range of cells with tag.
7.5 proc tag::ranges {w tag args}
Return list of cells with tag.
OPTIONS:
{ -values False "Return values instead of data" }
{ -title False "Use title instead of body" }
extern ranges {w tag args} {. . . {opts -values -title}}
7.6 proc tag::remove {w tag cell1 {cell2 {}} args}
Remove tag from cells.
7.7 proc tag::value {w cell {option {}} args}
Return value or name of option(s) set at cell.
If $option=={}, return name/value pairs of set attributes.
OPTIONS:
{ -name False "Return name of tag instead of value" }
{ -title False "Use title instead of body" }
extern value {w cell {option {}} args} {. . . . {opts -name -title}}
8. Sub-commands for: tree
8.1 proc tree::children {w {cell {}} args}
Return list of children for cell.
OPTIONS:
{ -nodes True "Return node ids instead of indexes" }
{ -count False "Return the number of children" }
extern children {w {cell {}} args} {. . . {opts -nodes -count}}
8.2 proc tree::close {w cell1 {cell2 {}} args}
Close trees if open.
8.3 proc tree::init {w {start 1.0} {end end}}
Update raw inserted text with tree tags, image, etc..
8.4 proc tree::isopen {w cell}
Return isopen status for row.
8.5 proc tree::istree {w cell}
Return 1 if cell has a subtree.
8.6 proc tree::level {w cell}
Return nest level of tree (ie. leading spaces/4).
8.7 proc tree::open {w cell1 {cell2 {}} args}
Open trees if closed.
8.8 proc tree::parent {w cell}
8.9 proc tree::path {w cell args}
Return the tree path-list down to given cell.
OPTIONS:
{ -inds False "Return text indices instead of text" }
{ -nodes False "Return node ids instead of text" }
extern path {w cell args} {. . . {opts -inds -nodes}}
8.10 proc tree::toggle {w cell args}
Toggle open/close of subtree cell.
OPTIONS:
{ -activate True "Make active" }
extern toggle {w cell args} {. . . {opts -activate}}
RCS: @(#) $Id: Tabular.tcl,v 1.4211 2008/08/27 16:36:28 pcmacdon Exp pcmacdon $
(File: Tabular.tcl )
© 2008 Peter MacDonald