hwtk::table

Create and manipulate tables.

Format

hwtk::table - pathName ?option value? …

Description

The table command creates a new window (given by the pathName argument) and makes it into a table widget. The table can be one of two modes; editable or view only. Various commands and options enable you to manipulate the rows, columns and general appearance of the table widget.

Standard Options

-borderwidth
Database name: borderWidth
Database class: BorderWidth
The desired width of the widget border. Defaults to 0.
-clientdata
Database name: clientData
Database class: ClientData
Acts as a data storage for a widgets. User can store any data and this will not have any effect on widget property.
-height
Database name: height
Database class: Height
If specified, the widget’s requested height in pixels.
-helpcommand
Database name: helpcommand
Database class: Command
Dynamic help which calls an assigned -helpcommand when the user moves the mouse on the widget. The text which is returned by the -helpcommand will be in turn be displayed on the tooltip.
-width
Database name: width
Database class: Width
Specifies the width of a widget.

Widget Specific Options

-cellmenucommand
Database name: cellmenucommand
Database class: Cellmenucommand
Command to run when the user right clicks on a cell.
-closeeditor
Database name: closeeditor
Database class: Closeeditor
Boolean option when set to true, the editor unposts upon successful set value. Default is set to false.
-columndnd
Database name: columndnd
Database class: ColumnDnd
Boolean option to enable drag and drop of column headers to reorder the columns. Default is set to true.
-menu
Database name: menu
Database class: Menu
Option to attach a menu to the table widget which is invoked when the user right or left clicks in the header region of the row number column.
-menuindicator
Database name: menuindicator
Database class: Indicator
Specifies whether or not a menuindicator (small double down-arrow) should be shown in the column header. A value of true indicates that the menuindicator should be visible; a value of false indicates that it should not be visible.
-mode
Database name: mode
Database class: Mode
The mode for the table can be edit or view mode. View mode makes the table read-only. Edit mode allows the user to edit values in the table.
-showborder
Database name: showborder
Database class: Showborder
Boolean option to have a border on the table. If the option is set to true then the border will be shown in the width specified by the configuration option of -borderwidth. The default value is true.
-showheader
Database name: showHeader
Database class: ShowHeader
Specifies a boolean value that determines whether this widget should display the header line with the column names at the top of the widget. The default value is true.
-showrownumbers
Database name: showrownumbers
Database class: Showrownumbers
Boolean option that specifies whether or not to show row numbers in the table. The default value is true.

Widget Commands

pathName cellget cell_row, cell_column
Retrieves the value of a given cell in the table. The row (cell_row) and column (cell_column) index must be comma separated.
pathName cellset cell_row, cell_column value
Sets the value of a given cell in the table. The row (cell_row) and column (cell_column) index must be comma separated. The display value and display image are fetched from the associated editor.
pathName cget option
Returns the current value of the configuration option given by option.
pathName columncget columnDesc option ?arg arg …?
This command returns the current value of the named option for the column specified by the column description columnDesc. ColumnDesc may also be the string tail to specify the tail column. Option may have any of the values accepted by the column -configure widget command.
pathName columnconfigure columnDesc ?arg arg …?
This command is similar to the -configure widget command except that it modifies options associated with the columns specified by the column description columnDesc instead of modifying options for the overall table widget. If no option is specified, the command returns a list describing all of the available options for columnDesc. If an 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 option(s) to have the given value(s) for columnDesc; in this case the command returns an empty string.
pathName columncreate columnDesc ?arg arg …?
This command creates a new column in the table widget. The new column is placed to the right of all other columns (except the tail column). Any option-value arguments configure the new column according to the column configure command. The return value is the column identifier of the new column. Valid options are -type, -text, -image, -resize, -itemjustify, -justify, -width, -expand, -sort, -validatecommand, -validate, -valueaccept, -valuelistcommand, -clientdata, and -editable. The -valuelistcommand requires a command which accepts one argument which is the row identifier.
Note: If a column is deleted and added again, the last column ID will not match the number of columns or rows in the table.
pathName columndelete columnDesc
Deletes the specified column given by columnDesc. ColumnDesc must be a valid column description. The tail column cannot be deleted and it is an error to specify it.
pathName columnlist
This command returns a list of identifiers for every column (except the tail) from left to right.
pathName columnmove columnDesc beforecolumnDesc
Moves the column specified by columnDesc to the left of the column specified by beforeDesc. Both columnDesc and beforeDesc must be valid column descriptions. If beforeDesc is the string tail, the column columnDesc will become the last column.
pathName columntypes
Returns the column types registered with table (both std editors and user registered editors)
pathName component table
Since hwtk::table is a compound widget wrapped on top of treectrl, this command returns the internal path for treectrl widget, which can then be used to execute a command directly on the treectrl itself.
pathName configure ?option? ?value option value …?
Query or modify the configuration options of the widget. 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 command returns an empty string. If option is specified with no value, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no option is specified, returns a list describing all of the available options for pathName.
pathName identify element x y
Returns the name of the element under the point given by x and y, or an empty string if the point does not lie within any element. x and y are pixel coordinates relative to the widget. Some widgets accept other identify subcommands.
pathName instate statespec ?script?
Test the widget’s state. If script is not specified, returns 1 if the widget state matches statespec and 0 otherwise. If script is specified, equivalent to
if{[pathNameinstatestateSpec]}script
pathName iscelleditable cell
Returns 1 if the given cell is editable, and 0 if it is not.
pathName refresh
Dismisses the editor.
Warning: Deprecated
pathName registertype type classname
Register the type of the column. Every column type is tightly associated with editor class name. The editors are posted against the cell where the user clicked. The table takes the input through the editors.
pathName reqheight
Return the height required to fit the contents of table. More accurate than winfo reqheight.
pathName reqwidth
Return the width required to fit the contents of table. More accurate than winfo reqwidth.
pathName rowcget rowDesc option
Returns the value for a given configuration option.
pathName rowconfigure rowDesc ?arg arg …?
Configures the row given by rowDesc. Valid options are -values, -background or -foreground. Arguments for -values must be given in the form of “[list column1 value1 column2 value2 …]”.
pathName rowdelete rowDesc
Deletes the row specified by rowDesc.
pathName rowinsert position rowDesc ?arg arg …?
Creates the new row at given position. To insert values in this row upon creation, use the -values option with an argument list of column value pairs (-values [list col1 $value1 col2 $value2...]). Returns the unique rowDesc for newly created row. Valid options are -values, -background or -foreground.
pathName rowlist
Returns the rows in the table.
pathName rowmove rowDesc beforeDesc
Moves the row specified by rowDesc to the top of the row specified by beforeDesc. Both rowDesc and beforeDesc must be valid row descriptions. If beforeDesc is the string end, the row rowDesc will become the last row.
pathName selectionadd row,column
Adds to the current selection a comma separated row,column pair.
pathName selectionclear
Clears the selection in the table.
pathName selectionget
Returns the current selection in the table as row,column pairs.
pathName selectiontoggle row,column row1, column …
Toggles the selection of the passed in row,column pairs.
pathName state ?stateSpec?
Modify or inquire widget state. If stateSpec is present, sets the widget state: for each flag in stateSpec, sets the corresponding flag or clears it if prefixed by an exclamation point. Returns a new state spec indicating which flags were changed:
setchanges[pathNamestatespec]
pathNamestate$changes
will restore pathName to the original state. If stateSpec is not specified, returns a list of the currently-enabled state flags.

Example

#::hwtk::table

proc SetValueCallback {row col value } { 
    puts "SetValueCallback value is $value for row: $row and col: $col"
    return true
}

proc GetValueList {col row} {
    return [list "Bay City" Detroit Flint Saginaw Troy]
}

::hwtk::dialog .d -title "::hwtk::table"
set table [::hwtk::table [.d recess].table]
pack $table -fill both -expand true

$table columncreate int -type int -text "Integer" -validatecommand "SetValueCallback %I %C %V"
$table columncreate double -type real -text "Double" -validatecommand "SetValueCallback %I %C %V"
$table columncreate color -type intcolor -image palette-16.png -validatecommand "SetValueCallback %I %C %V"
$table columncreate city -type combobox -text "Combobox" -valuelistcommand "GetValueList city" -validatecommand "SetValueCallback %I %C %V"
$table columncreate string -text "String" -validatecommand "SetValueCallback %I %C %V"

for {set j 1} {$j < 5} {incr j} {
    set color [expr {int( rand()*64)}]
    set values "int $j double $j.0 color $color city Troy string {String value $j}";"
    $table rowinsert end row$j -values $values 
}

.d post