shared_source/c_tk_base_7_5_w_mods/tkselect.h

/* $Header$ */

/*
 * tkSelect.h --
 *
 *      Declarations of types shared among the files that implement
 *      selection support.
 *
 * Copyright (c) 1995 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
 * RCS: @(#) $Id: tkselect.h,v 1.1.1.1 2001/06/13 05:08:09 dtashley Exp $
 */

#ifndef _TKSELECT
#define _TKSELECT

/*
 * When a selection is owned by a window on a given display, one of the
 * following structures is present on a list of current selections in the
 * display structure.  The structure is used to record the current owner of
 * a selection for use in later retrieval requests.  There is a list of
 * such structures because a display can have multiple different selections
 * active at the same time.
 */

typedef struct TkSelectionInfo {
    Atom selection;             /* Selection name, e.g. XA_PRIMARY. */
    Tk_Window owner;            /* Current owner of this selection. */
    int serial;                 /* Serial number of last XSelectionSetOwner
                                 * request made to server for this
                                 * selection (used to filter out redundant
                                 * SelectionClear events). */
    Time time;                  /* Timestamp used to acquire selection. */
    Tk_LostSelProc *clearProc;  /* Procedure to call when owner loses
                                 * selection. */
    ClientData clearData;       /* Info to pass to clearProc. */
    struct TkSelectionInfo *nextPtr;
                                /* Next in list of current selections on
                                 * this display.  NULL means end of list */
} TkSelectionInfo;

/*
 * One of the following structures exists for each selection handler
 * created for a window by calling Tk_CreateSelHandler.  The handlers
 * are linked in a list rooted in the TkWindow structure.
 */

typedef struct TkSelHandler {
    Atom selection;             /* Selection name, e.g. XA_PRIMARY */
    Atom target;                /* Target type for selection
                                 * conversion, such as TARGETS or
                                 * STRING. */
    Atom format;                /* Format in which selection
                                 * info will be returned, such
                                 * as STRING or ATOM. */
    Tk_SelectionProc *proc;     /* Procedure to generate selection
                                 * in this format. */
    ClientData clientData;      /* Argument to pass to proc. */
    int size;                   /* Size of units returned by proc
                                 * (8 for STRING, 32 for almost
                                 * anything else). */
    struct TkSelHandler *nextPtr;
                                /* Next selection handler associated
                                 * with same window (NULL for end of
                                 * list). */
} TkSelHandler;

/*
 * When the selection is being retrieved, one of the following
 * structures is present on a list of pending selection retrievals.
 * The structure is used to communicate between the background
 * procedure that requests the selection and the foreground
 * event handler that processes the events in which the selection
 * is returned.  There is a list of such structures so that there
 * can be multiple simultaneous selection retrievals (e.g. on
 * different displays).
 */

typedef struct TkSelRetrievalInfo {
    Tcl_Interp *interp;         /* Interpreter for error reporting. */
    TkWindow *winPtr;           /* Window used as requestor for
                                 * selection. */
    Atom selection;             /* Selection being requested. */
    Atom property;              /* Property where selection will appear. */
    Atom target;                /* Desired form for selection. */
    int (*proc) _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp,
        char *portion));        /* Procedure to call to handle pieces
                                 * of selection. */
    ClientData clientData;      /* Argument for proc. */
    int result;                 /* Initially -1.  Set to a Tcl
                                 * return value once the selection
                                 * has been retrieved. */
    Tcl_TimerToken timeout;     /* Token for current timeout procedure. */
    int idleTime;               /* Number of seconds that have gone by
                                 * without hearing anything from the
                                 * selection owner. */
    Tcl_EncodingState encState; /* Holds intermediate state during translations
                                 * of data that cross buffer boundaries. */
    int encFlags;               /* Encoding translation state flags. */
    Tcl_DString buf;            /* Buffer to hold translation data. */
    struct TkSelRetrievalInfo *nextPtr;
                                /* Next in list of all pending
                                 * selection retrievals.  NULL means
                                 * end of list. */
} TkSelRetrievalInfo;

/*
 * The clipboard contains a list of buffers of various types and formats.
 * All of the buffers of a given type will be returned in sequence when the
 * CLIPBOARD selection is retrieved.  All buffers of a given type on the
 * same clipboard must have the same format.  The TkClipboardTarget structure
 * is used to record the information about a chain of buffers of the same
 * type.
 */

typedef struct TkClipboardBuffer {
    char *buffer;                       /* Null terminated data buffer. */
    long length;                        /* Length of string in buffer. */
    struct TkClipboardBuffer *nextPtr;  /* Next in list of buffers.  NULL
                                         * means end of list . */
} TkClipboardBuffer;

typedef struct TkClipboardTarget {
    Atom type;                          /* Type conversion supported. */
    Atom format;                        /* Representation used for data. */
    TkClipboardBuffer *firstBufferPtr;  /* First in list of data buffers. */
    TkClipboardBuffer *lastBufferPtr;   /* Last in list of clipboard buffers.
                                         * Used to speed up appends. */
    struct TkClipboardTarget *nextPtr;  /* Next in list of targets on
                                         * clipboard.  NULL means end of
                                         * list. */
} TkClipboardTarget;

/*
 * It is possible for a Tk_SelectionProc to delete the handler that it
 * represents.  If this happens, the code that is retrieving the selection
 * needs to know about it so it doesn't use the now-defunct handler
 * structure.  One structure of the following form is created for each
 * retrieval in progress, so that the retriever can find out if its
 * handler is deleted.  All of the pending retrievals (if there are more
 * than one) are linked into a list.
 */

typedef struct TkSelInProgress {
    TkSelHandler *selPtr;       /* Handler being executed.  If this handler
                                 * is deleted, the field is set to NULL. */
    struct TkSelInProgress *nextPtr;
                                /* Next higher nested search. */
} TkSelInProgress;

/*
 * Chunk size for retrieving selection.  It's defined both in
 * words and in bytes;  the word size is used to allocate
 * buffer space that's guaranteed to be word-aligned and that
 * has an extra character for the terminating NULL.
 */

#define TK_SEL_BYTES_AT_ONCE 4000
#define TK_SEL_WORDS_AT_ONCE 1001

/*
 * Declarations for procedures that are used by the selection-related files
 * but shouldn't be used anywhere else in Tk (or by Tk clients):
 */

extern TkSelInProgress * 
                        TkSelGetInProgress _ANSI_ARGS_((void));
extern void             TkSelSetInProgress _ANSI_ARGS_((
                            TkSelInProgress *pendingPtr));

extern void             TkSelClearSelection _ANSI_ARGS_((Tk_Window tkwin,
                            XEvent *eventPtr));
extern int              TkSelDefaultSelection _ANSI_ARGS_((
                            TkSelectionInfo *infoPtr, Atom target,
                            char *buffer, int maxBytes, Atom *typePtr));
extern int              TkSelGetSelection _ANSI_ARGS_((Tcl_Interp *interp,
                            Tk_Window tkwin, Atom selection, Atom target,
                            Tk_GetSelProc *proc, ClientData clientData));
#ifndef TkSelUpdateClipboard
extern void             TkSelUpdateClipboard _ANSI_ARGS_((TkWindow *winPtr,
                            TkClipboardTarget *targetPtr));
#endif

#endif /* _TKSELECT */

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