wsutils.h revision 320e696b 
1/** ------------------------------------------------------------------------
2	This file contains routines for manipulating generic lists.
3	Lists are implemented with a "harness".  In other words, each
4	node in the list consists of two pointers, one to the data item
5	and one to the next node in the list.  The head of the list is
6	the same struct as each node, but the "item" ptr is used to point
7	to the current member of the list (used by the first_in_list and
8	next_in_list functions).
9
10Copyright 1994 Hewlett-Packard Co.
11Copyright 1996, 1998  The Open Group
12
13Permission to use, copy, modify, distribute, and sell this software and its
14documentation for any purpose is hereby granted without fee, provided that
15the above copyright notice appear in all copies and that both that
16copyright notice and this permission notice appear in supporting
17documentation.
18
19The above copyright notice and this permission notice shall be included
20in all copies or substantial portions of the Software.
21
22THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
23OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
26OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
27ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28OTHER DEALINGS IN THE SOFTWARE.
29
30Except as contained in this notice, the name of The Open Group shall
31not be used in advertising or otherwise to promote the sale, use or
32other dealings in this Software without prior written authorization
33from The Open Group.
34
35    ------------------------------------------------------------------------ **/
36
37/******************************************************************************
38 *
39 * This file contains various typedef's, macros and procedure declarations for
40 * a set of example utility procedures contained in the file "wsutils.c".
41 *
42 ******************************************************************************/
43
44/* This is the actual structure returned by the X server describing the
45 * SERVER_OVERLAY_VISUAL property.
46 */
47typedef struct
48{
49  VisualID	visualID;		/* The VisualID of the overlay visual */
50  int		transparentType;	/* Can be None, TransparentPixel or
51					 * TransparentMask */
52  Pixel		value;			/* Pixel value */
53  int		layer;			/* Overlay planes will always be in
54					 * layer 1 */
55} OverlayVisualPropertyRec;
56
57
58/* This is structure also describes the SERVER_OVERLAY_VISUAL property, but
59 * should be more useful than the one actually returned by the X server
60 * because it actually points to the visual's XVisualInfo struct rather than
61 * refering to the visual's ID.
62 */
63typedef struct
64{
65  XVisualInfo	*pOverlayVisualInfo;	/* Pointer to the XVisualInfo struct */
66  int		transparentType;	/* Can be None, TransparentPixel or
67					 * TransparentMask */
68  Pixel		value;			/* Pixel value */
69  int		layer;			/* Overlay planes will always be in
70					 * layer 1 */
71} OverlayInfo;
72
73
74/* These macros are the values of the "transparentType" above: */
75#ifndef None
76#define None 0
77#endif
78#ifndef TransparentPixel
79#define TransparentPixel	1
80#endif
81
82
83/* These macros define how flexible a program is when it requests a window's
84 * creation with either the CreateImagePlanesWindow() or
85 * CreateOverlayPlanesWindow():
86 */
87#ifndef NOT_FLEXIBLE
88#define NOT_FLEXIBLE		0
89#define FLEXIBLE		1
90#endif
91
92
93/* These macros define the values of the "sbCmapHint" parameter of the
94 * CreateImagePlanesWindow():
95 */
96#ifndef SB_CMAP_TYPE_NORMAL
97#define SB_CMAP_TYPE_NORMAL	1
98#endif
99
100#ifndef SB_CMAP_TYPE_MONOTONIC
101#define SB_CMAP_TYPE_MONOTONIC	2
102#endif
103
104#ifndef SB_CMAP_TYPE_FULL
105#define SB_CMAP_TYPE_FULL	4
106#endif
107
108
109/******************************************************************************
110 *
111 * GetXVisualInfo()
112 *
113 * This routine takes an X11 Display, screen number, and returns whether the
114 * screen supports transparent overlays and three arrays:
115 *
116 *	1) All of the XVisualInfo struct's for the screen.
117 *	2) All of the OverlayInfo struct's for the screen.
118 *	3) An array of pointers to the screen's image plane XVisualInfo
119 *	   structs.
120 *
121 * The code below obtains the array of all the screen's visuals, and obtains
122 * the array of all the screen's overlay visual information.  It then processes
123 * the array of the screen's visuals, determining whether the visual is an
124 * overlay or image visual.
125 *
126 * If the routine sucessfully obtained the visual information, it returns zero.
127 * If the routine didn't obtain the visual information, it returns non-zero.
128 *
129 ******************************************************************************/
130
131extern int GetXVisualInfo(
132    Display	*display,		/* Which X server (aka "display"). */
133    int		screen,			/* Which screen of the "display". */
134    int		*transparentOverlays,	/* Non-zero if there's at least one
135					 * overlay visual and if at least one
136					 * of those supports a transparent
137					 * pixel. */
138    int		*numVisuals,		/* Number of XVisualInfo struct's
139					 * pointed to to by pVisuals. */
140    XVisualInfo	**pVisuals,		/* All of the device's visuals. */
141    int		*numOverlayVisuals,	/* Number of OverlayInfo's pointed
142					 * to by pOverlayVisuals.  If this
143					 * number is zero, the device does
144					 * not have overlay planes. */
145    OverlayInfo	**pOverlayVisuals,	/* The device's overlay plane visual
146					 * information. */
147    int		*numImageVisuals,	/* Number of XVisualInfo's pointed
148					 * to by pImageVisuals. */
149    XVisualInfo	***pImageVisuals	/* The device's image visuals. */
150		    );
151
152
153/******************************************************************************
154 *
155 * FreeXVisualInfo()
156 *
157 * This routine frees the data that was allocated by GetXVisualInfo().
158 *
159 ******************************************************************************/
160
161extern void FreeXVisualInfo(
162    XVisualInfo	*pVisuals,
163    OverlayInfo	*pOverlayVisuals,
164    XVisualInfo	**pImageVisuals
165		     );
166
167
168/******************************************************************************
169 *
170 * FindImagePlanesVisual()
171 *
172 * This routine attempts to find a visual to use to create an image planes
173 * window based upon the information passed in.
174 *
175 * The "Hint" values give guides to the routine as to what the program wants.
176 * The "depthFlexibility" value tells the routine how much the program wants
177 * the actual "depthHint" specified.  If the program can't live with the
178 * screen's image planes visuals, the routine returns non-zero, and the
179 * "depthObtained" and "pImageVisualToUse" return parameters are NOT valid.
180 * Otherwise, the "depthObtained" and "pImageVisualToUse" return parameters
181 * are valid and the routine returns zero.
182 *
183 * NOTE: This is just an example of what can be done.  It may or may not be
184 * useful for any specific application.
185 *
186 ******************************************************************************/
187
188extern int FindImagePlanesVisual(
189    Display	*display,		/* Which X server (aka "display"). */
190    int		screen,			/* Which screen of the "display". */
191    int		numImageVisuals,	/* Number of XVisualInfo's pointed
192					 * to by pImageVisuals. */
193    XVisualInfo	**pImageVisuals,	/* The device's image visuals. */
194    int		sbCmapHint,		/* What Starbase cmap modes will be
195					 * used with the visual.  NOTE: This
196					 * is a mask of the possible values. */
197    int		depthHint,		/* Desired depth. */
198    int		depthFlexibility,	/* How much the actual value in
199					 * "depthHint" is desired. */
200    Visual	**pImageVisualToUse,	/* The screen's image visual to use. */
201    int		*depthObtained		/* Actual depth of the visual. */
202				     );
203
204
205/******************************************************************************
206 *
207 * FindOverlayPlanesVisual()
208 *
209 * This routine attempts to find a visual to use to create an overlay planes
210 * window based upon the information passed in.
211 *
212 * While the CreateImagePlanesWindow() routine took a sbCmapHint, this
213 * routine doesn't.  Starbase's CMAP_FULL shouldn't be used in overlay planes
214 * windows.  This is partially because this functionality is better suited in
215 * the image planes where there are generally more planes, and partially
216 * because the overlay planes generally have PseudoColor visuals with one
217 * color being transparent (the transparent normally being the "white" color
218 * for CMAP_FULL).
219 *
220 * The "depthHint" values give guides to the routine as to what depth the
221 * program wants the window to be.  The "depthFlexibility" value tells the
222 * routine how much the program wants the actual "depthHint" specified.  If
223 * the program can't live with the screen's overlay planes visuals, the
224 * routine returns non-zero, and the "depthObtained" and "pOverlayVisualToUse"
225 * return parameters are NOT valid.  Otherwise, the "depthObtained" and
226 * "pOverlayVisualToUse" return parameters are valid and the routine returns
227 * zero.
228 *
229 * NOTE: This is just an example of what can be done.  It may or may not be
230 * useful for any specific application.
231 *
232 ******************************************************************************/
233
234extern int FindOverlayPlanesVisual(
235    Display	*display,		/* Which X server (aka "display"). */
236    int		screen,			/* Which screen of the "display". */
237    int		numOverlayVisuals,	/* Number of OverlayInfo's pointed
238					 * to by pOverlayVisuals. */
239    OverlayInfo	*pOverlayVisuals,	/* The device's overlay plane visual
240					 * information. */
241    int		depthHint,		/* Desired depth. */
242    int		depthFlexibility,	/* How much the actual value in
243					 * "depthHint" is desired. */
244    int		transparentBackground,	/* Non-zero if the visual must have
245					 * a transparent color. */
246    Visual	**pOverlayVisualToUse,	/* The screen's overlay visual to
247					 * use. */
248    int		*depthObtained,		/* Actual depth of the visual. */
249    int		*transparentColor	/* The transparent color the program
250					 * can use with the visual. */
251				);
252
253
254/******************************************************************************
255 *
256 * CreateImagePlanesWindow()
257 *
258 * This routine creates an image planes window, potentially creates a colormap
259 * for the window to use, and sets the window's standard properties, based
260 * upon the information passed in to the routine.  While "created," the window
261 * has not been mapped.
262 *
263 * If the routine suceeds, it returns zero and the return parameters
264 * "imageWindow", "imageColormap" and "mustFreeImageColormap" are valid.
265 * Otherwise, the routine returns non-zero and the return parameters are
266 * NOT valid.
267 *
268 * NOTE: This is just an example of what can be done.  It may or may not be
269 * useful for any specific application.
270 *
271 ******************************************************************************/
272
273extern int CreateImagePlanesWindow(
274    Display	*display,		/* Which X server (aka "display"). */
275    int		screen,			/* Which screen of the "display". */
276    Window	parentWindow,		/* Window ID of the parent window for
277					 * the created window. */
278    int		windowX,		/* Desired X coord. of the window. */
279    int		windowY,		/* Desired Y coord of the window. */
280    int		windowWidth,		/* Desired width of the window. */
281    int		windowHeight,		/* Desired height of the window. */
282    int		windowDepth,		/* Desired depth of the window. */
283    Visual	*pImageVisualToUse,	/* The window's image planes visual. */
284    int		argc,			/* Program's argc parameter. */
285    char	*argv[],		/* Program's argv parameter. */
286    char	*windowName,		/* Name to put on window's border. */
287    char	*iconName,		/* Name to put on window's icon. */
288    Window	*imageWindow,		/* Window ID of the created window. */
289    Colormap	*imageColormap,		/* The window's colormap. */
290    int		*mustFreeImageColormap	/* Non-zero if the program must call
291					 * XFreeColormap() for imageColormap. */
292				);
293
294
295/******************************************************************************
296 *
297 * CreateOverlayPlanesWindow()
298 *
299 * This routine creates an overlay planes window, potentially creates a colormap
300 * for the window to use, and sets the window's standard properties, based
301 * upon the information passed in to the routine.  While "created," the window
302 * has not been mapped.
303 *
304 * If the routine suceeds, it returns zero and the return parameters
305 * "overlayWindow", "overlayColormap" and "mustFreeOverlayColormap" are valid.
306 * Otherwise, the routine returns non-zero and the return parameters are
307 * NOT valid.
308 *
309 * NOTE: This is just an example of what can be done.  It may or may not be
310 * useful for any specific application.
311 *
312 ******************************************************************************/
313
314int CreateOverlayPlanesWindow(
315    Display	*display,		/* Which X server (aka "display"). */
316    int		screen,			/* Which screen of the "display". */
317    Window	parentWindow,		/* Window ID of the parent window for
318					 * the created window. */
319    int		windowX,		/* Desired X coord. of the window. */
320    int		windowY,		/* Desired Y coord of the window. */
321    int		windowWidth,		/* Desired width of the window. */
322    int		windowHeight,		/* Desired height of the window. */
323    int		windowDepth,		/* Desired depth of the window. */
324    Visual	*pOverlayVisualToUse,	/* The window's overlay planes visual.*/
325    int		argc,			/* Program's argc parameter. */
326    char	*argv[],		/* Program's argv parameter. */
327    char	*windowName,		/* Name to put on window's border. */
328    char	*iconName,		/* Name to put on window's icon. */
329    int		transparentBackground,	/* Non-zero if the window's background
330					 * should be a transparent color. */
331    int		*transparentColor,	/* The transparent color to use as the
332					 * window's background. */
333    Window	*overlayWindow,		/* Window ID of the created window. */
334    Colormap	*overlayColormap,	/* The window's colormap. */
335    int		*mustFreeOverlayColormap/* Non-zero if the program must call
336					  * XFreeColormap() for
337					  * overlayColormap. */
338				);
339