libjava/java/awt/ScrollPane.java

   1 /* ScrollPane.java -- Scrolling window
   2    Copyright (C) 1999, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import java.awt.event.MouseEvent;
  42 import java.awt.peer.ComponentPeer;
  43 import java.awt.peer.ScrollPanePeer;
  44 import javax.accessibility.Accessible;
  45
  46 /**
  47   * This widget provides a scrollable region that allows a single
  48   * subcomponent to be viewed through a smaller window.
  49   *
  50   * @author Aaron M. Renn (arenn@urbanophile.com)
  51   */
  52 public class ScrollPane extends Container implements Accessible
  53 {
  54
  55 /*
  56  * Static Variables
  57  */
  58
  59 /**
  60   * Constant indicating that scrollbars are created as needed in this
  61   * windows.
  62   */
  63 public static final int SCROLLBARS_AS_NEEDED = 0;
  64
  65 /**
  66   * Constant indicating that scrollbars are always displayed in this
  67   * window.
  68   */
  69 public static final int SCROLLBARS_ALWAYS = 1;
  70
  71 /**
  72   * Constant indicating that scrollbars are never displayed in this window.
  73   */
  74 public static final int SCROLLBARS_NEVER = 2;
  75
  76 // Serialization constant
  77 private static final long serialVersionUID = 7956609840827222915L;
  78
  79 /*************************************************************************/
  80
  81 /*
  82  * Instance Variables
  83  */
  84
  85 /**
  86   * @serial The horizontal scrollbar for this window.  The methods
  87   * <code>setMinimum()</code>, <code>setMaximum</code>, and
  88   * <code>setVisibleAmount</code> must not be called on this scrollbar.
  89   */
  90 private ScrollPaneAdjustable hAdjustable;
  91
  92 /**
  93   * @serial The vertical scrollbar for this window.  The methods
  94   * <code>setMinimum()</code>, <code>setMaximum</code>, and
  95   * <code>setVisibleAmount</code> must not be called on this scrollbar.
  96   */
  97 private ScrollPaneAdjustable vAdjustable;
  98
  99 /**
 100   * @serial Indicates when scrollbars are displayed in this window, will
 101   * be one of the constants from this class.
 102   */
 103 private int scrollbarDisplayPolicy;
 104
 105 // Current scroll position
 106 private Point scrollPosition = new Point(0, 0);
 107
 108 private boolean wheelScrollingEnabled;
 109
 110 /*************************************************************************/
 111
 112 /*
 113  * Constructors
 114  */
 115
 116 /**
 117   * Initializes a new instance of <code>ScrollPane</code> with a default
 118   * scrollbar policy of <code>SCROLLBARS_AS_NEEDED</code>.
 119   *
 120   * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 121   */
 122 public
 123 ScrollPane()
 124 {
 125   this(SCROLLBARS_AS_NEEDED);
 126 }
 127
 128 /*************************************************************************/
 129
 130 /**
 131   * Initializes a new instance of <code>ScrollPane</code> with the
 132   * specified scrollbar policy.
 133   *
 134   * @param scrollbarDisplayPolicy When to display scrollbars, which must
 135   * be one of the constants defined in this class.
 136   *
 137   * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 138   */
 139 public
 140 ScrollPane(int scrollbarDisplayPolicy)
 141 {
 142   if (GraphicsEnvironment.isHeadless ())
 143     throw new HeadlessException ();
 144
 145   this.scrollbarDisplayPolicy = scrollbarDisplayPolicy;
 146
 147   if (scrollbarDisplayPolicy != SCROLLBARS_ALWAYS
 148       && scrollbarDisplayPolicy != SCROLLBARS_AS_NEEDED
 149       && scrollbarDisplayPolicy != SCROLLBARS_NEVER)
 150     throw new IllegalArgumentException("Bad scrollbarDisplayPolicy: " +
 151                                        scrollbarDisplayPolicy);
 152
 153   if (scrollbarDisplayPolicy != SCROLLBARS_NEVER)
 154     {
 155       hAdjustable = new ScrollPaneAdjustable (this, Scrollbar.HORIZONTAL);
 156       vAdjustable = new ScrollPaneAdjustable (this, Scrollbar.VERTICAL);
 157     }
 158
 159   wheelScrollingEnabled = true;
 160 }
 161
 162 /*************************************************************************/
 163
 164 /*
 165  * Instance Variables
 166  */
 167
 168 /**
 169   * Returns the current scrollbar display policy.
 170   *
 171   * @return The current scrollbar display policy.
 172   */
 173 public int
 174 getScrollbarDisplayPolicy()
 175 {
 176   return(scrollbarDisplayPolicy);
 177 }
 178
 179 /*************************************************************************/
 180
 181 /**
 182   * Returns the horizontal scrollbar for this object.  If the scrollbar
 183   * display policy is set to <code>SCROLLBARS_NEVER</code> then this
 184   * will be <code>null</code>.
 185   *
 186   * @return The horizontal scrollbar for this window.
 187   */
 188 public Adjustable
 189 getHAdjustable()
 190 {
 191   return(hAdjustable);
 192 }
 193
 194 /*************************************************************************/
 195
 196 /**
 197   * Returns the vertical scrollbar for this object.  If the scrollbar
 198   * display policy is set to <code>SCROLLBARS_NEVER</code> then this
 199   * will be <code>null</code>.
 200   *
 201   * @return The horizontal scrollbar for this window.
 202   */
 203 public Adjustable
 204 getVAdjustable()
 205 {
 206   return(vAdjustable);
 207 }
 208
 209 /*************************************************************************/
 210
 211 /**
 212   * Returns the current viewport size.  The viewport is the region of
 213   * this object's window where the child is actually displayed.
 214   *
 215   * @return The viewport size.
 216   */
 217 public Dimension getViewportSize ()
 218 {
 219   Dimension viewsize = getSize ();
 220   Insets insets = getInsets ();
 221   viewsize.width = (viewsize.width
 222                     - (insets.left + insets.right)
 223                     - getVScrollbarWidth ());
 224   viewsize.height = (viewsize.height
 225                      - (insets.top + insets.bottom)
 226                      - getHScrollbarHeight ());
 227   return viewsize;
 228 }
 229
 230 /*************************************************************************/
 231
 232 /**
 233   * Returns the height of a horizontal scrollbar.
 234   *
 235   * @return The height of a horizontal scrollbar.
 236   */
 237 public int
 238 getHScrollbarHeight()
 239 {
 240   ScrollPanePeer spp = (ScrollPanePeer)getPeer();
 241   if (spp != null)
 242     return(spp.getHScrollbarHeight());
 243   else
 244     return(0); // FIXME: What to do here?
 245 }
 246
 247 /*************************************************************************/
 248
 249 /**
 250   * Returns the width of a vertical scrollbar.
 251   *
 252   * @return The width of a vertical scrollbar.
 253   */
 254 public int
 255 getVScrollbarWidth()
 256 {
 257   ScrollPanePeer spp = (ScrollPanePeer)getPeer();
 258   if (spp != null)
 259     return(spp.getVScrollbarWidth());
 260   else
 261     return(0); // FIXME: What to do here?
 262 }
 263
 264 /*************************************************************************/
 265
 266 /**
 267   * Returns the current scroll position of the viewport.
 268   *
 269   * @return The current scroll position of the viewport.
 270   */
 271 public Point
 272 getScrollPosition()
 273 {
 274   int x = 0;
 275   int y = 0;
 276
 277   Adjustable v = getVAdjustable();
 278   Adjustable h = getHAdjustable();
 279
 280   if (v != null)
 281     y = v.getValue();
 282   if (h != null)
 283     x = h.getValue();
 284
 285   return(new Point(x, y));
 286 }
 287
 288 /*************************************************************************/
 289
 290 /**
 291   * Sets the scroll position to the specified value.
 292   *
 293   * @param scrollPosition The new scrollPosition.
 294   *
 295   * @exception IllegalArgumentException If the specified value is outside
 296   * the legal scrolling range.
 297   */
 298 public void
 299 setScrollPosition(Point scrollPosition) throws IllegalArgumentException
 300 {
 301   setScrollPosition(scrollPosition.x, scrollPosition.y);
 302 }
 303
 304 /*************************************************************************/
 305
 306 /**
 307   * Sets the scroll position to the specified value.
 308   *
 309   * @param x The new X coordinate of the scroll position.
 310   * @param y The new Y coordinate of the scroll position.
 311   *
 312   * @exception IllegalArgumentException If the specified value is outside
 313   * the legal scrolling range.
 314   */
 315 public void
 316 setScrollPosition(int x, int y)
 317 {
 318   Adjustable h = getHAdjustable();
 319   Adjustable v = getVAdjustable();
 320
 321   if (h != null)
 322     h.setValue(x);
 323   if (v != null)
 324     v.setValue(y);
 325
 326   ScrollPanePeer spp = (ScrollPanePeer)getPeer();
 327   if (spp != null)
 328     spp.setScrollPosition(x, y);
 329 }
 330
 331 /*************************************************************************/
 332
 333 /**
 334   * Notifies this object that it should create its native peer.
 335   */
 336 public void
 337 addNotify()
 338 {
 339   if (!isDisplayable ())
 340     return;
 341
 342   setPeer((ComponentPeer)getToolkit().createScrollPane(this));
 343   super.addNotify();
 344 }
 345
 346 /*************************************************************************/
 347
 348 /**
 349   * Notifies this object that it should destroy its native peers.
 350   */
 351 public void
 352 removeNotify()
 353 {
 354   super.removeNotify();
 355 }
 356
 357 /*************************************************************************/
 358
 359 /**
 360   * Adds the specified child component to this container.  A
 361   * <code>ScrollPane</code> can have at most one child, so if a second
 362   * one is added, then first one is removed.
 363   *
 364   * @param component The component to add to this container.
 365   * @param constraints A list of layout constraints for this object.
 366   * @param index The index at which to add the child, which is ignored
 367   * in this implementation.
 368   */
 369   protected final void addImpl (Component component, Object constraints,
 370                                 int index)
 371 {
 372   Component[] list = getComponents();
 373   if ((list != null) && (list.length > 0))
 374     remove(list[0]);
 375
 376   super.addImpl(component, constraints, -1);
 377
 378   doLayout();
 379 }
 380
 381 /*************************************************************************/
 382
 383 /**
 384   * Lays out this component.  This consists of resizing the sole child
 385   * component to its perferred size.
 386   */
 387 public void
 388 doLayout()
 389 {
 390   Component[] list = getComponents();
 391   if ((list != null) && (list.length > 0))
 392     {
 393       Dimension dim = list[0].getPreferredSize();
 394       list[0].resize(dim);
 395
 396       Point p = getScrollPosition();
 397       if (p.x > dim.width)
 398         p.x = dim.width;
 399       if (p.y > dim.height)
 400         p.y = dim.height;
 401
 402       setScrollPosition(p);
 403     }
 404 }
 405
 406 /*************************************************************************/
 407
 408 /**
 409   * Lays out this component.  This consists of resizing the sole child
 410   * component to its perferred size.
 411   *
 412   * @deprecated This method is deprecated in favor of
 413   * <code>doLayout()</code>.
 414   */
 415 public void
 416 layout()
 417 {
 418   doLayout();
 419 }
 420
 421 /*************************************************************************/
 422
 423 /**
 424   * This method overrides its superclass method to ensure no layout
 425   * manager is set for this container.  <code>ScrollPane</code>'s do
 426   * not have layout managers.
 427   *
 428   * @param layoutManager Ignored
 429   */
 430 public final void
 431 setLayout(LayoutManager layoutManager)
 432 {
 433   return;
 434 }
 435
 436 /*************************************************************************/
 437
 438 /**
 439   * Prints all of the components in this container.
 440   *
 441   * @param graphics The desired graphics context for printing.
 442   */
 443 public void
 444 printComponents(Graphics graphics)
 445 {
 446   super.printComponents(graphics);
 447 }
 448
 449 /*************************************************************************/
 450
 451 /**
 452   * Returns a debug string for this object.
 453   *
 454   * @return A debug string for this object.
 455   */
 456 public String
 457 paramString()
 458 {
 459   return(getClass().getName());
 460 }
 461
 462   /**
 463    * Tells whether or not an event is enabled.
 464    *
 465    * @since 1.4
 466    */
 467   protected boolean eventTypeEnabled (int type)
 468   {
 469     if (type == MouseEvent.MOUSE_WHEEL)
 470       return wheelScrollingEnabled;
 471
 472     return super.eventTypeEnabled (type);
 473   }
 474
 475   /**
 476    * Tells whether or not wheel scrolling is enabled.
 477    *
 478    * @since 1.4
 479    */
 480   public boolean isWheelScrollingEnabled ()
 481   {
 482     return wheelScrollingEnabled;
 483   }
 484
 485   /**
 486    * Enables/disables wheel scrolling.
 487    *
 488    * @since 1.4
 489    */
 490   public void setWheelScrollingEnabled (boolean enable)
 491   {
 492     wheelScrollingEnabled = enable;
 493   }
 494 } // class ScrollPane
 495