Nevron Open Vision Documentation
Cursors
Cursors Overview

A cursor is a visual indicator that is always positioned on top of the desktop and which follows the current position of the mouse. Cursors are often used to indicate the possible effect of a mouse button click for a specific window area (widget). The cursor shape is defined by a cursor pixel map, that is a two dimensional array, holding black, white, transparent and inverted values. The point inside the cursor shape, which gets glued to the current mouse position is called hot spot and is specified relatively to the cursor shape (as an offset from the left-top corner of the cursor shape). In NOV cursors are represented by the NCursor attribute.

Cursors are a common feature of the Window Managers and NOV tries to integrate with the native support for cursors when it meets the NOV standards for cursors. When that is not possible NOV hosts emulate a system with true cursors support to achieve the same functional effect (Silverlight for example does not support custom cursors, and that is why the NOV host for Silverlight emulates true cursors support in Silverlight).

Cursors, Windows and NMouse

Since cursors are a feature of the native Window Manager, each NWindow peer has the ability to have a cursor (see Windows and The Desktop for more information about window peers). The native window peer cursor that is actually created for each NOV cursor, is specific for the integration platform and that is why the native cursors management is one of the responsibilities of NOV hosts. NOV is however responsible for the proper update of the cursor, which is handled by the NMouse static class.

NMouse opens a cursor requests session prior to raising the Move, Down or Up events, and closes the session after the event is raised. It is up to the DOM to request the cursor that it wishes by calling the NMouse.RequestCursor method during an opened cursor requests session. The first cursor that was requested during a cursor request session is applied to the window peer, which originally captured the mouse event. You can query whether it makes sense to call NMouse.RequestCursor by first calling NMouse.CanRequestCursor – it returns false if a cursor requests session is not opened or a cursor was already requested for this session.

A higher level support for cursors is implemented by the NInputElement class, which allows you to specify its cursor by simply setting its Cursor property (see Input Elements for more info).

Predefined Cursors

NOV comes with a large set of predefined cursors, that are enumerated by the ENPredefinedCursor enumeration. Most of the predefined cursors have native Windows Managers counterparts. That is why when you create a predefined cursor, NOV by default tries to use the native Windows Manager cursor, if such exists. The following code applies the Hand predefined cursor to a button. If the native Windows Managers has a native Hand cursor, NOV will try to use it. Otherwise it will create a custom Hand cursor.

Creating a Predefined Cursor
Copy Code
NCursor cursor = new NCursor(ENPredefinedCursor.Hand);
NButton button = new NButton("Click me");
button.Cursor = cursor;

Sometimes you may want NOV to always use the predefined cursor definitions that it has (i.e. never use the native Windows Manager cursor even if such exists). To do that, you need to use the second overload of the predefined cursor constructor. The following code applies a Hand cursor that is always using the NOV cursor definition for a Hand cursor (looks the same in all environments supported by NOV):

Creating a Predefined Cursor that Looks the Same Everywhere
Copy Code
NCursor cursor = new NCursor(ENPredefinedCursor.Hand, false);
NButton button = new NButton("Click me");
button.Cursor = cursor;

The following table lists the predefined cursors supported by NOV and their built-in definitions:

Preview Name Description
AppStarting The cursor that appears when an application starts.
Arrow The arrow cursor.
Cross The crosshair cursor.
Hand The hand cursor, typically used when hovering over a Web link.
Help The Help cursor, which is a combination of an arrow and a question mark.
HSplit The cursor that appears when the mouse is positioned over a horizontal splitter bar.
IBeam The I-beam cursor, which is used to show where the text cursor appears when the mouse is clicked.
No The cursor that indicates that a particular region is invalid for the current operation.
NoMove2D The cursor that appears during wheel operations when the mouse is not moving, but the window can be scrolled in both a horizontal and vertical direction.
NoMoveH The cursor that appears during wheel operations when the mouse is not moving, but the window can be scrolled in a horizontal direction.
NoMoveV The cursor that appears during wheel operations when the mouse is not moving, but the window can be scrolled in a vertical direction.
PanEast The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally to the right.
PanNorthEast The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally and vertically upward and to the right.
PanNorth The cursor that appears during wheel operations when the mouse is moving and the window is scrolling vertically in an upward direction.
PanNorthWest The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally and vertically upward and to the left.
PanSouthEast The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally and vertically downward and to the right.
PanSouth The cursor that appears during wheel operations when the mouse is moving and the window is scrolling vertically in a downward direction.
PanSouthWest The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally and vertically downward and to the left.
PanWest The cursor that appears during wheel operations when the mouse is moving and the window is scrolling horizontally to the left.
SizeAll The four-headed sizing cursor, which consists of four joined arrows that point north, south, east, and west.
SizeNESW The two-headed diagonal (northeast/southwest) sizing cursor.
SizeNS The two-headed vertical (north/south) sizing cursor.
SizeNWSE The two-headed diagonal (northwest/southeast) sizing cursor.
SizeWE The two-headed horizontal (west/east) sizing cursor.
UpArrow The up arrow cursor, typically used to identify an insertion point.
VSplit The cursor that appears when the mouse is positioned over a vertical splitter bar.
Wait The wait cursor, typically an hourglass shape.

Custom Cursors

Besides the predefined cursors, NOV allows you to create custom cursors in the following ways:

The stream passed to the cursor constructor must contain a monochrome cursor in the .CUR format. NOV comes with its own .CUR format decoder that allows it create custom cursors from .CUR files (streams) regardless of the platform. For example: even though Silverlight does not support custom cursors and .CUR format is even not mentioned in Silverlight, you can create custom NOV cursors from .CUR format streams in Silverlight.

Cursors are one of the resource formats that are supported for embedding in NOV embedded resources. That is why the resource embedding process automatically creates cursor constructors for the cursors that it has embedded. The following code creates a custom cursor from the embedded resource for the Hand cursor:

Creating a Custom Cursor from an Embedded Resource
Copy Code
NButton button = new NButton("Click me");
button.Cursor = Nevron.Presentation.NResources.Cursor_Hand_cur;

The creation of custom cursors from embedded resources is the most widely used method in NOV. This is because the cursors that are embedded can be edited directly in Visual Studio, and furthermore because NOV is optimized to share cursor definitions that arrive from embedded resources.

NOV does not use the .NET framework embedded resources and implements it's own way for embedding resource data into it's assemblies. In NOV embedded resources are embedded directly into the C# code - the most portable media in .NET. That is why NOV does not depend on the resource embedding features of the .NET framework(s) in general, because it simply does not use them. See Embedded Resources for more info.

A cursor definition is a way for verbatim specification of the cursor. The following code creates a 32x32 cursor, that consists of black and white stripes. The hot spot of the cursor is located in its the center.

Create a Custom Cursor from Code
Copy Code
ENCursorPixel[] cursorPixels = new ENCursorPixel[32 * 32];
for (int i = 0; i < 32; i++)
{
    ENCursorPixel cursorPixel = (i % 2) == 0 ? ENCursorPixel.White : ENCursorPixel.Black;
    for (int j = 0; j < 32; j++)
    {
        cursorPixels[i * 32 + j] = cursorPixel;
    }
}
NCursor cursor = new NCursor(32, 32, 16, 16, cursorPixels);
See Also
Send Feedback