1
.\" $Xorg: Xnest.man,v 1.3 2000/08/17 19:53:28 cpqbld Exp $
2
.\" Copyright (c) 1993, 1994 X Consortium
4
.\" Permission is hereby granted, free of charge, to any person obtaining
5
.\" a copy of this software and associated documentation files (the
6
.\" "Software"), to deal in the Software without restriction, including
7
.\" without limitation the rights to use, copy, modify, merge, publish,
8
.\" distribute, sublicense, and/or sell copies of the Software, and to
9
.\" permit persons to whom the Software is furnished to do so, subject to
10
.\" the following conditions:
12
.\" The above copyright notice and this permission notice shall be included
13
.\" in all copies or substantial portions of the Software.
15
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
19
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
20
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
21
.\" OTHER DEALINGS IN THE SOFTWARE.
23
.\" Except as contained in this notice, the name of the X Consortium shall
24
.\" not be used in advertising or otherwise to promote the sale, use or
25
.\" other dealings in this Software without prior written authorization
26
.\" from the X Consortium.
28
.\" $XFree86: xc/programs/Xserver/hw/xnest/Xnest.man,v 1.6 2001/01/27 18:21:00 dawes Exp $
30
.TH Xnest __appmansuffix__ __xorgversion__
32
Xnest \- a nested X server
40
is both an X client and an X server.
42
is a client of the real server which manages windows and graphics requests on
45
is a server to its own clients.
47
manages windows and graphics requests on their behalf.
50
appears to be a conventional server.
53
supports all standard options of the sample server implementation.
54
For more details, please see
55
.BR Xserver (__appmansuffix__).
56
The following additional arguments are supported as well.
58
.BI "\-display " string
59
This option specifies the display name of the real server that
61
should try to connect to.
62
If it is not provided on the command line,
66
environment variable in order to find out this information.
71
to synchronize its window and graphics operations with the real server.
72
This is a useful option for debugging, but it will slow down
74
performance considerably.
75
It should not be used unless absolutely necessary.
80
to utilize full regeneration of real server objects and reopen a new connection
81
to the real server each time the nested server regenerates.
82
The sample server implementation regenerates all objects in the server when the
83
last client of this server terminates.
86
by default maintains the same top-level window and the same real server
87
connection in each new generation.
88
If the user selects full regeneration, even the top-level window and the
89
connection to the real server will be regenerated for each server generation.
92
This option specifies the default visual class of the nested server.
95
option from the set of standard options except that it will accept a string
96
rather than a number for the visual class specification.
99
must be one of the following six values:
111
options are specified, the last instance of either option takes precedence.
112
The class of the default visual of the nested server need not be the same as the
113
class of the default visual of the real server, but it must be supported by the
116
.BR xdpyinfo (__appmansuffix__)
117
to obtain a list of supported visual classes on the real server before starting
119
If the user chooses a static class, all the colors in the default color map will
121
If the user chooses a dynamic class, colors in the default color map will be
122
available to individual clients for allocation.
125
This option specifies the default visual depth of the nested server.
126
The depth of the default visual of the nested server need not be the same as the
127
depth of the default visual of the real server, but it must be supported by the
130
.BR xdpyinfo (__appmansuffix__)
131
to obtain a list of supported visual depths on the real server before starting
137
to use the software screen saver.
140
will use the screen saver that corresponds to the hardware screen saver in the
142
Of course, even this screen saver is software-generated since
144
does not control any actual hardware.
145
However, it is treated as a hardware screen saver within the sample server code.
147
.B \-geometry \fIW\fBx\fIH\fB+\fIX\fB+\fIY\fP
148
This option specifies the geometry parameters for the top-level
151
See \(lqGEOMETRY SPECIFICATIONS\(rq in
152
.BR X (__miscmansuffix__)
153
for a discusson of this option's syntax.
154
This window corresponds to the root window of the nested server.
159
specified with this option will be the maximum width and height of each
164
will allow the user to make any top-level window smaller, but it will not
165
actually change the size of the nested server root window.
167
does not yet support the RANDR extension for resizing, rotation, and reflection
169
If this option is not specified,
175
to be 3/4ths the dimensions of the root window of the real server.
178
This option specifies the border width of the top-level
181
The integer parameter
184
The default border width is 1.
187
This option specifies the name of the top-level
191
The default value is the program name.
194
This option specifies the number of screens to create in the nested server.
197
will create a separate top-level window.
198
Each screen is referenced by the number after the dot in the client display name
201
.B xterm \-display :1.1
203
.BR xterm (__appmansuffix__)
204
client in the nested server with the display number
206
on the second screen.
207
The number of screens is limited by the hard-coded constant in the server sample
208
code, which is usually 3.
213
to do its own color map installation by bypassing the real window manager.
214
For it to work properly, the user will probably have to temporarily quit the
218
will keep the nested client window whose color map should be installed in the
220
.I WM_COLORMAP_WINDOWS
221
property of the top-level
224
If this color map is of the same visual type as the root window of the nested
227
will associate this color map with the top-level
230
Since this does not have to be the case, window managers should look primarily
232
.I WM_COLORMAP_WINDOWS
233
property rather than the color map associated with the top-level
236
.\" Is the following still true? This sentence is several years old.
237
Unfortunately, window managers are not very good at doing that yet so this
238
option might come in handy.
240
.BI "\-parent " window_id
245
as the root window instead of creating a window.
246
.\" XRX is dead, dead, dead.
247
.\" This option is used by the xrx xnestplugin.
248
.SH "EXTENDED DESCRIPTION"
251
is just as simple as starting up
252
.BR xclock (__appmansuffix__)
253
from a terminal emulator.
254
If a user wishes to run
257
workstation as the real server, it is important that the nested server is given
258
its own listening socket address.
259
Therefore, if there is a server already running on the user's workstation,
261
will have to be started up with a new display number.
262
Since there is usually no more than one server running on a workstation,
264
.RB \(oq "Xnest :1" \(cq
265
on the command line will be sufficient for most users.
266
For each server running on the workstation, the display number needs to be
268
Thus, if you wish to start another
270
you will need to type
271
.RB \(oq "Xnest :2" \(cq
274
To run clients in the nested server, each client needs to be given the same
275
display number as the nested server.
277
.RB \(oq "xterm \-display :1" \(cq
280
process in the first nested server
282
.RB \(oq "xterm \-display :2" \(cq
285
in the second nested server from the example above.
286
Additional clients can be started from these
288
in each nested server.
289
.SS "Xnest as a client"
291
behaves and looks to the real server and other real clients as another real
293
It is a rather demanding client, however, since almost any window or graphics
294
request from a nested client will result in a window or graphics request from
297
Therefore, it is desirable that
299
and the real server are on a local network, or even better, on the same machine.
301
assumes that the real server supports the SHAPE extension.
302
There is no way to turn off this assumption dynamically.
304
can be compiled without the SHAPE extension built in, in which case the real
305
server need not support it.
306
Dynamic SHAPE extension selection support may be considered in further
312
need not use the same default visual as the the real server, the top-level
315
client always has its own color map.
316
This implies that other windows' colors will not be displayed properly while the
317
keyboard or pointer focus is in the
319
window, unless the real server has support for more than one installed color map
321
The color map associated with the top window of the
323
client need not be the appropriate color map that the nested server wants
324
installed in the real server.
325
In the case that a nested client attempts to install a color map of a different
326
visual from the default visual of the nested server,
328
will put the top window of this nested client and all other top windows of the
329
nested clients that use the same color map into the
330
.I WM_COLORMAP_WINDOWS
331
property of the top-level
333
window on the real server.
334
Thus, it is important that the real window manager that manages the
336
top-level window looks at the
337
.I WM_COLORMAP_WINDOWS
338
property rather than the color map associated with the top-level
341
Since most window managers don't yet appear to implement this convention
344
can optionally do direct installation of color maps into the real server
345
bypassing the real window manager.
346
If the user chooses this option, it is usually necessary to temporarily disable
347
the real window manager since it will interfere with the
349
scheme of color map installation.
351
Keyboard and pointer control procedures of the nested server change the keyboard
352
and pointer control parameters of the real server.
355
is started up, it will change the keyboard and pointer controls of the real
356
server to its own internal defaults.
357
.SS "Xnest as a server"
359
as a server looks exactly like a real server to its own clients.
360
For the clients, there is no way of telling if they are running on a real or a
363
As already mentioned,
365
is a very user-friendly server when it comes to customization.
367
will pick up a number of command-line arguments that can configure its default
368
visual class and depth, number of screens, etc.
370
The only apparent intricacy from the users' perspective about using
372
as a server is the selection of fonts.
374
manages fonts by loading them locally and then passing the font name to the real
375
server and asking it to load that font remotely.
376
This approach avoids the overload of sending the glyph bits across the network
377
for every text operation, although it is really a bug.
378
The consequence of this approach is that the user will have to worry about two
379
different font paths \(em a local one for the nested server and a remote one for
380
the real server \(em since
382
does not propagate its font path to the real server.
383
The reason for this is because real and nested servers need not run on the same
384
file system which makes the two font paths mutually incompatible.
385
Thus, if there is a font in the local font path of the nested server, there is
386
no guarantee that this font exists in the remote font path of the real server.
388
.BR xlsfonts (__appmansuffix__)
389
client, if run on the nested server, will list fonts in the local font path and,
390
if run on the real server, will list fonts in the remote font path.
391
Before a font can be successfully opened by the nested server, it has to exist
392
in local and remote font paths.
393
It is the users' responsibility to make sure that this is the case.
394
.SH "FUTURE DIRECTIONS"
395
Make dynamic the requirement for the SHAPE extension in the real server, rather
396
than having to recompile
398
to turn this requirement on and off.
400
Perhaps there should be a command-line option to tell
402
to inherit the keyboard and pointer control parameters from the real server
403
rather than imposing its own.
406
should read a customization input file to provide even greater freedom and
407
simplicity in selecting the desired layout.
409
There is no support for backing store and save unders, but this should also be
412
.\" Is the following still true now that client-side font rendering is
413
.\" considered the way to go?
414
The proper implementation of fonts should be moved into the
418
Doesn't run well on servers supporting different visual depths.
420
Still crashes randomly.
422
Probably has some memory leaks.
424
Davor Matic, MIT X Consortium
426
.BR Xserver (__appmansuffix__),
427
.BR xdpyinfo (__appmansuffix__),
428
.BR X (__miscmansuffix__)
added
removed
hw/xnest/Xnest.man.pre
