Merged branch cargo into trunk (see TIP 729).

Author: csaba

doc/attribtable.n

@@ -0,0 +1,154 @@
+.\"
+.\" Copyright (c) 2025 Csaba Nemethi
+.\"
+.\" See the file "license.terms" for information on usage and redistribution
+.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+.\"
+.TH tk attribtable n 9.1 "" Tk "Tk Built-in Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tk attribtable \- Create an attribute table, used to query and modify
+arbitrary data attached to any widget.
+.SH SYNOPSIS
+\fBtk attribtable \fItableName\fR
+.BE
+.SH DESCRIPTION
+.PP
+This command creates an attribute table of the name \fItableName\fR,
+implemented as a hash table and accessible as a command in the namespace of
+the calling context if not fully qualified, and returns the fully qualified
+name of the command just created.
+.PP
+An attribute table is used to query and modify arbitrary data attached to any
+widget.  These data are commonly called \fIattributes\fR.
+.PP
+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.
+.PP
+\fBREMARK 1:\fR  When the \fItableName\fR command is deleted (via \fBrename\fR
+\fItableName\fR "" 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.
+.PP
+\fBREMARK 2:\fR  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.
+.PP
+The command \fItableName\fR created by this command has the signature
+.PP
+.CS
+\fItableName\fR \fBset\fR|\fBget\fR|\fBunset\fR|\fBclear\fR|\fBexists\fR|\fBnames\fR|\fBpathnames\fR \fIargs\fR
+.CE
+.PP
+In the description of the supported forms below, \fIpathName\fR specifies a
+widget whose attributes are being queried or modified via the \fItableName\fR
+command.
+.\" METHOD: set
+.TP
+\fItableName\fR \fBset\fR \fIpathName name value\fR ?\fIname value\fR ...?
+.
+Sets (i.e., adds or updates) the attributes identified by the \fIname\fR
+arguments to the values given by the \fIvalue\fR arguments.  Returns an empty
+string.  Example:
+.RS
+.PP
+.CS
+# Save and then change the button's text
+\fBtk attribtable\fR table
+table \fBset\fR .btn prevText [.btn cget -text]
+\&.btn configure -text "NewText"
+.CE
+.RE
+.\" METHOD: get
+.TP
+\fItableName\fR \fBget\fR \fIpathName\fR ?\fIname\fR ?\fIdefaultValue\fR??
+.
+If \fIname\fR is specified then returns the corresponding attribute value, or
+an empty string or \fIdefaultValue\fR (if given) if no corresponding value
+exists.  Otherwise returns a list consisting of all attribute names and values
+of the widget \fIpathName\fR.  Example:
+.RS
+.PP
+.CS
+# Restore the button's previous text
+\&.btn configure -text [table \fBget\fR .btn prevText]
+.CE
+.RE
+.\" METHOD: unset
+.TP
+\fItableName\fR \fBunset\fR \fIpathName name\fR ?\fIname\fR ...?
+.
+Unsets the attributes identified by the \fIname\fR arguments.  Returns an
+empty string.  Example:
+.RS
+.PP
+.CS
+table \fBunset\fR .btn prevText
+.CE
+.RE
+.\" METHOD: clear
+.TP
+\fItableName\fR \fBclear\fR \fIpathName\fR
+.
+Unsets all attributes and removes \fIpathName\fR from the list of those
+widgets that have attributes set via \fItableName\fR \fBset\fR.  Returns an
+empty string.  Example:
+.RS
+.PP
+.CS
+table \fBclear\fR .btn
+.CE
+.RE
+.\" METHOD: exists
+.TP
+\fItableName\fR \fBexists\fR \fIpathName\fR ?\fIname\fR?
+.
+If the optional argument is present then returns \fB1\fR if the attribute
+identified by \fIname\fR exists and \fB0\fR otherwise.  Without the optional
+argument the return value is \fB1\fR if the widget \fIpathName\fR has at
+least one attribute set via \fItableName\fR \fBset\fR and \fB0\fR otherwise.
+Example:
+.RS
+.PP
+.CS
+if [table \fBexists\fR .btn prevText] {
+    # Restore the button's previous text
+    \&.btn configure -text [table \fBget\fR .btn prevText]
+}
+.CE
+.RE
+.\" METHOD: names
+.TP
+\fItableName\fR \fBnames\fR \fIpathName\fR
+.
+Returns a list consisting of all attribute names of the widget
+\fIpathName\fR.  Example:
+.RS
+.PP
+.CS
+puts "attribute names for .btn: [table \fBnames\fR .btn]"
+.CE
+.RE
+.\" METHOD: pathnames
+.TP
+\fItableName\fR \fBpathnames\fR
+.
+Returns a list consisting of the path names of all widgets that have
+attributes set via \fItableName\fR \fBset\fR.
+Example:
+.RS
+.PP
+.CS
+puts "widgets in table: [table \fBpathnames\fR]"
+.CE
+.RE
+.SH KEYWORDS
+widget, attribute, attribute table
+.\" Local Variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:

doc/tk.n

@@ -45,13 +45,21 @@ be able to find some options for the application.
 If sends have been disabled by deleting the \fBsend\fR command,
 this command will reenable them and recreate the \fBsend\fR
 command.
+.\" METHOD: attribtable
+.TP
+\fBtk attribtable \fItableName\fR
+.
+This command creates an attribute table of the name \fItableName\fR as a
+command in the namespace of the calling context if not fully qualified.  An
+attribute table is used to query and modify arbitrary data attached to any
+widget.  For more details see the \fBattribtable\fR manual page.
 .\" METHOD: busy
 .TP
 \fBtk busy \fIsubcommand\fR ...
 .
 This command controls the marking of window hierarchies as
 .QW busy ,
-rendering them non-interactive while some other operation is proceeding. For
+rendering them non-interactive while some other operation is proceeding.  For
 more details see the \fBbusy\fR manual page.
 .\" METHOD: caret
 .TP
@@ -71,7 +79,7 @@ of the specified \fIwindow\fR if none is given.
 \fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR?
 .
 Returns a positive integer, the number of milliseconds since the last
-time the user interacted with the system. If the \fB\-displayof\fR
+time the user interacted with the system.  If the \fB\-displayof\fR
 option is given then the return value refers to the display of
 \fIwindow\fR; otherwise it refers to the display of the application's
 main window.
@@ -81,23 +89,23 @@ main window.
 is not supported by the system, and in safe interpreters.
 .PP
 If the literal string \fBreset\fR is given as an additional argument,
-the timer is reset and an empty string is returned. Resetting the
+the timer is reset and an empty string is returned.  Resetting the
 inactivity time is forbidden in safe interpreters and will throw an
 error if tried.
 .RE
 .\" METHOD: fontchooser
 .TP
 \fBtk fontchooser \fIsubcommand\fR ...
 .
-Controls the Tk font selection dialog. For more details see the
+Controls the Tk font selection dialog.  For more details see the
 \fBfontchooser\fR manual page.
 .\" METHOD: print
 .TP
 \fBtk print \fIwindow\fR
 .
 The \fBtk print\fR command posts a dialog that allows users to print output
-from the \fBcanvas\fR and \fBtext\fR widgets. The printing will be done using
-platform-native APIs and dialogs where available. For more details see the
+from the \fBcanvas\fR and \fBtext\fR widgets.  The printing will be done using
+platform-native APIs and dialogs where available.  For more details see the
 \fBprint\fR manual page.
 .\" METHOD: scaling
 .TP
@@ -127,25 +135,25 @@ accommodate the new scaling factor.
 .RE
 .\" METHOD: sysnotify
 .TP
-\fBtk sysnotify \fP \fItitle\fP? \fImessage\fP?
+\fBtk sysnotify \fItitle message\fR
 .
 The \fBtk sysnotify\fP  command creates a platform-specific system
-notification alert. Its intent is to provide a brief, unobtrusive
+notification alert.  Its intent is to provide a brief, unobtrusive
 notification to the user by popping up a window that briefly appears in a
-corner of the screen. For more details see the \fBsysnotify\fR manual page.
+corner of the screen.  For more details see the \fBsysnotify\fR manual page.
 .\" METHOD: systray
 .TP
-\fBtk systray create\fP \fIsubcommand...\fP
+\fBtk systray \fIsubcommand\fR ...
 .
 The \fBtk systray\fP command creates an icon in the platform-specific
-tray. For more details see the \fBsystray\fR manual page.
+tray.  For more details see the \fBsystray\fR manual page.
 .\" METHOD: useinputmethods
 .TP
 \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR?
 .
 Sets and queries the state of whether Tk should use XIM (X Input Methods)
 for filtering events.  The resulting state is returned.  XIM is used in
-some locales (i.e., Japanese, Korean), to handle special input devices. This
+some locales (i.e., Japanese, Korean), to handle special input devices.  This
 feature is only significant on X.  If XIM support is not available, this
 will always return 0.  If the \fIwindow\fR argument is omitted, it defaults
 to the main window.  If the \fIboolean\fR argument is omitted, the current
@@ -158,9 +166,10 @@ Returns the current Tk windowing system, one of
 \fBx11\fR (X11-based), \fBwin32\fR (MS Windows),
 or \fBaqua\fR (macOS Aqua).
 .SH "SEE ALSO"
-busy(n), fontchooser(n), print(n), send(n), sysnotify(n), systray(n), winfo(n)
+attribtable(n), busy(n), fontchooser(n), print(n), send(n), sysnotify(n),
+systray(n), winfo(n)
 .SH KEYWORDS
-application name, print, send, sysnotify, systray
+application name, attribute, print, send, sysnotify, systray
 '\" Local Variables:
 '\" mode: nroff
 '\" End: