src/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	dashley	71	/* $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 */