Article
11/17/2011

FrameworkElement.Cursor Property

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Gets or sets the cursor image that displays while the mouse pointer is over a FrameworkElement.

Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Property Cursor As Cursor

public Cursor Cursor { get; set; }

<frameworkElement Cursor="cursorsValue"/>

XAML Values

cursorsValue
A string that names a Cursors constant value, such as Arrow or IBeam.

Property Value

Type: System.Windows.Input.Cursor
The cursor image to display. The default is defined as nulla null reference (Nothing in Visual Basic) for code access. However, the appearance of the cursor image in UI at run time will come from a variety of factors.

Remarks

Dependency property identifier field: CursorProperty

When you set this property in XAML, the XAML processor relies on type conversion for the Cursor class to evaluate the attribute string value. The provided string should evaluate to a string that is a Cursors constant. For more information, see Cursor.

To revert the effects of setting this property from code, and to use the run-time UI defaults instead, set Cursor to nulla null reference (Nothing in Visual Basic).

The null default really means that determination of the cursor/pointer image in UI is deferred as a specific per-object property set and should be obtained from elsewhere. If presented without programmatic values from any source, the default cursor that is visually over a Silverlight-based application will be an arrow. However, the transient cursor changes are not set to the Cursor values of the objects when they are passed over. The Cursor property will only report non-null values in cases where it was actually set, for example through code.

Specific controls might also influence Cursor values as part of their composition (perhaps through a style, or a visual state in a style) and through their class implementation. An example is any control that contains a TextBox, or TextBox itself.

When you set a Cursor value on a layout container such as a panel, the cursor value will "inherit" to be the hover-over behavior for contained child elements that do not otherwise specify what the cursor should be. However, if any specific element does request a specific cursor, as a TextBox typically does, the specific per-element cursor is used regardless of any Cursor value on the container.

Note:
Silverlight models its cursor API on the WPF cursor API. However, cursors are not extensible in Silverlight 5 (the Silverlight Cursor is sealed). This is the architectural reason for why you use the Cursor intermediate type for the Cursor property value in code, rather than as a Cursors static property values directly.

Version Notes

In Silverlight 3, Cursor is a dependency property, even though the identifier field is not public. You can still set it in XAML, and you can style it in XAML. However, you cannot use property system APIs against it (such as SetValue).

Examples

The following example implements a utility method that sets the cursor on a target FrameworkElement to be an appropriate visual cursor (Hand) for a "Grab" operation. Alternatively, the method resets any previously set "Grab" cursor back to the nulla null reference (Nothing in Visual Basic) default for use after the "Grab" operation is complete.

private static void ChangeGrabState(bool canGrab, FrameworkElement target)
{
    if (canGrab)
    {
        target.Cursor = Cursors.Hand;
    }
    else
    {
        target.Cursor = null;
        //deliberate null set causes the target to resume a default cursor handling
        //based on context, the specific target's behavior, etc.
    }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Share via