![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch04a.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 ch04a.t CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib |
1.1 root 1: .NH
2: Opening and Closing the Display
3: .XS
4: Initializing the Window System
5: .XE
6: .PP
7: The window system is a network service.
8: You must connect to the X server before you can perform any operations.
9: There is one X server for each hardware display.
10: This library interface presumes you are working with a single display at
11: one time, and
12: therefore has an idea of the current display you are using.
13: .FD
14: .IN "Definitions" "XOpenDisplay"
15: .IN "XOpenDisplay"
16: Display *XOpenDisplay (name)
17: char *name;
18: .FN
19: This function takes the \fIname\fP of the server, and opens a connection to the
20: server for the display hardware.
21: .IN "DISPLAY Environment Variable"
22: .IN "Environment" "DISPLAY"
23: If the display name string is NULL, it uses the environment variable DISPLAY
24: to determine which display and which communications domain to use.
25: The
26: display string or DISPLAY environment variable should be in the format
27: ``hostname:number'', where ``hostname'' is the name of a machine, and
28: ``number'' is the number of the display on that machine.
29: For example, ``mit-athena:3'' would be display 3 on the machine
30: ``mit-athena''.
31: .IN "Protocol" "TCP"
32: .IN "Protocol" "DECnet"
33: XOpenDisplay connects through TCP, Unix or DECnet streams to the server.
34: If the ``hostname'' is ``unix'', Unix domain IPC is used.
35: If there is only a single ``:'' between hostname and display number,
36: TCP streams are used.
37: If hostname and display number are seperated by a ``::'', DECnet streams
38: will be used.
39: Note that you must build all software for DECnet if you want to use DECnet.
40: A single X server will accept both TCP and DECnet connections if it has been
41: built for DECnet.
42: .PP
43: .IN "Definitions" "Display"
44: .IN "Data Structures" "Display"
45: If the call is successful, it returns a pointer to a Display structure,
46: .IN "File" "<X/Xlib.h>"
47: which is defined in \fI<X/Xlib.h>\fP.
48: .PP
49: The procedure returns NULL on failure.
50: .PP
51: There are a number of useful macros and functions
52: which return information out of the
53: Display structure.
54: .IN "Unix System Call" "select"
55: Some programs may find it useful to perform select(2) on the file descriptor
56: .IN "Macro" "dpyno()"
57: returned using the \fIdpyno()\fP macro,
58: which returns the file descriptor of the connection.
59: This comes up most often in applications which drive more than one
60: display at a time.
61: The length of the input queue on the display connection is
62: .IN "Macro" "QLength()"
63: returned using the \fIQLength()\fP macro.
64: This may be useful to make sure you have processed all events
65: already read in before performing a select again.
66: .IN "Macro" "DisplayType()"
67: .IN "Macro" "DisplayPlanes()"
68: .IN "Macro" "DisplayCells()"
69: The \fIDisplayType()\fP, \fIDisplayPlanes()\fP, \fIDisplayCells()\fP and
70: .IN "Macro" "ProtocolVersion()"
71: \fIProtocolVersion()\fP macros
72: return the appropriate information out of the current display structure.
73: .IN "Window" "RootWindow"
74: .IN "RootWindow"
75: .IN "Macro" "RootWindow"
76: .PP
77: The \fIRootWindow\fP variable (actually a reference to the current display
78: structure) is often useful in other calls, as many subroutines take a
79: parent window as an argument.
80: .PP
81: .IN "Macro" "DisplayType()"
82: There may be different performance tradeoffs a client program
83: may wish to make depending on the display type.
84: The \fIDisplayType()\fP macro returns the type of the device, as
85: .IN "File" "<X/X.h>"
86: defined in <X/X.h>.
87: Its use is discouraged; programs should be prepared to work on different
88: displays of various sizes and characteristics.
89: .PP
90: .IN "Macro" "DisplayName()"
91: The \fIDisplayName()\fP macro returns the string that was passed to
92: \fIXOpenDisplay\fP
93: when the current display was opened (or, if that was NULL, the value of
94: the DISPLAY environment variable when the current display was opened).
95: .IN "Unix System Call" "fork"
96: This is especially useful to applications which \fIfork()\fP, and want to open
97: a new connection to the same display from the child process.
98: .PP
99: .IN "BlackPixmap"
100: .IN "WhitePixmap"
101: .IN "Pixmap"
102: .IN "Macro" "BlackPixmap"
103: .IN "Macro" "WhitePixmap"
104: \fIXOpenDisplay\fP
105: automatically creates a solid black and a solid white pixmap,
106: suitable for use as a background or border tile.
107: You can refer to these
108: by using the \fIBlackPixmap\fP and \fIWhitePixmap\fP macros,
109: which refer to the
110: current display structure.
111: .PP
112: .IN "DisplayWidth"
113: .IN "DisplayHeight"
114: .IN "Definitions" "DisplayWidth"
115: .IN "Definitions" "DisplayHeight"
116: The size of the current display's root window can be determined with the
117: \fIDisplayWidth()\fP and \fIDisplayHeight()\fP functions,
118: which return integers describing the size of the screen in pixels.
119: .PP
120: .IN "Data Structures" "Display"
121: Other elements of the \fIDisplay\fP structure are private to
122: the X library and must not be used.
123: .FD
124: .IN "XSetDisplay"
125: .IN "Definitions" "XSetDisplay"
126: XSetDisplay(display)
127: Display *display;
128: .FN
129: .PP
130: This procedure sets the current \fIdisplay\fP
131: connection which you are talking to.
132: It is used to switch between displays.
133: .FD
134: .IN "XCloseDisplay"
135: .IN "Definitions" "XCloseDisplay"
136: XCloseDisplay (display)
137: Display *display;
138: .FN
139: .LP
140: \fIXCloseDisplay\fP closes the connection associated with the specified
141: \fIdisplay\fP.
142: All windows or other resources that the caller has created on this display
143: server are destroyed; they should never be referenced again.
144: Any output events
145: that have been buffered but not yet sent are discarded.
146: .PP
147: The effect of \fIXCloseDisplay\fP is automatically achieved if a process exits.
148: For this reason, most clients
149: will not need to call \fIXCloseDisplay\fP.
150: .PP
151: .IN "Resource ID"
152: If a client has created Window, Font, Bitmap, Pixmap, or Cursor
153: resource ID's with this display server, they must not be used after calling
154: .IN "XCloseDisplay"
155: XCloseDisplay.
156: .PP
157: .IN "Unix System Call" "fork"
158: A special note on \fIfork()\fP: if a program has a connection to a display
159: server open and then
160: calls \fIfork()\fP you must take typical
161: UNIX care when dealing with the
162: connection to the window system.
163: Do not forget to flush the output buffer before waiting on the child
164: process, and do not forget to make sure that you have processed all input
165: events before forking or exiting in the child, or your programs
166: may perform the operations twice.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.