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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       selection - Manipulate the X selection

SYNOPSIS
       selection option	?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       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
	      string.

       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
	      well.

	      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.

WIDGET FACILITIES
       The  text, entry, ttk::entry, listbox, spinbox and ttk::spinbox widgets
       have the	option -exportselection.  If a widget has this option  set  to
       boolean	true,  then (in	an unsafe interpreter) a selection made	in the
       widget is automatically written to the PRIMARY selection.

       A GUI event, for	example	<<PasteSelection>>, can	copy the  PRIMARY  se-
       lection to certain widgets.  This copy is implemented by	a widget bind-
       ing to the event.  The binding script makes appropriate	calls  to  the
       selection command.

PORTABILITY ISSUES
       On X11, the PRIMARY selection is	a system-wide feature of the X server,
       allowing	 communication	between	 different  processes  that  are   X11
       clients.

       On  Windows,  the  PRIMARY selection is not provided by the system, but
       only by Tk, and so it is	shared only between windows of a master	inter-
       preter and its unsafe slave interpreters.  It is	not shared between in-
       terpreters in different processes or different  threads.	  Each	master
       interpreter  has	 a separate PRIMARY selection that is shared only with
       its unsafe slaves.

SECURITY
       A safe interpreter cannot read from the PRIMARY selection  because  its
       selection  command  is  hidden.	 For this reason the PRIMARY selection
       cannot be written to the	Tk widgets of a	safe interpreter.

       A Tk widget can have its	option -exportselection	set to	boolean	 true,
       but  in	a safe interpreter this	option has no effect: writing from the
       widget to the PRIMARY selection is disabled.

       These are security features.  A	safe  interpreter  may	run  untrusted
       code,  and  it  is  a  security risk if this untrusted code can read or
       write the PRIMARY selection used	by other interpreters.

EXAMPLES
       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-1}]]
	      }

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

SEE ALSO
       clipboard(n)

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

Tk				      8.1			  selection(n)

NAME | SYNOPSIS | DESCRIPTION | WIDGET FACILITIES | PORTABILITY ISSUES | SECURITY | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=selection.tk86&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help