Jump into JavaFX, Part 3: The basic APIs

Sky-Tiger

In addition to LINEAR interpolation, the Interpolator class supports DISCRETE, EASEIN, EASEOUT, and EASEBOTH forms of interpolation. With DISCRETE interpolation, you end up with discrete keyframe animation because intermediate key frames aren't calculated. The EASEIN, EASEOUT, and EASEBOTH forms are similar to LINEAR, except for slowly easing into, out of, or both into and out of the animation.

There's a great deal more to learn about animation in JavaFX, but we'll move on now to some of the javafx.application classes, where you'll begin to experience JavaFX's distinctive approach to rich Internet application development.

Sky-Tiger

Make a Window: Frame and Stage

The javafx.application package's Frame and Stage classes are used to specify a decorated top-level application window and its content area for a JavaFX application. Frame (a subclass of javafx.application.Window) provides access to a variety of attributes, including the six described below:

    * closeAction (of type function():Void) identifies the function to execute whenever the user closes the window.
    * height (of type Integer) specifies the window's height (in pixels).
    * stage (of type Stage) identifies the window's content area, or stage.
    * title (of type String) specifies the window's title.
    * visible (of type Boolean) causes the window to appear when true is assigned to this attribute.
    * width (of type Integer) specifies the window's width (in pixels).

Similarly, Stage provides access to four attributes:

    * content (of type javafx.scene.Node[]) specifies the stage's content as a sequence of nodes -- which I'll discuss later.
    * fill (of type javafx.scene.paint.Paint) describes the stage's background paint.
    * height and width (both of type Integer) are read-only attributes that provide the current dimensions of the content area.

You might recall that I illustrated the Frame and Stage classes in "Jump into JavaFX, Part 1," via my Hello, JavaFX! (Main.fx) script. After declaring a Model class to record the script's application state in Model's text, opacity, and rotAngle attributes (whenever these attributes change, user interface attributes bound to them also change), the script uses a pair of object literals to instantiate Model, followed by Frame.

The first attribute initializer in the Frame object literal, title: bind model.text, binds Frame's title attribute to the script's model's text attribute. Whenever the model's text attribute changes, the new title appears on the frame window's title bar. It also appears centered within the window's content area (the stage).

Sky-Tiger

Remaining attribute initializers size the window by assigning values to width and height; create the content area via a Stage literal and assign this literal to the stage attribute; display the window by assigning true to visible; and assign an anonymous function to closeAction. This function executes when the window closes.
Models

While exploring JavaFX scripts, you'll often encounter model classes and user interface attributes bound to model attributes. Separating an application's model from its user interface is recommended practice for all JavaFX scripts.

The stage presents the content that's stored in Stage's content sequence attribute. Before we look at several interesting kinds of content that can be assigned to content, let's learn how to paint the stage's background.

Sky-Tiger

Paint the stage: Paint, Color, and Gradients

Stage's fill attribute lets you determine how the content area's background is painted. Because this attribute is of type Paint, and because the javafx.scene.paint.Color, javafx.scene.paint.LinearGradient, and javafx.scene.paint.RadialGradiant classes subclass this abstract class, you can paint the background using either a solid color or a gradient pattern.

The Color class lets you specify a solid color in various ways. For example, you can create an object literal, assigning the color's red, green, and blue components to the literal's red, green, and blue Number attributes. Alternatively, you can work with functions such as those listed below:

    * public static color(red: Number, green: Number, blue: Number, opacity: Number): Color returns a solid color in the sRGB color space with the specified red, green, blue, and opacity values in the range 0.0-1.0.
    * public static fromAWTColor(c: java.awt.Color): Color returns a solid color derived from the provided java.awt.Color instance.
    * public static hsb(hue: Number, saturation: Number, brightness: Number, opacity: Number): Color returns a solid color based on the specified values for the HSB color model. The saturation, brightness, and opacity components should be floating-point values ranging from 0.0 through 1.0. The hue component can be any floating-point number. The floor of this number is subtracted from it to create a fraction between 0 and 1. This fractional number is then multiplied by 360 to produce the hue angle in the HSB color model.
    * public static rgb(red: Integer, green: Integer, blue: Integer, opacity: Number): Color returns a solid color in the sRGB color space with the specified red, green, and blue values in the range 0-255, and the opacity value in the range 0.0-1.0.
    * public static web(color: java.lang.String, opacity: Number): Color returns a solid color specified in hexadecimal notation, and having the specified opacity.

If you refer back to the Hello, JavaFX! script from "Jump into JavaFX, Part 1," you'll discover that I assigned an instance of LinearGradient (via the object literal that I've reproduced below) to fill, to establish a gradient pattern with black at the top and blue-violet at the bottom for the content area's background:

Sky-Tiger

Listing 7. Creating a linear gradient background pattern

fill: LinearGradient
{
    startX: 0.0
    startY: 0.0
    endX: 0.0
    endY: 1.0
    stops:
    [
        Stop { offset: 0.0 color: Color.BLACK },
        Stop { offset: 1.0 color: Color.BLUEVIOLET }
    ]
}

LinearGradientPaint provides startX, startY, endX, and endY attributes that identify the start and end points of a linear gradient, which fills a shape with interpolated colors. By leaving the X values at 0.0, and by having Y range from 0.0 through 1.0, this gradient paint will paint its gradient in a vertical direction.

The stops attribute identifies a sequence of javafx.scene.paint.Stop instances that describe how colors are distributed along the gradient. Each Stop instance is like a key frame -- its offset attribute identifies a solid color position along a 0.0 through 1.0 range, and its color attribute (a Color instance) identifies this solid color.

Now that we know how to paint a stage's background, we're almost ready to specify the stage's node-based content. Before we can do this, however, we need to learn about the Node class.

Sky-Tiger

Understand the Node class

Stage's content attribute lets you describe a graphical scene via a sequence of nodes, instances of classes that subclass the abstract javafx.scene.Node class. This sequence of nodes may include hierarchical groups of nodes, much like Swing GUIs consist of component/container hierarchies. The resulting nodes hierarchy is known as a scene graph.
More about scene graphs

For a good introduction to scene graphs, check out Wikipedia's Scene graph entry. Also see Java.net's Project Scene Graph, which provides the foundation for JavaFX's scene-graph support.

When it comes to creating scenes in JavaFX, you'll need to familiarize yourself with Node and its subclasses. For starters, Node defines a local coordinate system with (0, 0) representing a node's upper-left corner, x increasing to the right, and y increasing downwards. This class also provides a variety of attributes and functions, including those listed below, which all subclasses share:

    * anchorX (of type Number) specifies the X coordinate of this node's anchor point (the point around which node content rotates) -- 0.0 is the default value.
    * anchorY (of type Number) specifies the Y coordinate of this node's anchor point -- 0.0 is the default value.
    * cursor (of type javafx.scene.Cursor) identifies this node's mouse cursor.
    * effect (of type javafx.scene.effect.Effect) identifies this node's visual effect (such as dropshadow, glow, and motion blur).
    * onKeyPressed (of type function(:KeyEvent):Void) identifies a function that's invoked when this node has input focus and a key is pressed.
    * onKeyReleased (of type function(:KeyEvent):Void) identifies a function that's invoked when this node has input focus and a key is released.
    * onKeyTyped (of type function(:KeyEvent):Void) identifies a function that's invoked when this node has input focus and a key is pressed and released.
    * onMouseClicked (of type function(:MouseEvent):Void) identifies a function that's invoked when a mouse button is pressed and released while the mouse cursor is over this node.
    * onMouseDragged (of type function(:MouseEvent):Void) identifies a function that's invoked when a mouse button is pressed while the mouse cursor is over this node and the mouse cursor is moved while the mouse button remains pressed.
    * onMouseEntered (of type function(:MouseEvent):Void) identifies a function that's invoked when the mouse cursor enters this node.
    * onMouseExited (of type function(:MouseEvent):Void) identifies a function that's invoked when the mouse cursor exits this node.
    * onMouseMoved (of type function(:MouseEvent):Void) identifies a function that's invoked when the mouse is moved over this node.
    * onMousePressed (of type function(:MouseEvent):Void) identifies a function that's invoked when a mouse button is pressed while the mouse cursor is over this node.
    * onMouseReleased (of type function(:MouseEvent):Void) identifies a function that's invoked when a mouse button is released while the mouse cursor is over this node.
    * opacity (of type Number) identifies this node's opacity, from 0.0 (invisible) to 1.0 (fully visible).
    * rotate (of type Number) specifies the angle (in degrees) by which this node is rotated (the default value is 0.0).
    * scaleX (of type Number) specifies this node's scaling factor in the X direction (the default value is 1.0).
    * scaleY (of type Number) specifies this node's scaling factor in the Y direction (the default value is 1.0).
    * shearX (of type Number) specifies the multiplier by which this node's coordinates are shifted in the direction of the positive X axis as a factor of their Y coordinate.
    * shearY (of type Number) specifies the multiplier by which this node's coordinates are shifted in the direction of the positive Y axis as a factor of their X coordinate.
    * translateX (of type Number) specifies this node's translation factor in the X direction (the default value is 0.0).
    * translateY (of type Number) specifies this node's translation factor in the Y direction (the default value is 0.0).
    * visible (of type Boolean) specifies this node's visibility (the default value is true).
    * public contains(x: Number, y: Number): Boolean returns true if the (x, y) point (specified in this node's coordinate system) is located within this node's visual bounds (whether or not this node is visible).
    * public bound getBoundsHeight(): Number returns this node's current height, taking into account any specified transformations.
    * public bound getBoundsWidth(): Number returns this node's current width, taking into account any specified transformations.
    * public bound getBoundsX(): Number returns the X coordinate of this node's origin, taking into account any specified transformations.
    * public bound getBoundsY(): Number returns the Y coordinate of this node's origin, taking into account any specified transformations.
    * public bound getHeight(): Number returns this node's current height without accounting for transformations.
    * public bound getWidth(): Number returns this node's current width without accounting for transformations.
    * public bound getX(): Number returns the X coordinate of this node's origin without accounting for transformations.
    * public bound getY(): Number returns the Y coordinate of this node's origin without accounting for transformations.

Sky-Tiger

Responding to input events

As you saw in the above listing, Node offers onMouseClicked, onMouseDragged, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, and onMouseReleased attributes for responding to mouse events. Each function assigned to one of these attributes requires a javafx.input.MouseEvent argument. This class provides the functions below for ascertaining various kinds of information about the event:

    * public getButton(): Integer returns an indication of which (if any) buttons have changed state.
    * public getClickCount(): Integer returns the number of mouse clicks associated with this event.
    * public getDragX(): Number returns the X offset of the event relative to the most recent press event if the MouseEvent is part of a press-drag-release gesture, otherwise returns 0.
    * public getDragY(): Number returns the Y offset of the event relative to the most recent press event if the MouseEvent is part of a press-drag-release gesture, otherwise returns 0.
    * public getScreenX(): Number returns the mouse cursor's horizontal X position relative to the upper-left corner of the screen.
    * public getScreenY(): Number returns the mouse cursor's horizontal Y position relative to the upper-left corner of the screen.
    * public getStageX(): Number returns the mouse cursor's horizontal X position relative to the stage's origin.
    * public getStageY(): Number returns the mouse cursor's horizontal Y position relative to the stage's origin.
    * public getWheelRotation(): Number returns the number of "clicks" the mouse wheel has rotated.
    * public getX(): Number returns the mouse cursor's horizontal X position relative to this node's origin.
    * public getY(): Number returns the mouse cursor's horizontal Y position relative to this node's origin.
    * public isAltDown(): Boolean returns true if the Alt modifier key is down.
    * public isControlDown(): Boolean returns true if the Control modifier key is down.
    * public isMetaDown(): Boolean returns true if the Meta modifier key is down.
    * public isPopupTrigger(): Boolean returns true if this mouse event is the popup menu trigger event for the platform. Because popup menus are triggered differently on different systems, isPopupTrigger() should be invoked in functions assigned to both of a node's onMousePressed and onMouseReleased attributes to ensure proper cross-platform behavior.
    * public isShiftDown(): Boolean returns true if the Shift modifier key is down.

Node also provides onKeyPressed, onKeyReleased, and onKeyTyped attributes for responding to key events. Each function assigned to one of these attributes requires a javafx.input.KeyEvent argument. This class provides the following functions for obtaining different kinds of event information:

    * public getKeyChar(): java.lang.String returns the character associated with this key event -- "A" returns when Shift and A are simultaneously pressed, for example.
    * public getKeyCode(): Integer returns the integer keycode associated with this key event.
    * public getKeyText(): java.lang.String returns a String describing the keycode (such as "HOME", "F1" or "A") for key-pressed and key-released events -- null returns for key-typed events.
    * public isAltDown(): Boolean returns true if the Alt modifier key is down.
    * public isControlDown(): Boolean returns true if the Control modifier key is down.
    * public isMetaDown(): Boolean returns true if the Meta modifier key is down.
    * public isShiftDown(): Boolean returns true if the Shift modifier key is down.

Keystrokes and input focus

A node cannot respond to keystrokes without having the input focus. You can provide that focus by invoking Node's requestFocus() function. When invoked, requestFocus() asks the runtime to give input focus to the invoking node, and to make the node's top-level ancestor the focused window.

Sky-Tiger

Adding keyboard support

One of the samples bundled with NetBeans IDE 6.1 with JavaFX is Transparency, whose GUI I revealed in the first article in this series. The Transparency sample demonstrates how to set an image's opacity so that background pixels are partly visible. This sample responds to mouse-moved events by moving the image horizontally in the direction of the mouse.

Let's extend this sample script to also support keyboard input. For example, we can modify the code to respond to key-pressed events. Whenever a left-arrow key is pressed, we'll move the image to the left. Similarly, when a right-arrow key is pressed, we'll move the image to the right. Listing 8 presents the relevant part of Transparency.fx, with the new code highlighted. (Note that I've removed the imports and copyright preamble from the revised Transparency.fx script below.)
Listing 8. Transparency.fx with keyboard support

var x : Number = 40;
   
var img : Image = Image { url : "{__DIR__}/../resources/overlay.png" };

Frame {
    stage : Stage {
        content : [
            ImageView {
                image : Image { url : "{__DIR__}/../resources/background.png" }
                onMouseMoved : function( e : MouseEvent ):Void {
                    x = e.getX() - 100 * 0.5;
                }
                onKeyPressed: function(e: javafx.input.KeyEvent):Void {
                    if (e.getKeyCode () == javafx.input.KeyCode.VK_LEFT)
                        x--
                    else
                    if (e.getKeyCode () == javafx.input.KeyCode.VK_RIGHT)
                        x++;
                }
            },
            ImageView {
                image : bind img
                transform : [ Translate { x : bind x, y : 100 - 32 }, Scale { x : 0.5, y : 0.5 } ]
                opacity : 0.5
            }
        ]
    }
   
    visible : true
    title : "Transparency"
    width : 200
    height : 232
    closeAction : function() { java.lang.System.exit( 0 ); }
}

The new (bolded and italicized) code assigns an anonymous function to the onKeyPressed attribute of the ImageView node (I discuss ImageView later). When a key is pressed, this function extracts the key's code via its KeyEvent argument's getkeyCode() function, and compares it with KeyCode virtual key codes for the left- and right-arrow keys. The image's location is updated when there's a match.

Given our understanding of Node, we can now begin to appreciate this class's children, starting with the Text subclass. We'll also learn how to work with the related Font class.

Sky-Tiger

Adding keyboard support

One of the samples bundled with NetBeans IDE 6.1 with JavaFX is Transparency, whose GUI I revealed in the first article in this series. The Transparency sample demonstrates how to set an image's opacity so that background pixels are partly visible. This sample responds to mouse-moved events by moving the image horizontally in the direction of the mouse.

Let's extend this sample script to also support keyboard input. For example, we can modify the code to respond to key-pressed events. Whenever a left-arrow key is pressed, we'll move the image to the left. Similarly, when a right-arrow key is pressed, we'll move the image to the right. Listing 8 presents the relevant part of Transparency.fx, with the new code highlighted. (Note that I've removed the imports and copyright preamble from the revised Transparency.fx script below.)
Listing 8. Transparency.fx with keyboard support

var x : Number = 40;
   
var img : Image = Image { url : "{__DIR__}/../resources/overlay.png" };

Frame {
    stage : Stage {
        content : [
            ImageView {
                image : Image { url : "{__DIR__}/../resources/background.png" }
                onMouseMoved : function( e : MouseEvent ):Void {
                    x = e.getX() - 100 * 0.5;
                }
                onKeyPressed: function(e: javafx.input.KeyEvent):Void {
                    if (e.getKeyCode () == javafx.input.KeyCode.VK_LEFT)
                        x--
                    else
                    if (e.getKeyCode () == javafx.input.KeyCode.VK_RIGHT)
                        x++;
                }
            },
            ImageView {
                image : bind img
                transform : [ Translate { x : bind x, y : 100 - 32 }, Scale { x : 0.5, y : 0.5 } ]
                opacity : 0.5
            }
        ]
    }
   
    visible : true
    title : "Transparency"
    width : 200
    height : 232
    closeAction : function() { java.lang.System.exit( 0 ); }
}

The new (bolded and italicized) code assigns an anonymous function to the onKeyPressed attribute of the ImageView node (I discuss ImageView later). When a key is pressed, this function extracts the key's code via its KeyEvent argument's getkeyCode() function, and compares it with KeyCode virtual key codes for the left- and right-arrow keys. The image's location is updated when there's a match.

Given our understanding of Node, we can now begin to appreciate this class's children, starting with the Text subclass. We'll also learn how to work with the related Font class.

Sky-Tiger

You'll notice that it's possible to introduce local variables into object literals. These variables are handy for referencing containing attributes and a class's functions. By convention, Ref is appended to each local variable name. Also, the bind keyword is required to access the stage's current dimensions, and to access Text's calculated x and y values.

Because Text subclasses Node, it inherits that class's opacity and rotation-oriented attributes that I previously listed when discussing the Node class. But where do the fill and stroke Paint attributes, which let you determine how the text's interior (fill) and outline (stroke) are painted, come from? Let's find out.