home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / selection.n < prev    next >
Encoding:
Text File  |  1993-04-01  |  6.3 KB  |  140 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/selection.n,v 1.8 93/04/01 09:52:55 ouster Exp $ SPRITE (Berkeley)
  22. '/" 
  23. .so man.macros
  24. .HS selection tk
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. selection \- Manipulate the X selection
  29. .SH SYNOPSIS
  30. \fBselection \fIoption\fR ?\fIarg arg ...\fR?
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. This command provides a Tcl interface to the X selection mechanism and
  36. implements the full selection functionality described in the
  37. X Inter-Client Communication Conventions Manual (ICCCM), except that it
  38. supports only the primary selection.
  39. .PP
  40. The first argument to \fBselection\fR determines the format of the
  41. rest of the arguments and the behavior of the command.  The following
  42. forms are currently supported:
  43. .TP
  44. \fBselection clear \fIwindow\fR
  45. .VS
  46. If there is a selection anywhere on \fIwindow\fR's display, clear it
  47. so that no window owns the selection anymore.  Returns an empty string.
  48. .VE
  49. .TP
  50. \fBselection get \fR?\fItype\fR?
  51. Retrieves the value
  52. of the primary selection and returns it as a result.
  53. \fBType\fR specifies the form in which the selection is to be
  54. returned (the desired ``target'' for conversion, in ICCCM
  55. terminology), and should be an
  56. atom name such as STRING or FILE_NAME;  see the Inter-Client
  57. Communication Conventions Manual for complete details.
  58. \fBType\fR defaults to STRING.  The selection owner may choose to
  59. return the selection in any of several different representation
  60. formats, such as STRING, ATOM, INTEGER, etc. (this format is
  61. different than the selection type;  see the ICCCM for all the
  62. confusing details).  If the selection is returned in
  63. a non-string format, such as INTEGER or ATOM, the \fBselection\fR
  64. command converts it to string format as a collection of fields
  65. separated by spaces:  atoms are converted to their
  66. textual names, and anything else is converted to hexadecimal
  67. integers.
  68. .TP
  69. \fBselection handle \fIwindow command \fR?\fItype\fR? ?\fIformat\fR?
  70. Creates a handler for selection requests, such that \fIcommand\fR will
  71. be executed whenever the primary selection is
  72. owned by \fIwindow\fR and someone attempts to retrieve it in the form
  73. given by \fItype\fR (e.g. \fItype\fR is specified in the \fBselection get\fR
  74. command).  \fIType\fR defaults to STRING.
  75. .VS
  76. If \fIcommand\fR is an empty string then any existing handler for
  77. \fIwindow\fR and \fItype\fR is removed.
  78. .VE
  79. .RS
  80. .PP
  81. When the selection is requested and \fIwindow\fR is the selection owner
  82. and \fItype\fR is the requested type, \fIcommand\fR will be executed
  83. as a Tcl command with two additional numbers appended to it
  84. (with space separators).  The two additional numbers
  85. are \fIoffset\fR and \fImaxBytes\fR:  \fIoffset\fR specifies a starting
  86. character position in the selection and \fImaxBytes\fR gives the maximum
  87. number of bytes to retrieve.  The command should return a value consisting
  88. of at most \fImaxBytes\fR of the selection, starting at position
  89. \fIoffset\fR.  For very large selections (larger than \fImaxBytes\fR)
  90. the selection will be retrieved using several invocations of \fIcommand\fR
  91. with increasing \fIoffset\fR values.  If \fIcommand\fR returns a string
  92. whose length is less than \fImaxBytes\fR, the return value is assumed to
  93. include all of the remainder of the selection;  if the length of
  94. \fIcommand\fR's result is equal to \fImaxBytes\fR then
  95. \fIcommand\fR will be invoked again, until it eventually
  96. returns a result shorter than \fImaxBytes\fR.  The value of \fImaxBytes\fR
  97. will always be relatively large (thousands of bytes).
  98. .PP
  99. If \fIcommand\fR returns an error then the selection retrieval is rejected
  100. .VS
  101. just as if the selection didn't exist at all.
  102. .VE
  103. .PP
  104. The \fIformat\fR argument specifies the representation that should be
  105. used to transmit the selection to the requester (the second column of
  106. Table 2 of the ICCCM), and defaults to STRING.  If \fIformat\fR is
  107. STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
  108. just in the form returned by \fIcommand\fR).  If \fIformat\fR is
  109. ATOM, then the return value from \fIcommand\fR is divided into fields
  110. separated by white space;  each field is converted to its atom value,
  111. and the 32-bit atom value is transmitted instead of the atom name.
  112. For any other \fIformat\fR, the return value from \fIcommand\fR is
  113. divided into fields separated by white space and each field is
  114. converted to a 32-bit integer;  an array of integers is transmitted
  115. to the selection requester.
  116. .PP
  117. The \fIformat\fR argument is needed only for compatibility with
  118. selection requesters that don't use Tk.  If the Tk toolkit is being
  119. used to retrieve the selection then the value is converted back to
  120. a string at the requesting end, so \fIformat\fR is
  121. irrelevant.
  122. .RE
  123. .TP
  124. \fBselection own \fR?\fIwindow\fR? ?\fIcommand\fR?
  125. .VS
  126. If \fIwindow\fR is specified, then it becomes the new selection owner
  127. and the command returns an empty string as result.
  128. The existing owner, if any, is notified that it has lost the selection.
  129. If \fIcommand\fR is specified, it is a Tcl script to execute when
  130. some other window claims ownership of the selection away from
  131. \fIwindow\fR.
  132. If neither \fIwindow\fR nor \fIcommand\fR is specified then
  133. the command returns the path name of the window in this application
  134. that owns the selection, or an empty string if no window in this
  135. application owns the selection.
  136. .VE
  137.  
  138. .SH KEYWORDS
  139. clear, format, handler, ICCCM, own, selection, target, type
  140.