APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javafx.scene

public Class ImageCursor

extends Cursor
Class Inheritance
Imports
java.util.HashMap, .Map, .Arrays, javafx.beans.InvalidationListener, .Observable, .NamedArg, javafx.beans.property.ReadOnlyDoubleProperty, .ReadOnlyDoublePropertyBase, .ReadOnlyObjectProperty, .ReadOnlyObjectPropertyBase, javafx.geometry.Dimension2D, javafx.scene.image.Image, com.sun.javafx.cursor.CursorFrame, .ImageCursorFrame, com.sun.javafx.tk.Toolkit
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

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
ImageCursor.DelayedInitialization

private class
ImageCursor.DoublePropertyImpl

private class
ImageCursor.ObjectPropertyImpl<T>

Field Summary

Modifier and TypeField and Description
private int
activeCounter

Indicates whether the image cursor is currently in use.

private CursorFrame
currentCursorFrame

private ImageCursorFrame
firstCursorFrame

Stores the first cursor frame.

private ImageCursor.DoublePropertyImpl
hotspotX

The X coordinate of the cursor's hot spot.

private ImageCursor.DoublePropertyImpl
hotspotY

The Y coordinate of the cursor's hot spot.

private ImageCursor.ObjectPropertyImpl<Image>
image

The image to display when the cursor is active.

private InvalidationListener
imageListener

private Map<Object, ImageCursorFrame>
otherCursorFrames

Maps platform images to cursor frames.

Inherited from javafx.scene.Cursor:
CLOSED_HANDCROSSHAIRDEFAULTDISAPPEARE_RESIZEH_RESIZEHANDMOVEN_RESIZENE_RESIZENONENW_RESIZEOPEN_HANDS_RESIZESE_RESIZESW_RESIZETEXTV_RESIZEW_RESIZEWAIT

Constructor Summary

AccessConstructor and Description
public
ImageCursor()

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

public
ImageCursor(final Image
the image
image)

Constructs an ImageCursor from the specified image.

public
ImageCursor(final Image
the image
image, double
the X coordinate of the cursor's hot spot
hotspotX, double
the Y coordinate of the cursor's hot spot
hotspotY)

Constructs an ImageCursor from the specified image and hotspot coordinates.

Method Summary

Modifier and TypeMethod and Description
pack-priv void
activate()

Overrides javafx.scene.Cursor.activate.

Activates the cursor.

private void
bindImage(final Image toImage)

public static ImageCursor

Returns:

a cursor created from the best image
chooseBestCursor(final Image[]
a sequence of images from which to choose, in order of preference
images, final double
the X coordinate of the hotspot within the first image in the images sequence
hotspotX, final double
the Y coordinate of the hotspot within the first image in the images sequence
hotspotY)

Creates a custom image cursor from one of the specified images.

pack-priv void
deactivate()

Overrides javafx.scene.Cursor.deactivate.

Deactivates the cursor.

private static Image
findBestImage(final Image[] images)

public static Dimension2D

Returns:

the supported cursor size
getBestSize(double
the preferred width of the cursor
preferredWidth, double
the preferred height of the cursor
preferredHeight)

Gets the supported cursor size that is closest to the specified preferred size.

pack-priv CursorFrame
getCurrentFrame()

Implements abstract javafx.scene.Cursor.getCurrentFrame.

public final double
getHotspotX()

public final double
getHotspotY()

public final Image
getImage()

private InvalidationListener
getImageListener()

public static int

Returns:

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

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

public final ReadOnlyDoubleProperty
hotspotXProperty()

private ImageCursor.DoublePropertyImpl
hotspotXPropertyImpl()

public final ReadOnlyDoubleProperty
hotspotYProperty()

private ImageCursor.DoublePropertyImpl
hotspotYPropertyImpl()

public final ReadOnlyObjectProperty<Image>
imageProperty()

private ImageCursor.ObjectPropertyImpl<Image>
imagePropertyImpl()

private void
initialize(final Image[] images, final double hotspotX, final double hotspotY)

private void
initialize(Image newImage, double newHotspotX, double newHotspotY)

private void
invalidateCurrentFrame()

private static boolean
needsDelayedInitialization(final Image[] images)

private void
unbindImage(final Image fromImage)

Inherited from javafx.scene.Cursor:
cursortoString

Field Detail

activeCounterback to summary
private int activeCounter

Indicates whether the image cursor is currently in use. The active cursor is bound to the image and invalidates its platform cursor when the image changes.

currentCursorFrameback to summary
private CursorFrame currentCursorFrame
firstCursorFrameback to summary
private ImageCursorFrame firstCursorFrame

Stores the first cursor frame. For non-animated cursors there is only one frame and so the restCursorFrames is null.

hotspotXback to summary
private ImageCursor.DoublePropertyImpl hotspotX

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
hotspotYback to summary
private ImageCursor.DoublePropertyImpl hotspotY

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
imageback to summary
private ImageCursor.ObjectPropertyImpl<Image> image

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

Default Value
null
imageListenerback to summary
private InvalidationListener imageListener
otherCursorFramesback to summary
private Map<Object, ImageCursorFrame> otherCursorFrames

Maps platform images to cursor frames. It doesn't store the first cursor frame and so it needs to be created only for animated cursors.

Constructor Detail

ImageCursorback to summary
public ImageCursor()

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

ImageCursorback to summary
public ImageCursor(final Image image)

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

Parameters
image:Image

the image

ImageCursorback to summary
public ImageCursor(final Image image, double hotspotX, double hotspotY)

Constructs an ImageCursor from the specified image and hotspot coordinates.

Parameters
image:Image

the image

hotspotX:double

the X coordinate of the cursor's hot spot

hotspotY:double

the Y coordinate of the cursor's hot spot

Method Detail

activateback to summary
pack-priv void activate()

Overrides javafx.scene.Cursor.activate.

Doc from javafx.scene.Cursor.activate.

Activates the cursor. Cursor should be activated to make sure that the getCurrentFrame returns up-to date values.

Annotations
@Override
bindImageback to summary
private void bindImage(final Image toImage)
chooseBestCursorback to summary
public static ImageCursor chooseBestCursor(final Image[] images, final double hotspotX, final 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:Image[]

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

hotspotX:double

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

hotspotY:double

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

Returns:ImageCursor

a cursor created from the best image

deactivateback to summary
pack-priv void deactivate()

Overrides javafx.scene.Cursor.deactivate.

Doc from javafx.scene.Cursor.deactivate.

Deactivates the cursor. Cursor should be deactivated, when no longer in use to make it collectible by GC.

Annotations
@Override
findBestImageback to summary
private static Image findBestImage(final Image[] images)
getBestSizeback to summary
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:double

the preferred width of the cursor

preferredHeight:double

the preferred height of the cursor

Returns:Dimension2D

the supported cursor size

getCurrentFrameback to summary
pack-priv CursorFrame getCurrentFrame()

Implements abstract javafx.scene.Cursor.getCurrentFrame.

Annotations
@Override
getHotspotXback to summary
public final double getHotspotX()
getHotspotYback to summary
public final double getHotspotY()
getImageback to summary
public final Image getImage()
getImageListenerback to summary
private InvalidationListener getImageListener()
getMaximumColorsback to summary
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:int

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

hotspotXPropertyback to summary
public final ReadOnlyDoubleProperty hotspotXProperty()
hotspotXPropertyImplback to summary
private ImageCursor.DoublePropertyImpl hotspotXPropertyImpl()
hotspotYPropertyback to summary
public final ReadOnlyDoubleProperty hotspotYProperty()
hotspotYPropertyImplback to summary
private ImageCursor.DoublePropertyImpl hotspotYPropertyImpl()
imagePropertyback to summary
public final ReadOnlyObjectProperty<Image> imageProperty()
imagePropertyImplback to summary
private ImageCursor.ObjectPropertyImpl<Image> imagePropertyImpl()
initializeback to summary
private void initialize(final Image[] images, final double hotspotX, final double hotspotY)
initializeback to summary
private void initialize(Image newImage, double newHotspotX, double newHotspotY)
invalidateCurrentFrameback to summary
private void invalidateCurrentFrame()
needsDelayedInitializationback to summary
private static boolean needsDelayedInitialization(final Image[] images)
unbindImageback to summary
private void unbindImage(final Image fromImage)
javafx.scene back to summary

private final Class ImageCursor.DelayedInitialization

extends Object
implements InvalidationListener
Class Inheritance
All Implemented Interfaces
javafx.beans.InvalidationListener

Field Summary

Modifier and TypeField and Description
private final double
hotspotX

private final double
hotspotY

private final Image[]
images

private final boolean
initAsSingle

private final ImageCursor
targetCursor

private int
waitForImages

Constructor Summary

AccessConstructor and Description
private
DelayedInitialization(final ImageCursor targetCursor, final Image[] images, final double hotspotX, final double hotspotY, final boolean initAsSingle)

Method Summary

Modifier and TypeMethod and Description
public static void
applyTo(final ImageCursor imageCursor, final Image[] images, final double hotspotX, final double hotspotY)

public static void
applyTo(final ImageCursor imageCursor, final Image image, final double hotspotX, final double hotspotY)

private void
cleanupAndFinishInitialization()

public void
invalidated(Observable valueModel)

Implements javafx.beans.InvalidationListener.invalidated.

This method needs to be provided by an implementation of InvalidationListener.

private void
start()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

hotspotXback to summary
private final double hotspotX
hotspotYback to summary
private final double hotspotY
imagesback to summary
private final Image[] images
initAsSingleback to summary
private final boolean initAsSingle
targetCursorback to summary
private final ImageCursor targetCursor
waitForImagesback to summary
private int waitForImages

Constructor Detail

DelayedInitializationback to summary
private DelayedInitialization(final ImageCursor targetCursor, final Image[] images, final double hotspotX, final double hotspotY, final boolean initAsSingle)

Method Detail

applyToback to summary
public static void applyTo(final ImageCursor imageCursor, final Image[] images, final double hotspotX, final double hotspotY)
applyToback to summary
public static void applyTo(final ImageCursor imageCursor, final Image image, final double hotspotX, final double hotspotY)
cleanupAndFinishInitializationback to summary
private void cleanupAndFinishInitialization()
invalidatedback to summary
public void invalidated(Observable valueModel)

Implements javafx.beans.InvalidationListener.invalidated.

Doc from javafx.beans.InvalidationListener.invalidated.

This method needs to be provided by an implementation of InvalidationListener. It is called if an Observable becomes invalid.

In general, it is considered bad practice to modify the observed value in this method.

Annotations
@Override
startback to summary
private void start()
javafx.scene back to summary

private final Class ImageCursor.DoublePropertyImpl

extends ReadOnlyDoublePropertyBase
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final String
name

private double
value

Constructor Summary

AccessConstructor and Description
public
DoublePropertyImpl(final String name)

Method Summary

Modifier and TypeMethod and Description
public void
fireValueChangedEvent()

Overrides javafx.beans.property.ReadOnlyDoublePropertyBase.fireValueChangedEvent.

Sends notifications to all attached InvalidationListeners and ChangeListeners.

public double
get()

Implements javafx.beans.value.ObservableDoubleValue.get.

Returns the current value of this ObservableDoubleValue.

public Object
getBean()

Implements javafx.beans.property.ReadOnlyProperty.getBean.

Returns the Object that contains this property.

public String
getName()

Implements javafx.beans.property.ReadOnlyProperty.getName.

Returns the name of this property.

public void
store(final double value)

Inherited from javafx.beans.property.ReadOnlyDoublePropertyBase:
addListeneraddListenerremoveListenerremoveListener

Field Detail

nameback to summary
private final String name
valueback to summary
private double value

Constructor Detail

DoublePropertyImplback to summary
public DoublePropertyImpl(final String name)

Method Detail

fireValueChangedEventback to summary
public void fireValueChangedEvent()

Overrides javafx.beans.property.ReadOnlyDoublePropertyBase.fireValueChangedEvent.

Doc from javafx.beans.property.ReadOnlyDoublePropertyBase.fireValueChangedEvent.

Sends notifications to all attached InvalidationListeners and ChangeListeners. This method needs to be called, if the value of this property changes.

Annotations
@Override
getback to summary
public double get()

Implements javafx.beans.value.ObservableDoubleValue.get.

Doc from javafx.beans.value.ObservableDoubleValue.get.

Returns the current value of this ObservableDoubleValue.

Annotations
@Override
getBeanback to summary
public Object getBean()

Implements javafx.beans.property.ReadOnlyProperty.getBean.

Doc from javafx.beans.property.ReadOnlyProperty.getBean.

Returns the Object that contains this property. If this property is not contained in an Object, null is returned.

Annotations
@Override
getNameback to summary
public String getName()

Implements javafx.beans.property.ReadOnlyProperty.getName.

Doc from javafx.beans.property.ReadOnlyProperty.getName.

Returns the name of this property. If the property does not have a name, this method returns an empty String.

Annotations
@Override
storeback to summary
public void store(final double value)
javafx.scene back to summary

private final Class ImageCursor.ObjectPropertyImpl<T>

extends ReadOnlyObjectPropertyBase<T>
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final String
name

private T
value

Constructor Summary

AccessConstructor and Description
public
ObjectPropertyImpl(final String name)

Method Summary

Modifier and TypeMethod and Description
public void
fireValueChangedEvent()

Overrides javafx.beans.property.ReadOnlyObjectPropertyBase.fireValueChangedEvent.

Sends notifications to all attached InvalidationListeners and ChangeListeners.

public T
get()

Implements javafx.beans.value.ObservableObjectValue.get.

Returns the current value of this ObservableObjectValue<T>.

public Object
getBean()

Implements javafx.beans.property.ReadOnlyProperty.getBean.

Returns the Object that contains this property.

public String
getName()

Implements javafx.beans.property.ReadOnlyProperty.getName.

Returns the name of this property.

public void
store(final T value)

Inherited from javafx.beans.property.ReadOnlyObjectPropertyBase:
addListeneraddListenerremoveListenerremoveListener

Field Detail

nameback to summary
private final String name
valueback to summary
private T value

Constructor Detail

ObjectPropertyImplback to summary
public ObjectPropertyImpl(final String name)

Method Detail

fireValueChangedEventback to summary
public void fireValueChangedEvent()

Overrides javafx.beans.property.ReadOnlyObjectPropertyBase.fireValueChangedEvent.

Doc from javafx.beans.property.ReadOnlyObjectPropertyBase.fireValueChangedEvent.

Sends notifications to all attached InvalidationListeners and ChangeListeners. This method needs to be called, if the value of this property changes.

Annotations
@Override
getback to summary
public T get()

Implements javafx.beans.value.ObservableObjectValue.get.

Doc from javafx.beans.value.ObservableObjectValue.get.

Returns the current value of this ObservableObjectValue<T>.

Annotations
@Override
getBeanback to summary
public Object getBean()

Implements javafx.beans.property.ReadOnlyProperty.getBean.

Doc from javafx.beans.property.ReadOnlyProperty.getBean.

Returns the Object that contains this property. If this property is not contained in an Object, null is returned.

Annotations
@Override
getNameback to summary
public String getName()

Implements javafx.beans.property.ReadOnlyProperty.getName.

Doc from javafx.beans.property.ReadOnlyProperty.getName.

Returns the name of this property. If the property does not have a name, this method returns an empty String.

Annotations
@Override
storeback to summary
public void store(final T value)