Tk_CreateSelHandler(3)

______________________________________________________________________________

NAME

       Tk_CreateSelHandler,  Tk_DeleteSelHandler  - arrange to handle requests
       for a selection

SYNOPSIS

       #include <tk.h>

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

       Tk_DeleteSelHandler(tkwin, selection, target)

ARGUMENTS

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

       Atom               selection    (in)      The name of the selection for
                                                 which   proc   will   provide
                                                 selection 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
                                                 tkwin 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
                                                 isn't in this process, format
                                                 determines the representation
                                                 used to transmit  the  selec-
                                                 tion to its requestor.
_________________________________________________________________

DESCRIPTION

       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-
       Proc:
              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
       retrieve 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
       replaced 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.

KEYWORDS

       format, handler, selection, target

Tk                                    4.0               Tk_CreateSelHandler(3)