Commit | Line | Data |
---|---|---|
a09e091a JB |
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. |