ScrollPane - JavaFX

ScrollPane

Sometimes, the contents of a control will exceed the amount of screen space that you want to give to it. Here are two examples: A large image may not fit within reasonable boundaries, or you might want to display text that is longer than will fit within a small window. Whatever the reason, JavaFX makes it easy to provide scrolling capabilities to any node in a scene graph. This is accomplished by wrapping the node in a ScrollPane. When a ScrollPane is used, scrollbars are automatically implemented that scroll the contents of the wrapped node. No further action is required on your part. Because of the versatility of ScrollPane, you will seldom need to use individual scrollbar controls.

ScrollPane defines two constructors. The first is the default constructor. The second lets you specify a node that you want to scroll. It is shown here:

ScrollPane(Node content)

In this case, content specifies the information to be scrolled. When using the default constructor, you will add the node to be scrolled by calling setContent( ). It is shown here:

final void setContent(Node content)

After you have set the content, add the scroll pane to the scene graph. When displayed, the content can be scrolled.

Although a default size is provided, as a general rule, you will want to set the dimensions of the viewport. The viewport is the viewable area of a scroll pane. It is the area in which the content being scrolled is displayed. Thus, the viewport displays the visible portion of the content. The scrollbars scroll the content through the viewport. Thus, by moving a scrollbar, you change what part of the content is visible.

You can set the viewport dimensions by using these two methods: final void setPrefViewportHeight(double height)

final void setPrefViewportWidth(double width)

In its default behavior, a ScrollPane will dynamically add or remove a scrollbar as needed. For example, if the component is taller than the viewport, a vertical scrollbar is added. If the component will completely fit within the viewport, the scrollbars are removed.

One nice feature of ScrollPane is its ability to pan the contents by dragging the mouse. By default, this feature is off. To turn it on, use setPannable( ), shown here:

final void setPannable(boolean enable)

If enable is true, then panning is allowed. Otherwise, it is disabled.

You can set the position of the scrollbars under program control using setHvalue( ) and setVvalue( ), shown here:

final void setHvalue(double newHval) final void setVvalue(double newVval)

The new horizontal position is specified by newHval, and the new vertical position is specified by newVval. Be default, scrollbar positions start at zero.

ScrollPane supports various other options. For example, it is possible to set the minimum and maximum scrollbar positions. You can also specify when and if the scrollbars are shown by setting a scrollbar policy. The current position of the scrollbars can be obtained by calling getHvalue( ) and getVvalue( ).

The following program demonstrates ScrollPane by using one to scroll the contents of a multiline label. Notice that it also enables panning.

     //Demonstrate a scroll pane.

     //This program scrolls the contents of a multiline

     //label, but any node can be scrolled.

import javafx.application.*; import javafx.scene.*; import javafx.stage.*; import javafx.scene.layout.*; import javafx.scene.control.*; import javafx.event.*;

import javafx.geometry.*;

public class ScrollPaneDemo extends Application {

ScrollPane scrlPane;

public static void main(String[] args) {

// Start the JavaFX application by calling launch().

launch(args);

}

// Override the start() method.

public void start(Stage myStage) {

     //Give the stage a title.

     myStage.setTitle("Demonstrate a ScrollPane");

     //Use a FlowPane for the root node.

     FlowPane rootNode = new FlowPane(10, 10);

     //Center the controls in the scene.

     rootNode.setAlignment(Pos.CENTER);

     //Create a scene.

Scene myScene = new Scene(rootNode, 200, 200);

     //Set the scene on the stage.

     myStage.setScene(myScene);

     //Create a label that will be scrolled.

     Label scrlLabel = new Label(

"A ScrollPane streamlines the process of\n" +

"adding scroll bars to a window whose\n" + "contents exceed the window's dimensions.\n" + "It also enables a control to fit in a\n" + "smaller space than it otherwise would.\n" + "As such, it often provides a superior\n" + "approach over using individual scroll bars.");

     //Create a scroll pane, setting scrlLabel as the content.

     scrlPane = new ScrollPane(scrlLabel);

     Set the viewport width and height.

     scrlPane.setPrefViewportWidth(130); scrlPane.setPrefViewportHeight(80);

     //Enable panning.

scrlPane.setPannable(true);

// Create a reset label.

Button btnReset = new Button("Reset Scroll Bar Positions");

// Handle action events for the reset button.

btnReset.setOnAction(new EventHandler<ActionEvent>() {

public void handle(ActionEvent ae) {

// Set the scroll bars to their zero position.

scrlPane.setVvalue(0);

scrlPane.setHvalue(0);

}

});

     Add the label to the scene graph.

     rootNode.getChildren().addAll(scrlPane, btnReset);

     //Show the stage and its scene.

myStage.show();

}

}

Sample output is shown here: