![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch05a.t CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib|
Return to ch05a.t CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib |
1.1 root 1: .NH
2: Creating and Destroying Windows
3: .XS
4: Window Related Operations
5: .XE
6: .PP
7: .IN "Definitions" "Opaque Window"
8: .IN "Definitions" "Transparent Window"
9: There are two kinds of windows, opaque and transparent.
10: If an opaque
11: window is stacked `on top of' another window, it obscures that other
12: window for the purpose of both input and output.
13: Attempts to output to
14: the obscured area will do nothing, and no input events (e.g. mouse
15: motion) will be generated for the obscured area.
16: Most windows are opaque.
17: Opaque windows have borders of a programmable width and pattern
18: and a background pattern (or `tile').
19: .IN "Tile Pixmaps"
20: Tile and border patterns are described using Pixmaps.
21: In a program, you refer to the window using its resource id,
22: of type `Window'.
23: .PP
24: .IN "Resource ID's" "Freeing"
25: .IN "Freeing" "Resources"
26: The background and border pixmaps may be destroyed immediately after
27: creating the window if no further explicit references to them
28: are to be made.
29: .PP
30: .IN "Definitions" "Tile Mode"
31: An opaque window's background is tiled with a pattern (most commonly a constant
32: color).
33: This pattern can either be relative to the parent (the pattern will be
34: shifted appropriately to match the parent window) or absolute
35: (the pattern will be positioned in the window independently of the
36: parent window).
37: This is called the `tile mode' of a window,
38: and can be set by subroutine calls.
39: .PP
40: .IN "Definitions" "Clip Mode"
41: It is also possible to specify if graphics operations will be clipped by
42: child windows or will write through the children.
43: This is called the `clip mode' of a window.
44: .PP
45: .IN "Input" "Transparent Window"
46: A transparent window obscures other windows for the purpose of input
47: only.
48: .IN "Parent Window"
49: .IN "Output" "On Transparent Windows"
50: Doing output to a transparent window is equivalent to output to
51: the parent window, except that the transparent window's own clip mode is
52: .IN "XClipMode"
53: used instead of the parent's (see \fIXClipMode\fP below), and the output is
54: clipped to the boundaries of the transparent window.
55: If a transparent window is moved, it has no effect on the display.
56: Transparent windows do not have borders.
57: .PP
58: .IN "Window" "RootWindow"
59: .IN "RootWindow"
60: .IN "Macro" "RootWindow"
61: The macro \fIRootWindow\fP is a convenient shorthand for referring to the
62: root of the window hierarchy, and is usually used as the \fIparent\fPn
63: argument to most calls.
64: .PP
65: When windows are first created, they are not visible on the screen.
66: Any output to a window not visible (not `mapped') on the screen
67: will be discarded.
68: An application may wish to create a window long before it is
69: mapped to the screen.
70: When an opaque window is eventually mapped to the screen
71: (using \fIXMapWindow\fP)
72: .IN "Window" "Mapping to screen"
73: .IN "XMapWindow"
74: it will generate an exposure event for the window.
75: .IN "Exposure Event"
76: .FD
77: .IN "Definitions" "XCreateWindow"
78: .IN "XCreateWindow"
79: Window XCreateWindow (parent, x, y, width, height, borderwidth, border, bgnd)
80: Window parent;
81: int x, y, width, height;
82: int borderwidth; /* border width */
83: Pixmap border;
84: Pixmap background;
85: .FN
86: \fIXCreateWindow\fP creates an unmapped,
87: opaque subwindow of the specified parent window,
88: which must also be opaque.
89: The created window will always be wholly
90: contained within its \fIparent\fP,
91: any part of the window extending outside its parent window will be clipped.
92: .PP
93: The \fIx\fP and \fIy\fP
94: coordinates represent the top left outside corner of the new window's
95: borders.
96: They are relative to the inside of the \fIparent\fP window's
97: borders.
98: The \fIwidth\fP and \fIheight\fP parameters are the new window's inside
99: dimensions--they do not include the new window's borders,
100: which are entirely outside of the window.
101: The new window will have a border \fIborderwidth\fP pixels wide.
102: .PP
103: .IN "Window" "Border"
104: .IN "Window" "Background"
105: .IN "Macro" "BlackPixmap"
106: .IN "Macro" "WhitePixmap"
107: .IN "BlackPixmap"
108: .IN "WhitePixmap"
109: A \fIborder\fP Pixmap need not be given if the border width is zero,
110: in which case the window will not have a border.
111: If no \fIbackground\fP Pixmap is given, the parent's background Pixmap is
112: used. A monochrome application may find the macros \fIBlackPixmap\fP and
113: \fIWhitePixmap\fP useful; these refer to solid black and white pixmaps that
114: are automatically created by \fIXOpenDisplay\fP.
115: .PP
116: .IN "Window" "Tile Mode"
117: The \fItilemode\fP of the new window is absolute.
118: .IN "Window" "Clip Mode"
119: The \fIclipmode\fP of the new window is `clipped'.
120: .IN "Icon" "Creating Windows"
121: The new window does not have an associated icon window.
122: .IN "Window" "Name"
123: The \fIname\fP of the window is the null string.
124: .PP
125: The created window is not yet displayed (`mapped') on the user's display;
126: to display the
127: .IN "XMapWindow"
128: window, call \fIXMapWindow\fP.
129: .IN "Cursor" "Initial State"
130: The new window will not have a cursor defined; the cursor will
131: be that of the window's parent until/unless a cursor is registered.
132: The window will not be visible on the screen unless it and all of its
133: ancestors are `mapped', and it is not obscured by any of its ancestors.
134: .IN "XDefineCursor"
135: .PP
136: The subroutine returns the window id of the created window, or 0 if
137: the subroutine fails.
138: .FD
139: .IN "Definitions" "XCreateTransparency"
140: .IN "XCreateTransparency"
141: Window XCreateTransparency (parent, x, y, width, height)
142: Window parent;
143: int x, y, width, height;
144: .FN
145: \fIXCreateTransparency\fP creates an unmapped transparent
146: window.
147: Transparent windows do not have borders.
148: The coordinates are relative to the parents coordinate system.
149: .IN "Transparent Window" "Clip Mode"
150: .IN "Transparent Window" "Initial Cursor"
151: The
152: window will not initially have a cursor registered, and will have a
153: clipmode of \fIClipModeClipped\fP
154: (i.e. output to the window is obscured by subwindows of
155: the parent).
156: .IN "Transparent Window" "Background"
157: .IN "Transparent Window" "Border"
158: .IN "Transparent Window" "Tile Mode"
159: A transparent window does not have a border or background pattern.
160: It initially has a tile mode of \fITileModeRelative\fP.
161: .PP
162: The subroutine returns the window id of the created window, or 0 if
163: the subroutine fails.
164: .FD
165: .IN "Definitions" "XDestroyWindow"
166: .IN "XDestroyWindow"
167: XDestroyWindow (w)
168: Window w;
169: .FN
170: \fIXDestroyWindow\fP unmaps and destroys the window and all of its subwindows.
171: The windows should never again be referenced.
172: \fIXDestroyWindow\fP may be
173: called on either opaque or transparent windows.
174: .PP
175: .IN "Icon" "Mapping Behavior"
176: If the window has an icon window, that icon window is automatically unmapped
177: and sent an unmap window event.
178: If the window is a mapped icon window,
179: its corresponding `regular' window is automatically mapped.
180: This prevents windows being lost when a window manager exits unexpectedly.
181: .PP
182: Destroying a mapped opaque window will generate exposure events on other
183: opaque windows that were obscured by the window being destroyed.
184: .PP
185: .IN "XCloseDisplay"
186: \fIXCloseDisplay\fP automatically destroys all windows that have been created
187: .IN "Unix System Call" "fork"
188: on that server (unless called after a \fIfork()\fP--see note under
189: \fIXCloseDisplay\fP).
190: .FD
191: .IN "Definitions" "XDestroySubwindows"
192: .IN "XDestroySubwindows"
193: XDestroySubwindows (w)
194: Window w;
195: .FN
196: .IN "XDestroySubwindows"
197: \fIXDestroySubwindows\fP destroys all subwindows of this window. The
198: subwindows should never again be referenced.
199: .PP
200: \fIXDestroySubwindows\fP generates exposure events on \fIw\fP, if any mapped
201: opaque subwindows were actually destroyed.
202: .PP
203: Note that this is MUCH more efficient than deleting many windows
204: one at a time, as much of the work need only be performed once for all
205: of the windows rather than for each window.
206: .PP
207: To allow efficient creation of many similar windows or subwindows
208: simultaneously
209: (a function often wanted when creating menus or complex forms),
210: .IN "XCreateWindow"
211: .IN "XCreateTransparency"
212: .IN "XCreateWindowBatch"
213: both \fIXCreateWindow\fP and \fIXCreateTransparency\fP have analogous forms
214: which take structures of the form:
215: .DS
216: .TA .5i 3i
217: .ta .5i 3i
218: typedef struct _OpaqueFrame {
219: Window self; /* window id of the window, filled in later */
220: short x, y; /* where to create the window */
221: short width, height; /* window size */
222: short bdrwidth; /* border width */
223: Pixmap border; /* border pixmap */
224: Pixmap background;
225: } OpaqueFrame;
226: .DE
227: .IN "Definitions" "OpaqueFrame"
228: .IN "Data Structures" "OpaqueFrame"
229: .IN "OpaqueFrame"
230: .DS
231: .TA .5i 3i
232: .ta .5i 3i
233: typedef struct _TransparentFrame {
234: Window self; /* window id of the window, filled in later */
235: short x, y; /* where to create the window */
236: short width, height;
237: } TransparentFrame;
238: .DE
239: .IN "Definitions" "BatchFrame"
240: .IN "Data Structures" "BatchFrame"
241: .IN "BatchFrame"
242: .DS
243: .TA .5i 3i
244: .ta .5i 3i
245: typedef struct _BatchFrame {
246: short type; /* One of (IsOpaque, IsTransparent). */
247: Window parent; /* Window if of the window's parent. */
248: Window self; /* Window id of the window, filled in later. */
249: short x, y; /* Where to create the window. */
250: short width, height; /* Window width and height. */
251: short bdrwidth; /* Window border width. */
252: Pixmap border; /* Window border pixmap */
253: Pixmap background; /* Window background pixmap. */
254: } BatchFrame;
255: .DE
256: .fi
257: .IN "Definitions" "TransparentFrame"
258: .IN "Data Structures" "TransparentFrame"
259: .IN "TransparentFrame"
260: .FD
261: .IN "Definitions" "XCreateWindows"
262: .IN "XCreateWindows"
263: int XCreateWindows (parent, defs, ndefs)
264: Window parent;
265: OpaqueFrame defs[];
266: int ndefs;
267: .FN
268: This subroutine takes an array of window information definitions
269: and creates them in a single handshake with the window system.
270: The caller should have filled in the structure except for the window id.
271: The window id's of the created windows are returned in the structure
272: passed to the subroutine.
273: You must specify the number of windows to be created using the
274: \fIndefs\fP argument.
275: .IN "XCreateWindow"
276: The other side-effects are the same as for \fIXCreateWindow\fP.
277: The subroutine returns the number of windows actually created.
278: .FD
279: .IN "Definitions" "XCreateTransparencies"
280: .IN "XCreateTransparencies"
281: int XCreateTransparencies(parent, defs, ndefs)
282: Window parent;
283: TransparentFrame defs[];
284: int ndefs;
285: .FN
286: This subroutine takes an array of window information definitions
287: and creates the transparencies in a single handshake with the window system.
288: The caller should have filled in the structure except for the window id.
289: The window id's of the created windows are returned in the structure
290: passed to the subroutine.
291: You must specify the number of windows to be created using the
292: ndefs argument.
293: .IN "XCreateWindow"
294: The side effects are the same as for \fIXCreateWindow\fP.
295: The subroutine returns the number of windows actually created.
296: .FD
297: .IN "Definitions" "XCreateWindowBatch"
298: .IN "XCreateWindowBatch"
299: int XCreateWindowBatch(defs, ndefs)
300: Window parent;
301: BatchFrame defs[];
302: int ndefs;
303: .FN
304: This subroutine takes an array of window information definitions
305: and creates the windows of the specified types
306: in a single handshake with the window system.
307: The caller should have filled in the structure except for the window id.
308: The window id's of the created windows are returned in the structure
309: passed to the subroutine.
310: You must specify the number of windows to be created using the
311: ndefs argument.
312: .IN "XCreateWindow"
313: .IN "XCreateTransparency"
314: The side effects are the same as for \fIXCreateWindow\fP and \fIXCreateTransparency\fP.
315: The subroutine returns the number of windows actually created.
316: The parent windows must already exist.
317: .FD
318: .IN "Definitions" "XCreate"
319: .IN "XCreate"
320: Window XCreate(prompt, program, geometry, default, frame, minwidth, minheight)
321: char *prompt; /* prompt string */
322: char *program; /* program name for Xdefaults */
323: char *geometry, *default; /* geometry specs */
324: OpaqueFrame *frame; /* background and border pixmaps in */
325: int minwidth, minheight; /* minimum size for the window */
326: .FN
327: XCreate does all the work for automatic and manual placement of a window,
328: and is commonly used by most applications for creating graphics related
329: windows.
330: .PP
331: The \fIprompt\fP argument is used in a prompt window (if needed) to inform the
332: user what application wants to be placed.
333: The \fIprogram\fP name must be passed in with the program argument (usually
334: it should be \fIargv[0]\fP) so that \fIXGetDefault\fP can find out how the
335: user likes to be prompted to create the window.
336: .PP
337: The \fIgeometry\fP and \fIdefault\fP arguments are used to place the position
338: and/or size of the window.
339: .PP
340: The \fIframe\fP passed in must include the background and border pixmaps
341: already specified, and the border width of the window.
342: .PP
343: \fIMinwidth\fP and \fIminheight\fP specify the minimum size of the created window
344: in pixels.
345: .PP
346: The window is not mapped after creation.
347: The function returns the window id of the window just created,
348: and all values in the passed in window \fIframe\fP (as defined above)
349: will be set.
350: .PP
351: The following paragraphs describes the current user interface;
352: it may change in the
353: future somewhat.
354: .IN "XGeometry"
355: .IN "XParseGeometry"
356: If a sufficiently complete geometry specification (see \fIXParseGeometry\fP
357: and \fIXGeometry\fP)
358: is passed in, the window will be created automatically.
359: If no X or Y locations are set by the geometry spec, the user will be
360: prompted to interactively position the window.
361: A prompt window will be popped up in the upper left hand corner,
362: and the mouse grabbed.
363: .PP
364: .IN "XGrabMouse"
365: .IN "Grabbing" "Mouse"
366: .IN "XGetDefault"
367: The ``MakeWindow'' X defaults ``BodyFont'', ``ReverseVideo'',
368: ``BorderWidth'', ``InternalBorder'', ``Freeze'',
369: ``Foreground'', ``Background'', ``Border''
370: ``Mouse'', ``MouseMask'' control the appearance
371: of a prompt window and the cursor to be used when rubber banding.
372: If ``freeze'' is ``on'', the server will be frozen while the window is being
373: created.
374: So for example, one of these might be specified as ``.MakeWindow.Freeze''
375: in your \fI~/.Xdefaults\fP file.
376: .IN "XGrabServer"
377: .IN "Grabbing" "Server"
378: A box the size of the minimum window will be rubber banded on the
379: screen.
380: .PP
381: If the left button is pressed, the outline of the default window at its
382: default size and location will be shown; when the button is released, the
383: window will be created.
384: If the right button is pressed, the outline of the default window at its
385: default size and the current location of the mouse will be shown;
386: when the button is released, the window's upper left corner will be created
387: at the current cursor location.
388: If the center button is pressed, it indicates one corner of the window should
389: be set at the current mouse location.
390: When the center button is released, the window will be created with the
391: other corner of the window at the current mouse location unless the
392: minimum size has not been met.
393: .FD
394: .IN "Definitions" "XCreateTerm"
395: .IN "XCreateTerm"
396: Window XCreateTerm(prompt, program, geometry, default, frame, minwidth, minheight,
397: xadder, yadder, cwidth, cheight, f, fwidth, fheight)
398: char *prompt; /* prompt string */
399: char *program; /* program name for Xdefaults */
400: char *geometry, *default; /* geometry specs */
401: OpaqueFrame *frame; /* background and border pixmaps in */
402: int minwidth, minheight; /* minimum size for the window */
403: int xadder, yadder; /* additional space inside window needed */
404: int *cwidth, *cheight; /* RETURNs created size of window */
405: FontInfo *f; /* font for prompt window */
406: int fwidth, fheight; /* size of geometry units */
407: .FN
408: \fIXCreateTerm\fP
409: does all the work for automatic and manual placement of a window
410: which should be sized in multiples of \fIfwidth\fP and \fIfheight\fP,
411: and is commonly used by most applications for creating text related
412: windows.
413: .PP
414: The \fIprompt\fP argument is used in a prompt window (if needed) to inform the
415: user what application wants to be placed.
416: The program name must be passed in with the \fIprogram\fP argument (usually
417: it should be \fIargv[0]\fP) so that \fIXGetDefault\fP can find out how the
418: user likes to be prompted to create the window.
419: .PP
420: The geometry and default arguments are used to place the position
421: and/or size of the window.
422: .PP
423: The \fIfwidth\fP and \fIfheight\fP arguments specify the size of the units used in
424: the geometry spec,
425: and the increments the window should be sized in.
426: These are typically the size of a fixed width font, or other
427: graphic object in a window.
428: .PP
429: The \fIframe\fP passed in must include the background and border pixmaps
430: already specified, and the border width of the window.
431: .PP
432: \fIMinwidth\fP and \fIminheight\fP specify the minimum size of the created window in
433: multiples of \fIfwidth\fP and \fIfheight\fP.
434: \fIXadder\fP and \fIyadder\fP is additional interior padding needed in the window.
435: The function returns the window id of the window just created,
436: and all values in the passed in window frame will be set.
437: .PP
438: The window is not `mapped' after creation.
439: .PP
440: The following paragraphs describes the current user interface;
441: it may change in the
442: future somewhat.
443: .IN "XGeometry"
444: .IN "XParseGeometry"
445: If a sufficiently complete geometry specification (see \fIXParseGeometry\fP
446: and \fIXGeometry\fP)
447: is passed in, the window will be created automatically.
448: If no X or Y locations are set by the geometry spec, the user will be
449: prompted to interactively position the window.
450: A prompt window will be `popped' in the upper left hand corner,
451: and the mouse grabbed.
452: In the prompt window will be appended the width and height of the window
453: in the units specified by \fIfwidth\fP and \fIfheight\fP.
454: .PP
455: .IN "XGrabMouse"
456: .IN "Grabbing" "Mouse"
457: .IN "XGetDefault"
458: The ``MakeWindow'' X defaults ``BodyFont'', ``ReverseVideo'',
459: ``BorderWidth'', ``InternalBorder'', ``Freeze'',
460: ``Foreground'', ``Background'', ``Border''
461: ``Mouse'', ``MouseMask'' control the appearance
462: of a prompt window and the cursor to be used when rubber banding.
463: If ``freeze'' is ``on'', the server will be frozen while the window is being
464: created.
465: So for example, one of these might be specified as ``.MakeWindow.Freeze''
466: in your X defaults file.
467: .IN "XGrabServer"
468: .IN "Grabbing" "Server"
469: A box the size of the minimum window will be rubber banded on the
470: screen.
471: .PP
472: If the left button is pressed, the outline of the default window at the
473: mouse's current position of the default size
474: will be shown; when the button is released, the
475: window will be created.
476: If the right button is pressed, the outline of the default window at its
477: default size and the current location of the mouse will be shown;
478: when the button is released, the window's upper left corner will be created
479: at the current cursor location, and the height of the window will be
480: determined by the height of the screen.
481: If ``.MakeWindow.ClipToScreen'' is ``on'', the window will be
482: clipped to the screen until and unless the minimum size requirements
483: preclude it.
484: If the center button is pressed, it indicates one corner of the window should
485: be set at the current mouse location.
486: When the center button is released, the window will be created with the
487: other corner of the window at the current mouse location unless the
488: minimum size has not been met.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.