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