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.

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