Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
selection(n)		     Tk	Built-In Commands		  selection(n)


       selection - Manipulate the X selection

       selection option	?arg arg ...?

       This  command provides a	Tcl interface to the X selection mechanism and
       implements the full selection functionality described in	the  X	Inter-
       Client Communication Conventions	Manual (ICCCM).

       Note  that  for	management of the CLIPBOARD selection (see below), the
       clipboard command may also be used.

       The first argument to selection determines the format of	 the  rest  of
       the arguments and the behavior of the command.  The following forms are
       currently supported:

       selection clear ?-displayof window? ?-selection selection?
	      If selection exists anywhere on window's display,	 clear	it  so
	      that  no window owns the selection anymore.  Selection specifies
	      the X selection that should be cleared, and should  be  an  atom
	      name such	as PRIMARY or CLIPBOARD; see the Inter-Client Communi-
	      cation Conventions Manual	for complete details.	Selection  de-
	      faults  to PRIMARY and window defaults to	".".  Returns an empty

       selection get ?-displayof window? ?-selection selection?	?-type type?
	      Retrieves	the value of selection from window's display  and  re-
	      turns  it	as a result.  Selection	defaults to PRIMARY and	window
	      defaults to ".".	Type specifies the form	in which the selection
	      is to be returned	(the desired "target" for conversion, in ICCCM
	      terminology), and	should be an  atom  name  such	as  STRING  or
	      FILE_NAME; see the Inter-Client Communication Conventions	Manual
	      for complete details.  Type defaults to STRING.	The  selection
	      owner  may choose	to return the selection	in any of several dif-
	      ferent representation  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  se-
	      lection  is  returned in a non-string format, such as INTEGER or
	      ATOM, the	selection 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 hexadeci-
	      mal integers.  Note that selection get does not retrieve the se-
	      lection in the UTF8_STRING format	unless told to.

       selection handle	?-selection s? ?-type t? ?-format f? window command
	      Creates a	handler	for selection requests,	such that command will
	      be  executed whenever selection s	is owned by window and someone
	      attempts to retrieve it in the form given	by type	t (e.g.	 t  is
	      specified	in the selection get command).	S defaults to PRIMARY,
	      t	defaults to STRING, and	f defaults to STRING.  If  command  is
	      an  empty	 string	then any existing handler for window, t, and s
	      is removed.  Note	that when the selection	 is  handled  as  type
	      STRING  it  is also automatically	handled	as type	UTF8_STRING as

	      When selection is	requested, window is the selection owner,  and
	      type  is	the  requested type, command will be executed as a Tcl
	      command with two additional numbers appended to it  (with	 space
	      separators).   The  two  additional  numbers are offset and max-
	      Chars:  offset specifies a starting character  position  in  the
	      selection	and maxChars gives the maximum number of characters to
	      retrieve.	 The command should return a value  consisting	of  at
	      most  maxChars  of  the  selection, starting at position offset.
	      For very large selections	(larger	than maxChars)	the  selection
	      will  be retrieved using several invocations of command with in-
	      creasing offset values.	If  command  returns  a	 string	 whose
	      length is	less than maxChars, the	return value is	assumed	to in-
	      clude all	of the remainder of the	selection;  if the  length  of
	      command's	 result	 is equal to maxChars then command will	be in-
	      voked again, until it eventually returns a result	 shorter  than
	      maxChars.	 The value of maxChars will always be relatively large
	      (thousands of characters).

	      If command returns an error then the selection retrieval is  re-
	      jected just as if	the selection did not exist at all.

	      The  format argument specifies the representation	that should be
	      used to transmit the selection to	the requester (the second col-
	      umn of Table 2 of	the ICCCM), and	defaults to STRING.  If	format
	      is STRING, the selection is transmitted as 8-bit	ASCII  charac-
	      ters  (i.e.  just	in the form returned by	command, in the	system
	      encoding;	the UTF8_STRING	format always uses UTF-8 as its	encod-
	      ing).   If format	is ATOM, then the return value from command is
	      divided into fields separated by white  space;   each  field  is
	      converted	to its atom value, and the 32-bit atom value is	trans-
	      mitted instead of	the atom name.	For any	other format, the  re-
	      turn  value  from	 command  is  divided into fields separated by
	      white space and each field is converted to a 32-bit integer;  an
	      array of integers	is transmitted to the selection	requester.

	      The format argument is needed only for compatibility with	selec-
	      tion requesters that do not use Tk.  If Tk is being used to  re-
	      trieve  the  selection  then  the	 value	is converted back to a
	      string at	the requesting end, so format is irrelevant.

       selection own ?-displayof window? ?-selection selection?

       selection own ?-command command?	?-selection selection? window
	      The first	form of	selection own returns the  path	 name  of  the
	      window  in  this	application that owns selection	on the display
	      containing window, or an empty string if no window in  this  ap-
	      plication	owns the selection.  Selection defaults	to PRIMARY and
	      window defaults to ".".

       The second form of selection own	causes window to become	the new	 owner
       of  selection on	window's display, returning an empty string as result.
       The existing owner, if any, is notified that it has lost	the selection.
       If  command is specified, it is a Tcl script to execute when some other
       window claims ownership of the selection	away from  window.   Selection
       defaults	to PRIMARY.

       On  X11 platforms, one of the standard selections available is the SEC-
       ONDARY selection. Hardly	anything uses it, but here is how to  read  it
       using Tk:
	      set selContents [selection get -selection	SECONDARY]

       Many different types of data may	be available for a selection; the spe-
       cial type TARGETS allows	you to get a list of available types:
	      foreach type [selection get -type	TARGETS] {
		 puts "Selection PRIMARY supports type $type"

       To claim	the selection, you must	first set up a handler to  supply  the
       data for	the selection.	Then you have to claim the selection...
	      #	Set up the data	handler	ready for incoming requests
	      set foo "This is a string	with some data in it...	blah blah"
	      selection	handle -selection SECONDARY . getData
	      proc getData {offset maxChars} {
		 puts "Retrieving selection starting at	$offset"
		 return	[string	range $::foo $offset [expr {$offset+$maxChars}]]

	      #	Now we grab the	selection itself
	      puts "Claiming selection"
	      selection	own -command lost -selection SECONDARY .
	      proc lost	{} {
		 puts "Lost selection"


       clear, format, handler, ICCCM, own, selection, target, type

Tk				      8.1			  selection(n)


Want to link to this manual page? Use this URL:

home | help