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 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.
111 Currently \fB\-fullscreen\fP may only be applied to one X screen.
114 Do not give the Cygwin/X window a \fIWindows\fP window border, title bar,
116 This parameter is ignored when the \fB\-fullscreen\fP parameter is specified.
119 Alternative name for \fB\-resize=scrollbars\fP.
121 .SH OPTIONS CONTROLLING RESIZE BEHAVIOUR
123 .B \-resize[=none|scrollbars|randr]
124 Select the resize mode of an X screen. The default is randr.
127 .IP \fB\-resize=none\fP 8
128 The screen is not resizable.
130 In windowed mode, if the window has decorations, a fixed frame is used.
132 Alternative name is \fB\-noresize\fP.
134 .IP \fB\-resize=scrollbars\fP 8
135 The screen window is resizeable, but the screen is not resizable.
137 In windowed mode, if the window has decorations, a resizing frame is used.
138 Scrollbars are drawn when needed to allow the entire X screen
139 to viewed by adjusting them.
141 This also permits screens bigger than the \fIWindows\fP virtual desktop to be used.
143 This parameter is ignored in \fB-multiwindow\fP or \fB-rootless\fP mode.
144 Alternative name is \fB\-scrollbars\fP.
146 .IP \fB\-resize=randr\fP 8
147 The screen is resizable and the screen window is resizeable.
149 In windowed mode, if the window has decorations, a resizing frame is used.
151 Resizing the \fIWindows\fP window will use the RANDR extension to change
152 the size of the X screen. Likewise, changing the size of
153 the X screen using the RANDR extension will cause the size
154 of the \fIWindows\fP window containing the X screen to be changed.
156 In \fB-multiwindow\fP or \fB-rootless\fP mode, if the X screen is
157 of the same dimensions as a Windows monitor or the virtual desktop,
158 the X server will respond to the WM_DISPLAYCHANGED sent when those
159 dimensions change by resizing the X screen. Changing the size
160 of the X screen using the RANDR extension is not permitted.
162 The maximum dimensions of the screen are the dimensions of the \fIWindows\fP virtual desktop.
165 on its own is equivalent to \fB\-resize=randr\fP
168 .SH OPTIONS CONTROLLING WINDOWS INTEGRATION
171 Enables [disables] the integration between the Cygwin/X clipboard and
172 \fIWindows\fP clipboard. The default is enabled.
174 .B "\-emulate3buttons [\fItimeout\fP]"
175 Emulate a three button mouse; pressing both buttons within
177 milliseconds causes an emulated middle button press. The default
179 is 50 milliseconds. Note that most mice with scroll wheel have middle
180 button functionality, usually you will need this option only if you have
181 a two button mouse without scroll wheel. Default is to enable this
182 option if \fIWindows\fP reports a two button mouse, disabled otherwise.
185 Enable [disable] a low-level keyboard hook for catching
186 special keypresses like Menu and Alt+Tab and passing them to the X
187 Server instead of letting \fIWindows\fP handle them.
190 Normally the \fIWindows\fP mouse cursor is hidden when the mouse is
191 over an active Cygwin/X window. This option causes the mouse cursor
192 also to be hidden when it is over an inactive Cygwin/X window. This
193 prevents the \fIWindows\fP mouse cursor from being drawn on top of the X
195 This parameter has no effect unless \fB-swcursor\fP is also specified.
198 Disable the usage of the \fIWindows\fP cursor and use the X11 software cursor instead.
201 Do not create a tray icon. Default is to create one
202 icon per screen. You can globally disable tray icons with
203 \fB\-notrayicon\fP, then enable it for specific screens with
204 \fB\-trayicon\fP for those screens.
206 .B \-nounicodeclipboard
207 Do not use Unicode clipboard even if on a NT-based platform.
210 Enable or disable the \fICtrl-Alt-Backspace\fP key combination as a
211 signal to exit the X Server. The \fICtrl-Alt-Backspace\fP key combination
212 is disabled by default.
215 Enable [disable] the GLX extension to use the native Windows WGL interface
216 for hardware accelerated OpenGL (AIGLX). The default is enabled.
219 Enable or disable the \fIAlt-F4\fP key combination as a signal to exit the
221 The \fIAlt-F4\fP key combination is enabled by default.
223 .SH DRAWING ENGINE OPTIONS
225 .B "\-clipupdates \fInum_boxes\fP"
226 Specify an optional threshold, above which the regions in a shadow
227 update operation will be collected into a GDI clipping region. The
228 clipping region is then used to do a single bit block transfer that is
229 constrained to the updated area by the clipping region. There is some
230 overhead involved in creating, installing, destroying, and removing
231 the clipping region, thus there may not be much benefit for a small
232 number of boxes (less than 10). It is even possible that this
233 functionality does not provide a benefit at any number of boxes; we
234 can only determine the usefulness of this feature through testing.
235 This option probably has limited effect on current \fIWindows\fP versions
236 as they already perform GDI batching.
237 This parameter works in conjunction with engines 1, 2, and 4 (Shadow
238 GDI, Shadow DirectDraw, and Shadow DirectDraw Non-Locking,
241 .B "\-engine \fIengine_type_id\fP"
242 This option, which is intended for Cygwin/X developers,
243 overrides the server's automatically selected drawing engine type. This
244 parameter will be ignored if the specified drawing engine type is not
245 supported on the current system.
247 Default behavior is to select the drawing engine with optimum performance that
248 supports the specified depth and window configuration.
250 The engine type ids are:
257 Shadow DirectDraw Non-Locking
259 Primary DirectDraw (unsupported, obsolete)
261 Native GDI (unsupported, experimental and barely functional)
264 .SH FULLSCREEN OPTIONS
266 .B "\-depth \fIdepth\fP"
267 Specify the color depth, in bits per pixel, to use when running in
268 fullscreen with a DirectDraw engine. This parameter is ignored if
269 \fB\-fullscreen\fP is not specified.
271 .B "\-refresh \fIrate_in_Hz\fP"
272 Specify an optional refresh rate to use when running in
273 fullscreen with a DirectDraw engine. This parameter is ignored if
274 \fB\-fullscreen\fP is not specified.
276 .SH MISCELLANEOUS OPTIONS
277 See also the normal server options described in the \fIXserver(1)\fP
282 Write a help text listing supported command line options and their description to the console.
285 Ignore keyboard and mouse input. This is usually only used for testing
286 and debugging purposes.
288 .B "\-logfile \fIfilename\fP"
289 Change the server log file from the default of \fI
290 __logdir__/XWin.n.log\fP,
291 where \fIn\fP is the display number of the XWin server, to \fIfilename\fP.
293 .B "\-logverbose \fIlevel\fP"
294 Control the degree of verbosity of the log messages with the integer
295 parameter \fIlevel\fP. For \fIlevel\fP=0 only fatal errors are
296 reported, for \fIlevel\fP=1 simple information about
297 configuration is also given, for \fIlevel\fP=2 (default)
298 additional runtime information is recorded
299 and for \fIlevel\fP=3 detailed log
300 information (including trace and debug output) is produced. Bigger
301 values will yield a still more detailed debug output.
303 .B \-silent-dup-error
304 If another instance of \fIXWin\fP with the same display number is found running,
305 exit silently and don't display any error message.
307 .B "\-xkblayout \fIlayout\fP"
309 .B "\-xkbmodel \fImodel\fP"
311 .B "\-xkboptions \fIoption\fP"
313 .B "\-xkbrules \fIrule\fP"
315 .B "\-xkbvariant \fIvariant\fp"
316 These options configure the xkeyboard extension to load
317 a particular keyboard map as the X server starts. The behavior is similar
318 to the \fIsetxkbmap\fP(1) program.
320 See the \fIxkeyboard-config\fP(__miscmansuffix__) manual page for a list of
321 keyboard configurations.
323 The keyboard layout data is located at \fI__datadir__/X11/xkb/\fP. Additional information
324 can be found in the README files there and in the \fIsetxkbmap\fP(1) manual page.
326 For example, in order to load a German layout for a pc105 keyboard, use the options:
328 .I " \-xkblayout de \-xkbmodel pc105"
330 Alternatively, you can use the \fIsetxkbmap\fP(1) program after \fIXWin\fP is
333 The default is to select a keyboard configuration matching your current layout as
334 reported by \fIWindows\fP, if known, or the default X server configuration
335 if no matching keyboard configuration was found.
337 .SH UNDOCUMENTED OPTIONS
338 These options are undocumented. Do not use them.
342 Create a depth 8 PseudoColor visual when running in depths 15, 16, 24,
343 or 32, collectively known as TrueColor depths.
344 Color map manipulation is not supported, so the PseudoColor visual will
345 not have the correct colors.
346 This option is intended to allow applications which only work with a depth 8
347 visual to operate in TrueColor modes.
350 Run the internal window manager.
353 As it runs \fIXWin\fP writes messages indicating the most relevant events
355 from which it was called and to a log file that by default is located at \fI
356 __logdir__/XWin.0.log\fP. This file is mainly for debugging purposes.
360 On startup \fIXWin\fP looks for the file \fI$HOME/.XWinrc\fP or, if
361 the previous file does not exist, \fI
362 __sysconfdir__/X11/system.XWinrc\fP. \fI.XWinrc\fP allows setting
363 preferences for the following:
365 * To include items into the menu associated with the \fIXWin\fP icon
366 which is in the \fIWindows\fP system tray. This functions in all
367 modes that have a tray icon.
369 * To include items in the system menu which is associated with the \fIWindows\fP
370 window that \fIXWin -multiwindow\fP produces for each top-level X
371 window, in both the generic case and for particular programs.
373 * To change the icon that is associated to the \fIWindows\fP window that
374 \fIXWin -multiwindow\fP produces for each top-level X-window.
376 * To change the style that is associated to the \fIWindows\fP window that
377 \fXWin I-multiwindow\fP produces for each top-level X window.
379 The format of the \fI.XWinrc\fP file is given in the XWinrc(5) manual page.
386 X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(__filemansuffix__),
387 setxkbmap(1), xkeyboard-config(__miscmansuffix__).
392 and this manual page still have many limitations.
394 The \fIXWin\fP software is continuously developing; it is therefore possible that
395 this manual page is not up to date. It is always prudent to
396 look also at the output of \fIXWin -help\fP in order to
397 check the options that are operative.
401 This list is by no means complete, but direct contributors to the
402 Cygwin/X project include (in alphabetical order by last name): Stuart
403 Adamson, Michael Bax, Jehan Bing, Lev Bishop, Dr. Peter Busch, Biju G
404 C, Robert Collins, Nick Crabtree, Early Ehlinger, Christopher Faylor,
405 John Fortin, Brian Genisio, Fabrizio Gennari, Alexander Gottwald, Ralf
406 Habacker, Colin Harrison, Matthieu Herrb, Alan Hourihane, Pierre A
407 Humblet, Harold L Hunt II, Dakshinamurthy Karra, Joe Krahn,
408 Paul Loewenstein, Kensuke Matsuzaki,
409 Takuma Murakami, Earle F. Philhower III, Benjamin Riefenstahl, Yaakov Selkowitz,
410 Suhaib Siddiqi, Jack Tanner, Jon Turney and Nicholas Wourms.