Back to the DOSBox-X Wiki Welcome page.

Mouse support in DOSBox-X

Overview

DOSBox-X by default provides mouse support when using the integrated emulated DOS. When booting a guest OS, such as MS-DOS or Windows 9x, the guest OS is responsible for providing the mouse support.

Relative vs Absolute mode

Most mice only support relative mode, and this is what DOS and Windows drivers and applications typically expected. It means the mouse, when moved, gives an offset and the application will move the mouse cursor by that offset.

Absolute mode is where the mouse (as is typical for a touchscreen), returns the exact position of the mouse.

Relative mode works well in fullscreen mode, but starts to be a problem when running something like DOSBox-X in a window, when the mouse is not confined to the window (seamless). After a bit the mouse would start to drift and the host mouse cursor and the mouse cursor in DOSBox-X would start to diverge, causing problems properly controlling the guest mouse cursor.

As such, when running DOSBox-X in a window, using the integrated mouse support, it defaults to absolute mode which allows to seamlessly move the mouse in and out of the DOSBox-X window. This works because the integrated mouse support (unlike legacy mouse drivers), supports absolute mode.

However, if the application loads its own mouse driver, it will typically revert to relative mode and DOSBox-X will require that the mouse is locked to the window. Example of cases where you will encounter this:

  • Running Windows inside DOSBox-X (using the standard Windows mouse drivers)

  • Booting a guest OS, like MS-DOS, and loading a typical DOS mouse driver

  • Some rare applications and games that have their own mouse driver built-in

In some cases, such as running Windows inside DOSBox-X, there may be a 3rd party driver you can install to get absolute mode mapping support. See the Windows installation guides for more information on this.

Capturing mouse

When running DOSBox-X in windowed mode, by default you can capture (confine to the DOSBox-X window), and release the mouse using CTRL-F10 (this key combination can be remapped in the key mapper).

Alternatively, you can select "Main" → "Capture mouse" from the menus.

From the menus, you can also get it to autolock the mouse when you click in the window using the "Main" → "Autolock mouse" option.

These options can also be controlled from the DOSBox-X config file.

Note
 While capturing the mouse in windowed mouse is typically not needed, as DOSBox-X will try to enable seamless integration with the host OS. In some cases you will want to do it anyway, as leaving the DOSBox-X window with the mouse may cause gameplay problems.

autolock

  • Default value: false

  • Possible values: false, true

Set in the [sdl] section, to allow the mouse to be captured, when clicking in the DOSBox-X window:

autolock_feedback

  • Default value: beep

  • Possible values: none, beep, flash

Set in the [sdl] section, to give user feedback type when the mouse is auto locked:

middle_unlock

  • Default value: manual

  • Possible values: none, manual, auto, both

Set in the [sdl] section, to allow the middle mouse button to release the mouse:

If set to "manual", it works only with autolock=false.

If set to "auto", it works only with autolock=true.

If set to "both", it works regardless of autolock= setting.

Mouse wheel support

The first mice with scroll wheel came out in 1995. But the much more popular Microsoft IntelliMouse came out in 1996, together with drivers for Windows 95.

True mouse wheel support

DOSBox-X has support for the Microsoft IntelliMouse with scroll wheel from the integrated emulated DOS.

But true mouse wheel support is disabled by default as legacy DOS applications don’t support it (DOS and DOS applications at this time, generally were being sunset).

To get the scroll wheel working, you will have to set mouse_wheel_key=0 in the [SDL] section of the DOSBox-X config file, as this option will otherwise interfere.

The option can also be disabled from the menus, by selecting the "Main" → "Mouse wheel movements" → "Do not convert to arrow keys" option. But this will not be saved on DOSBox-X shutdown.

If you boot DOS as a guest OS, you will also need to load the CuteMouse driver v2.1 as such: CTMOUSE /O, and make sure no other mouse drivers are being loaded in the AUTOEXEC.BAT file.

Emulated mouse wheel support

Since most DOS applications (and early Windows) don’t support the scroll wheel, DOSBox-X by default maps the mouse wheel movements to keyboard keys. By default, DOSBox-X maps the mouse wheel to the up/down arrow (aka cursor) keys.

The mouse wheel options can be found, when running DOSBox-X in a window, from the menu bar under "Main" → "Mouse wheel movements". But changes here will not be saved on DOSBox-X shutdown.

These options can also be controlled from the DOSBox-X config file.

mouse_wheel_key

  • Default value: -1

  • Possible values: -7 to 7

Set in the [sdl] section, converts mouse wheel movements into keyboard presses such as arrow keys.

valid settings:

  • mouse_wheel_key = 0: disabled

  • mouse_wheel_key = 1: up/down arrows

  • mouse_wheel_key = 2: left/right arrows

  • mouse_wheel_key = 3: PgUp/PgDn keys

  • mouse_wheel_key = 4: Ctrl+up/down arrows

  • mouse_wheel_key = 5: Ctrl+left/right arrows

  • mouse_wheel_key = 6: Ctrl+PgUp/PgDn keys

  • mouse_wheel_key = 7: Ctrl+W/Z, as supported by text editors like WordStar and MS-DOS EDIT.

Putting a minus sign in front will disable the conversion for guest systems.

Other mouse settings

aux

  • Default value: true

  • Possible values: false, true

Set in the [keyboard] section, enables or disables the i8042 auxiliary port. Needed for PS/2 mouse emulation in a guest OS such as Windows ME which does not use the BIOS to receive mouse events.

auxdevice

  • Default value: intellimouse

  • Possible values: none, 2button, 3button, intellimouse, intellimouse45

Set in the [keyboard] section if the DOSBox-X config file. Sets the type of PS/2 mouse attached to the AUX port.

valid options:

  • auxdevice = none: disables PS/2 mouse emulation

  • auxdevice = 2button: emulate a Microsoft 2 button mouse

  • auxdevice = 3button: emulate a Microsoft 3 button mouse

  • auxdevice = intellimouse: emulate an MS IntelliMouse with scroll wheel

  • auxdevice = intellimouse45: emulate an MS IntelliMouse Explorer with scroll wheel and 4th and 5th button

Note
 The auxdevice=3button option requires that you set middle_unlock=none in the [sdl] section of the DOSBox-X config file. Also, this option does not currently work when you boot a guest OS.

mouse_emulation

  • Default value: locked

  • Possible values: integration, locked, always, never

Set in the [sdl] section of the DOSBox-X config file. Determines when the mouse is emulated ?

Valid options:

  • mouse_emulation = integration: when not locked

  • mouse_emulation = locked: when locked

  • mouse_emulation = always: every time

  • mouse_emulation = never: at no time

If disabled, the mouse position in DOSBox-X is exactly where the host OS reports it.

When using a high DPI mouse, the emulation of mouse movement can noticeably reduce the sensitiveness of your device, i.e. the mouse is slower but more precise.

For the "integration" option, the setting integration device=true must also be set in the [cpu] section.

sensitivity

  • Default value: 100

  • Possible values:

Set in the [sdl] section, adjusts mouse sensitivity. The optional second parameter specifies vertical sensitivity (e.g. 100,-50).

usesystemcursor

  • Default value: false

  • Possible values: false, true

Set in the [sdl] section, uses the mouse cursor of the host system instead of drawing a DOS mouse cursor.

Activated when the mouse is not locked to the window.

vmware

  • Default value: true

  • Possible values: false, true

Enable VMware interface emulation including guest mouse integration (when used along with e.g. VMware mouse driver for Windows 3.x).

int33

  • Default value: true

  • Possible values: false, true

Enable INT 33H for mouse support.

int33 hide host cursor if interrupt subroutine

  • Default value: true

  • Possible values: false, true

If set, the cursor on the host will be hidden if the DOS application provides its own interrupt subroutine for the mouse driver to call, which is usually an indication that the DOS game wishes to draw the cursor with its own support routines (DeluxePaint II).

int33 hide host cursor when polling

  • Default value: false

  • Possible values: false, true

If set, the cursor on the host will be hidden even if the DOS application has also hidden the cursor in the guest, as long as the DOS application is polling position and button status.

This can be useful for DOS programs that draw the cursor on their own instead of using the mouse driver, including most games and DeluxePaint II.

int33 disable cell granularity

  • Default value: false

  • Possible values: false, true

If set, the mouse pointer position is reported at full precision (as if 640x200 coordinates) in all modes.

If not set, the mouse pointer position is rounded to the top-left corner of a character cell in text modes.

This option is OFF by default.

biosps2

  • Default value: true

  • Possible values: true, false

Emulate BIOS INT 15h PS/2 mouse services.

Note
 Some OS’s like Microsoft Windows (prior to ME) neither use INT 33h nor probe the AUX port directly and depend on this BIOS interface exclusively for PS/2 mouse support.

In other cases there is no harm in leaving this enabled

int15 mouse callback does not preserve registers

  • Default value: false

  • Possible values: false, true

Set to true if the guest OS or DOS program assigns an INT 15h mouse callback, but does not properly preserve CPU registers.

Diagnostic function only (default off).

Serial mouse

By default, DOSBox-X emulates a PS/2 mouse. But some early DOS applications or Windows versions come with their own mouse driver that only works with serial mice. For this purpose, DOSBox-X can be set to emulate a Microsoft serial mouse. If serial mouse emulation is enabled, the PS/2 mouse emulation is automatically disabled.

Set the following setting to enable serial mouse emulation:

[serial]
serial1=serialmouse
Note
 most software will expect to find the serial mouse on COM1, as such it is recommended to use the above serial1= setting, which maps to COM1.

Mouse in a guest OS

When booting a guest OS, such as MS-DOS or Windows 95, DOSBox-X no longer provides a mouse driver, as this is up to the guest OS.

In the case of MS-DOS, IBM PC-DOS or FreeDOS, the recommended mouse driver is CuteMouse (aka ctmouse). It supports both PS/2 and Serial mice, and requires less memory than other mouse drivers.

However, any Microsoft mouse compatible mouse driver should work, at least for basic functionality.

Another option is VBMOUSE.EXE, which provides seamless support, and also supports the scroll wheel on modern mice. It is however limited to PS/2 mice, so will not work with the optional serial mouse emulation that DOSBox-X provides.