VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
IMouse Interface Reference

The IMouse interface represents the virtual machine's mouse. More...

Inheritance diagram for IMouse:

Public Member Functions

void putMouseEvent (in long dx, in long dy, in long dz, in long dw, in long buttonState)
 Initiates a mouse event using relative pointer movements along x and y axis. More...
 
void putMouseEventAbsolute (in long x, in long y, in long dz, in long dw, in long buttonState)
 Positions the mouse pointer using absolute x and y coordinates. More...
 
void putEventMultiTouch (in long count, in long long[] contacts, in unsigned long scanTime)
 Sends a multi-touch pointer event. More...
 
void putEventMultiTouchString (in long count, in wstring contacts, in unsigned long scanTime)
 

Public Attributes

readonly attribute boolean absoluteSupported
 Whether the guest OS supports absolute mouse pointer positioning or not. More...
 
readonly attribute boolean relativeSupported
 Whether the guest OS supports relative mouse pointer positioning or not. More...
 
readonly attribute boolean multiTouchSupported
 Whether the guest OS has enabled the multi-touch reporting device. More...
 
readonly attribute boolean needsHostCursor
 Whether the guest OS can currently switch to drawing it's own mouse cursor on demand. More...
 
readonly attribute IMousePointerShape pointerShape
 The current mouse pointer used by the guest. More...
 
readonly attribute IEventSource eventSource
 Event source for mouse events. More...
 

Detailed Description

The IMouse interface represents the virtual machine's mouse.

Used in IConsole::mouse.

Through this interface, the virtual machine's virtual mouse can be controlled.

Interface ID:
{EE35ADB0-4748-3E12-E7FD-5AAD957BBA0F}

Member Function Documentation

void IMouse::putMouseEvent ( in long  dx,
in long  dy,
in long  dz,
in long  dw,
in long  buttonState 
)

Initiates a mouse event using relative pointer movements along x and y axis.

Parameters
dxAmount of pixels the mouse should move to the right. Negative values move the mouse to the left.
dyAmount of pixels the mouse should move downwards. Negative values move the mouse upwards.
dzAmount of mouse wheel moves. Positive values describe clockwise wheel rotations, negative values describe counterclockwise rotations.
dwAmount of horizontal mouse wheel moves. Positive values describe a movement to the left, negative values describe a movement to the right.
buttonStateThe current state of mouse buttons. Every bit represents a mouse button as follows:
Bit 0 (0x01) left mouse button
Bit 1 (0x02) right mouse button
Bit 2 (0x04) middle mouse button
A value of 1 means the corresponding button is pressed. otherwise it is released.
Expected result codes:
E_ACCESSDENIED Console not powered up.
VBOX_E_IPRT_ERROR Could not send mouse event to virtual mouse.
void IMouse::putMouseEventAbsolute ( in long  x,
in long  y,
in long  dz,
in long  dw,
in long  buttonState 
)

Positions the mouse pointer using absolute x and y coordinates.

These coordinates are expressed in pixels and start from [1,1] which corresponds to the top left corner of the virtual display.

Parameters
xX coordinate of the pointer in pixels, starting from 1.
yY coordinate of the pointer in pixels, starting from 1.
dzAmount of mouse wheel moves. Positive values describe clockwise wheel rotations, negative values describe counterclockwise rotations.
dwAmount of horizontal mouse wheel moves. Positive values describe a movement to the left, negative values describe a movement to the right.
buttonStateThe current state of mouse buttons. Every bit represents a mouse button as follows:
Bit 0 (0x01) left mouse button
Bit 1 (0x02) right mouse button
Bit 2 (0x04) middle mouse button
A value of 1 means the corresponding button is pressed. otherwise it is released.
Expected result codes:
E_ACCESSDENIED Console not powered up.
VBOX_E_IPRT_ERROR Could not send mouse event to virtual mouse.
Note
This method will have effect only if absolute mouse positioning is supported by the guest OS.
See also
absoluteSupported
void IMouse::putEventMultiTouch ( in long  count,
in long long[]  contacts,
in unsigned long  scanTime 
)

Sends a multi-touch pointer event.

The coordinates are expressed in pixels and start from [1,1] which corresponds to the top left corner of the virtual display.

Parameters
countNumber of contacts in the event.
contactsEach array element contains packed information about one contact. Bits 0..15: X coordinate in pixels. Bits 16..31: Y coordinate in pixels. Bits 32..39: contact identifier. Bit 40: "in contact" flag, which indicates that there is a contact with the touch surface. Bit 41: "in range" flag, the contact is close enough to the touch surface. All other bits are reserved for future use and must be set to 0.
scanTimeTimestamp of the event in milliseconds. Only relative time between events is important.
Expected result codes:
E_ACCESSDENIED Console not powered up.
VBOX_E_IPRT_ERROR Could not send event to virtual device.
Note
The guest may not understand or may choose to ignore this event.
See also
multiTouchSupported
void IMouse::putEventMultiTouchString ( in long  count,
in wstring  contacts,
in unsigned long  scanTime 
)
Parameters
count
contactsContains information about all contacts: "id1,x1,y1,inContact1,inRange1;...;idN,xN,yN,inContactN,inRangeN". For example for two contacts: "0,10,20,1,1;1,30,40,1,1"
scanTime
See also
putEventMultiTouch

Member Data Documentation

readonly attribute boolean IMouse::absoluteSupported

Whether the guest OS supports absolute mouse pointer positioning or not.

Note
You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution.
See also
putMouseEventAbsolute
readonly attribute boolean IMouse::relativeSupported

Whether the guest OS supports relative mouse pointer positioning or not.

Note
You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution.
See also
putMouseEvent
readonly attribute boolean IMouse::multiTouchSupported

Whether the guest OS has enabled the multi-touch reporting device.

Note
You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution.
See also
putMouseEvent
readonly attribute boolean IMouse::needsHostCursor

Whether the guest OS can currently switch to drawing it's own mouse cursor on demand.

Note
You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution.
See also
putMouseEvent
readonly attribute IMousePointerShape IMouse::pointerShape

The current mouse pointer used by the guest.

readonly attribute IEventSource IMouse::eventSource

Event source for mouse events.