Module javafx.graphics

Package javafx.scene

Class ImageCursor

java.lang.Object

javafx.scene.Cursor

javafx.scene.ImageCursor

public class ImageCursor
extends Cursor

A custom image representation of the mouse cursor. On platforms that don't support custom cursors, Cursor.DEFAULT will be used in place of the specified ImageCursor.

Example:

import javafx.scene.*;
import javafx.scene.image.*;

Image image = new Image("mycursor.png");

Scene scene = new Scene(400, 300);
scene.setCursor(new ImageCursor(image,
                                image.getWidth() / 2,
                                image.getHeight() /2));
 

Since:

JavaFX 2.0

Property Summary

Properties

Type	Property	Description
final ReadOnlyDoubleProperty	hotspotX	The X coordinate of the cursor's hot spot.
final ReadOnlyDoubleProperty	hotspotY	The Y coordinate of the cursor's hot spot.
final ReadOnlyObjectProperty<Image>	image	The image to display when the cursor is active.

Field Summary

Fields declared in class javafx.scene.Cursor

CLOSED_HAND, CROSSHAIR, DEFAULT, DISAPPEAR, E_RESIZE, H_RESIZE, HAND, MOVE, N_RESIZE, NE_RESIZE, NONE, NW_RESIZE, OPEN_HAND, S_RESIZE, SE_RESIZE, SW_RESIZE, TEXT, V_RESIZE, W_RESIZE, WAIT

Constructor Summary

Constructors

Constructor	Description
ImageCursor()	Constructs a new empty ImageCursor which will look as Cursor.DEFAULT.
ImageCursor(Image image)	Constructs an ImageCursor from the specified image.
ImageCursor(Image image, double hotspotX, double hotspotY)	Constructs an ImageCursor from the specified image and hotspot coordinates.

Method Summary

Modifier and Type	Method	Description
static ImageCursor	chooseBestCursor(Image[] images, double hotspotX, double hotspotY)	Creates a custom image cursor from one of the specified images.
static Dimension2D	getBestSize(double preferredWidth, double preferredHeight)	Gets the supported cursor size that is closest to the specified preferred size.
final double	getHotspotX()	Gets the value of the hotspotX property.
final double	getHotspotY()	Gets the value of the hotspotY property.
final Image	getImage()	Gets the value of the image property.
static int	getMaximumColors()	Returns the maximum number of colors supported in a custom image cursor palette.
final ReadOnlyDoubleProperty	hotspotXProperty()	The X coordinate of the cursor's hot spot.
final ReadOnlyDoubleProperty	hotspotYProperty()	The Y coordinate of the cursor's hot spot.
final ReadOnlyObjectProperty<Image>	imageProperty()	The image to display when the cursor is active.

Methods declared in class javafx.scene.Cursor

cursor, toString

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Property Details

image

public final ReadOnlyObjectProperty<Image> imageProperty

The image to display when the cursor is active. If the image is null, Cursor.DEFAULT will be used.

Default value:

null

See Also:

• getImage()
• imageProperty()

hotspotX

public final ReadOnlyDoubleProperty hotspotXProperty

The X coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.width-1]. A value less than 0 will be set to 0. A value greater than image.width-1 will be set to image.width-1.

Default value:

0

See Also:

• getHotspotX()
• hotspotXProperty()

hotspotY

public final ReadOnlyDoubleProperty hotspotYProperty

The Y coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.height-1]. A value less than 0 will be set to 0. A value greater than image.height-1 will be set to image.height-1.

Default value:

0

See Also:

• getHotspotY()
• hotspotYProperty()

Constructor Details

ImageCursor

public ImageCursor()

Constructs a new empty ImageCursor which will look as Cursor.DEFAULT.

ImageCursor

public ImageCursor(Image image)

Constructs an ImageCursor from the specified image. The cursor's hot spot will default to the upper left corner.

Parameters:

image - the image

ImageCursor

public ImageCursor(Image image,
 double hotspotX,
 double hotspotY)

Constructs an ImageCursor from the specified image and hotspot coordinates.

Parameters:

image - the image

hotspotX - the X coordinate of the cursor's hot spot

hotspotY - the Y coordinate of the cursor's hot spot

Method Details

getImage

public final Image getImage()

Gets the value of the image property.

Property description:

The image to display when the cursor is active. If the image is null, Cursor.DEFAULT will be used.

Default value:

null

Returns:

the value of the image property

See Also:

• imageProperty()

imageProperty

public final ReadOnlyObjectProperty<Image> imageProperty()

The image to display when the cursor is active. If the image is null, Cursor.DEFAULT will be used.

Default value:

null

Returns:

the image property

See Also:

• getImage()

getHotspotX

public final double getHotspotX()

Gets the value of the hotspotX property.

Property description:

The X coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.width-1]. A value less than 0 will be set to 0. A value greater than image.width-1 will be set to image.width-1.

Default value:

0

Returns:

the value of the hotspotX property

See Also:

• hotspotXProperty()

hotspotXProperty

public final ReadOnlyDoubleProperty hotspotXProperty()

The X coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.width-1]. A value less than 0 will be set to 0. A value greater than image.width-1 will be set to image.width-1.

Default value:

0

Returns:

the hotspotX property

See Also:

• getHotspotX()

getHotspotY

public final double getHotspotY()

Gets the value of the hotspotY property.

Property description:

The Y coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.height-1]. A value less than 0 will be set to 0. A value greater than image.height-1 will be set to image.height-1.

Default value:

0

Returns:

the value of the hotspotY property

See Also:

• hotspotYProperty()

hotspotYProperty

public final ReadOnlyDoubleProperty hotspotYProperty()

The Y coordinate of the cursor's hot spot. This hotspot represents the location within the cursor image that will be displayed at the mouse position. This must be in the range of [0,image.height-1]. A value less than 0 will be set to 0. A value greater than image.height-1 will be set to image.height-1.

Default value:

0

Returns:

the hotspotY property

See Also:

• getHotspotY()

getBestSize

public static Dimension2D getBestSize(double preferredWidth,
 double preferredHeight)

Gets the supported cursor size that is closest to the specified preferred size. A value of (0,0) is returned if the platform does not support custom cursors.

Note: if an image is used whose dimensions don't match a supported size (as returned by this method), the implementation will resize the image to a supported size. This may result in a loss of quality.

Note: These values can vary between operating systems, graphics cards and screen resolution, but at the time of this writing, a sample Windows Vista machine returned 32x32 for all requested sizes, while sample Mac and Linux machines returned the requested size up to a maximum of 64x64. Applications should provide a 32x32 cursor, which will work well on all platforms, and may optionally wish to provide a 64x64 cursor for those platforms on which it is supported.

Parameters:

preferredWidth - the preferred width of the cursor

preferredHeight - the preferred height of the cursor

Returns:

the supported cursor size

getMaximumColors

public static int getMaximumColors()

Returns the maximum number of colors supported in a custom image cursor palette.

Note: if an image is used which has more colors in its palette than the supported maximum, the implementation will attempt to flatten the palette to the maximum. This may result in a loss of quality.

Note: These values can vary between operating systems, graphics cards and screen resolution, but at the time of this writing, a sample Windows Vista machine returned 256, a sample Mac machine returned Integer.MAX_VALUE, indicating support for full color cursors, and a sample Linux machine returned 2. Applications may want to target these three color depths for an optimal cursor on each platform.

Returns:

the maximum number of colors supported in a custom image cursor palette

chooseBestCursor

public static ImageCursor chooseBestCursor(Image[] images,
 double hotspotX,
 double hotspotY)

Creates a custom image cursor from one of the specified images. This function will choose the image whose size most closely matched the best cursor size. The hotpotX of the returned ImageCursor is scaled by chosenImage.width/images[0].width and the hotspotY is scaled by chosenImage.height/images[0].height.

On platforms that don't support custom cursors, Cursor.DEFAULT will be used in place of the returned ImageCursor.

Parameters:

images - a sequence of images from which to choose, in order of preference

hotspotX - the X coordinate of the hotspot within the first image in the images sequence

hotspotY - the Y coordinate of the hotspot within the first image in the images sequence

Returns:

a cursor created from the best image