| 1 | .TH XWIN 1 __vendorversion__ |
| 2 | .SH NAME |
| 3 | XWin \- X Server for the Cygwin environment on Microsoft Windows |
| 4 | |
| 5 | |
| 6 | .SH SYNOPSIS |
| 7 | .B XWin |
| 8 | [ options ] ... |
| 9 | |
| 10 | |
| 11 | .SH DESCRIPTION |
| 12 | \fIXWin\fP is an X Server for the X Window System on the Cygwin environment |
| 13 | running on Microsoft Windows. |
| 14 | |
| 15 | |
| 16 | .SH MODES |
| 17 | \fIXWin\fP can operate in 3 different modes: |
| 18 | .br |
| 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 |
| 21 | within this window. |
| 22 | (In X terminology, the \fIWindows\fP window contains the root window for |
| 23 | the screen) |
| 24 | .br |
| 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. |
| 28 | .br |
| 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. |
| 32 | |
| 33 | .SH OPTIONS |
| 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: |
| 37 | |
| 38 | .SH OPTIONS CONTROLLING WINDOWING MODE |
| 39 | Only one of these options may be specified. |
| 40 | .TP 8 |
| 41 | .B (default) |
| 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. |
| 45 | .TP 8 |
| 46 | .B \-multiwindow |
| 47 | Each top-level X window appears in its own \fIWindows\fP window. |
| 48 | Also start the integrated \fIWindows\fP-based window manager. |
| 49 | .TP 8 |
| 50 | .B \-rootless |
| 51 | Run the server in rootless mode. |
| 52 | The X server works on a window covering the whole screen but the root window |
| 53 | is hidden from view. |
| 54 | .TP 8 |
| 55 | .B \-mwextwm |
| 56 | Experimental. |
| 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. |
| 59 | .PP |
| 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. |
| 63 | |
| 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). |
| 69 | |
| 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. |
| 75 | .TP 8 |
| 76 | .B \-[no]multimonitors or \-[no]multiplemonitors |
| 77 | Create a screen 0 that covers all monitors [the primary monitor] on a system with |
| 78 | multiple monitors. |
| 79 | This option is currently enabled by default in \fB\-multiwindow\fP mode. |
| 80 | .TP 8 |
| 81 | .B "\-screen \fIscreen_number\fP [\fIW\fP \fIH\fP [\fIX\fP \fIY\fP] | [[\fIW\fPx\fIH\fP[+\fIX\fP+\fIY\fP]][@\fIM\fP]] ] " |
| 82 | Create screen number |
| 83 | .I screen_number |
| 84 | and optionally specify it's |
| 85 | .I height, |
| 86 | .I width |
| 87 | and |
| 88 | .I initial position. |
| 89 | Additionally a |
| 90 | .I |
| 91 | monitor number |
| 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. |
| 95 | |
| 96 | Examples: |
| 97 | |
| 98 | .I " -screen 0 @1 ; on 1st monitor using its full resolution (the default)" |
| 99 | |
| 100 | .I " -screen 0 800x600+100+100@2 ; on 2nd monitor offset 100,100 size 800x600" |
| 101 | |
| 102 | .I " -screen 0 1024x768@3 ; on 3rd monitor size 1024x768" |
| 103 | |
| 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. |
| 107 | .TP 8 |
| 108 | .B "\-fullscreen" |
| 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. |
| 112 | .TP 8 |
| 113 | .B \-nodecoration |
| 114 | Do not give the Cygwin/X window a \fIWindows\fP window border, title bar, |
| 115 | etc. |
| 116 | This parameter is ignored when the \fB\-fullscreen\fP parameter is specified. |
| 117 | .TP 8 |
| 118 | .B \-scrollbars |
| 119 | Alternative name for \fB\-resize=scrollbars\fP. |
| 120 | |
| 121 | .SH OPTIONS CONTROLLING RESIZE BEHAVIOUR |
| 122 | .TP 8 |
| 123 | .B \-resize[=none|scrollbars|randr] |
| 124 | Select the resize mode of an X screen. The default is randr. |
| 125 | |
| 126 | .RS |
| 127 | .IP \fB\-resize=none\fP 8 |
| 128 | The screen is not resizable. |
| 129 | |
| 130 | In windowed mode, if the window has decorations, a fixed frame is used. |
| 131 | |
| 132 | Alternative name is \fB\-noresize\fP. |
| 133 | |
| 134 | .IP \fB\-resize=scrollbars\fP 8 |
| 135 | The screen window is resizeable, but the screen is not resizable. |
| 136 | |
| 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. |
| 140 | |
| 141 | This also permits screens bigger than the \fIWindows\fP virtual desktop to be used. |
| 142 | |
| 143 | This parameter is ignored in \fB-multiwindow\fP or \fB-rootless\fP mode. |
| 144 | Alternative name is \fB\-scrollbars\fP. |
| 145 | |
| 146 | .IP \fB\-resize=randr\fP 8 |
| 147 | The screen is resizable and the screen window is resizeable. |
| 148 | |
| 149 | In windowed mode, if the window has decorations, a resizing frame is used. |
| 150 | |
| 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. |
| 155 | |
| 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. |
| 161 | |
| 162 | The maximum dimensions of the screen are the dimensions of the \fIWindows\fP virtual desktop. |
| 163 | |
| 164 | .IP \fB\-resize\fP 8 |
| 165 | on its own is equivalent to \fB\-resize=randr\fP |
| 166 | .RE |
| 167 | |
| 168 | .SH OPTIONS CONTROLLING WINDOWS INTEGRATION |
| 169 | .TP 8 |
| 170 | .B \-[no]clipboard |
| 171 | Enables [disables] the integration between the Cygwin/X clipboard and |
| 172 | \fIWindows\fP clipboard. The default is enabled. |
| 173 | .TP 8 |
| 174 | .B "\-emulate3buttons [\fItimeout\fP]" |
| 175 | Emulate a three button mouse; pressing both buttons within |
| 176 | .I timeout |
| 177 | milliseconds causes an emulated middle button press. The default |
| 178 | .I timeout |
| 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. |
| 183 | .TP 8 |
| 184 | .B \-[no]keyhook |
| 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. |
| 188 | .TP 8 |
| 189 | .B \-lesspointer |
| 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 |
| 194 | cursor. |
| 195 | This parameter has no effect unless \fB-swcursor\fP is also specified. |
| 196 | .TP 8 |
| 197 | .B \-swcursor |
| 198 | Disable the usage of the \fIWindows\fP cursor and use the X11 software cursor instead. |
| 199 | .TP 8 |
| 200 | .B \-[no]trayicon |
| 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. |
| 205 | .TP 8 |
| 206 | .B \-nounicodeclipboard |
| 207 | Do not use Unicode clipboard even if on a NT-based platform. |
| 208 | .TP 8 |
| 209 | .B \-[no]unixkill |
| 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. |
| 213 | .TP 8 |
| 214 | .B \-[no]wgl |
| 215 | Enable [disable] the GLX extension to use the native Windows WGL interface |
| 216 | for hardware accelerated OpenGL (AIGLX). The default is enabled. |
| 217 | .TP 8 |
| 218 | .B \-[no]winkill |
| 219 | Enable or disable the \fIAlt-F4\fP key combination as a signal to exit the |
| 220 | X Server. |
| 221 | The \fIAlt-F4\fP key combination is enabled by default. |
| 222 | |
| 223 | .SH DRAWING ENGINE OPTIONS |
| 224 | .TP 8 |
| 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, |
| 239 | respectively). |
| 240 | .TP 8 |
| 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. |
| 246 | |
| 247 | Default behavior is to select the drawing engine with optimum performance that |
| 248 | supports the specified depth and window configuration. |
| 249 | |
| 250 | The engine type ids are: |
| 251 | .RS |
| 252 | .IP 1 4 |
| 253 | Shadow GDI |
| 254 | .IP 2 4 |
| 255 | Shadow DirectDraw |
| 256 | .IP 4 4 |
| 257 | Shadow DirectDraw Non-Locking |
| 258 | .IP 8 4 |
| 259 | Primary DirectDraw (unsupported, obsolete) |
| 260 | .IP 16 4 |
| 261 | Native GDI (unsupported, experimental and barely functional) |
| 262 | .RE |
| 263 | |
| 264 | .SH FULLSCREEN OPTIONS |
| 265 | .TP 8 |
| 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. |
| 270 | .TP 8 |
| 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. |
| 275 | |
| 276 | .SH MISCELLANEOUS OPTIONS |
| 277 | See also the normal server options described in the \fIXserver(1)\fP |
| 278 | manual page |
| 279 | |
| 280 | .TP 8 |
| 281 | .B \-help |
| 282 | Write a help text listing supported command line options and their description to the console. |
| 283 | .TP 8 |
| 284 | .B \-ignoreinput |
| 285 | Ignore keyboard and mouse input. This is usually only used for testing |
| 286 | and debugging purposes. |
| 287 | .TP 8 |
| 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. |
| 292 | .TP 8 |
| 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. |
| 302 | .TP 8 |
| 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. |
| 306 | .TP 8 |
| 307 | .B "\-xkblayout \fIlayout\fP" |
| 308 | .TP 8 |
| 309 | .B "\-xkbmodel \fImodel\fP" |
| 310 | .TP 8 |
| 311 | .B "\-xkboptions \fIoption\fP" |
| 312 | .TP 8 |
| 313 | .B "\-xkbrules \fIrule\fP" |
| 314 | .TP 8 |
| 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. |
| 319 | |
| 320 | See the \fIxkeyboard-config\fP(__miscmansuffix__) manual page for a list of |
| 321 | keyboard configurations. |
| 322 | |
| 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. |
| 325 | |
| 326 | For example, in order to load a German layout for a pc105 keyboard, use the options: |
| 327 | .br |
| 328 | .I " \-xkblayout de \-xkbmodel pc105" |
| 329 | |
| 330 | Alternatively, you can use the \fIsetxkbmap\fP(1) program after \fIXWin\fP is |
| 331 | running. |
| 332 | |
| 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. |
| 336 | |
| 337 | .SH UNDOCUMENTED OPTIONS |
| 338 | These options are undocumented. Do not use them. |
| 339 | |
| 340 | .TP 8 |
| 341 | .B \-emulatepseudo |
| 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. |
| 348 | .TP 8 |
| 349 | .B \-internalwm |
| 350 | Run the internal window manager. |
| 351 | |
| 352 | .SH LOG FILE |
| 353 | As it runs \fIXWin\fP writes messages indicating the most relevant events |
| 354 | to the console |
| 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. |
| 357 | |
| 358 | |
| 359 | .SH PREFERENCES FILE |
| 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: |
| 364 | .br |
| 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. |
| 368 | .br |
| 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. |
| 372 | .br |
| 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. |
| 375 | .br |
| 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. |
| 378 | .PP |
| 379 | The format of the \fI.XWinrc\fP file is given in the XWinrc(5) manual page. |
| 380 | |
| 381 | .SH EXAMPLES |
| 382 | Need some examples |
| 383 | |
| 384 | |
| 385 | .SH "SEE ALSO" |
| 386 | X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(__filemansuffix__), |
| 387 | setxkbmap(1), xkeyboard-config(__miscmansuffix__). |
| 388 | |
| 389 | |
| 390 | .SH BUGS |
| 391 | .I XWin |
| 392 | and this manual page still have many limitations. |
| 393 | |
| 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. |
| 398 | |
| 399 | |
| 400 | .SH AUTHORS |
| 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. |