JavaFX Technical Article | Make JavaFX Browser Applets Draggable -- or Not

Make JavaFX Browser Applets Draggable — or Not

Skill Level Intermediate
Product JavaFX
Key Features Draggable Applets, Deployment
Last Updated August 2009

Learn how to configure browser applets to allow or disallow dragging behavior outside the browser, and how to customize your application to take advantage of this dragging behavior.

When you deploy a browser applet, you must decide whether the applet will be draggable to the desktop. This draggable feature is available on platforms running Java SE Version 6 update 10 at minimum. By default, the NetBeans IDE enables dragging when it builds the application, which will enable the applet to be dragged out of the browser by holding down the Alt key and dragging.

This article shows how to make a browser applet draggable or not, and, if it is draggable, how to customize the dragging behavior in the following ways:

Create a custom window title message that can be viewed only by users in the correct dragging environment.
Enable dragging without holding down the Alt key.
Changing the look and feel of the application after it is dragged.

If you do not want to plan the behavior of dragged applets, it is a good idea to configure the browser applet so it cannot be dragged.

What a Dragged Applet Looks Like

On systems running Java SE Version 6 update 10 at minimum, viewers can drag the applet out of the browser to the desktop and click a Close button to return it to the browser. Figure 1 shows an applet that was dragged out of the browser. The Close button appears at the upper right.

ShouldDrag Applet Screenshot Figure 1: ShouldDrag Applet Running Outside the Browser

Configure the Applet to be Draggable or Not

Applets can only be dragged when the draggable configuration parameter is set to true in the JavaScript code embedded in the HTML page.

If you are using the NetBeans IDE to generate the application package, the Draggable Applet checkbox in the Application pane of the Project Properties dialog box is selected by default. When you build the application in the NetBeans IDE, the draggable: true parameter is generated in the HTML file and included when you copy the JavaScript code to your own HTML page.

If you create the script for the HTML page by some other method, add the draggable: true parameter to the script, as in the following example for the applet displayed on this page.

Source Code: Script to Call Applet From HTML Page

<script src="http://dl.javafx.com/1.2/dtfx.js"></script>
<script>
    javafx(
        {
              archive: "dist/ShouldDrag.jar",
              draggable: true,
              width: 240,
              height: 270,
              code: "shoulddrag.Main",
              name: "ShouldDrag"
        }
    );
</script>

If you do not want your application to be draggable, do one of the following:

In the NetBeans IDE, clear the Draggable Applet checkbox in the Application pane of the Project Properties dialog box.
Change the draggable parameter from true to false in the markup in your HTML page, or add the line draggable: false with a comma at the end.

Create a Draggable Window Title Bar

An applet that is configured to be draggable can be dragged by holding down the Alt key while dragging with the mouse, but your application should enable users to drag the applet without using the Alt key. The following applet shows a draggable window title bar, containing a message that is visible only to users who have versions of Java software installed that enable draggable applets.

Figure 2 shows the applet text that is displayed only to users who can make use of it. If the text in the orange oval appears when the cursor hovers over the window title bar, users can click anywhere in the black rectangle and drag the applet out of the browser.

ShouldDrag Applet Screenshot Figure 2: ShouldDrag Applet With Mouseover Text

Macintosh users, and users whose version of Java software does not support dragging, see all of the applet except the mouseover text.

The application takes the following actions:

Checks whether applet dragging is supported by the user's version of Java
Defines a black window title bar that becomes the draggable area
Adds mouseover text inside the window title bar that is visible only if the applet is draggable
Provides the logic to move the stage when the applet is dragged

The following application source code has highlighted text that maps to these actions.

Source Code: Custom Window Title Message

package shoulddrag;

import javafx.scene.input.MouseEvent;
import javafx.scene.paint.Color;
import javafx.scene.paint.LinearGradient;
import javafx.scene.paint.Stop;
import javafx.scene.Scene;
import javafx.scene.shape.Circle;
import javafx.scene.shape.Rectangle;
import javafx.scene.text.Font;
import javafx.scene.text.Text;
import javafx.scene.text.TextAlignment;
import javafx.stage.AppletStageExtension;
import javafx.stage.Stage;
import javafx.stage.StageStyle;


var inbrowser = true;

//The Following variable is true if browser and Java configuration support applet dragging.
var draggable = AppletStageExtension.appletDragSupported;

// Rectangle for the window title bar
var dragRect: Rectangle;
dragRect = Rectangle {  //define draggable region
    x: 0
    y: 0
    width: 240
    height: 30
    fill: LinearGradient {
        startX: 0.0
        startY: 0.0
        endX: 0.0
        endY: 1.0
        stops: [
            Stop {
                color: Color.BLACK
                offset: 0.0
            },
            Stop {
                color: Color.LIGHTSLATEGRAY
                offset: 0.3
            },
            Stop {
                color: Color.BLACK
                offset: 1.0
            },

        ]
    }
    /* The following code implements the standard dragging behavior after
    the applet has moved outside of the browser.
    */
    onMouseDragged: function(e:MouseEvent):Void {
        stage.x += e.dragX;
        stage.y += e.dragY;
    }

};

/* The following variable makes the window title message visible if the following
two conditions are true:
- applet dragging is supported by platform and Java version;
- the cursor is hovering over the draggable area;
*/

var dragTextVisible = bind draggable and dragRect.hover;

//Text for window title bar
var can_drag_me_text: Text = Text {
    content: bind if(inbrowser) {
        "Drag this bar out of the browser!"
        }
        else {
        "Click 'x' to return me to the browser"
        }
    fill: Color.WHITE
    underline: bind if (inbrowser) false else true
    font: Font {
    size: 12
//        embolden: true
        name: "Arial Bold"
    }
      visible: bind dragTextVisible
    x: 18
    y: 18
};

var stage = Stage {
    title: "A Draggable Applet"
    width: 240
    height: 270
    style: StageStyle.TRANSPARENT

    scene: Scene {
       fill: LinearGradient {
            startX: 0.0
            startY: 0.0
            endX: 1.0
            endY: 1.0
            stops: [
              Stop {
                  color: Color.POWDERBLUE
                  offset: 0.0
                  },
                  Stop {
                      color: Color.DARKSLATEGRAY
                      offset: 1.0
                      },
                      ]
        }


        content: [
                Circle {
            centerX: 120, centerY: 150
            radius: 120
            fill: bind if (inbrowser) Color.WHITE else Color.MIDNIGHTBLUE
            opacity: bind if (inbrowser) 0.85 else 0.30
        }

                Text {
                     content: bind if (inbrowser) {
                           "Qualified users see text \n "
                              "in the top bar when \n "
                              "they mouse over it. \n "
                              "They can drag the applet \n"
                              "out of the window."
                              }
                              else { "I'm free!" }

                     textAlignment: TextAlignment.CENTER
                     fill: bind if (inbrowser) Color.DARKSLATEGRAY else Color.WHITE
                         font: bind if (inbrowser) {
                           Font {
                             size: 14
                             embolden: true
                             name: "Arial"
                             }
                             }
                             else {
                                 Font {
                                size: 48
                             embolden: true
                             name: "Arial"
                             }
                           }

                        x: 30
                        y: bind if (inbrowser) 120 else 170
                 }
            dragRect,
            can_drag_me_text

        ]
    }
    extensions: [
        AppletStageExtension {
            //define mouse state if cursor is in draggable region
            shouldDragStart: function(e): Boolean {
                return e.primaryButtonDown and dragRect.hover;
            }
            //set variable to indicate when applet is out of the browser
            onDragFinished: function(): Void  {
                inbrowser=false;
            }
            //set variable to indicate when applet is in the browser
            onAppletRestored: function(): Void  {
                inbrowser=true;
            }

            useDefaultClose: true
        }
    ]

}

The AppletStageExtension class is an essential element for draggable applets. Its appletDragSupported variable returns a value of true if the browser and Java configuration support applet dragging.

The rectangle for the window title bar, assigned to the dragRect variable, contains logic that implements the standard dragging behavior after the applet has moved outside of the browser. Note that you do not need to make this dragging logic conditional for supported Java versions programmatically, because other runtimes do not have access to this functionality.

The dragTextVisible variable obtains its value from two other variables, which store information about whether the applet is draggable and whether the cursor is hovering over the draggable area. Both conditions must be true for dragTextVisible to be true. This variable is then bound to the visible attribute in the Text instance to determine whether the text is displayed.

The shouldDragStart variable of the AppletStageExtension class is a function. It is called by the browser at the start of a mouse event that might cause a drag out of the browser. The variable also returns the conditions under which dragging can occur, namely the primary mouse button being held down and the mouse cursor hovering over the draggable area.

Change the Look and Feel of the Dragged Application

In the source code in the last section, the AppletStageExtension class instance includes two functions that apply when the browser determines whether the applet has been dragged (onDragFinished) or has been returned to the browser (onAppletRestored). When these functions are called, a Boolean variable named inbrowser is set to true or false. This variable is then used in several places in the application to change the display after the applet is dragged, as shown in Figure 3.

ShouldDrag Applet Screenshot Figure 3: Dragged Applet After Changing Look and Feel

The text in the window title bar changes from "Drag this bar out of the browser!" to "Click 'x' to return me to the browser." The message inside the circle changes to "I'm free!" when the circle is dragged, and the text color, size, and position change also. Search the source code for the inbrowser variable to see all the places in the code in which this variable is utilized to change the look and feel of the dragged applet.

Try It

Here are some variations that you can try, to increase your understanding of the application.

Use the inbrowser variable to customize the look and feel of the dragged applet in other ways.
Make the draggable region the circle instead of the top bar.

FX