Class GorgonRawMouse

Provides events and state for mouse data returned from Raw Input.

Inheritance

object

GorgonRawMouse

Implements

IGorgonMouse

IGorgonRawInputDevice

IGorgonRawInputDeviceData<GorgonRawMouseData>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Gorgon.Input

Assembly: Gorgon.Input.dll

Syntax

public class GorgonRawMouse : IGorgonMouse, IGorgonRawInputDevice, IGorgonRawInputDeviceData<GorgonRawMouseData>

Remarks

This allows a user to read mouse data from Raw Input for all mouse devices, or an individual device depending on what is passed to the constructor.

The raw input mouse is primarily meant for use in cases where the built-in Windows cursor ballistics interfere with tracking. Because of how Raw Input works, the mouse may behave strangely compared to how the usual mouse events deliver data. For example, in a WinForms MouseMove event, the position of the mouse is relative to the client area of the window receiving the message. In the Raw Input scheme, there is no concept or knowledge of a window. The data sent from the device to Raw Input will be in the context of raw data for that device (in most cases, this would be a mickey).

Because there is no concept of a window (or screen dimensions either) for Raw Input, the data is usually received as relative. That is, the values received from raw input are vectors based on the last known position of the mouse. In some cases this data may be absolute (e.g. a touch device), and in this case the position is given in the coordinates for the device. To see these values, an application can read the Position or RelativePositionOffset properties.

tip

This object is ideal for things like rotating a camera, as cursor ballistics may cause strange behaviour when moving. It is not recommended to use this object for things like a GUI as cursor ballistics are not applied, and the positioning is not relative to any window or control. For those scenarios, the standard windows event mechanism is preferred.

Constructors

GorgonRawMouse(IGorgonMouseInfo)

Initializes a new instance of the GorgonRawMouse class.

Declaration

public GorgonRawMouse(IGorgonMouseInfo mouseInfo = null)

Parameters

Type	Name	Description
IGorgonMouseInfo	mouseInfo	[Optional] A IGorgonMouseInfo value to determine which device to use..

Remarks

When the mouseInfo is set to null, the system mouse (that is, all mice attached to the computer) will be used. No differentiation between mouse devices is made. To specify an individual mouse, pass an appropriate IGorgonMouseInfo obtained from the EnumerateMice() method.

Exceptions

Type	Condition
InvalidCastException	Thrown if the mouseInfo is not the expected type.

Properties

Buttons

Property to set or return the pointing device button(s) that are currently down.

Declaration

public MouseButtons Buttons { get; set; }

Property Value

Type	Description
MouseButtons

CursorVisible

Property to set or return whether the mouse cursor is visible.

Declaration

public static bool CursorVisible { get; set; }

Property Value

Type	Description
bool

Remarks

This is a convenience property that will show or hide the mouse cursor. It has an advantage over Show() in that it will keep the mouse cursor visibility reference count at a constant value.

DoubleClickDelay

Property to set or return the delay between button clicks, in milliseconds, for a double click event.

Declaration

public int DoubleClickDelay { get; set; }

Property Value

Type	Description
int

DoubleClickSize

Property to set or return the Size of the area, in pixels, surrounding the cursor that represents a valid double click area.

Declaration

public Size2 DoubleClickSize { get; set; }

Property Value

Type	Description
Size2

Remarks

When this value is set, and a mouse button is double clicked, this value is checked to see if the mouse Position falls within -value.Size.Width to value.Size.Width, and -value.Size.Height" to value.Size.Height on the second click. If the Position is within this area, then the double click event will be triggered. Otherwise, it will not.

Passing Size.Empty to this property will disable double clicking.

Info

Property to return information about this mouse.

Declaration

public IGorgonMouseInfo Info { get; }

Property Value

Type	Description
IGorgonMouseInfo

Position

Property to set or return the position of the mouse.

Declaration

public Point Position { get; set; }

Property Value

Type	Description
Point

Remarks

This property is affected by the PositionConstraint value.

PositionConstraint

Property to set or return the Rectangle used to constrain the mouse Position.

Declaration

public Rectangle PositionConstraint { get; set; }

Property Value

Type	Description
Rectangle

Remarks

This will constrain the value of the Position within the specified Rectangle. This means that a cursor positioned at 320x200 with a region located at 330x210 with a width and height of 160x160 will make the Position property return 330x210. If the cursor was positioned at 500x400, the Position property would return 480x360.

Passing Rectangle.Empty to this property will remove the constraint on the position.

warning

This will constrain the mouse cursor to the area defined. If more than one mouse device is being used, the mouse cursor will always be constrained to the last GorgonRawMouse that set this value. In such cases, it is best to turn off the mouse cursor and handle drawing of a mouse cursor manually.

RelativePositionOffset

Property to set or return the last reported relative position movement offset.

Declaration

public Point RelativePositionOffset { get; set; }

Property Value

Type	Description
Point

Remarks

This value represents the number of units that the mouse moved since its last MouseMove event.

Users should reset this value when they are done with it. Otherwise, it will not be reset until the next MouseWheelMove event.

Raw input devices that use relative tracking will update this value as-is. That is, no calculation from a prior position is done inside of this object except to update the Position property. For devices with absolute tracking, this value is calculated from the last known position. Due to this, the relative amount on the first read may be 0, 0 because there is no point of reference to derive the relative offset from.

RelativeWheelDelta

Property to set or return the last reported relative wheel movement delta.

Declaration

public int RelativeWheelDelta { get; set; }

Property Value

Type	Description
int

Remarks

This value represents the number of units that the mouse wheel moved since its last MouseWheelMove event.

Users should reset this value when they are done with it. Otherwise, it will not be reset until the next MouseWheelMove event.

WheelConstraint

Property to set or return the GorgonRange used to constrain the mouse WheelPosition.

Declaration

public GorgonRange WheelConstraint { get; set; }

Property Value

Type	Description
GorgonRange

Remarks

If a mouse wheel exists on the device, this will constrain the value of the WheelPosition within the specified GorgonRange. This means that a wheel with a position of 160, with a constraint of 180-190 will make the WheelPosition property return 180.

Passing Empty to this property will remove the constraint on the position.

WheelPosition

Property to set or return the pointing device wheel position.

Declaration

public int WheelPosition { get; set; }

Property Value

Type	Description
int

Remarks

This property is affected by the WheelConstraint value.

Events

MouseButtonDown

Event triggered when a mouse button is held down.

Declaration

public event EventHandler<GorgonMouseEventArgs> MouseButtonDown

Event Type

Type	Description
EventHandler<GorgonMouseEventArgs>

MouseButtonUp

Event triggered when a mouse button is released.

Declaration

public event EventHandler<GorgonMouseEventArgs> MouseButtonUp

Event Type

Type	Description
EventHandler<GorgonMouseEventArgs>

MouseDoubleClicked

Event triggered when a double click is performed on a mouse button.

Declaration

public event EventHandler<GorgonMouseEventArgs> MouseDoubleClicked

Event Type

Type	Description
EventHandler<GorgonMouseEventArgs>

MouseMove

Event triggered when the mouse is moved.

Declaration

public event EventHandler<GorgonMouseEventArgs> MouseMove

Event Type

Type	Description
EventHandler<GorgonMouseEventArgs>

MouseWheelMove

Event triggered when a mouse wheel (if present) is moved.

Declaration

public event EventHandler<GorgonMouseEventArgs> MouseWheelMove

Event Type

Type	Description
EventHandler<GorgonMouseEventArgs>

Implements

IGorgonMouse

IGorgonRawInputDevice

IGorgonRawInputDeviceData<T>

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)