summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2007-10-30 15:20:19 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2007-10-30 15:20:19 (GMT)
commit06e0381cd6b26bb2a980d4452a3bf9c04f43d11d (patch)
tree4fe477dcb740e136bbe2ce4d07599e90715c453c /doc
parentc2ac4e4f1a6af8291b828ddb4d6b48222b70b180 (diff)
downloadtk-06e0381cd6b26bb2a980d4452a3bf9c04f43d11d.zip
tk-06e0381cd6b26bb2a980d4452a3bf9c04f43d11d.tar.gz
tk-06e0381cd6b26bb2a980d4452a3bf9c04f43d11d.tar.bz2
Clarify UTF8_STRING handling. [Bug 1778563]
Diffstat (limited to 'doc')
-rw-r--r--doc/selection.n31
1 files changed, 18 insertions, 13 deletions
diff --git a/doc/selection.n b/doc/selection.n
index 80e8031..af2072b 100644
--- a/doc/selection.n
+++ b/doc/selection.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: selection.n,v 1.10 2007/10/29 16:04:14 dkf Exp $
+'\" RCS: @(#) $Id: selection.n,v 1.11 2007/10/30 15:20:21 dkf Exp $
'\"
.so man.macros
.TH selection n 8.1 Tk "Tk Built-In Commands"
@@ -54,22 +54,27 @@ should be an atom name such as STRING or FILE_NAME; see the
Inter-Client Communication Conventions Manual for complete details.
\fIType\fR defaults to STRING. The selection owner may choose to
return the selection in any of several different representation
-formats, such as STRING, ATOM, INTEGER, etc. (this format is different
+formats, such as STRING, UTF8_STRING, ATOM, INTEGER, etc. (this format
+is different
than the selection type; see the ICCCM for all the confusing details).
If the selection is returned in a non-string format, such as INTEGER
or ATOM, the \fBselection\fR command converts it to string format as a
collection of fields separated by spaces: atoms are converted to their
textual names, and anything else is converted to hexadecimal integers.
+Note that \fBselection get\fR does not retrieve the selection in the
+UTF8_STRING format unless told to.
.TP
-\fBselection handle\fR ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-format\fR \fIformat\fR? \fIwindow command\fR
+\fBselection handle\fR ?\fB\-selection\fR \fIs\fR? ?\fB\-type\fR \fIt\fR? ?\fB\-format\fR \fIf\fR? \fIwindow command\fR
Creates a handler for selection requests, such that \fIcommand\fR will
-be executed whenever \fIselection\fR is owned by \fIwindow\fR and
-someone attempts to retrieve it in the form given by \fItype\fR
-(e.g. \fItype\fR is specified in the \fBselection get\fR command).
-\fISelection\fR defaults to PRIMARY, \fItype\fR defaults to STRING, and
-\fIformat\fR defaults to STRING. If \fIcommand\fR is an empty string
-then any existing handler for \fIwindow\fR, \fItype\fR, and
-\fIselection\fR is removed.
+be executed whenever selection \fIs\fR is owned by \fIwindow\fR and
+someone attempts to retrieve it in the form given by type \fIt\fR
+(e.g. \fIt\fR is specified in the \fBselection get\fR command).
+\fIS\fR defaults to PRIMARY, \fIt\fR defaults to STRING, and
+\fIf\fR defaults to STRING. If \fIcommand\fR is an empty string
+then any existing handler for \fIwindow\fR, \fIt\fR, and
+\fIs\fR is removed.
+Note that when the selection is handled as type STRING it is also
+automatically handled as type UTF8_STRING as well.
.RS
.PP
When \fIselection\fR is requested, \fIwindow\fR is the selection owner,
@@ -98,7 +103,9 @@ The \fIformat\fR argument specifies the representation that should be
used to transmit the selection to the requester (the second column of
Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is
STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
-just in the form returned by \fIcommand\fR). If \fIformat\fR is
+just in the form returned by \fIcommand\fR, in the system \fBencoding\fR;
+the UTF8_STRING format always uses UTF-8 as its encoding).
+If \fIformat\fR is
ATOM, then the return value from \fIcommand\fR is divided into fields
separated by white space; each field is converted to its atom value,
and the 32-bit atom value is transmitted instead of the atom name.
@@ -165,9 +172,7 @@ proc lost {} {
puts "Lost selection"
}
.CE
-
.SH "SEE ALSO"
clipboard(n)
-
.SH KEYWORDS
clear, format, handler, ICCCM, own, selection, target, type