NAME

hwtk::table - Create and manipulate tables

 

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 allow the user to manipulate the rows, columns and general appearance of the table widget. A table widget which can be one of two modes: view only or editable.

 

CLASS DIAGRAM

SYNOPSIS

hwtk::table - pathName ?option value? ...

 

STANDARD OPTIONS

-borderwidth, borderwidth, Borderwidth

-clientdata, clientData, ClientData

-height, height, Height

-helpcommand, helpcommand, Command

-width, width, Width

 

WIDGET-SPECIFIC OPTIONS

Command-Line Name: -closeeditor

Database Name: closeeditor

Database Class: Closeeditor

Boolean option when set to true, the editor unposts upon succesful set value. Default is set to false.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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.

 

Command-Line Name: -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 COMMAND

In addition to the standard configure, cget, identify, instate, and state commands, table support the following additional 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 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 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 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.

 

EXAMPLES

 

#::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