From 06e0381cd6b26bb2a980d4452a3bf9c04f43d11d Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 30 Oct 2007 15:20:19 +0000 Subject: Clarify UTF8_STRING handling. [Bug 1778563] --- ChangeLog | 2 ++ doc/selection.n | 31 ++++++++++++++++++------------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2a7c6aa..d20121c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2007-10-30 Donal K. Fellows + * doc/selection.n: Clarify UTF8_STRING handling. [Bug 1778563] + * doc/text.n: Clarify search subccommand docs. [Bug 1622919] 2007-10-29 Jeff Hobbs 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 -- cgit v0.12