java.awt
Class ScrollPane

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.ScrollPane
public class ScrollPane
extends Container

A container class which implements automatic horizontal and/or vertical scrolling for a single child component. The display policy for the scrollbars can be set to:

  1. as needed: scrollbars created and shown only when needed by scrollpane
  2. always: scrollbars created and always shown by the scrollpane
  3. never: scrollbars never created or shown by the scrollpane

The state of the horizontal and vertical scrollbars is represented by two objects (one for each dimension) which implement the Adjustable interface. The API provides methods to access those objects such that the attributes on the Adjustable object (such as unitIncrement, value, etc.) can be manipulated.

Certain adjustable properties (minimum, maximum, blockIncrement, and visibleAmount) are set internally by the scrollpane in accordance with the geometry of the scrollpane and its child and these should not be set by programs using the scrollpane.

If the scrollbar display policy is defined as "never", then the scrollpane can still be programmatically scrolled using the setScrollPosition() method and the scrollpane will move and clip the child's contents appropriately. This policy is useful if the program needs to create and manage its own adjustable controls.

The placement of the scrollbars is controlled by platform-specific properties set by the user outside of the program.

The initial size of this container is set to 100x100, but can be reset using setSize().

Insets are used to define any space used by scrollbars and any borders created by the scroll pane. getInsets() can be used to get the current value for the insets. If the value of scrollbarsAlwaysVisible is false, then the value of the insets will change dynamically depending on whether the scrollbars are currently visible or not.

See Also:
Serialized Form

Inner Class Summary
(package private)  class ScrollPane.PeerFixer
           
 
Inner classes inherited from class java.awt.Component
Component.AWTTreeLock, Component.NativeInLightFixer
 
Field Summary
private static String base
           
private  ScrollPaneAdjustable hAdjustable
          An adjustable Horizontal Scrollbar.
private static int nameCounter
           
private  int scrollbarDisplayPolicy
          There are 3 ways in which a scroll bar can be displayed.
static int SCROLLBARS_ALWAYS
          Specifies that horizontal/vertical scrollbars should always be shown regardless of the respective sizes of the scrollpane and child.
static int SCROLLBARS_AS_NEEDED
          Specifies that horizontal/vertical scrollbar should be shown only when the size of the child exceeds the size of the scrollpane in the horizontal/vertical dimension.
static int SCROLLBARS_NEVER
          Specifies that horizontal/vertical scrollbars should never be shown regardless of the respective sizes of the scrollpane and child.
private static long serialVersionUID
           
private  ScrollPaneAdjustable vAdjustable
          An adjustable Vertical Scrollbar.
 
Fields inherited from class java.awt.Container
component, containerListener, containerSerializedDataVersion, dispatcher, layoutMgr, maxSize, ncomponents, serialVersionUID
 
Fields inherited from class java.awt.Component
actionListenerK, adjustmentListenerK, appContext, assert, background, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, changeSupport, componentListener, componentListenerK, componentOrientation, componentSerializedDataVersion, containerListenerK, cursor, dropTarget, enabled, eventMask, focusListener, focusListenerK, font, foreground, hasFocus, height, incRate, inputMethodListener, inputMethodListenerK, isInc, isPacked, itemListenerK, keyListener, keyListenerK, LEFT_ALIGNMENT, locale, LOCK, minSize, mouseListener, mouseListenerK, mouseMotionListener, mouseMotionListenerK, name, nameExplicitlySet, newEventsOnly, ownedWindowK, parent, peer, peerFont, popups, prefSize, RIGHT_ALIGNMENT, serialVersionUID, textListenerK, TOP_ALIGNMENT, valid, visible, width, windowListenerK, x, y
 
Constructor Summary
ScrollPane()
          Create a new scrollpane container with a scrollbar display policy of "as needed".
ScrollPane(int scrollbarDisplayPolicy)
          Create a new scrollpane container.
 
Method Summary
(package private) static void ()
           
protected  void addImpl(Component comp, Object constraints, int index)
          Adds the specified component to this scroll pane container.
 void addNotify()
          Creates the scroll pane's peer.
(package private)  Dimension calculateChildSize()
          Determine the size to allocate the child component.
(package private)  String constructComponentName()
          Construct a name for this component.
 void doLayout()
          Lays out this container by resizing its child to its preferred size.
 Adjustable getHAdjustable()
          Returns the Adjustable object which represents the state of the horizontal scrollbar.
 int getHScrollbarHeight()
          Returns the height that would be occupied by a horizontal scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
 int getScrollbarDisplayPolicy()
          Returns the display policy for the scrollbars.
 Point getScrollPosition()
          Returns the current x,y position within the child which is displayed at the 0,0 location of the scrolled panel's view port.
 Adjustable getVAdjustable()
          Returns the Adjustable object which represents the state of the vertical scrollbar.
 Dimension getViewportSize()
          Returns the current size of the scroll pane's view port.
 int getVScrollbarWidth()
          Returns the width that would be occupied by a vertical scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
private static void initIDs()
          Initialize JNI field and method IDs
 void layout()
          Deprecated. As of JDK version 1.1, replaced by doLayout().
 String paramString()
           
 void printComponents(Graphics g)
          Prints the component in this scroll pane.
 void setLayout(LayoutManager mgr)
          Sets the layout manager for this container.
 void setScrollPosition(int x, int y)
          Scrolls to the specified position within the child component.
 void setScrollPosition(Point p)
          Scrolls to the specified position within the child component.
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyOrientation, countComponents, deliverEvent, dispatchEventImpl, dispatchEventToSelf, eventEnabled, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents_NoClientCode, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getMouseEventTarget, getPreferredSize, getWindow, insets, invalidate, invalidateTree, isAncestorOf, lightweightPrint, list, list, locate, minimumSize, nextFocus, paint, paintComponents, postProcessKeyEvent, postsOldMouseEvents, preferredSize, preProcessKeyEvent, print, printOneComponent, processContainerEvent, processEvent, proxyEnableEvents, proxyRequestFocus, readObject, remove, remove, removeAll, removeContainerListener, removeNotify, setFocusOwner, setFont, transferFocus, update, validate, validateTree, writeObject
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, areInputMethodsEnabled, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont_NoClientCode, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getName, getNativeContainer, getParent_NoClientCode, getParent, getPeer, getSize, getSize, getToolkit, getToolkitImpl, getTreeLock, getWidth, getWindowForObject, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isEnabledImpl, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait
 

Field Detail

SCROLLBARS_AS_NEEDED

public static final int SCROLLBARS_AS_NEEDED
Specifies that horizontal/vertical scrollbar should be shown only when the size of the child exceeds the size of the scrollpane in the horizontal/vertical dimension.

SCROLLBARS_ALWAYS

public static final int SCROLLBARS_ALWAYS
Specifies that horizontal/vertical scrollbars should always be shown regardless of the respective sizes of the scrollpane and child.

SCROLLBARS_NEVER

public static final int SCROLLBARS_NEVER
Specifies that horizontal/vertical scrollbars should never be shown regardless of the respective sizes of the scrollpane and child.

scrollbarDisplayPolicy

private int scrollbarDisplayPolicy
There are 3 ways in which a scroll bar can be displayed. This integer will represent one of these 3 displays - (SCROLLBARS_ALWAYS, SCROLLBARS_AS_NEEDED, SCROLLBARS_NEVER)
See Also:
getScrollbarDisplayPolicy()

vAdjustable

private ScrollPaneAdjustable vAdjustable
An adjustable Vertical Scrollbar. It is important to not that you must NOT call 3 Adjustable methods ie : setMinimum(), setMaximum(), setVisibleAmount().
See Also:
getVAdjustable(), Adjustable

hAdjustable

private ScrollPaneAdjustable hAdjustable
An adjustable Horizontal Scrollbar. It is important to not that you must NOT call 3 Adjustable method ie : setMinimum(), setMaximum(), setVisibleAmount().
See Also:
getHAdjustable(), Adjustable

base

private static final String base

nameCounter

private static int nameCounter

serialVersionUID

private static final long serialVersionUID
Constructor Detail

ScrollPane

public ScrollPane()
Create a new scrollpane container with a scrollbar display policy of "as needed".

ScrollPane

public ScrollPane(int scrollbarDisplayPolicy)
Create a new scrollpane container.
Parameters:
scrollbarDisplayPolicy - policy for when scrollbars should be shown
Method Detail

initIDs

private static void initIDs()
Initialize JNI field and method IDs

static void ()

constructComponentName

String constructComponentName()
Construct a name for this component. Called by getName() when the name is null.
Overrides:
constructComponentName in class Component

addImpl

protected final void addImpl(Component comp,
                             Object constraints,
                             int index)
Adds the specified component to this scroll pane container. If the scroll pane has an existing child component, that component is removed and the new one is added.
Parameters:
comp - the component to be added
constraints - not applicable
index - position of child component (must be <= 0)
Overrides:
addImpl in class Container

getScrollbarDisplayPolicy

public int getScrollbarDisplayPolicy()
Returns the display policy for the scrollbars.
Returns:
the display policy for the scrollbars

getViewportSize

public Dimension getViewportSize()
Returns the current size of the scroll pane's view port.
Returns:
the size of the view port in pixels

getHScrollbarHeight

public int getHScrollbarHeight()
Returns the height that would be occupied by a horizontal scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
Returns:
the height of a horizontal scrollbar in pixels

getVScrollbarWidth

public int getVScrollbarWidth()
Returns the width that would be occupied by a vertical scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
Returns:
the width of a vertical scrollbar in pixels

getVAdjustable

public Adjustable getVAdjustable()
Returns the Adjustable object which represents the state of the vertical scrollbar.

getHAdjustable

public Adjustable getHAdjustable()
Returns the Adjustable object which represents the state of the horizontal scrollbar.

setScrollPosition

public void setScrollPosition(int x,
                              int y)
Scrolls to the specified position within the child component. A call to this method is only valid if the scroll pane contains a child. Specifying a position outside of the legal scrolling bounds of the child will scroll to the closest legal position. Legal bounds are defined to be the rectangle: x = 0, y = 0, width = (child width - view port width), height = (child height - view port height). This is a convenience method which interfaces with the Adjustable objects which represent the state of the scrollbars.
Parameters:
x - the x position to scroll to
y - the y position to scroll to

setScrollPosition

public void setScrollPosition(Point p)
Scrolls to the specified position within the child component. A call to this method is only valid if the scroll pane contains a child and the specified position is within legal scrolling bounds of the child. Specifying a position outside of the legal scrolling bounds of the child will scroll to the closest legal position. Legal bounds are defined to be the rectangle: x = 0, y = 0, width = (child width - view port width), height = (child height - view port height). This is a convenience method which interfaces with the Adjustable objects which represent the state of the scrollbars.
Parameters:
p - the Point representing the position to scroll to

getScrollPosition

public Point getScrollPosition()
Returns the current x,y position within the child which is displayed at the 0,0 location of the scrolled panel's view port. This is a convenience method which interfaces with the adjustable objects which represent the state of the scrollbars.
Returns:
the coordinate position for the current scroll position

setLayout

public final void setLayout(LayoutManager mgr)
Sets the layout manager for this container. This method is overridden to prevent the layout mgr from being set.
Parameters:
mgr - the specified layout manager
Overrides:
setLayout in class Container

doLayout

public void doLayout()
Lays out this container by resizing its child to its preferred size. If the new preferred size of the child causes the current scroll position to be invalid, the scroll position is set to the closest valid position.
Overrides:
doLayout in class Container
See Also:
Component.validate()

calculateChildSize

Dimension calculateChildSize()
Determine the size to allocate the child component. If the viewport area is bigger than the childs preferred size then the child is allocated enough to fill the viewport, otherwise the child is given it's preferred size.

layout

public void layout()
Deprecated. As of JDK version 1.1, replaced by doLayout().
Overrides:
layout in class Container

printComponents

public void printComponents(Graphics g)
Prints the component in this scroll pane.
Parameters:
g - the specified Graphics window
Overrides:
printComponents in class Container
See Also:
Component.print(java.awt.Graphics), Component.printAll(java.awt.Graphics)

addNotify

public void addNotify()
Creates the scroll pane's peer.
Overrides:
addNotify in class Container

paramString

public String paramString()
Overrides:
paramString in class Container