Class GorgonRawInput

Raw Input functionality for keyboards, mice and human interface devices.

Inheritance

object

GorgonRawInput

Implements

IGorgonRawInput

IDisposable

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 GorgonRawInput : IGorgonRawInput, IDisposable

Remarks

This enables use of the Raw Input functionality provided by windows.

This object will allow for enumeration of multiple keyboard, mouse and human interface devices attached to the system and will allow an application to register these types of devices for use with the application.

The GorgonRawInput object will also coordinate WM_INPUT messages and forward Raw Input data to an appropriate raw input device. This is done to allow multiple devices of the same type (e.g. multiple mice) to be used individually.

Examples

The following code shows how to create a mouse device and register it with the GorgonRawInput object for use in an application:

private GorgonRawMouse _mouse;
private GorgonRawInput _rawInput;

private void CreateRawMouse(Control yourMainApplicationWindow)
{
   // The 'yourMainApplicationWindow' is the primary window used by your application.
   _rawInput = new GorgonRawInput(yourMainApplicationWindow);

   _mouse = new GorgonRawMouse();

   _rawInput.RegisterDevice(_mouse);

   // Configure your mouse object for events here...
}

private void ApplicationShutDown()
{
	// The device should be unregistered as soon as it's no longer needed.
    _rawInput.UnregisterDevice(_mouse);

	// Always dispose this object, otherwise message hooks may still persist and cause issues.
    _rawInput.Dispose();
}

Constructors

GorgonRawInput(IWin32Window, IGorgonLog)

Initializes a new instance of the GorgonRawInput class.

Declaration

public GorgonRawInput(IWin32Window applicationWindow, IGorgonLog log = null)

Parameters

Type	Name	Description
IWin32Window	applicationWindow	The main application window.
IGorgonLog	log	[Optional] The logger used for debugging.

Remarks

This constructor will only allow Windows Forms controls as the main application window. For other window types, use the overloaded constructor.

The applicationWindow parameter is required in order to set up the application to receive WM_INPUT messages. Ideally, this window should be the primary application window.

Exceptions

Type	Condition
ArgumentNullException	thrown when the applicationWindow is set to null.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

EnumerateHumanInterfaceDevices()

Function to retrieve a list of human interface devices (HID).

Declaration

public IReadOnlyList<GorgonRawHIDInfo> EnumerateHumanInterfaceDevices()

Returns

Type	Description
IReadOnlyList<GorgonRawHIDInfo>	A read only list containing information about each human interface device.

EnumerateKeyboards()

Function to retrieve a list of keyboards.

Declaration

public IReadOnlyList<IGorgonKeyboardInfo> EnumerateKeyboards()

Returns

Type	Description
IReadOnlyList<IGorgonKeyboardInfo>	A read only list containing information about each keyboard.

EnumerateMice()

Function to retrieve a list of mice.

Declaration

public IReadOnlyList<IGorgonMouseInfo> EnumerateMice()

Returns

Type	Description
IReadOnlyList<IGorgonMouseInfo>	A read only list containing information about each mouse.

~GorgonRawInput()

Finalizes an instance of the GorgonRawInput class.

Declaration

protected ~GorgonRawInput()

RegisterDevice(IGorgonKeyboard, GorgonRawInputSettings?)

Function to register a keyboard device with the raw input provider.

Declaration

public void RegisterDevice(IGorgonKeyboard device, GorgonRawInputSettings? settings = null)

Parameters

Type	Name	Description
IGorgonKeyboard	device	The keyboard device to register with the raw input provider.
GorgonRawInputSettings?	settings	[Optional] Settings for the device type.

Remarks

This will register the IGorgonKeyboard device with the application. For the very first device the Raw Input object will set up the registration for the keyboard. This enables an application to start receiving Raw Input messages from a keyboard.

The optional settings parameter allows an application change how raw input handles the device being registered. It can be used to set up background input monitoring, or a target window for raw input messages (which must be set if the background option is turned on). By default, there is no background message processing and no target window (messages go to whichever window has focus).

Every call to this method should be paired with a call to UnregisterDevice(IGorgonKeyboard) when the keyboard is no longer needed.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

RegisterDevice(IGorgonMouse, GorgonRawInputSettings?)

Function to register a mouse device with the raw input provider.

Declaration

public void RegisterDevice(IGorgonMouse device, GorgonRawInputSettings? settings = null)

Parameters

Type	Name	Description
IGorgonMouse	device	The mouse device to register with the raw input provider.
GorgonRawInputSettings?	settings	[Optional] Settings for the device type.

Remarks

This will register the IGorgonMouse device with the application. For the very first device the Raw Input object will set up the registration for the mouse. This enables an application to start receiving Raw Input messages from a mouse.

The optional settings parameter allows an application change how raw input handles the device being registered. It can be used to set up background input monitoring, or a target window for raw input messages (which must be set if the background option is turned on). By default, there is no background message processing and no target window (messages go to whichever window has focus).

Every call to this method should be paired with a call to UnregisterDevice(IGorgonMouse) when the mouse is no longer needed.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

RegisterDevice(IGorgonRawHID, GorgonRawInputSettings?)

Function to register a HID with the raw input provider.

Declaration

public void RegisterDevice(IGorgonRawHID device, GorgonRawInputSettings? settings = null)

Parameters

Type	Name	Description
IGorgonRawHID	device	The HID to register with the raw input provider.
GorgonRawInputSettings?	settings	[Optional] Settings for the device type.

Remarks

This will register the IGorgonRawHID device with the application. For the very first device the Raw Input object will set up the registration for the HID. This enables an application to start receiving Raw Input messages from a HID.

The optional settings parameter allows an application change how raw input handles the device being registered. It can be used to set up background input monitoring, or a target window for raw input messages (which must be set if the background option is turned on). By default, there is no background message processing and no target window (messages go to whichever window has focus).

Every call to this method should be paired with a call to UnregisterDevice(IGorgonRawHID) when the HID is no longer needed.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

UnregisterDevice(IGorgonKeyboard)

Function to unregister a keyboard from the raw input provider.

Declaration

public void UnregisterDevice(IGorgonKeyboard device)

Parameters

Type	Name	Description
IGorgonKeyboard	device	The keyboard to unregister from the raw input provider.

Remarks

This will unregister a previously registered IGorgonKeyboard. When the last keyboard is unregistered, then the Raw Input messages for that device type will also be unregistered and the application will no longer receive messages from any keyboard.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

UnregisterDevice(IGorgonMouse)

Function to unregister a mouse from the raw input provider.

Declaration

public void UnregisterDevice(IGorgonMouse device)

Parameters

Type	Name	Description
IGorgonMouse	device	The mouse to unregister from the raw input provider.

Remarks

This will unregister a previously registered IGorgonMouse. When the last mouse is unregistered, then the Raw Input messages for that device type will also be unregistered and the application will no longer receive messages from any mouse.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

UnregisterDevice(IGorgonRawHID)

Function to unregister a HID from the raw input provider.

Declaration

public void UnregisterDevice(IGorgonRawHID device)

Parameters

Type	Name	Description
IGorgonRawHID	device	The HID to unregister from the raw input provider.

Remarks

This will unregister a previously registered IGorgonRawHID. When the last HID is unregistered, then the Raw Input messages for that device type will also be unregistered and the application will no longer receive messages from any HID.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the device parameter is null.

Implements

IGorgonRawInput

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)