| JavaTM 2 Platform Std. Ed. v1.6.0
javax.swing
Class JScrollPane
java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JScrollPane
- All Implemented Interfaces:
- ImageObserver, MenuContainer, Serializable, Accessible, ScrollPaneConstants
public class JScrollPane - extends JComponent
- implements ScrollPaneConstants, Accessible
Provides a scrollable view of a lightweight component.
A JScrollPane manages a viewport, optional
vertical and horizontal scroll bars, and optional row and
column heading viewports.
You can find task-oriented documentation of JScrollPane in
How to Use Scroll Panes,
a section in The Java Tutorial. Note that
JScrollPane does not support heavyweight components.
The JViewport provides a window,
or "viewport" onto a data
source -- for example, a text file. That data source is the
"scrollable client" (aka data model) displayed by the
JViewport view.
A JScrollPane basically consists of JScrollBars,
a JViewport, and the wiring between them,
as shown in the diagram at right.
In addition to the scroll bars and viewport,
a JScrollPane can have a
column header and a row header. Each of these is a
JViewport object that
you specify with setRowHeaderView,
and setColumnHeaderView.
The column header viewport automatically scrolls left and right, tracking
the left-right scrolling of the main viewport.
(It never scrolls vertically, however.)
The row header acts in a similar fashion.
Where two scroll bars meet, the row header meets the column header,
or a scroll bar meets one of the headers, both components stop short
of the corner, leaving a rectangular space which is, by default, empty.
These spaces can potentially exist in any number of the four corners.
In the previous diagram, the top right space is present and identified
by the label "corner component".
Any number of these empty spaces can be replaced by using the
setCorner method to add a component to a particular corner.
(Note: The same component cannot be added to multiple corners.)
This is useful if there's
some extra decoration or function you'd like to add to the scroll pane.
The size of each corner component is entirely determined by the size of the
headers and/or scroll bars that surround it.
A corner component will only be visible if there is an empty space in that
corner for it to exist in. For example, consider a component set into the
top right corner of a scroll pane with a column header. If the scroll pane's
vertical scrollbar is not present, perhaps because the view component hasn't
grown large enough to require it, then the corner component will not be
shown (since there is no empty space in that corner created by the meeting
of the header and vertical scroll bar). Forcing the scroll bar to always be
shown, using
setVerticalScrollBarPolicy(VERTICAL_SCROLLBAR_ALWAYS),
will ensure that the space for the corner component always exists.
To add a border around the main viewport,
you can use setViewportBorder.
(Of course, you can also add a border around the whole scroll pane using
setBorder.)
A common operation to want to do is to set the background color that will
be used if the main viewport view is smaller than the viewport, or is
not opaque. This can be accomplished by setting the background color
of the viewport, via scrollPane.getViewport().setBackground().
The reason for setting the color of the viewport and not the scrollpane
is that by default JViewport is opaque
which, among other things, means it will completely fill
in its background using its background color. Therefore when
JScrollPane draws its background the viewport will
usually draw over it.
By default JScrollPane uses ScrollPaneLayout
to handle the layout of its child Components. ScrollPaneLayout
determines the size to make the viewport view in one of two ways:
- If the view implements
Scrollable
a combination of getPreferredScrollableViewportSize,
getScrollableTracksViewportWidth and
getScrollableTracksViewportHeightis used, otherwise
getPreferredSize is used.
Warning: Swing is not thread safe. For more
information see Swing's Threading
Policy.
Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing. As of 1.4, support for long term storage
of all JavaBeansTM
has been added to the java.beans package.
Please see XMLEncoder.
- See Also:
JScrollBar,
JViewport,
ScrollPaneLayout,
Scrollable,
Component.getPreferredSize(),
setViewportView(java.awt.Component),
setRowHeaderView(java.awt.Component),
setColumnHeaderView(java.awt.Component),
setCorner(java.lang.String, java.awt.Component),
setViewportBorder(javax.swing.border.Border)
| Fields inherited from interface javax.swing.ScrollPaneConstants |
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT |
|
Constructor Summary |
JScrollPane()
Creates an empty (no viewport view) JScrollPane
where both horizontal and vertical scrollbars appear when needed. |
JScrollPane(Component view)
Creates a JScrollPane that displays the
contents of the specified
component, where both horizontal and vertical scrollbars appear
whenever the component's contents are larger than the view. |
JScrollPane(Component view,
int vsbPolicy,
int hsbPolicy)
Creates a JScrollPane that displays the view
component in a viewport
whose view position can be controlled with a pair of scrollbars. |
JScrollPane(int vsbPolicy,
int hsbPolicy)
Creates an empty (no viewport view) JScrollPane
with specified
scrollbar policies. |
|
Method Summary |
JScrollBar |
createHorizontalScrollBar()
Returns a JScrollPane.ScrollBar by default. |
JScrollBar |
createVerticalScrollBar()
Returns a JScrollPane.ScrollBar by default. |
protected JViewport |
createViewport()
Returns a new JViewport by default. |
AccessibleContext |
getAccessibleContext()
Gets the AccessibleContext associated with this JScrollPane. |
JViewport |
getColumnHeader()
Returns the column header. |
Component |
getCorner(String key)
Returns the component at the specified corner. |
JScrollBar |
getHorizontalScrollBar()
Returns the horizontal scroll bar that controls the viewport's
horizontal view position. |
int |
getHorizontalScrollBarPolicy()
Returns the horizontal scroll bar policy value. |
JViewport |
getRowHeader()
Returns the row header. |
ScrollPaneUI |
getUI()
Returns the look and feel (L&F) object that renders this component. |
String |
getUIClassID()
Returns the suffix used to construct the name of the L&F class used to
render this component. |
JScrollBar |
getVerticalScrollBar()
Returns the vertical scroll bar that controls the viewports
vertical view position. |
int |
getVerticalScrollBarPolicy()
Returns the vertical scroll bar policy value. |
JViewport |
getViewport()
Returns the current JViewport. |
Border |
getViewportBorder()
Returns the Border object that surrounds the viewport. |
Rectangle |
getViewportBorderBounds()
Returns the bounds of the viewport's border. |
boolean |
isValidateRoot()
Overridden to return true so that any calls to revalidate
on any descendants of this JScrollPane will cause the
entire tree beginning with this JScrollPane to be
validated. |
boolean |
isWheelScrollingEnabled()
Indicates whether or not scrolling will take place in response to the
mouse wheel. |
protected String |
paramString()
Returns a string representation of this JScrollPane. |
void |
setColumnHeader(JViewport columnHeader)
Removes the old columnHeader, if it exists; if the new columnHeader
isn't null, syncs the x coordinate of its viewPosition
with the viewport (if there is one) and then adds it to the scroll pane. |
void |
setColumnHeaderView(Component view)
Creates a column-header viewport if necessary, sets
its view, and then adds the column-header viewport
to the scrollpane. |
void |
setComponentOrientation(ComponentOrientation co)
Sets the orientation for the vertical and horizontal
scrollbars as determined by the
ComponentOrientation argument. |
void |
setCorner(String key,
Component corner)
Adds a child that will appear in one of the scroll panes
corners, if there's room. |
void |
setHorizontalScrollBar(JScrollBar horizontalScrollBar)
Adds the scrollbar that controls the viewport's horizontal view
position to the scrollpane. |
void |
setHorizontalScrollBarPolicy(int policy)
Determines when the horizontal scrollbar appears in the scrollpane. |
void |
setLayout(LayoutManager layout)
Sets the layout manager for this JScrollPane. |
void |
setRowHeader(JViewport rowHeader)
Removes the old rowHeader, if it exists; if the new rowHeader
isn't null, syncs the y coordinate of its
viewPosition with
the viewport (if there is one) and then adds it to the scroll pane. |
void |
setRowHeaderView(Component view)
Creates a row-header viewport if necessary, sets
its view and then adds the row-header viewport
to the scrollpane. |
void |
setUI(ScrollPaneUI ui)
Sets the ScrollPaneUI object that provides the
look and feel (L&F) for this component. |
void |
setVerticalScrollBar(JScrollBar verticalScrollBar)
Adds the scrollbar that controls the viewports vertical view position
to the scrollpane. |
void |
setVerticalScrollBarPolicy(int policy)
Determines when the vertical scrollbar appears in the scrollpane. |
void |
setViewport(JViewport viewport)
Removes the old viewport (if there is one); forces the
viewPosition of the new viewport to be in the +x,+y quadrant;
syncs up the row and column headers (if there are any) with the
new viewport; and finally syncs the scrollbars and
headers with the new viewport. |
void |
setViewportBorder(Border viewportBorder)
Adds a border around the viewport. |
void |
setViewportView(Component view)
Creates a viewport if necessary and then sets its view. |
void |
setWheelScrollingEnabled(boolean handleWheel)
Enables/disables scrolling in response to movement of the mouse wheel. |
void |
updateUI()
Replaces the current ScrollPaneUI object with a version
from the current default look and feel. |
| Methods inherited from class javax.swing.JComponent |
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update |
| Methods inherited from class java.awt.Container |
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree |
| Methods inherited from class java.awt.Component |
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle |
verticalScrollBarPolicy
protected int verticalScrollBarPolicy
- The display policy for the vertical scrollbar.
The default is
ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED.
- See Also:
setVerticalScrollBarPolicy(int)
horizontalScrollBarPolicy
protected int horizontalScrollBarPolicy
- The display policy for the horizontal scrollbar.
The default is
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED.
- See Also:
setHorizontalScrollBarPolicy(int)
viewport
protected JViewport viewport
- The scrollpane's viewport child. Default is an empty
JViewport.
- See Also:
setViewport(javax.swing.JViewport)
verticalScrollBar
protected JScrollBar verticalScrollBar
- The scrollpane's vertical scrollbar child.
Default is a
JScrollBar.
- See Also:
setVerticalScrollBar(javax.swing.JScrollBar)
horizontalScrollBar
protected JScrollBar horizontalScrollBar
- The scrollpane's horizontal scrollbar child.
Default is a
JScrollBar.
- See Also:
setHorizontalScrollBar(javax.swing.JScrollBar)
rowHeader
protected JViewport rowHeader
- The row header child. Default is
null.
- See Also:
setRowHeader(javax.swing.JViewport)
columnHeader
protected JViewport columnHeader
- The column header child. Default is
null.
- See Also:
setColumnHeader(javax.swing.JViewport)
lowerLeft
protected Component lowerLeft
- The component to display in the lower left corner.
Default is
null.
- See Also:
setCorner(java.lang.String, java.awt.Component)
lowerRight
protected Component lowerRight
- The component to display in the lower right corner.
Default is
null.
- See Also:
setCorner(java.lang.String, java.awt.Component)
upperLeft
protected Component upperLeft
- The component to display in the upper left corner.
Default is
null.
- See Also:
setCorner(java.lang.String, java.awt.Component)
upperRight
protected Component upperRight
- The component to display in the upper right corner.
Default is
null.
- See Also:
setCorner(java.lang.String, java.awt.Component)
JScrollPane
public JScrollPane(Component view,
int vsbPolicy,
int hsbPolicy)
- Creates a
JScrollPane that displays the view
component in a viewport
whose view position can be controlled with a pair of scrollbars.
The scrollbar policies specify when the scrollbars are displayed,
For example, if vsbPolicy is
VERTICAL_SCROLLBAR_AS_NEEDED
then the vertical scrollbar only appears if the view doesn't fit
vertically. The available policy settings are listed at
setVerticalScrollBarPolicy(int) and
setHorizontalScrollBarPolicy(int).
- Parameters:
view - the component to display in the scrollpanes viewportvsbPolicy - an integer that specifies the vertical
scrollbar policyhsbPolicy - an integer that specifies the horizontal
scrollbar policy- See Also:
setViewportView(java.awt.Component)
JScrollPane
public JScrollPane(Component view)
- Creates a
JScrollPane that displays the
contents of the specified
component, where both horizontal and vertical scrollbars appear
whenever the component's contents are larger than the view.
- Parameters:
view - the component to display in the scrollpane's viewport- See Also:
setViewportView(java.awt.Component)
JScrollPane
public JScrollPane(int vsbPolicy,
int hsbPolicy)
- Creates an empty (no viewport view)
JScrollPane
with specified
scrollbar policies. The available policy settings are listed at
setVerticalScrollBarPolicy(int) and
setHorizontalScrollBarPolicy(int).
- Parameters:
vsbPolicy - an integer that specifies the vertical
scrollbar policyhsbPolicy - an integer that specifies the horizontal
scrollbar policy- See Also:
setViewportView(java.awt.Component)
JScrollPane
public JScrollPane()
- Creates an empty (no viewport view)
JScrollPane
where both horizontal and vertical scrollbars appear when needed.
getUI
public ScrollPaneUI getUI()
- Returns the look and feel (L&F) object that renders this component.
- Returns:
- the
ScrollPaneUI object that renders this
component - See Also:
setUI(javax.swing.plaf.ScrollPaneUI)
setUI
public void setUI(ScrollPaneUI ui)
- Sets the
ScrollPaneUI object that provides the
look and feel (L&F) for this component.
- Parameters:
ui - the ScrollPaneUI L&F object- See Also:
getUI()
updateUI
public void updateUI()
- Replaces the current
ScrollPaneUI object with a version
from the current default look and feel.
To be called when the default look and feel changes.
- Overrides:
updateUI in class JComponent
- See Also:
JComponent.updateUI(),
UIManager.getUI(javax.swing.JComponent)
getUIClassID
public String getUIClassID()
- Returns the suffix used to construct the name of the L&F class used to
render this component.
- Overrides:
getUIClassID in class JComponent
- Returns:
- the string "ScrollPaneUI"
- See Also:
JComponent.getUIClassID(),
UIDefaults.getUI(javax.swing.JComponent)
setLayout
public void setLayout(LayoutManager layout)
- Sets the layout manager for this
JScrollPane.
This method overrides setLayout in
java.awt.Container to ensure that only
LayoutManagers which
are subclasses of ScrollPaneLayout can be used in a
JScrollPane. If layout is non-null, this
will invoke syncWithScrollPane on it.
- Overrides:
setLayout in class Container
- Parameters:
layout - the specified layout manager
- Throws:
ClassCastException - if layout is not a
ScrollPaneLayout- See Also:
Container.getLayout(),
Container.setLayout(java.awt.LayoutManager)
isValidateRoot
public boolean isValidateRoot()
- Overridden to return true so that any calls to
revalidate
on any descendants of this JScrollPane will cause the
entire tree beginning with this JScrollPane to be
validated.
- Overrides:
isValidateRoot in class JComponent
- Returns:
- true
- See Also:
Container.validate(),
JComponent.revalidate(),
JComponent.isValidateRoot()
getVerticalScrollBarPolicy
public int getVerticalScrollBarPolicy()
- Returns the vertical scroll bar policy value.
- Returns:
- the
verticalScrollBarPolicy property - See Also:
setVerticalScrollBarPolicy(int)
setVerticalScrollBarPolicy
public void setVerticalScrollBarPolicy(int policy)
- Determines when the vertical scrollbar appears in the scrollpane.
Legal values are:
ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED
ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER
ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS
- Parameters:
policy - one of the three values listed above
- Throws:
IllegalArgumentException - if policy
is not one of the legal values shown above- See Also:
getVerticalScrollBarPolicy()
getHorizontalScrollBarPolicy
public int getHorizontalScrollBarPolicy()
- Returns the horizontal scroll bar policy value.
- Returns:
- the
horizontalScrollBarPolicy property - See Also:
setHorizontalScrollBarPolicy(int)
setHorizontalScrollBarPolicy
public void setHorizontalScrollBarPolicy(int policy)
- Determines when the horizontal scrollbar appears in the scrollpane.
The options are:
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS
- Parameters:
policy - one of the three values listed above
- Throws:
IllegalArgumentException - if policy
is not one of the legal values shown above- See Also:
getHorizontalScrollBarPolicy()
getViewportBorder
public Border getViewportBorder()
- Returns the
Border object that surrounds the viewport.
- Returns:
- the
viewportBorder property - See Also:
setViewportBorder(javax.swing.border.Border)
setViewportBorder
public void setViewportBorder(Border viewportBorder)
- Adds a border around the viewport. Note that the border isn't
set on the viewport directly,
JViewport doesn't support
the JComponent border property.
Similarly setting the JScrollPanes
viewport doesn't affect the viewportBorder property.
The default value of this property is computed by the look
and feel implementation.
- Parameters:
viewportBorder - the border to be added- See Also:
|