XWIN

Section: User Commands (1)
Updated: xorg-server 21.1.1
Index Return to Main Contents

NAME

XWin - X Server for the Cygwin environment on Microsoft Windows

SYNOPSIS

XWin [ options ] ...

DESCRIPTION

XWin is an X Server for the X Window System on the Cygwin environment running on Microsoft Windows.

MODES

XWin can operate in 3 different modes:
* Single Window: This is the default mode. Each X screen appears as a single Windows window and all X windows are contained within this window. (In X terminology, the Windows window contains the root window for the screen)
* Multi-Window: In this mode XWin uses its own integrated window manager in order to handle the top-level X windows, in such a way that they appear as normal Windows windows.
* Rootless: In this mode the X server works in a window containing the whole screen but this root window (traditionally covered with an X hatch pattern) is hidden from view, so only top-level X windows are seen.

OPTIONS

In addition to the normal server options described in the Xserver(1) manual page, XWin accepts the following command line switches, all of which are optional:

OPTIONS CONTROLLING WINDOWING MODE

Only one of these options may be specified.

(default): Windowed or rooted mode. Each X screen appears as a single Windows window and all X windows are contained within those windows.
-multiwindow: Each top-level X window appears in its own Windows window. Also start the integrated Windows-based window manager.
-rootless: Run the server in rootless mode. The X server works on a window covering the whole screen but the root window is hidden from view.

NOTE: -multiwindow mode uses its own internal window manager. All other modes require an external window manager in order to move, resize, and perform other operations on the individual X windows.

OPTIONS FOR SPECIFYING X SCREENS

An X display may be composed of multiple screens. The default behaviour is to create a single screen 0 that is roughly the size of useful area of the primary monitor (allowing for any window decorations and the task-bar).

Screen specific parameters can be applied as a default to all screens by placing those screen specific parameters before any -screen parameter. Screen specific parameters placed after the first -screen parameter will apply only to the immediately preceding -screen parameter.

-[no]multimonitors or -[no]multiplemonitors

Create a screen 0 that covers all monitors [the primary monitor] on a system with multiple monitors. Fake XINERAMA data is created describing the individual monitors, (This is similar to the 'merged framebuffer' or 'pseudo-xinerama' mode provided by some drivers for the xorg X server). This option is currently enabled by default in -multiwindow mode.

-screen screen_number [W H [X Y] | [[WxH[+X+Y]][@M]] ]

Create screen number screen_number and optionally specify its height, width and initial position. Additionally a monitor number (which count from 1) can be specified to place the screen on, at which point, all coordinates become relative to that monitor. Screen numbers must be contiguous starting from zero and cannot be duplicated.

Examples:

-screen 0 @1 ; on 1st monitor using its full resolution (the default)

-screen 0 800x600+100+100@2 ; on 2nd monitor offset 100,100 size 800x600

-screen 0 1024x768@3 ; on 3rd monitor size 1024x768

OPTIONS CONTROLLING THE APPEARANCE OF THE X SCREEN WINDOWS

These parameters only apply to windowed mode screens i.e. not in -multiwindow or -rootless mode.

-fullscreen: The X screen window takes the full screen, covering completely the Windows desktop. Currently -fullscreen may only be applied to one X screen.
-icon icon-specifier: Override the window icon for the screen window from the default. The icon-specifier is as defined in XWinrc(5).
-nodecoration: Do not give the X screen window a Windows window border, title bar, etc. This parameter is ignored when the -fullscreen parameter is specified.
-scrollbars: Alternative name for -resize=scrollbars.

OPTIONS CONTROLLING RESIZE BEHAVIOUR

-resize[=none|scrollbars|randr]

Select the resize mode of an X screen. The default is none if -fullscreen is used, randr otherwise.

-resize=none

The screen is not resizable.

In windowed mode, if the window has decorations, a fixed frame is used.

Alternative name is -noresize.

-resize=scrollbars

The screen window is resizeable, but the screen is not resizable.

In windowed mode, if the window has decorations, a resizing frame is used. Scrollbars are drawn when needed to allow the entire X screen to viewed by adjusting them.

This also permits screens bigger than the Windows virtual desktop to be used.

This parameter is ignored in -multiwindow or -rootless mode. Alternative name is -scrollbars.

-resize=randr

The screen is resizable and the screen window is resizeable.

In windowed mode, if the window has decorations, a resizing frame is used.

Resizing the Windows window will use the RANDR extension to change the size of the X screen. Likewise, changing the size of the X screen using the RANDR extension will cause the size of the Windows window containing the X screen to be changed.

In -multiwindow or -rootless mode, if the X screen is of the same dimensions as a Windows monitor or the virtual desktop, the X server will respond to the WM_DISPLAYCHANGED sent when those dimensions change by resizing the X screen. Changing the size of the X screen using the RANDR extension is not permitted.

The maximum dimensions of the screen are the dimensions of the Windows virtual desktop.

-resize

on its own is equivalent to -resize=randr

OPTIONS FOR MULTIWINDOW MODE

-[no]hostintitle

Add the host name to the window title for X applications which are running on remote hosts, when that information is available and it's useful to do so. The default is enabled.

-[no]compositewm

Use Composite extension redirection to maintain a bitmap image of each top-level X window, so window contents which are occluded show correctly in task bar and task switcher previews. The default is enabled.

-[no]compositealpha

X windows with per-pixel alpha are composited into the Windows desktop (i.e. a Windows window can be seen through any transparency in an X window placed over it).

This option has no effect on Windows 8 and 8.1. This option has no effect if -compositewm is disabled. The default is disabled.

OPTIONS CONTROLLING WINDOWS INTEGRATION

-[no]clipboard: Enables [disables] the integration between the X11 clipboard and Windows clipboard. The default is enabled.
-emulate3buttons [timeout]: Emulate a three button mouse; pressing both buttons within timeout milliseconds causes an emulated middle button press. The default timeout is 50 milliseconds. Note that most mice with scroll wheel have middle button functionality, usually you will need this option only if you have a two button mouse without scroll wheel. Default is to enable this option if Windows reports a two button mouse, disabled otherwise.
-[no]keyhook: Enable [disable] a low-level keyboard hook for catching special keypresses like Menu and Alt+Tab and passing them to the X Server instead of letting Windows handle them.
-lesspointer: Normally the Windows mouse cursor is hidden when the mouse is over an active X window. This option causes the mouse cursor also to be hidden when it is over an inactive X window. This prevents the Windows mouse cursor from being drawn on top of the X cursor. This parameter has no effect unless -swcursor is also specified.
-[no]primary: Clipboard integration may [will not] use the PRIMARY selection. The default is enabled.
-swcursor: Disable the usage of the Windows cursor and use the X11 software cursor instead. This option is ignored if -compositewm is also enabled.
-[no]trayicon: Do not create a tray icon. Default is to create one icon per screen. You can globally disable tray icons with -notrayicon, then enable it for specific screens with -trayicon for those screens.
-[no]unixkill: Enable or disable the Ctrl-Alt-Backspace key combination as a signal to exit the X Server. The Ctrl-Alt-Backspace key combination is disabled by default.
-[no]wgl: Enable [disable] the GLX extension to use the native Windows WGL interface for hardware accelerated OpenGL (AIGLX). The default is enabled.
-[no]winkill: Enable or disable the Alt-F4 key combination as a signal to exit the X Server. The Alt-F4 key combination is enabled by default.

DRAWING ENGINE OPTIONS

-clipupdates num_boxes

Specify an optional threshold, above which the regions in a shadow update operation will be collected into a GDI clipping region. The clipping region is then used to do a single bit block transfer that is constrained to the updated area by the clipping region. There is some overhead involved in creating, installing, destroying, and removing the clipping region, thus there may not be much benefit for a small number of boxes (less than 10). It is even possible that this functionality does not provide a benefit at any number of boxes; we can only determine the usefulness of this feature through testing. This option probably has limited effect on current Windows versions as they already perform GDI batching.

-engine engine_type_id

This option, which is intended for developers, overrides the server's automatically selected drawing engine type. This parameter will be ignored if the specified drawing engine type is not supported on the current system.

Default behavior is to select the drawing engine with optimum performance that supports the specified depth and window configuration.

The engine type ids are:

1: Shadow GDI
4: Shadow DirectDraw Non-Locking

FULLSCREEN OPTIONS

-depth depth: Specify the color depth, in bits per pixel, to use when running in fullscreen with a DirectDraw engine. This parameter is ignored if -fullscreen is not specified.
-refresh rate_in_Hz: Specify an optional refresh rate to use when running in fullscreen with a DirectDraw engine. This parameter is ignored if -fullscreen is not specified.

MISCELLANEOUS OPTIONS

See also the normal server options described in the Xserver(1) manual page

-help

Write a help text listing supported command line options and their description to the console.

-ignoreinput

Ignore keyboard and mouse input. This is usually only used for testing and debugging purposes.

-logfile filename

Change the server log file from the default of /var/log/xwin/XWin.n.log, where n is the display number of the XWin server, to filename.

-logverbose level

Control the degree of verbosity of the log messages with the integer parameter level. For level=0 only fatal errors are reported, for level=1 simple information about configuration is also given, for level=2 (default) additional runtime information is recorded and for level=3 detailed log information (including trace and debug output) is produced. Bigger values will yield a still more detailed debug output.

-silent-dup-error

If another instance of XWin with the same display number is found running, exit silently and don't display any error message.

-xkblayout layout

-xkbmodel model

-xkboptions option

-xkbrules rule

-xkbvariant variant

These options configure the xkeyboard extension to load a particular keyboard map as the X server starts. The behavior is similar to the setxkbmap(1) program.

See the xkeyboard-config(7) manual page for a list of keyboard configurations.

The keyboard layout data is located at /usr/share/X11/xkb/. Additional information can be found in the README files there and in the setxkbmap(1) manual page.

For example, in order to load a German layout for a pc105 keyboard, use the options:
-xkblayout de -xkbmodel pc105

Alternatively, you can use the setxkbmap(1) program after XWin is running.

The default is to select a keyboard configuration matching your current layout as reported by Windows, if known, or the default X server configuration if no matching keyboard configuration was found.

UNDOCUMENTED OPTIONS

These options are undocumented. Do not use them.

-emulatepseudo: Create a depth 8 PseudoColor visual when running in depths 15, 16, 24, or 32, collectively known as TrueColor depths. Color map manipulation is not supported, so the PseudoColor visual will not have the correct colors. This option is intended to allow applications which only work with a depth 8 visual to operate in TrueColor modes.

LOG FILE

As it runs XWin writes messages indicating the most relevant events to the console from which it was called and to a log file that by default is located at /var/log/xwin/XWin.0.log. This file is mainly for debugging purposes.

PREFERENCES FILE

On startup XWin looks for the file $HOME/.XWinrc or, if the previous file does not exist, /etc/X11/system.XWinrc. .XWinrc allows setting preferences for the following:
* To include items into the menu associated with the XWin icon which is in the Windows system tray. This functions in all modes that have a tray icon.
* To include items in the system menu which is associated with the Windows window that XWin -multiwindow produces for each top-level X window, in both the generic case and for particular programs.
* To change the icon that is associated to the Windows window that XWin -multiwindow produces for each top-level X-window.
* To change the style that is associated to the Windows window that Win I-multiwindow produces for each top-level X window.

The format of the .XWinrc file is given in the XWinrc(5) manual page.

EXAMPLES

Need some examples

BUGS

XWin and this manual page still have many limitations.

The XWin software is continuously developing; it is therefore possible that this manual page is not up to date. It is always prudent to look also at the output of XWin -help in order to check the options that are operative.

AUTHORS

This list is by no means complete, but direct contributors to the Cygwin/X project include (in alphabetical order by last name): Stuart Adamson, Michael Bax, Jehan Bing, Lev Bishop, Dr. Peter Busch, Biju G C, Robert Collins, Nick Crabtree, Early Ehlinger, Christopher Faylor, John Fortin, Brian Genisio, Fabrizio Gennari, Alexander Gottwald, Ralf Habacker, Colin Harrison, Matthieu Herrb, Alan Hourihane, Pierre A Humblet, Harold L Hunt II, Dakshinamurthy Karra, Joe Krahn, Paul Loewenstein, Kensuke Matsuzaki, Takuma Murakami, Earle F. Philhower III, Benjamin Riefenstahl, Yaakov Selkowitz, Suhaib Siddiqi, Jack Tanner, Jon Turney and Nicholas Wourms.

Index

NAME
SYNOPSIS
DESCRIPTION
MODES
OPTIONS
OPTIONS CONTROLLING WINDOWING MODE
OPTIONS FOR SPECIFYING X SCREENS
OPTIONS CONTROLLING THE APPEARANCE OF THE X SCREEN WINDOWS
OPTIONS CONTROLLING RESIZE BEHAVIOUR
OPTIONS FOR MULTIWINDOW MODE
OPTIONS CONTROLLING WINDOWS INTEGRATION
DRAWING ENGINE OPTIONS
FULLSCREEN OPTIONS
MISCELLANEOUS OPTIONS
UNDOCUMENTED OPTIONS
LOG FILE
PREFERENCES FILE
EXAMPLES
SEE ALSO
BUGS
AUTHORS

This document was created by man2html, using the manual pages.
Time: 19:03:14 GMT, December 12, 2021