Is JViewport scrollRectToVisible API Javadoc ambigious or just plain wrong?

Question

I've been working on a JPanel derived class that demonstrates how to position the JViewport of a JScrollPane using JViewport's scrollRectToVisible method. I've got it working, but only after trial & error regarding the scrollRectToVisible's interpretation of the Rectangle input parameter.
The issue is that the JDK API javadocs gave me the impression that the Rectangle fields "x" and "y" would specify the (x,y) coordinates of the upper right corner in absolute client area coordinates. The impression resulted from past usage of Rectangles where the "x" and "y" fields were always absolute coordinates. But my trial & error revealed that the "x" and"y" fields in the Rectangle are interpreted by scrollRectToVisible as signed relative deltas within the client area, not absolute client area coordinates.
Here is the javadoc excerpt fom class JViewport: It does not really say how the Rectangle is interpreted...
public void scrollRectToVisible(Rectangle contentRect)+
Scrolls the view so that Rectangle within the view becomes visible.+
This attempts to validate the view before scrolling if the view is currently not valid - isValid returns false. To avoid excessive validation when the containment hierarchy is being created this will not validate if one of the ancestors does not have a peer, or there is no validate root ancestor, or one of the ancestors is not a Window or Applet.+
Note that this method will not scroll outside of the valid viewport; for example, if contentRect is larger than the viewport, scrolling will be confined to the viewport's bounds.+
It says the "*Scrolls the view so that Rectangle within the view becomes visible.*"
h3. *{color:#ff6600}How would you interpret this? Is this 'wrong by omission' or am I all wet?{color}*
Here is the relevant chunk of code that operates by creating a Rectangle with deltas, not absolute coordinates. It works. The whole class is too big for this forum post, but I can put the JAR file up for download if requested...
public class BigPanel extends JPanel implements MouseListener, MouseMotionListener {
     // Data defs and constructor omitted for brevity...
     private void scrollView() {
          SwingUtilities.invokeLater(new Runnable() {
               @Override
               public void run() {
                    //scrollRectToVisible(dxyRect); // WRONG, compiles OK, jumps around but mouse response is all wrong.
                    //scrollPane.scrollRectToVisible(dxyRect);  // WRONG, compiles OK, but does nothing!!!
                    scrollPane.getViewport().scrollRectToVisible(dxyRect);  // RIGHT!!!
     private void setDeltaXY(int mouseX, int mouseY) {
          // Use the base (x,y) coordinate of the view port rectangle
          // when calculating mouse coordinates (mx,my) relative to the
          // visible view port.
          Rectangle viewRect = scrollPane.getViewport().getViewRect();
          int mx = mouseX - viewRect.x;
          int my = mouseY - viewRect.y;
          // Use center of the view port rectangle as the point to subtract
          // from the mouse relative coordinate (mx,my) to calculate the
          // movement delta (dx,dy).
          int dx = mx - viewRect.width / 2;
          int dy = my - viewRect.height / 2;
          // Now create a rectangle with the delta (dx,dy) and the view port
          // (width,height) as the input to scrollRectToVisible.
          // Note that the (x,y) in the rectangle is not an absolute unsigned
          // (x,y) coordinate, but a signed relative delta (dx,dy),
          // which scrollRectToVisible uses to as the relative amount to shift.
          dxyRect = new Rectangle(dx, dy, viewRect.width, viewRect.height);
     private void moveView(MouseEvent e) {
          setDeltaXY(e.getX(), e.getY());
          scrollView();
     @Override
     public void mouseClicked(MouseEvent e) {
          info("mouseClicked");
          moveView(e);
     @Override
     public void mousePressed(final MouseEvent e) {
          info("mousePressed");
          setDeltaXY(e.getX(), e.getY());
          startRepeat();
     @Override
     public void mouseReleased(MouseEvent e) {
          info("mouseReleased");
          cancelRepeat();
     / *(non-Javadoc)*
@see java.awt.event.MouseMotionListener#mouseDragged(java.awt.event.MouseEvent)
     @Override
     public void mouseDragged(MouseEvent e) {
          setDeltaXY(e.getX(), e.getY());
}

Answer 1

I'm Barkin up the wrong tree, Huh?I think Darryl is right.
I tried it as you suggested, on the JScrollpane instance, not the JScrollpane's JViewport. The results were not what I expected of absolute or relative coordinate systems.You got it wrong, try calling scrollRectToVisible on the component being scrolled i.e. viewport view.
I have written a class which demonstrates working of scrollRectToVisible, that may help you:
import java.awt.*;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.swing.*;
* @author talha
@SuppressWarnings("serial")
public class ViewportExample extends JFrame {
     private JPanel scrolledPanel = new JPanel() {
          Dimension SIZE = new Dimension(1500, 1000);
          GradientPaint paint = new GradientPaint(0, 0, Color.WHITE, SIZE.width,
                    SIZE.height, Color.BLACK);
          protected void paintComponent(java.awt.Graphics g) {
               Graphics2D g2 = (Graphics2D) g;
               g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
                         RenderingHints.VALUE_ANTIALIAS_ON);
               g2.setPaint(paint);
               g2.fillRect(0, 0, getWidth(), getHeight());
               if (rect != null) {
                    g2.setPaint(new GradientPaint(rect.x, rect.y,
                                        Color.BLACK, rect.x + rect.width, rect.y
                                                  + rect.height, Color.WHITE));
                    g2.fill(rect);
                    g2.setColor(Color.WHITE);
                    g2.setStroke(new BasicStroke(2));
                    g2.draw(rect);
                    g2.drawString("You wanted this rectangle to be visible",
                              rect.x + 5, rect.y + 20);
                    g2.setColor(Color.BLACK);
                    g2.setStroke(new BasicStroke(1, BasicStroke.CAP_BUTT,
                              BasicStroke.JOIN_BEVEL, 3, new float[] { 3 }, 1.0f));
                    g2.drawLine(0, rect.y, rect.x, rect.y);
                    g2.drawLine(0, rect.y + rect.height, rect.x, rect.y
                              + rect.height);
                    g2.drawLine(rect.x, 0, rect.x, rect.y);
                    g2.drawLine(rect.x + rect.width, 0, rect.x + rect.width,
                                        rect.y);
          public Dimension getPreferredSize() {
               return SIZE;
     private Rectangle rect;
     private JComponent verticalRule = new JComponent() {
          protected void paintComponent(java.awt.Graphics g) {
               Rectangle clip = g.getClipBounds();
               Graphics2D g2 = (Graphics2D) g;
               g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
                         RenderingHints.VALUE_ANTIALIAS_ON);
               g2.setColor(Color.BLACK);
               g2.fill(clip);
               int start = clip.y / 100 * 100;
               int end = ((clip.y + clip.height) / 100 + 1) * 100;
               g2.setColor(Color.WHITE);
               for (int i = start; i < end; i += 100) {
                    g2.drawLine(20, i, 30, i);
                    g2.drawString(Integer.toString(i), 2, i + 15);
        private JComponent horizontalRule = new JComponent() {
          protected void paintComponent(java.awt.Graphics g) {
               Rectangle clip = g.getClipBounds();
               Graphics2D g2 = (Graphics2D) g;
               g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
                         RenderingHints.VALUE_ANTIALIAS_ON);
               g2.setColor(Color.BLACK);
               g2.fill(clip);
               int start = clip.x / 100 * 100;
               int end = ((clip.x + clip.width) / 100 + 1) * 100;
               g2.setColor(Color.WHITE);
               for (int i = start; i < end; i += 100) {
                    g2.drawLine(i, 20, i, 30);
                    g2.drawString(Integer.toString(i), i + 2, 25);
     public ViewportExample() {
          super("Viewport Example");
          setDefaultCloseOperation(EXIT_ON_CLOSE);
          JScrollPane pane = new JScrollPane(scrolledPanel);
          verticalRule.setPreferredSize(new Dimension(30, 1000));
          pane.setRowHeaderView(verticalRule);
          horizontalRule.setPreferredSize(new Dimension(1500, 30));
          pane.setColumnHeaderView(horizontalRule);
          pane.setBackground(Color.DARK_GRAY);
          add(pane, BorderLayout.CENTER);
          add(getSouthPanel(), BorderLayout.SOUTH);
          setSize(700, 600);
          // setExtendedState(MAXIMIZED_BOTH);
          setLocationRelativeTo(null);
     private JPanel getSouthPanel() {
          JPanel panel = new JPanel();
          final JTextField field = new JTextField(30);
          field.addActionListener(new ActionListener() {
               Pattern pattern = Pattern
                         .compile("\\s*((?:-)?\\d+)\\s+((?:-)?\\d+)\\s+(\\d+)\\s+(\\d+)\\s*");
               @Override
               public void actionPerformed(ActionEvent e) {
                    Matcher matcher = pattern.matcher(field.getText());
                    if (matcher.matches()) {
                         rect = new Rectangle(Integer.parseInt(matcher.group(1)),
                                   Integer.parseInt(matcher.group(2)), Integer
                                             .parseInt(matcher.group(3)), Integer
                                             .parseInt(matcher.group(4)));
                         //-- mark this --
                         scrolledPanel.scrollRectToVisible(rect);
                         scrolledPanel.repaint();
                    } else {
                         Toolkit.getDefaultToolkit().beep();
          panel.add(new JLabel("Rectangle: (Formatted as : x y width height) "));
          panel.add(field);
          return panel;
     public static void main(String... args) {
          SwingUtilities.invokeLater(new Runnable() {
               @Override
               public void run() {
                    new ViewportExample().setVisible(true);
} This code has many irrelevant things but I added them just to learn new things, but they help in making overall application more usable. Have fun :)
Try typing "300 400 400 300" in the text field, hit Enter and see the result. Try out other values...
Thanks!