![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch01a.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 ch01a.t CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib |
1.1 root 1: .NH
2: Introduction
3: .XS ii
4: Table of Contents
5: .XE
6: .XS
7: Introduction
8: .XE
9: .PP
10: The X window system supports overlapping (sub)windows.
11: All the windows in an X server are arranged in a strict hierarchy. At
12: the top of the hierarchy is the `root' window,
13: which covers the entire display screen.
14: The root window is partially or completely covered by child windows.
15: All windows have parents except for the root window.
16: There is usually at least one window per application program.
17: .IN "Definitions" "Child Window"
18: .IN "Definitions" "Parent Window"
19: Child windows may in turn have
20: their own children.
21: In this way, an application program can create a tree of arbitrary depth.
22: .PP
23: A child window may be larger than its parent--that is, part or all of
24: the child window may extend beyond the boundaries of the parent.
25: However, all output to a window is clipped by the boundaries of its
26: parent window.
27: .PP
28: .IN "Definitions" "Stacking order"
29: If several children of a window have overlapping locations, then one of
30: the children is considered to be `on top of' or `raised over' the
31: others, obscuring them.
32: Output to areas covered by other windows will be suppressed by the window
33: system.
34: If a window is obscured
35: by a second window,
36: then the window will obscure only those ancestors of the second window which
37: are also ancestors of the window.
38: Normally, child windows obscure their parents
39: as well (but there are exceptions--see the discussions of
40: .IN "XOpenTransparency"
41: .IN "XClipMode"
42: \fIXOpenTransparency\fP and \fIXClipMode\fP for details).
43: .PP
44: .IN "Definitions" "Events"
45: .IN "Events"
46: Input from X takes the form of `events'.
47: Events may either be side effects of a command (restacking windows,
48: for example, generates exposure events),
49: or completely asynchronous (for example, the keyboard).
50: A client program asks to be informed of such events;
51: X never sends events a program did not ask for.
52: .PP
53: X does not take responsibility for the contents of windows; when (part or
54: all of) a window is hidden and then brought back onto the screen, its
55: contents may be lost lost and the client program is notified (by an exposure
56: event) that (part or all
57: of) the window needs to be repainted.
58: Programs should be prepared to regenerate their windows on demand.
59: .PP
60: .IN "Definitions" "Resource ID"
61: Most of the subroutines in Xlib just add requests to an output buffer;
62: these requests later execute asynchronously on the X server
63: (often referred to as ``display server'' below).
64: Subroutines that return values do not return (``block'')
65: until an explicit reply is
66: received or an error occurs.
67: This may be queried information or a ``resource id'' discussed below.
68: If such a call results in an error, the error will
69: generally not be reported (by a call to an optional error handler)
70: until some later, blocking call is made.
71: .PP
72: .IN "XSync"
73: If a
74: client does not want a request to execute asynchronously, he can follow
75: it with a call to \fIXSync\fP, which will block until all previously buffered
76: asynchronous events have been sent and acted on.
77: .PP
78: As an important side effect,
79: .IN "XPending"
80: .IN "XNextEvent"
81: .IN "XWindowEvent"
82: .IN "XFlush"
83: .IN "XSync"
84: the output buffer is always flushed by a call to any subroutine
85: which returns a value or by calls to \fIXPending\fP,
86: \fIXNextEvent\fP, \fIXWindowEvent\fP,
87: \fIXFlush\fP or \fIXSync\fP.
88: .PP
89: .IN "Resource ID" "Window"
90: .IN "Resource ID" "Font"
91: .IN "Resource ID" "Pixmap"
92: .IN "Resource ID" "Bitmap"
93: .IN "Resource ID" "Cursor"
94: Many subroutines will return an integer resource id.
95: These can be of type ``Window'', ``Font'', ``Pixmap'', ``Bitmap'',
96: and ``Cursor'',
97: .IN "File" "<X/X.h>"
98: as defined in \fI<X/X.h>\fP.
99: Some subroutines return ``Status'', an integer error indication.
100: If the subroutine fails, it will return 0.
101: .PP
102: .IN "Definitions" "Status"
103: Since C does not provide multiple return values, many subroutines return
104: their results by writing into client-passed storage. Any pointer that is
105: used to return a value is designated as ``/* RETURN */'' in the procedure
106: declarations below.
107: All other pointers passed to these subroutines are
108: used for reading only.
109: If such a procedure returns a status of 0,
110: then it has NOT updated the return parameters.
111: .IN "Error Handling"
112: By default, errors are handled by a standard library subroutine,
113: or you can provide your own.
114: Subroutines that return pointers to strings will return NULL pointers if
115: the string does not exist.
116: .PP
117: .PP
118: Input events (e.g. key pressed, mouse moved) arrive asynchronously from
119: the server and are queued until they are requested by a call to
120: \fIXNextEvent\fP or \fIXWindowEvent\fP. In addition, some of the library
121: .IN "XChangeWindow"
122: .IN "XRaiseWindow"
123: subroutines (e.g. \fIXChangeWindow\fP and \fIXRaiseWindow\fP)
124: generate ``exposure''
125: events--requests to repaint sections of a window that do not have valid
126: contents. These events also arrive asynchronously, but the client may
127: .IN "XSync"
128: wish to explicitly wait for them by calling \fIXSync\fP after calling a
129: subroutine which may generate exposure events.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.