Manual Pages for UNIX Operating System command usage for man Tk_CreateSelHandler

Tk Library Procedures                    Tk_CreateSelHandler(3TK)



_________________________________________________________________

NAME
     Tk_CreateSelHandler, Tk_DeleteSelHandler - arrange to handle
     requests for a selection

SYNOPSIS
     #include 

     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   provide  the
                                               selection    (e.g.
                                               STRING          or
                                               FILE_NAME).
                                               Corresponds     to
                                               type arguments  in
                                               selection     com-
                                               mands.

     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,



Tk                      Last change: 4.0                        1






Tk Library Procedures                    Tk_CreateSelHandler(3TK)



                                               format  determines
                                               the representation
                                               used  to  transmit
                                               the  selection  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_SelectionProc:
          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, client-
     Data points to  a  data  structure  containing  application-
     specific  information  that is needed to retrieve the selec-
     tion.  Offset specifies an offset position into  the  selec-
     tion,  buffer specifies a location at which to copy informa-
     tion about the selection, and maxBytes specifies the  amount
     of  space  available  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  characters
     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 transmission.  It will do this by calling
     proc  one or more times, using successively 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 addi-
     tional information in the selection, so Tk must make another
     call to proc to retrieve the next portion.





Tk                      Last change: 4.0                        2






Tk Library Procedures                    Tk_CreateSelHandler(3TK)



     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 argu-
     ment  to Tk_CreateSelHandler indicates what format should be
     used to transmit the selection to  its  requestor  (see  the
     middle  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 selection requestor along with  the  con-
     tents 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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.










Tk                      Last change: 4.0                        3