1Tk_CreateSelHandler(3)       Tk Library Procedures      Tk_CreateSelHandler(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_CreateSelHandler,  Tk_DeleteSelHandler  - arrange to handle requests
9       for a selection
10

SYNOPSIS

12       #include <tk.h>
13
14       Tk_CreateSelHandler(tkwin, selection, target, proc, clientData, format)
15
16       Tk_DeleteSelHandler(tkwin, selection, target)
17

ARGUMENTS

19       Tk_Window tkwin (in)                      Window for  which  proc  will
20                                                 provide   selection  informa‐
21                                                 tion.
22
23       Atom selection (in)                       The name of the selection for
24                                                 which   proc   will   provide
25                                                 selection information.
26
27       Atom target (in)                          Form in which proc  can  pro‐
28                                                 vide   the   selection  (e.g.
29                                                 STRING or FILE_NAME).  Corre‐
30                                                 sponds  to  type arguments in
31                                                 selection commands.
32
33       Tk_SelectionProc *proc (in)               Procedure to invoke  whenever
34                                                 the  selection  is  owned  by
35                                                 tkwin and the selection  con‐
36                                                 tents  are  requested  in the
37                                                 format given by target.
38
39       ClientData clientData (in)                Arbitrary one-word  value  to
40                                                 pass to proc.
41
42       Atom format (in)                          If the selection requestor is
43                                                 not in this  process,  format
44                                                 determines the representation
45                                                 used to transmit  the  selec‐
46                                                 tion to its requestor.
47______________________________________________________________________________
48

DESCRIPTION

50       Tk_CreateSelHandler  arranges  for  a particular procedure (proc) to be
51       called whenever selection is owned by tkwin and the selection  contents
52       are requested in the form given by target.  Target should be one of the
53       entries defined in the left column of Table 2  of  the  X  Inter-Client
54       Communication  Conventions Manual (ICCCM) or any other form in which an
55       application is willing to present the selection.  The most common  form
56       is STRING.
57
58       Proc should have arguments and result that match the type Tk_Selection‐
59       Proc:
60              typedef int Tk_SelectionProc(
61                      ClientData clientData,
62                      int offset,
63                      char *buffer,
64                      int maxBytes);
65       The clientData parameter to proc is a copy of the  clientData  argument
66       given  to  Tk_CreateSelHandler.  Typically, clientData points to a data
67       structure containing application-specific information that is needed to
68       retrieve  the  selection.  Offset specifies an offset position into the
69       selection, buffer specifies a location at  which  to  copy  information
70       about  the selection, and maxBytes specifies the amount of space avail‐
71       able at buffer.  Proc should place a NULL-terminated string  at  buffer
72       containing  maxBytes or fewer characters (not including the terminating
73       NULL), and it should return a count of the number of  non-NULL  charac‐
74       ters stored at buffer.  If the selection no longer exists (e.g. it once
75       existed but the user deleted the range of  characters  containing  it),
76       then proc should return -1.
77
78       When  transferring large selections, Tk will break them up into smaller
79       pieces (typically a few thousand bytes each) for more efficient  trans‐
80       mission.  It will do this by calling proc one or more times, using suc‐
81       cessively higher values of offset to retrieve  successive  portions  of
82       the  selection.   If  proc  returns a count less than maxBytes it means
83       that the entire remainder of  the  selection  has  been  returned.   If
84       proc's return value is maxBytes it means there may be additional infor‐
85       mation in the selection, so Tk  must  make  another  call  to  proc  to
86       retrieve the next portion.
87
88       Proc  always  returns  selection information in the form of a character
89       string.  However, the ICCCM allows for information  to  be  transmitted
90       from  the  selection owner to the selection requestor in any of several
91       formats, such as a string, an array of atoms,  an  array  of  integers,
92       etc.   The format argument to Tk_CreateSelHandler indicates what format
93       should be used to transmit the selection to its requestor (see the mid‐
94       dle  column  of  Table  2 of the ICCCM for examples).  If format is not
95       STRING, then Tk will take the value returned by  proc  and  divided  it
96       into  fields separated by white space.  If format is ATOM, then Tk will
97       return the selection as an array of atoms, with each  field  in  proc's
98       result treated as the name of one atom.  For any other value of format,
99       Tk will return the selection as an array of 32-bit  values  where  each
100       field  of  proc's  result  is  treated  as a number and translated to a
101       32-bit value.  In any event, the format atom is returned to the  selec‐
102       tion requestor along with the contents of the selection.
103
104       If  Tk_CreateSelHandler  is  called when there already exists a handler
105       for selection and  target  on  tkwin,  then  the  existing  handler  is
106       replaced with a new one.
107
108       Tk_DeleteSelHandler  removes the handler given by tkwin, selection, and
109       target, if such a handler exists.  If there is no such handler then  it
110       has no effect.
111

KEYWORDS

113       format, handler, selection, target
114
115
116
117Tk                                    4.0               Tk_CreateSelHandler(3)
Impressum