Click or drag to resize
DigitalRuneIInputService Interface
Manages user input from keyboard, mouse, Xbox 360 controllers and other devices.

Namespace: DigitalRune.Game.Input
Assembly: DigitalRune.Game.Input (in DigitalRune.Game.Input.dll) Version: 1.8.0.0 (1.8.0.14467)
Syntax
public interface IInputService

The IInputService type exposes the following members.

Methods
  NameDescription
Public methodGetGamePadState(PlayerIndex)
Gets the gamepad state of the given game controller. (Not available in Silverlight.)
Public methodGetGamePadState(LogicalPlayerIndex)
Gets the gamepad state for the given player.
Public methodGetLogicalPlayer
Gets the game controller assigned to the specified player. (Not available in Silverlight.)
Public methodGetPreviousGamePadState(PlayerIndex)
Gets the gamepad state of the last frame of the given game controller. (Only available in XNA Windows Phone builds.)
Public methodGetPreviousGamePadState(LogicalPlayerIndex)
Gets the gamepad state of the last frame for the given player. (Not available in Silverlight.)
Public methodIsDoubleClick(Keys)
Determines whether the specified key was double-clicked.
Public methodIsDoubleClick(MouseButtons)
Determines whether the specified button has been double-clicked.
Public methodIsDoubleClick(Buttons, LogicalPlayerIndex)
Determines whether the specified button has been double-clicked by the given player. (Not available in Silverlight.)
Public methodIsDoubleClick(Buttons, PlayerIndex)
Determines whether the specified button has been double-clicked on the given game controller. (Not available in Silverlight.)
Public methodIsDown(Keys)
Determines whether the specified key is down.
Public methodIsDown(MouseButtons)
Determines whether the specified button is down.
Public methodIsDown(Buttons, LogicalPlayerIndex)
Determines whether the specified button is down for the given player. (Not available in Silverlight.)
Public methodIsDown(Buttons, PlayerIndex)
Determines whether the specified button is down on the given game controller. (Not available in Silverlight.)
Public methodIsGamePadHandled(PlayerIndex)
Gets a value indicating whether the input of a given game controller has already been handled. (Not available in Silverlight.)
Public methodIsGamePadHandled(LogicalPlayerIndex)
Gets a value indicating whether gamepad input of a given player has already been handled.
Public methodIsPressed(Keys, Boolean)
Determines whether the specified key was previously up and has been pressed.
Public methodIsPressed(MouseButtons, Boolean)
Determines whether the specified button was previously up and has been pressed.
Public methodIsPressed(Buttons, Boolean, LogicalPlayerIndex)
Determines whether the specified button has been pressed by the given player. (Not available in Silverlight.)
Public methodIsPressed(Buttons, Boolean, PlayerIndex)
Determines whether the specified button has been pressed on the given game controller. (Not available in Silverlight.)
Public methodIsReleased(Keys)
Determines whether the specified key was previously down and has been released.
Public methodIsReleased(MouseButtons)
Determines whether the specified button was previously down and has been released.
Public methodIsReleased(Buttons, LogicalPlayerIndex)
Determines whether the specified button has been released by the given player. (Not available in Silverlight.)
Public methodIsReleased(Buttons, PlayerIndex)
Determines whether the specified button has been released on the given game controller. (Not available in Silverlight.)
Public methodIsUp(Keys)
Determines whether the specified key is up.
Public methodIsUp(MouseButtons)
Determines whether the specified button is up.
Public methodIsUp(Buttons, LogicalPlayerIndex)
Determines whether the specified button is up for the given player. (Not available in Silverlight.)
Public methodIsUp(Buttons, PlayerIndex)
Determines whether the specified button is up on the given game controller. (Not available in Silverlight.)
Public methodSetAllHandled
Sets all "IsHandled" flags to the given value.
Public methodSetGamePadHandled(PlayerIndex, Boolean)
Sets the IsGamePadHandled flags of a given game controller. (Not available in Silverlight.)
Public methodSetGamePadHandled(LogicalPlayerIndex, Boolean)
Sets the IsGamePadHandled flags for the given player. (Not available in Silverlight.)
Public methodSetLogicalPlayer
Assigns a game controller to a player. (Not available in Silverlight.)
Top
Properties
  NameDescription
Public propertyAccelerometerValue
Gets the accelerometer value. (Only available in XNA Windows Phone builds.)
Public propertyCommands
Gets the input commands.
Public propertyEnableMouseCentering
Gets or sets a value indicating whether the mouse position is reset in each frame.
Public propertyGestures
Gets the detected touch gestures. (Not available in Silverlight.)
Public propertyIsAccelerometerActive
Gets a value indicating whether an accelerometer is connected and can be used. (Only available in XNA Windows Phone builds.)
Public propertyIsAccelerometerHandled
Gets or sets a value indicating whether accelerometer input has already been handled.
Public propertyIsKeyboardHandled
Gets or sets a value indicating whether keyboard input has already been handled.
Public propertyIsMouseOrTouchHandled
Gets or sets a value indicating whether mouse or touch input has already been handled.
Public propertyKeyboardState
Gets the state of the current keyboard state.
Public propertyMaxNumberOfPlayers
Gets the max number of players (= max number of game controllers that can be connected).
Public propertyModifierKeys
Gets the pressed modifier keys.
Public propertyMousePosition
Gets or sets the mouse position.
Public propertyMousePositionDelta
Gets or sets the mouse position change since the last frame.
Public propertyMousePositionDeltaRaw
Gets the raw mouse position change since the last frame.
Public propertyMousePositionRaw
Gets the raw mouse position.
Public propertyMouseState
Gets the state of the current mouse state.
Public propertyMouseWheelDelta
Gets a value representing the rotation change of the mouse wheel.
Public propertyPressedKeys
Gets the pressed keys.
Public propertyPreviousKeyboardState
Gets the keyboard state of the last frame.
Public propertyPreviousMouseState
Gets the mouse state of the last frame.
Public propertySettings
Gets or sets the settings that define input handling, timing, etc.
Public propertyTouchCollection
Gets the touch collection. (Not available in Silverlight.)
Top
Remarks

Note: Touch, accelerometer and gamepad input is not supported in Silverlight. (But those devices are supported on the Windows Phone.)

The input manager is the central method that should be used to check for user input. It contains many convenience methods that allow to detected key/button presses and double-clicks.

Typically, many game components can handle the input. But often input should only be processed by the foremost game component (e.g. the top-most window). For this, game components can set the flags IsAccelerometerHandled, IsGamePadHandled(LogicalPlayerIndex), IsKeyboardHandled, and IsMouseOrTouchHandled to indicate that input has already been processed and other game components should ignore the input. These flags are reset by the input service in each frame, but otherwise the input service itself does not read this flags. It is up to the game components to decide whether they want to consider these flags or not. (If, for example, IsMouseOrTouchHandled is set, methods like IsDown(MouseButtons) still work normally.)

Logical Players and Game Controllers: The PlayerIndex in XNA identifies a game controller. Beware that "Player One" may not be using the game controller that is assigned to PlayerIndex.One! A game needs to detect which player uses which game controller at runtime. (See example below.)

The LogicalPlayerIndex identifies a player. SetLogicalPlayer(LogicalPlayerIndex, NullablePlayerIndex) must be called to assign a game controller to a player. Gamepad input can be queried using the PlayerIndex to get the input of a certain game controller or the LogicalPlayerIndex to get the input of a certain player. LogicalPlayerIndex.Any can be used to query the game controllers of all players. Note that game controllers that are not associated with any player are ignored when LogicalPlayerIndex.Any is used.

IMPORTANT: The methods that take the LogicalPlayerIndex as a parameter return default values when no game controller is assigned to the specified player. Be sure to call SetLogicalPlayer(LogicalPlayerIndex, NullablePlayerIndex) to assign game controllers to players.

IsUp, IsDown and IsPressed: The input service defines simple methods that allow to check if a key or button is currently held down or not. This methods are called IsDown and IsUp. The methods IsPressed and IsReleased check whether a key or button was pressed down or released exactly in this frame. That means, if a key is not held down, IsUp returns true and all other methods return false. Then when the key is pressed, IsDown is true and IsPressed is true. If the key is still held down in the next frame, IsDown is still true but IsPressed is false.

Double-Clicks: The methods IsDoubleClick can be used to detect double-clicks. The two clicks must be within the DoubleClickTime to count as double-click. For GUI controls it is also necessary to check if both clicks were in the same region - but this is not checked by the input service and is left to the GUI system.

Virtual Key/Button Presses: When a key or button is held down for longer than RepetitionDelay the input service starts to create "IsPressed" events at a frequency defined by RepetitionInterval - this is convenient for text input in text box controls and text editors. The property PressedKeys contains a list of all keys that where pressed down in the current frame - including the virtual presses created by keys/buttons that were held down for a long time. In the IsPressed methods the second parameter allows to specify if virtual key/button repetitions events should be included or not.

Accelerometer: The accelerometer can only be used on the Windows Phone 7 device. In the Windows Phone 7 emulator the arrow keys and the space key can be used to create accelerometer readings.

Examples
At runtime an application needs to figure out which game controller is used to control the game. This is typically done by prompting the user to press Start or button A at the start screen. Include the following code in the Update method of the game:
C#
if (_inputManager.GetLogicalPlayer(LogicalPlayerIndex.One) == null)
{
  // Wait until the user presses A or START on any connected gamepad.
  for (var controller = PlayerIndex.One; controller <= PlayerIndex.Four; controller++)
  {
    if (_inputManager.IsDown(Buttons.A, controller) || _inputManager.IsDown(Buttons.Start, controller))
    {
      // A or START was pressed. Assign the controller to the first "logical player".
      _inputManager.SetLogicalPlayer(LogicalPlayerIndex.One, controller);
      break;
    }
  }
}
All subsequent methods can use LogicalPlayerIndex.One to query the input of the player.
See Also