Tk_GetSelection(3tk)

Tk_GetSelection(3)    Tk Library Procedures    Tk_GetSelection(3)

_________________________________________________________________

NAME

     Tk_GetSelection - retrieve the contents of a selection

SYNOPSIS

     #include <tk.h>

     int
     Tk_GetSelection(interp, tkwin, selection, target, proc, clientData)

ARGUMENTS

     Tcl_Interp *interp (in)                Interpreter  to   use
                                            for reporting errors.

     Tk_Window tkwin (in)                   Window    on    whose
                                            behalf   to  retrieve
                                            the selection (deter-
                                            mines   display  from
                                            which to retrieve).

     Atom selection (in)                    The   name   of   the
                                            selection    to    be
                                            retrieved.

     Atom target (in)                       Form  in   which   to
                                            retrieve selection.

     Tk_GetSelProc *proc (in)               Procedure  to  invoke
                                            to  process pieces of
                                            the selection as they
                                            are retrieved.

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

DESCRIPTION

     Tk_GetSelection retrieves the  selection  specified  by  the
     atom  selection  in  the  format  specified  by target.  The
     selection may actually be retrieved in  several  pieces;  as
     each  piece  is  retrieved,  proc  is  called to process the
     piece.  Proc should have arguments and result that match the
     type Tk_GetSelProc:
          typedef int Tk_GetSelProc(
              ClientData clientData,
              Tcl_Interp *interp,
              char *portion);
     The clientData and interp parameters to proc will be  copies
     of  the corresponding arguments to Tk_GetSelection.  Portion

Tk                      Last change: 4.0                        1

Tk_GetSelection(3)    Tk Library Procedures    Tk_GetSelection(3)

     will be a pointer to a string containing part or all of  the
     selection.   For  large  selections,  proc  will  be  called
     several times with successive  portions  of  the  selection.
     The X Inter-Client Communication Conventions Manual allows a
     selection to be returned in formats other than strings, e.g.
     as  an array of atoms or integers.  If this happens, Tk con-
     verts the selection back into a string before calling  proc.
     If a selection is returned as an array of atoms, Tk converts
     it to a string containing the atom names separated by  white
     space.   For  any other format besides string, Tk converts a
     selection  to  a  string   containing   hexadecimal   values
     separated by white space.

     Tk_GetSelection returns to its caller when the selection has
     been  completely  retrieved and processed by proc, or when a
     fatal error has occurred (e.g. the selection owner  did  not
     respond promptly).  Tk_GetSelection normally returns TCL_OK;
     if an error occurs, it returns TCL_ERROR and leaves an error
     message  in  interp->result.  Proc should also return either
     TCL_OK or TCL_ERROR. If proc encounters an error in  dealing
     with  the  selection,  it  should  leave an error message in
     interp->result and return TCL_ERROR;  this  will  abort  the
     selection retrieval.

KEYWORDS

     format, get, selection retrieval

Tk                      Last change: 4.0                        2