Introduction

Every Cursor in FlatRedBall belongs to a specific Camera. Since multiple Cameras can exist at a given time, Cursors must know which Camera to use to convert screen space to world space for collision against game objects including UI.

By default the Cursor which can be accessed through GuiManager.Cursor uses the default Camera which FlatRedBall creates for you (which can be accessed through SpriteManager.Camera).

Changing Camera

The Cursor's Camera property can be changed. To do this simply set the Camera property to the desired Camera instance:

myCursor.Camera = someCameraInstance;

Where is the Camera property used?

The Cursor uses the Camera property internally when performing checks. Methods which use the Camera include:

• FlatRedBall.Gui.Cursor.GetRay

• FlatRedBall.Gui.Cursor.IsOn3D

The Camera property can be changed at any point, and it can be changed multiple times per frame if the Cursor is going to be used to check for whether it is over objects on multiple Cameras.

Introduction

The CustomUpdate delegate allows for customizing the Cursor's behavior. Specifically this allows setting the Cursor's position and primary/secondary/middle values.

When is CustomUpdate used?

CustomUpdate is used if you would like to use the FRB Cursor class, but would like to provide custom input logic. The most common scenario for this is when using input devices which are not natively supported by FRB. For example, the Cursor could be used with the Wii's Remote hardware (which can be paired with a computer through bluetooth).

CustomUpdate replaces regular update logic

If a non-null CustomUpdate delegate is specified then the regular input logic for the Cursor no longer applies. In other words, the Cursor no longer responds to Mouse input if CustomUpdate is used.

Code Example

The following code shows how to control the cursor with the keyboard.

// In CustomInitialize or your Game's Initialize:
GuiManager.Cursor.CustomUpdate = HandleCursorUpdate;

// Then define HandleCursorUpdate:
void HandleCursorUpdate(Cursor cursor)
{
    Keyboard keyboard = InputManager.Keyboard;

    if (keyboard.KeyDown(Keys.Up))
    {
        cursor.ScreenY--;
    }
    if (keyboard.KeyDown(Keys.Down))
    {
        cursor.ScreenY++;
    }
    if (keyboard.KeyDown(Keys.Right))
    {
        cursor.ScreenX++;
    }
    if (keyboard.KeyDown(Keys.Left))
    {
        cursor.ScreenX--;
    }

    if (keyboard.KeyDown(Keys.Space))
    {
        cursor.PrimaryDown = true;
    }
}

The IgnoreInputThisFrame will result in input values being ignored for the remainder of this frame. This can be used if two independent systems rely on cursor input (such as a click) and clicks (or other input) should be ignored for all objects if one responds to it.

Introduction

The IsInWindow method can be used to tell if the Cursor is actually inside the game window. Using this can prevent clicks from being registered when the cursor is outside of the window.

Code Example

The following example shows how to detect clicks that fall only inside of the game window:

Cursor cursor = GuiManager.Cursor;
if(cursor.PrimaryClick && cursor.IsInGameWindow())
{
   // do something to respond to the click
}

Introduction

IsOn returns whether the calling Cursor is over a given object. This function will not behave properly if the Camera is not viewing down the Z axis (default). If you have a rotated Camera, then you should use IsOn3D. This function does a position check - it does not consider if anything is covering the argument, or if the Cursor is over any other UI component. For more information on checking of the Cursor is over UI (as a test before performing IsOn checks), see the WindowOver page.

IsOn(Layer)

The IsOn overload which takes a Layer will check if the Cursor is over the argument Layer in screen coordinates. In other words, this function will behave properly even if the Camera is rotated. This function will simply do a check of the Cursor's screen position against the bounds of the Layer. If a Layer occupies the full screen, then this function will return true.

The ClickNoSlideThreshold value is measured in pixels which determines if a releasing the mouse or touch screen should be treated as a ClickNoSlide. If the distance moved since the last push is less than ClickNoSlideThreshold, then the PrimaryClickNoSlide property is true for that frame. Otherwise, only the Click property is true.

If this value is increased, then the Cursor reports clicks even if the user has moved the cursor slightly since pushing the cursor (or touching the screen). If this value is reduced, then clicks will not register as often if the cursor has moved slightly since touch. This value primarily exists to help distinguish between actual push/release vs. push+slide. Since this value is in pixels it may need to be increased for high-resolution touch screens.

Introduction

The GetRay method can be used to get a Ray representing objects which the Cursor is over. This Ray can be used for complex object picking, and will work even when the Camera is rotated, unlike the WorldXAt and WorldYAt methods.

Code Example

The following code shows how the GetRay function can be used to get a Ray representing the Cursor's current position and direction of the camera. The following code is implemented in the CustomInitialize and CustomActivity of an otherwise empty screen.

void CustomInitialize()
{
    // Add a circle for reference:
    Circle circle = ShapeManager.AddCircle();
    circle.Radius = 64;

    // so we can see the cursor:
    FlatRedBallServices.Game.IsMouseVisible = true;
}

void CustomActivity(bool firstTimeCalled)
{
    var ray = GuiManager.Cursor.GetRay();

    FlatRedBall.Debugging.Debugger.Write(
        "Ray Position: " + ray.Position + "\n" +
        "Ray Direction: " + ray.Direction);

    // let's move the camera around too to make sure this works:
    const float velocity = 50;
    InputManager.Keyboard.ControlPositionedObject(Camera.Main, velocity);

}

Community Code

Mouse world coordinates for a rotated Camera by Scott Dancer

Introduction

The PrimaryClick property returns whether the Cursor has been clicked this frame. A click is defined as:

• PrimaryDown was true last frame and...

• PrimaryDown is false this frame

This occurs if the user pushes and releases the left moue button or touches and lifts on the touch screen. If developing games which may use a touch screen, you should consider PrimaryClickNoSlide to differentiate between when the user touches and releases in the same spot vs. when the user touches, slides, then releases.

Example

The cursor can be checked to see if a click occurred in any CustomActivity code. The following code creates a Circle wherever the user clicks:

if(GuiManager.Cursor.PrimaryClick)
{
    var circle = new Circle();
    circle.Visible = true;
    circle.X = GuiManager.Cursor.WorldXAt(0);
    circle.Y = GuiManager.Cursor.WorldYAt(0);
}

Introduction

The ScreenX and ScreenY properties return the X and Y coordinates of the Cursor in pixel coordinates. These values represent the location of the cursor relative to the top-left of the game screen. These values will not be impacted by properties set on the . These values can be used if you are manually handling gestures or if you are converting screen coordinates to world coordinates instead of using the FlatRedBall methods.

Code Example

The following code uses the Debugger class to display the Cursor's screen coordinates in real time:

Introduction

The IsOn3D method is a very powerful method that can be used to test if the cursor is over an object. IsOn3D is used by generated code to test if the Cursor is over an Entity if the Entity implements IClickable or IWindow. The IsOn3D method is very powerful and flexible. It considers:

• Object position

• Camera position

• Object orientation

• Camera orientation

• Camera perspective settings

• Layers

It can be used to check if the cursor is over any of the following objects:

• Sprite

• Text

• AxisAlignedCube

• Sphere

• Any other object implementing IPositionable, IScalable, IRotatable

Code Example

The following code creates a group of Sprites which turn invisible when the cursor moves over them. Add the following at class scope:

Add the following in Initialize after initializing FlatRedBall:

Add the following to Update:

IsOn3D for clicking UI

The IsOn3D method can be used to detect if the Cursor has clicked on an object. For example, the following code shows how to check if the user has clicked on a Sprite:

IsOn3D and Layers

The PrimaryClickNoSlide property returns whether the Cursor has clicked (the primary button was down last frame, not this frame) and if the cursor has not moved more than during the time the button was down. This property is often used on touch screens so that the game can differentiate between when the user intended to touch and release a UI element versus when a slide-release was performed.

Introduction

The FlatRedBall Cursor object uses mouse or touch screen input by default. This default behavior can be changed with the SetControllingGamepad method, which switches a Cursor to be used by an Xbox360GamePad instance. When using an Xbox360GamePad for cursor control, the following input is applied:

• Cursor position is controlled by the left analog stick and d-pad. Position is kept inside of the screen automatically.

• The primary action (usually left mouse button) is controlled by the A button

• The secondary action (usually the right mouse button) is controlled by the X button

• Scrolling is controlled by the right analog stick’s Y (vertical) position

When using an Xbox360GamePad, the native (Windows) cursor will not move in response to gamepad controls, so a visual representation must be manually added.

Code Example - Using an Xbox360GamePad to Control the Cursor

The following code assumes a Circle has been added to the current Screen:

Introduction

The PrimaryPushTime property returns the amount of time since the Cursor's PrimaryPush was last set to true. This value will return 0 if the PrimaryPush was just set, or if the Cursor's PrimaryDown is false. Otherwise, this value will be greater than 0. This value can be used to detect how long the mouse button has been pressed or the touch screen touched.

Code Example

Introduction

The Cursor class represents the moving cursor (on desktop) or the touch screen (on touch screens). The Cursor class is similar to the class in its interface, but provides a few additional features:

• The Cursor is a more abstract class supporting a variety of input sources such as Mouse, Xbox360Gamepad, and TouchScreen

• The Cursor works very well with the Window class and IWindow interface. The cursor is automatically used with Gum and FlatRedBall.Forms objects

We recommend using the Cursor class unless you specifically need to inspect the Mouse hardware.

Cursor and touch screens

The Cursor can handle both mouse and touch screen input. Many games can use the exact same Cursor class whether written for the mouse or touch screen. Games needing more control over touch screen input can use the class.

Accessing the Cursor

The Cursor class can be accessed through the Cursor property as follows:

"Primary" properties

The Cursor is a general-purpose class for handling cross-platform input. It can represent a mouse, touch screen, or visible cursor controlled by the Xbox 360 Gamepad.

Cursor visibility

By default the cursor is invisible when moving over a FlatRedBall game. The following code makes the cursor visible when over the game window:

Code Example - Detecting PrimaryPush

The following code creates a Circle wherever the Cursor is pushed:

Introduction

WorldPosition returns a Vector2 of the cursor's world position (as opposed to screen position). WorldPosition can be used to place objects or perform manual detection of whether the cursor is over an object.

Code Example - Moving an Object to the Cursor WorldPosition

The following code moves an object according to the cursor's position. Note that the ToVector3 extension method is used to convert a Vector2 to a Vector3

Introduction

The WindowOver returns the Window (or any object inheriting from Window such as Button, TextBox, etc.) that the Cursor is currently over. This will return the top-most window, so if the Cursor is over a Button which is contained inside a Window, the WindowOver property will contain a reference to the Button.

Speicifcally WindowOver considers:

• Gum objects

• FlatRedBall.Forms objects (since they use Gum as their visuals)

• Any Entity or code-only object which inherits from IWindow and has been added to the GuiManager.

Code Example

The following code performs "ClickLogic" when the user performs a primary click (left click on the mouse or a release on a touch screen) if the Cursor is not over any window. This is a common way to check if the cursor is over any UI.

Using WindowOver to debug GUI problems

One very common bug is related to having multiple IWindows overlapping. In this case events may not be raising even though it appears they should be graphically. You can use the Cursor's WindowOver property in combination with the to help identify the problem:

If the wrong window is being returned by WindowOver, you can diagnose/correct this by doing the following:

1. Verify that the two IWindows have different Z values if they are on the same layer or verify that the desired IWindows are on separate Layers

Gum and WindowOver

Introduction

SecondaryClick determines whether the secondary button (right mouse button on a mouse) was pushed last frame but released this frame.

Code Example - Detecting Click on a UI Element

The SecondaryClick property can be used to detect whether a UI element, such as a Gum GraphicalUiElement, was clicked with the right mouse button.

// This would be checked every frame, such as in a screen's CustomActivity
var cursor = GuiManager.Cursor;