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