Introduction

The ModifyMouseState event is an event you can add to the Mouse object to set/modify the Microsoft.Xna.Framework.Input.MouseState used by the mouse for positioning and clicking. This is useful if you are working on a platform which does not have mouse input but you would like to simulate mouse input, or if you are working on a platform which requires modifications of the mouse input.

Code Example

The following code can be used in a WPF project to properly set the mouse position. Add the following to your Game's Initialize function:

FlatRedBall.Input.Mouse.ModifyMouseState += HandleModifyMouseState;

Add the following implementation:

private void HandleModifyMouseState(ref Microsoft.Xna.Framework.Input.MouseState mouseState)
{
    var point = Control.MousePosition;

    var screen = mFrbControl.PointFromScreen(new System.Windows.Point(point.X, point.Y));
    var newMouseState = new Microsoft.Xna.Framework.Input.MouseState(
        MathFunctions.RoundToInt(screen.X),
        MathFunctions.RoundToInt(screen.Y),
        mouseState.ScrollWheelValue,
        mouseState.LeftButton,
        mouseState.MiddleButton,
        mouseState.RightButton,
        mouseState.XButton1,
        mouseState.XButton2);
    mouseState = newMouseState;
}

GrabbedPositionedObject

The Mouse class provides functionality for grabbing and moving any object which implements the PositionedObject class. This includes common FlatRedBall types like and as well as entities created in Glue. The following code creates 9 and allows the user to click and drag to control the . This code can be added to any FlatRedBall Screen

Setting the GrabbedPositionedObject does the following:

1. Stores the reference in the GrabbedPositionedObject property

2. Stores offset variables - this is the difference between the GrabbedPositionedObject's position and the cursor's world coordinates.

3. Updates the GrabbedPositionedObject's position every frame using the Mouse's world coordinates and the offset values. This is performed automatically - there is no need to manually manage positions when using GrabbedPositionedObject.

GrabbedPositionedObject and Parents

In the example above the Sprites do not have any parents so they can be grabbed and moved freely by the cursor. It is common to have Sprites as part of Glue entities, in which case the Sprite is attached to the entity. If the GrabbedPositionedObject has a non-null Parent, then it cannot be moved. In this situation it is more common to grab (and move) the parent entity.

Introduction

The Mouse class provides functionality for getting input data from the physical mouse. This class is automatically instantiated by and accessible through the InputManager.

Detecting Mouse Activity

There are many ways to get data from the mouse. The following section of code is a series of if-statements which could be used to detect input from the mouse.

if (InputManager.Mouse.ButtonPushed(Mouse.MouseButtons.LeftButton))
{
    // Left mouse button pushed - down this frame, not down last frame.
}
if (InputManager.Mouse.ButtonReleased(Mouse.MouseButtons.MiddleButton))
{
    // Middle mouse button released - not down this frame, down last frame.
    // This is the same as a click.
}
if (InputManager.Mouse.ButtonDown(Mouse.MouseButtons.RightButton))
{
    // Right mouse button down this frame;
}
if (InputManager.Mouse.ButtonDoubleClicked(Mouse.MouseButtons.LeftButton))
{
    // Left button double-clicked.
}

Mouse Scroll Wheel

The mouse scroll wheel is exposed through the InputManager.Mouse.ScrollWheel property. The ScrollWheel property returns the number of "clicks" that the scroll wheel has moved since last frame. The following code controls the Z position of the camera based on the ScrollWheel property.

SpriteManager.Camera.Z -= InputManager.Mouse.ScrollWheel;

Mouse Pixel Coordinates

The Mouse class provides information about the cursor's pixel coordinates.

int pixelXCoordinate = InputManager.Mouse.X;
int pixelYCoordinate = InputManager.Mouse.Y;

The mouse coordinates are top left justified, so (0,0) represents the top left corner of the screen. Keep in mind that the pixel coordinates are relative to the top-left of the screen, but not bound by your game screen. That means that if the cursor is to the left (outside of) your game screen, then the X value will be negative. Also, the mouse will continue to return values when the cursor is to the right or below the game screen, resulting in values which are potentially larger than the width or height of the screen.

Mouse World Coordinates

The Mouse reports the world coordinates of the cursor through the functions WorldXAt and WorldYAt.

float zPosition = 0; // or whatever other value, but 0 is the most common

float xWorldPosition = InputManager.Mouse.WorldXAt(zPosition);
float yWorldPosition = InputManager.Mouse.WorldYAt(zPosition);

// use this to set the position of something:
PlayerInstance.X = xWorldPosition;
PlayerInstance.Y = yWorldPosition;

Detecting Mouse in Window

Certain activities should only occur if the mouse is in the window. To test for this, use the following code: Add the following using statement:

using FlatRedBall.Input;

The following code performs the check:

if(InputManager.Mouse.IsInGameWindow())
{
   // perform activity
}

The SetScreenPosition method allows for control over the native Windows mouse. This method can be used to override the behavior of the mouse.

Introduction

The IsOn3D method is a method which can be used to detect whether the mouse is over a variety of different objects. The reason it is called IsOn3D is because it performs a 3D test (ray cast) so it works regardless of the camera orientation of the orientation of the object being tested.

IsOn3D and Text

The following code creates a Text object. This text object will turn white when the mouse moves over the Text, but will remain blue if the mouse is not over it.

Add the following using statements:

using FlatRedBall.Graphics;
using FlatRedBall.Input;

Add the following at class scope:

Text text;

Add the following to Initialize after initializing FlatRedBall:

IsMouseVisible = true;

text = TextManager.AddText("Hi, I am some text.");
text.X = .1f; // do this so the text doesn't appear between pixels
text.Y = .1f;

Add the following to Update:

bool relativeToCamera = false;

if (InputManager.Mouse.IsOn3D(text, relativeToCamera))
{
  text.Red = 1;
}
else
{
   text.Red = 0;
}

Warning: You should always use the non-generic version of IsOn3D when performing tests on Text objects. Want to know more? Read on!

There are a number of overloads for the IsOn3D method. The two which apply to the Text object are:

public bool IsOn3D(Text text, bool relativeToCamera)

public bool IsOn3D<T>(T objectToTest, bool relativeToCamera) where T : IPositionable, IRotatable, IReadOnlyScalable

You may be wondering which to use, why there are two versions, and how you can pick which version you are using.

First, you should use the non-generic version. That is, you should use the version that takes a Text argument.

So why are there two versions? The reason is because the generic IsOn3D is a method that is used to test whether the Mouse is over types such as Sprites and SpriteFrames. Since these objects all implement IPositionable, IRotatable, and IReadOnlyScalable, then this generic function works well.

The reason that the Text object can use the generic version of IsOn3D is because it also implements the necessary interfaces; however, even though it implements the IReadOnlyScalable, it is slightly different from the Sprite and SpriteFrame classes.

The Sprite and SpriteFrame classes both are always centered on their position. This means that the right edge of these objects is always X + ScaleX. However, this is not the case for the Text object due to its VerticalAlignment and HorizontalAlignment properties. These properties can change how the Text is drawn relative to its actual position. For this reason, the assumption that the Text's position is at its center is not valid.

This means that if the Text object is centered both horizontally and vertically, then the generic IsOn3D will accurately determine whether the mouse is over the Text. But if either property is not centered, then the generic IsOn3D will not perform accurately.

The non-generic version of IsOn3D (which has a Text argument) can perform Text-specific logic to accurately determine whether the mouse is over the Text object regardless of the HorizontalAlignment or VerticalAlignment.

This brings us to the third question - how can you pick which you are using? This all depends on how you call the method. The following code shows how to call each version:

// This calls the generic version:
InputManager.Mouse.IsOn3D<Text>(myText, false);

// This calls the non-generic version (the one you should probably call):
InputManager.Mouse.IsOn3D(myText, false); 

Working with Multiple Cameras

The following code creates two Cameras. Both cameras view a Sprite. If the cursor is over the Sprite on either Camera then it turns purple.

Add the following using statements:

using FlatRedBall.Graphics;
using FlatRedBall.Input;

Add the following at class scope:

Text text;
Sprite sprite;

Add the following to Initialize after initializing FlatRedBall:

IsMouseVisible = true;

SpriteManager.Camera.SetSplitScreenViewport(Camera.SplitScreenViewport.LeftHalf);

Camera camera = new Camera();
SpriteManager.Cameras.Add(camera);
camera.SetSplitScreenViewport(Camera.SplitScreenViewport.RightHalf);
camera.Z = 20;

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.ColorOperation = ColorOperation.Add;

Add the following to Update:

foreach (Camera camera in SpriteManager.Cameras)
{
    // The following method is only available in June 2008 and newer
    if (InputManager.Mouse.IsOn(camera))
    {
        if (InputManager.Mouse.IsOn3D(sprite, false, camera))
        {
            sprite.Blue = 1;
        }
    }
}

Selecting multiple objects

At the time of this writing there is no method to simply return all of the objects that the Mouse is over - instead you will have to manually loop through all objects to test whether the mouse is over the object. This means there are a few things to consider:

1. Performance may suffer if you have a lot of objects in your scene. If you are suffering from performance issues you may need to perform some type of higher-level partitioning to reduce calls to this method.

2. You will need to manually loop through objects and maintain a list of objects which you are over if you are interested in performing multiple-selection.

Introduction

Some games benefit from keeping the mouse within the screen bounds. The two common scenarios for keeping the mouse within the screen bounds are:

1. A first person shooter uses the mouse to move around. The mouse should be invisible and not move outside of the window when the window has focus.

2. Real time strategy games often implement "edge scrolling" (scrolling the camera when the mouse reaches the edge of the screen).

Keeping the mouse a the center of the screen

If the mouse is invisible then the easiest way to keep the mouse in screen is to continually reset its position every frame:

if(FlatRedBallServices.Game.IsActive)
{
   var centerX = FlatRedBallServices.Game.Window.ClientBounds.Width/2;
   var centerY = FlatRedBallServices.Game.Window.ClientBounds.Height/2;

   Microsoft.Xna.Framework.Input.Mouse.SetPosition(centerOfWindowX, centerOfWindowY);
}

Keeping the mouse bound to the window

The mouse can be bound to the window as shown in the following code:

[DllImport("user32.dll")]
static extern void ClipCursor(ref Rectangle rect);


protected override void Update(GameTime gameTime)
{
  if (IsActive)
  {
    Rectangle rect = Window.ClientBounds;
    rect.Width += rect.X;
    rect.Height += rect.Y;
    
    ClipCursor(ref rect);
  }
  
  base.Update(gameTime);
}

Code obtained from http://xboxforums.create.msdn.com/forums/p/3553/18372.aspx