Tcl 9.1/Tk9.1 Documentation > Tk Commands, version 9.1a1 > attribtable

Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

NAME

attribtable — Create an attribute table, used to query and modify arbitrary data attached to any widget.

SYNOPSIS

DESCRIPTION

tableName set pathName name value ?name value ...?

tableName get pathName ?name ?defaultValue??

tableName unset pathName name ?name ...?

tableName clear pathName

tableName exists pathName ?name?

tableName names pathName

tableName pathnames

KEYWORDS

NAME

SYNOPSIS

DESCRIPTION

An attribute table is used to query and modify arbitrary data attached to any widget. These data are commonly called attributes.

If an attribute table of the given name already exists then it is replaced with the new one and all the attributes of all widgets set using the old table instance will be unset.

REMARK 1: When the tableName command is deleted (via rename tableName "" or by deleting the containing namespace), all the attributes of all widgets set using this command are automatically unset and the underlying hash table is deleted. This will free all the memory used by the table.

REMARK 2: When a widget is destroyed, all of its attributes set by all attribute table commands are automatically unset. This will free all the memory used by the widget's attributes.

The command tableName created by this command has the signature

tableName set|get|unset|clear|exists|names|pathnames args

In the description of the supported forms below, pathName specifies a widget whose attributes are being queried or modified via the tableName command.

tableName set pathName name value ?name value ...?

Sets (i.e., adds or updates) the attributes identified by the name arguments to the values given by the value arguments. Returns an empty string. Example:

# Save and then change the button's text
tk attribtable table
table set .btn prevText [.btn cget -text]
	.btn configure -text "NewText"

tableName get pathName ?name ?defaultValue??

If name is specified then returns the corresponding attribute value, or an empty string or defaultValue (if given) if no corresponding value exists. Otherwise returns a list consisting of all attribute names and values of the widget pathName. Example:

# Restore the button's previous text
	.btn configure -text [table get .btn prevText]

tableName unset pathName name ?name ...?

Unsets the attributes identified by the name arguments. Returns an empty string. Example:

table unset .btn prevText

tableName clear pathName

Unsets all attributes and removes pathName from the list of those widgets that have attributes set via tableName set. Returns an empty string. Example:

table clear .btn

tableName exists pathName ?name?

If the optional argument is present then returns 1 if the attribute identified by name exists and 0 otherwise. Without the optional argument the return value is 1 if the widget pathName has at least one attribute set via tableName set and 0 otherwise. Example:

if [table exists .btn prevText] {
    # Restore the button's previous text
    	.btn configure -text [table get .btn prevText]
}

tableName names pathName

Returns a list consisting of all attribute names of the widget pathName. Example:

puts "attribute names for .btn: [table names .btn]"

tableName pathnames

Returns a list consisting of the path names of all widgets that have attributes set via tableName set. Example:

puts "widgets in table: [table pathnames]"

KEYWORDS