1/*
2 * tkSelect.h --
3 *
4 *	Declarations of types shared among the files that implement selection
5 *	support.
6 *
7 * Copyright (c) 1995 Sun Microsystems, Inc.
8 *
9 * See the file "license.terms" for information on usage and redistribution of
10 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
11 *
12 * RCS: @(#) $Id$
13 */
14
15#ifndef _TKSELECT
16#define _TKSELECT
17
18/*
19 * When a selection is owned by a window on a given display, one of the
20 * following structures is present on a list of current selections in the
21 * display structure. The structure is used to record the current owner of a
22 * selection for use in later retrieval requests. There is a list of such
23 * structures because a display can have multiple different selections active
24 * at the same time.
25 */
26
27typedef struct TkSelectionInfo {
28    Atom selection;		/* Selection name, e.g. XA_PRIMARY. */
29    Tk_Window owner;		/* Current owner of this selection. */
30    int serial;			/* Serial number of last XSelectionSetOwner
31				 * request made to server for this selection
32				 * (used to filter out redundant
33				 * SelectionClear events). */
34    Time time;			/* Timestamp used to acquire selection. */
35    Tk_LostSelProc *clearProc;	/* Procedure to call when owner loses
36				 * selection. */
37    ClientData clearData;	/* Info to pass to clearProc. */
38    struct TkSelectionInfo *nextPtr;
39				/* Next in list of current selections on this
40				 * display. NULL means end of list. */
41} TkSelectionInfo;
42
43/*
44 * One of the following structures exists for each selection handler created
45 * for a window by calling Tk_CreateSelHandler. The handlers are linked in a
46 * list rooted in the TkWindow structure.
47 */
48
49typedef struct TkSelHandler {
50    Atom selection;		/* Selection name, e.g. XA_PRIMARY. */
51    Atom target;		/* Target type for selection conversion, such
52				 * as TARGETS or STRING. */
53    Atom format;		/* Format in which selection info will be
54				 * returned, such as STRING or ATOM. */
55    Tk_SelectionProc *proc;	/* Procedure to generate selection in this
56				 * format. */
57    ClientData clientData;	/* Argument to pass to proc. */
58    int size;			/* Size of units returned by proc (8 for
59				 * STRING, 32 for almost anything else). */
60    struct TkSelHandler *nextPtr;
61				/* Next selection handler associated with same
62				 * window (NULL for end of list). */
63} TkSelHandler;
64
65/*
66 * When the selection is being retrieved, one of the following structures is
67 * present on a list of pending selection retrievals. The structure is used to
68 * communicate between the background procedure that requests the selection
69 * and the foreground event handler that processes the events in which the
70 * selection is returned. There is a list of such structures so that there can
71 * be multiple simultaneous selection retrievals (e.g. on different displays).
72 */
73
74typedef struct TkSelRetrievalInfo {
75    Tcl_Interp *interp;		/* Interpreter for error reporting. */
76    TkWindow *winPtr;		/* Window used as requestor for selection. */
77    Atom selection;		/* Selection being requested. */
78    Atom property;		/* Property where selection will appear. */
79    Atom target;		/* Desired form for selection. */
80    int (*proc) _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp,
81	char *portion));	/* Procedure to call to handle pieces of
82				 * selection. */
83    ClientData clientData;	/* Argument for proc. */
84    int result;			/* Initially -1. Set to a Tcl return value
85				 * once the selection has been retrieved. */
86    Tcl_TimerToken timeout;	/* Token for current timeout procedure. */
87    int idleTime;		/* Number of seconds that have gone by without
88				 * hearing anything from the selection
89				 * owner. */
90    Tcl_EncodingState encState;	/* Holds intermediate state during translations
91				 * of data that cross buffer boundaries. */
92    int encFlags;		/* Encoding translation state flags. */
93    Tcl_DString buf;		/* Buffer to hold translation data. */
94    struct TkSelRetrievalInfo *nextPtr;
95				/* Next in list of all pending selection
96				 * retrievals. NULL means end of list. */
97} TkSelRetrievalInfo;
98
99/*
100 * The clipboard contains a list of buffers of various types and formats. All
101 * of the buffers of a given type will be returned in sequence when the
102 * CLIPBOARD selection is retrieved. All buffers of a given type on the same
103 * clipboard must have the same format. The TkClipboardTarget structure is
104 * used to record the information about a chain of buffers of the same type.
105 */
106
107typedef struct TkClipboardBuffer {
108    char *buffer;		/* Null terminated data buffer. */
109    long length;		/* Length of string in buffer. */
110    struct TkClipboardBuffer *nextPtr;
111				/* Next in list of buffers. NULL means end of
112				 * list . */
113} TkClipboardBuffer;
114
115typedef struct TkClipboardTarget {
116    Atom type;			/* Type conversion supported. */
117    Atom format;		/* Representation used for data. */
118    TkClipboardBuffer *firstBufferPtr;
119				/* First in list of data buffers. */
120    TkClipboardBuffer *lastBufferPtr;
121				/* Last in list of clipboard buffers. Used to
122				 * speed up appends. */
123    struct TkClipboardTarget *nextPtr;
124				/* Next in list of targets on clipboard. NULL
125				 * means end of list. */
126} TkClipboardTarget;
127
128/*
129 * It is possible for a Tk_SelectionProc to delete the handler that it
130 * represents. If this happens, the code that is retrieving the selection
131 * needs to know about it so it doesn't use the now-defunct handler structure.
132 * One structure of the following form is created for each retrieval in
133 * progress, so that the retriever can find out if its handler is deleted. All
134 * of the pending retrievals (if there are more than one) are linked into a
135 * list.
136 */
137
138typedef struct TkSelInProgress {
139    TkSelHandler *selPtr;	/* Handler being executed. If this handler is
140				 * deleted, the field is set to NULL. */
141    struct TkSelInProgress *nextPtr;
142				/* Next higher nested search. */
143} TkSelInProgress;
144
145/*
146 * Chunk size for retrieving selection. It's defined both in words and in
147 * bytes; the word size is used to allocate buffer space that's guaranteed to
148 * be word-aligned and that has an extra character for the terminating NULL.
149 */
150
151#define TK_SEL_BYTES_AT_ONCE 4000
152#define TK_SEL_WORDS_AT_ONCE 1001
153
154/*
155 * Declarations for procedures that are used by the selection-related files
156 * but shouldn't be used anywhere else in Tk (or by Tk clients):
157 */
158
159MODULE_SCOPE TkSelInProgress *TkSelGetInProgress(void);
160MODULE_SCOPE void	TkSelSetInProgress(TkSelInProgress *pendingPtr);
161MODULE_SCOPE void	TkSelClearSelection(Tk_Window tkwin, XEvent *eventPtr);
162MODULE_SCOPE int	TkSelDefaultSelection(TkSelectionInfo *infoPtr,
163			    Atom target, char *buffer, int maxBytes,
164			    Atom *typePtr);
165MODULE_SCOPE int	TkSelGetSelection(Tcl_Interp *interp, Tk_Window tkwin,
166			    Atom selection, Atom target, Tk_GetSelProc *proc,
167			    ClientData clientData);
168#ifndef TkSelUpdateClipboard
169MODULE_SCOPE void	TkSelUpdateClipboard(TkWindow *winPtr,
170			    TkClipboardTarget *targetPtr);
171#endif
172
173#endif /* _TKSELECT */
174