1
.TH XWIN 1 __vendorversion__
3
XWin \- X Server for the Cygwin environment on Microsoft Windows
12
\fIXWin\fP is an X Server for the X Window System on the Cygwin environment
13
running on Microsoft Windows.
17
\fIXWin\fP can operate in 3 different modes:
19
* \fISingle Window\fP: This is the default mode. Each X screen
20
appears as a single \fIWindows\fP window and all X windows are contained
22
(In X terminology, the \fIWindows\fP window contains the root window for
25
* \fIMulti-Window\fP: In this mode \fIXWin\fP uses its own integrated
26
window manager in order to handle the top-level X windows, in such a
27
way that they appear as normal \fIWindows\fP windows.
29
* \fIRootless\fP: In this mode the X server works in a window
30
containing the whole screen but this root window (traditionally covered with an X hatch
31
pattern) is hidden from view, so only top-level X windows are seen.
34
In addition to the normal server options described in the \fIXserver(1)\fP
35
manual page, \fIXWin\fP accepts the following command line switches,
36
\fIall\fP of which are optional:
38
.SH OPTIONS CONTROLLING WINDOWING MODE
39
Only one of these options may be specified.
42
Windowed or rooted mode.
43
Each X screen appears as a single \fIWindows\fP window and all X windows are
44
contained within those windows.
47
Each top-level X window appears in its own \fIWindows\fP window.
48
Also start the integrated \fIWindows\fP-based window manager.
51
Run the server in rootless mode.
52
The X server works on a window covering the whole screen but the root window
57
The mode combines \fB\-rootless\fP mode drawing with native \fIWindows\fP
58
window frames managed by the experimental external window manager \fIxwinwm\fP.
60
\fBNOTE:\fP \fI-multiwindow\fP mode uses its own internal window manager.
61
All other modes require an external window manager in order to move, resize, and perform other
62
operations on the individual X windows.
64
.SH OPTIONS FOR SPECIFYING X SCREENS
65
An X display may be composed of multiple screens.
66
The default behaviour is to create a single screen 0 that is roughly the
67
size of useful area of the primary monitor (allowing for any window
68
decorations and the task-bar).
70
Screen specific parameters, such as \fB\-fullscreen\fP, can be applied as a
71
default to all screens by placing those screen specific parameters
72
before any \fB\-screen\fP parameter. Screen specific parameters placed after
73
the first \fB\-screen\fP parameter will apply only to the immediately
74
preceeding \fB\-screen\fP parameter.
76
.B \-[no]multimonitors or \-[no]multiplemonitors
77
Create a screen 0 that covers all monitors [the primary monitor] on a system with
79
This option is currently enabled by default in \fB\-multiwindow\fP mode.
81
.B "\-screen \fIscreen_number\fP [\fIW\fP \fIH\fP [\fIX\fP \fIY\fP] | [[\fIW\fPx\fIH\fP[+\fIX\fP+\fIY\fP]][@\fIM\fP]] ] "
84
and optionally specify it's
92
(which count from 1) can be specified to place the screen on,
93
at which point, all coordinates become relative to that monitor.
94
Screen numbers must be contiguous starting from zero and cannot be duplicated.
98
.I " -screen 0 @1 ; on 1st monitor using its full resolution (the default)"
100
.I " -screen 0 800x600+100+100@2 ; on 2nd monitor offset 100,100 size 800x600"
102
.I " -screen 0 1024x768@3 ; on 3rd monitor size 1024x768"
104
.SH OPTIONS CONTROLLING THE APPEARANCE OF THE X SCREEN WINDOWS
105
These parameters only apply to windowed mode screens i.e. not
106
in \fB-multiwindow\fP or \fB-rootless\fP mode.
109
The X server window takes the full screen, covering completely the
110
\fIWindows\fP desktop.
113
Do not give the Cygwin/X window a \fIWindows\fP window border, title bar,
115
This parameter is ignored when the \fB\-fullscreen\fP parameter is specified.
118
Alternative name for \fB\-resize=scrollbars\fP.
120
.SH OPTIONS CONTROLLING RESIZE BEHAVIOUR
122
.B \-resize[=none|scrollbars|randr]
123
Select the resize mode of an X screen.
126
.IP \fB\-resize=none\fP 8
127
(default). The screen is not resizable.
129
In windowed mode, if the window has decorations, a fixed frame is used.
131
.IP \fB\-resize=scrollbars\fP 8
132
The screen window is resizeable, but the screen is not resizable.
134
In windowed mode, if the window has decorations, a resizing frame is used.
135
Scrollbars are drawn when needed to allow the entire X screen
136
to viewed by adjusting them.
138
This also permits screens bigger than the \fIWindows\fP virtual desktop to be used.
140
This parameter is ignored in \fB-multiwindow\fP or \fB-rootless\fP mode.
141
Alternative name is \fB\-scrollbars\fP.
143
.IP \fB\-resize=randr\fP 8
144
The screen is resizable and the screen window is resizeable.
146
In windowed mode, if the window has decorations, a resizing frame is used.
148
Resizing the \fIWindows\fP window will use the RANDR extension to change
149
the size of the X screen. Likewise, changing the size of
150
the X screen using the RANDR extension will cause the size
151
of the \fIWindows\fP window containing the X screen to be changed.
153
In \fB-multiwindow\fP or \fB-rootless\fP mode, if the X screen is
154
of the same dimensions as a Windows monitor or the virtual desktop,
155
the X server will respond to the WM_DISPLAYCHANGED sent when those
156
dimensions change by resizing the X screen. Changing the size
157
of the X screen using the RANDR extension is not permitted.
159
The maximum dimensions of the screen are the dimensions of the \fIWindows\fP virtual desktop.
161
.IP \fB\--resize\fP 8
162
on its own is equivalent to \fB\--resize=randr\fP
165
.SH OPTIONS CONTROLLING WINDOWS INTEGRATION
168
Enables [disables] the integration between the Cygwin/X clipboard and
169
\fIWindows\fP clipboard. The default is enabled.
171
.B "\-emulate3buttons [\fItimeout\fP]"
172
Emulate a three button mouse; pressing both buttons within
174
milliseconds causes an emulated middle button press. The default
176
is 50 milliseconds. Note that most mice with scroll wheel have middle
177
button functionality, usually you will need this option only if you have
178
a two button mouse without scroll wheel.
181
Enable [disable] a low-level keyboard hook for catching
182
special keypresses like Menu and Alt+Tab and passing them to the X
183
Server instead of letting \fIWindows\fP handle them.
186
Normally the \fIWindows\fP mouse cursor is hidden when the mouse is
187
over an active Cygwin/X window. This option causes the mouse cursor
188
also to be hidden when it is over an inactive Cygwin/X window. This
189
prevents the \fIWindows\fP mouse cursor from being drawn on top of the X
191
This parameter has no effect unless \fB-swcursor\fP is also specified.
194
Disable the usage of the \fIWindows\fP cursor and use the X11 software cursor instead.
197
Do not create a tray icon. Default is to create one
198
icon per screen. You can globally disable tray icons with
199
\fB\-notrayicon\fP, then enable it for specific screens with
200
\fB\-trayicon\fP for those screens.
202
.B \-nounicodeclipboard
203
Do not use Unicode clipboard even if on a NT-based platform.
206
Enable or disable the \fICtrl-Alt-Backspace\fP key combination as a
207
signal to exit the X Server. The \fICtrl-Alt-Backspace\fP key combination
208
is disabled by default.
211
Enable or disable the \fIAlt-F4\fP key combination as a signal to exit the
213
The \fIAlt-F4\fP key combination is enabled by default.
215
.SH DRAWING ENGINE OPTIONS
217
.B "\-clipupdates \fInum_boxes\fP"
218
Specify an optional threshold, above which the regions in a shadow
219
update operation will be collected into a GDI clipping region. The
220
clipping region is then used to do a single bit block transfer that is
221
constrained to the updated area by the clipping region. There is some
222
overhead involved in creating, installing, destroying, and removing
223
the clipping region, thus there may not be much benefit for a small
224
number of boxes (less than 10). It is even possible that this
225
functionality does not provide a benefit at any number of boxes; we
226
can only determine the usefulness of this feature through testing.
227
This option probably has limited effect on current \fIWindows\fP versions
228
as they already perform GDI batching.
229
This parameter works in conjunction with engines 1, 2, and 4 (Shadow
230
GDI, Shadow DirectDraw, and Shadow DirectDraw Non-Locking,
233
.B "\-engine \fIengine_type_id\fP"
234
This option, which is intended for Cygwin/X developers,
235
overrides the server's automatically selected drawing engine type. This
236
parameter will be ignored if the specified drawing engine type is not
237
supported on the current system.
239
Default behavior is to select the drawing engine with optimum performance that
240
supports the specified depth and window configuration.
242
The engine type ids are:
249
Shadow DirectDraw Non-Locking
251
Primary DirectDraw (unsupported, obsolete)
253
Native GDI (unsupported, experimental and barely functional)
256
.SH FULLSCREEN OPTIONS
258
.B "\-depth \fIdepth\fP"
259
Specify the color depth, in bits per pixel, to use when running in
260
fullscreen with a DirectDraw engine. This parameter is ignored if
261
\fB\-fullscreen\fP is not specified.
263
.B "\-refresh \fIrate_in_Hz\fP"
264
Specify an optional refresh rate to use when running in
265
fullscreen with a DirectDraw engine. This parameter is ignored if
266
\fB\-fullscreen\fP is not specified.
268
.SH MISCELLANEOUS OPTIONS
269
See also the normal server options described in the \fIXserver(1)\fP
274
Write a help text listing supported command line options and their description to the console.
277
Ignore keyboard and mouse input. This is usually only used for testing
278
and debugging purposes.
280
.B "\-logfile \fIfilename\fP"
281
Change the server log file from the default of \fI
282
__logdir__/XWin.n.log\fP,
283
where \fIn\fP is the display number of the XWin server, to \fIfilename\fP.
285
.B "\-logverbose \fIlevel\fP"
286
Control the degree of verbosity of the log messages with the integer
287
parameter \fIlevel\fP. For \fIlevel\fP=0 only fatal errors are
288
reported, for \fIlevel\fP=1 simple information about
289
configuration is also given, for \fIlevel\fP=2 (default)
290
additional runtime information is recorded
291
and for \fIlevel\fP=3 detailed log
292
information (including trace and debug output) is produced. Bigger
293
values will yield a still more detailed debug output.
295
.B \-silent-dup-error
296
If another instance of \fIXWin\fP with the same display number is found running,
297
exit silently and don't display any error message.
299
.B "\-xkblayout \fIlayout\fP"
301
.B "\-xkbmodel \fImodel\fP"
303
.B "\-xkboptions \fIoption\fP"
305
.B "\-xkbrules \fIrule\fP"
307
.B "\-xkbvariant \fIvariant\fp"
308
These options configure the xkeyboard extension to load
309
a particular keyboard map as the X server starts. The behavior is similar
310
to the \fIsetxkbmap\fP program. The layout data is located at \fI
311
__datadir__/X11/xkb/\fP. Additional information is found in the
312
README files therein and in the man page of \fIsetxkbmap\fP. For example
313
in order to load a German layout for a pc105 keyboard one uses
316
.I " \-xkblayout de \-xkbmodel pc105"
318
Alternatively one may use the \fIsetxkbmap\fP program after \fIXWin\fP is
321
The default is to select a configuration matching your current layout as
322
reported by \fIWindows\fP, if known, or the default X server configuration
323
if no matching keyboard configuration was found.
325
.SH UNDOCUMENTED OPTIONS
326
These options are undocumented. Do not use them.
330
Create a depth 8 PseudoColor visual when running in depths 15, 16, 24,
331
or 32, collectively known as TrueColor depths.
332
Color map manipulation is not supported, so the PseudoColor visual will
333
not have the correct colors.
334
This option is intended to allow applications which only work with a depth 8
335
visual to operate in TrueColor modes.
338
Run the internal window manager.
341
As it runs \fIXWin\fP writes messages indicating the most relevant events
343
from which it was called and to a log file that by default is located at \fI
344
__logdir__/XWin.0.log\fP. This file is mainly for debugging purposes.
348
On startup \fIXWin\fP looks for the file \fI$HOME/.XWinrc\fP or, if
349
the previous file does not exist, \fI
350
__sysconfdir__/X11/system.XWinrc\fP. \fI.XWinrc\fP allows setting
351
preferences for the following:
353
* To include items into the menu associated with the \fIXWin\fP icon
354
which is in the \fIWindows\fP system tray. This functions in all
355
modes that have a tray icon.
357
* To include items in the system menu which is associated with the \fIWindows\fP
358
window that \fIXWin -multiwindow\fP produces for each top-level X
359
window, in both the generic case and for particular programs.
361
* To change the icon that is associated to the \fIWindows\fP window that
362
\fIXWin -multiwindow\fP produces for each top-level X-window.
364
* To change the style that is associated to the \fIWindows\fP window that
365
\fXWin I-multiwindow\fP produces for each top-level X window.
367
The format of the \fI.XWinrc\fP file is given in the man page XWinrc(5).
374
X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(__filemansuffix__), setxkbmap(1)
379
and this man page still have many limitations.
381
The \fIXWin\fP software is continuously developing; it is therefore possible that
382
this man page is not up to date. It is always prudent to
383
look also at the output of \fIXWin -help\fP in order to
384
check the options that are operative.
388
This list is by no means complete, but direct contributors to the
389
Cygwin/X project include (in alphabetical order by last name): Stuart
390
Adamson, Michael Bax, Jehan Bing, Lev Bishop, Dr. Peter Busch, Biju G
391
C, Robert Collins, Nick Crabtree, Early Ehlinger, Christopher Faylor,
392
John Fortin, Brian Genisio, Fabrizio Gennari, Alexander Gottwald, Ralf
393
Habacker, Colin Harrison, Matthieu Herrb, Alan Hourihane, Pierre A
394
Humblet, Harold L Hunt II, Dakshinamurthy Karra, Joe Krahn,
395
Paul Loewenstein, Kensuke Matsuzaki,
396
Takuma Murakami, Earle F. Philhower III, Benjamin Riefenstahl, Yaakov Selkowitz,
397
Suhaib Siddiqi, Jack Tanner, Jon Turney and Nicholas Wourms.