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

FreeBSD Manual Pages


home | help
Tk_CreateSelHandler(3)	     Tk	Library	Procedures	Tk_CreateSelHandler(3)


       Tk_CreateSelHandler,  Tk_DeleteSelHandler  - arrange to handle requests
       for a selection

       #include	<tk.h>

       Tk_CreateSelHandler(tkwin, selection, target, proc, clientData, format)

       Tk_DeleteSelHandler(tkwin, selection, target)

       Tk_Window tkwin (in)			 Window	for  which  proc  will
						 provide   selection  informa-

       Atom selection (in)			 The name of the selection for
						 which	proc  will provide se-
						 lection information.

       Atom target (in)				 Form in which proc  can  pro-
						 vide	the   selection	 (e.g.
						 STRING	or FILE_NAME).	Corre-
						 sponds	 to  type arguments in
						 selection commands.

       Tk_SelectionProc	*proc (in)		 Procedure to invoke  whenever
						 the selection is owned	by tk-
						 win and  the  selection  con-
						 tents	are  requested	in the
						 format	given by target.

       ClientData clientData (in)		 Arbitrary one-word  value  to
						 pass to proc.

       Atom format (in)				 If the	selection requestor is
						 not in	this  process,	format
						 determines the	representation
						 used to transmit  the	selec-
						 tion to its requestor.

       Tk_CreateSelHandler  arranges  for  a particular	procedure (proc) to be
       called whenever selection is owned by tkwin and the selection  contents
       are requested in	the form given by target.  Target should be one	of the
       entries defined in the left column of Table 2  of  the  X  Inter-Client
       Communication  Conventions Manual (ICCCM) or any	other form in which an
       application is willing to present the selection.	 The most common  form
       is STRING.

       Proc should have	arguments and result that match	the type Tk_Selection-
	      typedef int Tk_SelectionProc(
		      ClientData clientData,
		      int offset,
		      char *buffer,
		      int maxBytes);
       The clientData parameter	to proc	is a copy of the  clientData  argument
       given  to  Tk_CreateSelHandler.	Typically, clientData points to	a data
       structure containing application-specific information that is needed to
       retrieve	 the  selection.  Offset specifies an offset position into the
       selection, buffer specifies a location at  which	 to  copy  information
       about  the selection, and maxBytes specifies the	amount of space	avail-
       able at buffer.	Proc should place a NULL-terminated string  at	buffer
       containing  maxBytes or fewer characters	(not including the terminating
       NULL), and it should return a count of the number of  non-NULL  charac-
       ters stored at buffer.  If the selection	no longer exists (e.g. it once
       existed but the user deleted the	range of  characters  containing  it),
       then proc should	return -1.

       When  transferring large	selections, Tk will break them up into smaller
       pieces (typically a few thousand	bytes each) for	more efficient	trans-
       mission.	 It will do this by calling proc one or	more times, using suc-
       cessively higher	values of offset to retrieve  successive  portions  of
       the  selection.	 If  proc  returns a count less	than maxBytes it means
       that the	entire remainder of  the  selection  has  been	returned.   If
       proc's return value is maxBytes it means	there may be additional	infor-
       mation in the selection,	so Tk must make	another	call to	 proc  to  re-
       trieve the next portion.

       Proc  always  returns  selection	information in the form	of a character
       string.	However, the ICCCM allows for information  to  be  transmitted
       from  the  selection owner to the selection requestor in	any of several
       formats,	such as	a string, an array of atoms,  an  array	 of  integers,
       etc.   The format argument to Tk_CreateSelHandler indicates what	format
       should be used to transmit the selection	to its requestor (see the mid-
       dle  column  of	Table  2 of the	ICCCM for examples).  If format	is not
       STRING, then Tk will take the value returned by	proc  and  divided  it
       into  fields separated by white space.  If format is ATOM, then Tk will
       return the selection as an array	of atoms, with each  field  in	proc's
       result treated as the name of one atom.	For any	other value of format,
       Tk will return the selection as an array	of 32-bit  values  where  each
       field  of  proc's  result  is  treated  as a number and translated to a
       32-bit value.  In any event, the	format atom is returned	to the	selec-
       tion requestor along with the contents of the selection.

       If  Tk_CreateSelHandler	is  called when	there already exists a handler
       for selection and target	on tkwin, then the  existing  handler  is  re-
       placed with a new one.

       Tk_DeleteSelHandler  removes the	handler	given by tkwin,	selection, and
       target, if such a handler exists.  If there is no such handler then  it
       has no effect.

       format, handler,	selection, target

Tk				      4.0		Tk_CreateSelHandler(3)


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

home | help