home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _2def1c1c855c61d7f648586f20fafd9a < prev    next >
Encoding:
Text File  |  2004-06-01  |  7.0 KB  |  164 lines
  1. #  Copyright (c) 1990-1994 The Regents of the University of California.
  2. #  Copyright (c) 1994-1996 Sun Microsystems, Inc.
  3. #  See the file "license.terms" for information on usage and redistribution
  4. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  5. #
  6. #
  7.  
  8. =head1 NAME
  9.  
  10. Tk::Selection - Manipulate the X selection
  11.  
  12. =for category User Interaction
  13.  
  14. =head1 SYNOPSIS
  15.  
  16. I<$widget>-E<gt>B<Selection>I<Option>?(I<args>)?
  17.  
  18. =head1 DESCRIPTION
  19.  
  20. This command provides an interface to the X selection mechanism and
  21. implements the full selection functionality described in the
  22. X Inter-Client Communication Conventions Manual (ICCCM).
  23.  
  24. The widget object used to invoke the methods below determines which
  25. display is used to access the selection.
  26. In order to avoid conflicts with B<selection> methods of widget classes
  27. (e.g. B<Text>) this set of methods uses the prefix B<Selection>.
  28. The following methods are currently supported:
  29.  
  30. =over 4
  31.  
  32. =item I<$widget>-E<gt>B<SelectionClear>?(B<-selection>=E<gt>I<selection>)?
  33.  
  34. If I<selection> exists anywhere on I<$widget>'s display, clear it
  35. so that no window owns the selection anymore.  I<Selection>
  36. specifies the X selection that should be cleared, and should be an
  37. atom name such as PRIMARY or CLIPBOARD; see the Inter-Client
  38. Communication Conventions Manual for complete details.
  39. I<Selection> defaults to PRIMARY.
  40. Returns an empty string.
  41.  
  42. =item I<$widget>-E<gt>B<SelectionGet>?(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?)?
  43.  
  44. Retrieves the value of I<selection> from I<$widget>'s display and
  45. returns it as a result.  I<Selection> defaults to PRIMARY.
  46.  
  47. I<Type> specifies the form in which the selection is to be returned
  48. (the desired ``target'' for conversion, in ICCCM terminology), and
  49. should be an atom name such as STRING or FILE_NAME; see the
  50. Inter-Client Communication Conventions Manual for complete details.
  51. I<Type> defaults to STRING.  The selection owner may choose to
  52. return the selection in any of several different representation
  53. formats, such as STRING, ATOM, INTEGER, etc. (this format is different
  54. than the selection type; see the ICCCM for all the confusing details).
  55.  
  56. If I<format> is not STRING then things get messy, the following
  57. description is from the Tcl/Tk man page as yet incompetely translated for
  58. the perl version - it is misleading at best.
  59.  
  60. If the selection is returned in a non-string format, such as INTEGER
  61. or ATOM, the B<SelectionGet> converts it to a list of perl
  62. values: atoms are converted to their
  63. textual names, and anything else is converted integers.
  64.  
  65. A goal of the perl port is to provide better handling of different
  66. formats than Tcl/Tk does, which should be possible given perl's
  67. wider range of ``types''. Although some thought went into this
  68. in very early days of perl/Tk what exactly happens is still
  69. "not quite right" and subject to change.
  70.  
  71. =item I<$widget>-E<gt>B<SelectionHandle>(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?,?B<-format>=E<gt>I<format>? I<callback>)
  72.  
  73. Creates a handler for selection requests, such that I<callback> will
  74. be executed whenever I<selection> is owned by I<$widget> and
  75. someone attempts to retrieve it in the form given by I<type>
  76. (e.g. I<type> is specified in the B<selection get> command).
  77. I<Selection> defaults to PRIMARY, I<type> defaults to STRING, and
  78. I<format> defaults to STRING.  If I<callback> is an empty string
  79. then any existing handler for I<$widget>, I<type>, and
  80. I<selection> is removed.
  81.  
  82. =over 8
  83.  
  84. When I<selection> is requested, I<$widget> is the selection owner,
  85. and I<type> is the requested type, I<callback> will be executed
  86. with two additional arguments.
  87. The two additional arguments
  88. are I<offset> and I<maxBytes>:  I<offset> specifies a starting
  89. character position in the selection and I<maxBytes> gives the maximum
  90. number of bytes to retrieve.  The command should return a value consisting
  91. of at most I<maxBytes> of the selection, starting at position
  92. I<offset>.  For very large selections (larger than I<maxBytes>)
  93. the selection will be retrieved using several invocations of I<callback>
  94. with increasing I<offset> values.  If I<callback> returns a string
  95. whose length is less than I<maxBytes>, the return value is assumed to
  96. include all of the remainder of the selection;  if the length of
  97. I<callback>'s result is equal to I<maxBytes> then
  98. I<callback> will be invoked again, until it eventually
  99. returns a result shorter than I<maxBytes>.  The value of I<maxBytes>
  100. will always be relatively large (thousands of bytes).
  101.  
  102. If I<callback> returns an error (e.g. via B<die>)
  103. then the selection retrieval is rejected
  104. just as if the selection didn't exist at all.
  105.  
  106. The I<format> argument specifies the representation that should be
  107. used to transmit the selection to the requester (the second column of
  108. Table 2 of the ICCCM), and defaults to STRING.  If I<format> is
  109. STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
  110. just in the form returned by I<command>).
  111.  
  112. If I<format> is not STRING then things get messy, the following
  113. description is from the Tcl/Tk man page as yet untranslated for
  114. the perl version - it is misleading at best.
  115.  
  116. If I<format> is
  117. ATOM, then the return value from I<command> is divided into fields
  118. separated by white space;  each field is converted to its atom value,
  119. and the 32-bit atom value is transmitted instead of the atom name.
  120. For any other I<format>, the return value from I<command> is
  121. divided into fields separated by white space and each field is
  122. converted to a 32-bit integer;  an array of integers is transmitted
  123. to the selection requester.
  124.  
  125. The I<format> argument is needed only for compatibility with
  126. many selection requesters, except Tcl/Tk.  If Tcl/Tk is being
  127. used to retrieve the selection then the value is converted back to
  128. a string at the requesting end, so I<format> is
  129. irrelevant.
  130.  
  131. A goal of the perl port is to provide better handling of different
  132. formats than Tcl/Tk does, which should be possible given perl's
  133. wider range of ``types''. Although some thought went into this
  134. in very early days of perl/Tk what exactly happens is still
  135. "not quite right" and subject to change.
  136.  
  137. =item I<$widget>-E<gt>B<SelectionOwner>?(B<-selection>=E<gt>I<selection>)?
  138.  
  139. B<SelectionOwner> returns the
  140. window in this application that owns I<selection> on the display
  141. containing I<$widget>, or an empty string if no window in this
  142. application owns the selection.  I<Selection> defaults to PRIMARY.
  143.  
  144. =item I<$widget>-E<gt>B<SelectionOwn>?(?B<-command>=E<gt>I<callback>?,?B<-selection>=E<gt>I<selection>?)?
  145.  
  146. B<SelectionOwn> causes I<$widget> to become
  147. the new owner of I<selection> on I<$widget>'s display, returning
  148. an empty string as result. The existing owner, if any, is notified
  149. that it has lost the selection.
  150. If I<callback> is specified, it will be executed when
  151. some other window claims ownership of the selection away from
  152. I<$widget>.  I<Selection> defaults to PRIMARY.
  153.  
  154. =back
  155.  
  156. =back
  157.  
  158. =head1 KEYWORDS
  159.  
  160. clear, format, handler, ICCCM, own, selection, target, type
  161.  
  162. =cut
  163.  
  164.