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