ImageObserver
, MenuContainer
, Serializable
, Accessible
public class JViewport extends JComponent implements Accessible
By default, JViewport
is opaque. To change this, use the setOpaque
method.
NOTE:We have implemented a faster scrolling algorithm that does not require a buffer to draw in. The algorithm works as follows:
JComponents
, if they aren't, stop and repaint the whole viewport. Window
's graphics and do a copyArea
on the scrolled region. copyArea
s. Compared to the non backing store case this approach will greatly reduce the painted region. This approach can cause slower times than the backing store approach when the viewport is obscured by another window, or partially offscreen. When another window obscures the viewport the copyArea will copy garbage and a paint event will be generated by the system to inform us we need to paint the newly exposed region. The only way to handle this is to repaint the whole viewport, which can cause slower performance than the backing store case. In most applications very rarely will the user be scrolling while the viewport is obscured by another window or offscreen, so this optimization is usually worth the performance hit when obscured.
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 JavaBeans has been added to the java.beans
package. Please see XMLEncoder
.
Modifier and Type | Class | Description |
---|---|---|
protected class |
JViewport.AccessibleJViewport |
This class implements accessibility support for the JViewport class. |
protected class |
JViewport.ViewListener |
A listener for the view. |
JComponent.AccessibleJComponent
Container.AccessibleAWTContainer
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Modifier and Type | Field | Description |
---|---|---|
protected boolean |
backingStore |
Deprecated. As of Java 2 platform v1.3 |
static final int |
BACKINGSTORE_SCROLL_MODE |
Draws viewport contents into an offscreen image. |
protected Image |
backingStoreImage |
The view image used for a backing store. |
static final int |
BLIT_SCROLL_MODE |
Use graphics.copyArea to implement scrolling. |
protected boolean |
isViewSizeSet |
True when the viewport dimensions have been determined. |
protected Point |
lastPaintPosition |
The last viewPosition that we've painted, so we know how much of the backing store image is valid. |
protected boolean |
scrollUnderway |
The scrollUnderway flag is used for components like JList . |
static final int |
SIMPLE_SCROLL_MODE |
This mode uses the very simple method of redrawing the entire contents of the scrollpane each time it is scrolled. |
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor | Description |
---|---|
JViewport() |
Creates a JViewport . |
Modifier and Type | Method | Description |
---|---|---|
void |
addChangeListener |
Adds a ChangeListener to the list that is notified each time the view's size, position, or the viewport's extent size has changed. |
protected void |
addImpl |
Sets the JViewport 's one lightweight child, which can be null . |
protected boolean |
computeBlit |
Computes the parameters for a blit where the backing store image currently contains oldLoc in the upper left hand corner and we're scrolling to newLoc . |
protected LayoutManager |
createLayoutManager() |
Subclassers can override this to install a different layout manager (or null ) in the constructor. |
protected JViewport.ViewListener |
createViewListener() |
Creates a listener for the view. |
protected void |
firePropertyChange |
Notifies listeners of a property change. |
protected void |
fireStateChanged() |
Notifies all ChangeListeners when the views size, position, or the viewports extent size has changed. |
AccessibleContext |
getAccessibleContext() |
Gets the AccessibleContext associated with this JViewport. |
ChangeListener[] |
getChangeListeners() |
Returns an array of all the ChangeListener s added to this JViewport with addChangeListener(). |
Dimension |
getExtentSize() |
Returns the size of the visible part of the view in view coordinates. |
final Insets |
getInsets() |
Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on a JViewport . |
final Insets |
getInsets |
Returns an Insets object containing this JViewport s inset values. |
int |
getScrollMode() |
Returns the current scrolling mode. |
ViewportUI |
getUI() |
Returns the L&F object that renders this component. |
String |
getUIClassID() |
Returns a string that specifies the name of the L&F class that renders this component. |
Component |
getView() |
Returns the JViewport 's one child or null . |
Point |
getViewPosition() |
Returns the view coordinates that appear in the upper left hand corner of the viewport, or 0,0 if there's no view. |
Rectangle |
getViewRect() |
Returns a rectangle whose origin is getViewPosition and size is getExtentSize . |
Dimension |
getViewSize() |
If the view's size hasn't been explicitly set, return the preferred size, otherwise return the view's current size. |
boolean |
isBackingStoreEnabled() |
Deprecated. As of Java 2 platform v1.3, replaced by getScrollMode() . |
boolean |
isOptimizedDrawingEnabled() |
The JViewport overrides the default implementation of this method (in JComponent ) to return false. |
protected boolean |
isPaintingOrigin() |
Returns true if scroll mode is a BACKINGSTORE_SCROLL_MODE to cause painting to originate from JViewport , or one of its ancestors. |
void |
paint |
Depending on whether the backingStore is enabled, either paint the image through the backing store or paint just the recently exposed part, using the backing store to "blit" the remainder. |
protected String |
paramString() |
Returns a string representation of this JViewport . |
void |
remove |
Removes the Viewport s one lightweight child. |
void |
removeChangeListener |
Removes a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed. |
void |
repaint |
Always repaint in the parents coordinate system to make sure only one paint is performed by the RepaintManager . |
void |
reshape |
Sets the bounds of this viewport. |
void |
scrollRectToVisible |
Scrolls the view so that Rectangle within the view becomes visible. |
void |
setBackingStoreEnabled |
Deprecated. As of Java 2 platform v1.3, replaced by setScrollMode() . |
final void |
setBorder |
The viewport "scrolls" its child (called the "view") by the normal parent/child clipping (typically the view is moved in the opposite direction of the scroll). |
void |
setExtentSize |
Sets the size of the visible part of the view using view coordinates. |
void |
setScrollMode |
Used to control the method of scrolling the viewport contents. |
void |
setUI |
Sets the L&F object that renders this component. |
void |
setView |
Sets the JViewport 's one lightweight child (view ), which can be null . |
void |
setViewPosition |
Sets the view coordinates that appear in the upper left hand corner of the viewport, does nothing if there's no view. |
void |
setViewSize |
Sets the size of the view. |
Dimension |
toViewCoordinates |
Converts a size in pixel coordinates to view coordinates. |
Point |
toViewCoordinates |
Converts a point in pixel coordinates to view coordinates. |
void |
updateUI() |
Resets the UI property to a value from the current look and feel. |
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, 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, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
add, add, add, add, add, addContainerListener, 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, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree
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, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, 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, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
protected boolean isViewSizeSet
protected Point lastPaintPosition
viewPosition
that we've painted, so we know how much of the backing store image is valid.@Deprecated protected boolean backingStore
false
.protected transient Image backingStoreImage
protected boolean scrollUnderway
scrollUnderway
flag is used for components like JList
. When the downarrow key is pressed on a JList
and the selected cell is the last in the list, the scrollpane
autoscrolls. Here, the old selected cell needs repainting and so we need a flag to make the viewport do the optimized painting only when there is an explicit call to setViewPosition(Point)
. When setBounds
is called through other routes, the flag is off and the view repaints normally. Another approach would be to remove this from the JViewport
class and have the JList
manage this case by using setBackingStoreEnabled
. The default is false
.public static final int BLIT_SCROLL_MODE
graphics.copyArea
to implement scrolling. This is the fastest for most applications.public static final int BACKINGSTORE_SCROLL_MODE
JTable
. This mode may offer advantages over "blit mode" in some cases, but it requires a large chunk of extra RAM.public static final int SIMPLE_SCROLL_MODE
public JViewport()
JViewport
.public ViewportUI getUI()
getUI
in class JComponent
ViewportUI
object@BeanProperty(hidden=true, visualUpdate=true, description="The UI object that implements the Component\'s LookAndFeel.") public void setUI(ViewportUI ui)
ui
- the ViewportUI
L&F objectpublic void updateUI()
updateUI
in class JComponent
public String getUIClassID()
getUIClassID
in class JComponent
protected void addImpl(Component child, Object constraints, int index)
JViewport
's one lightweight child, which can be null
. (Since there is only one child which occupies the entire viewport, the constraints
and index
arguments are ignored.)public void remove(Component child)
Viewport
s one lightweight child.public void scrollRectToVisible(Rectangle contentRect)
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.
scrollRectToVisible
in class JComponent
contentRect
- the Rectangle
to displaypublic final void setBorder(Border border)
null
border, or non-zero insets, isn't supported, to prevent the geometry of this component from becoming complex enough to inhibit subclassing. To create a JViewport
with a border, add it to a JPanel
that has a border. Note: If border
is non-null
, this method will throw an exception as borders are not supported on a JViewPort
.
setBorder
in class JComponent
border
- the Border
to setIllegalArgumentException
- this method is not implementedpublic final Insets getInsets()
JViewport
.getInsets
in class JComponent
Rectangle
of zero dimension and zero origin@BeanProperty(expert=true) public final Insets getInsets(Insets insets)
Insets
object containing this JViewport
s inset values. The passed-in Insets
object will be reinitialized, and all existing values within this object are overwritten.getInsets
in class JComponent
insets
- the Insets
object which can be reusedpublic boolean isOptimizedDrawingEnabled()
JViewport
overrides the default implementation of this method (in JComponent
) to return false. This ensures that the drawing machinery will call the Viewport
's paint
implementation rather than messaging the JViewport
's children directly.isOptimizedDrawingEnabled
in class JComponent
protected boolean isPaintingOrigin()
BACKINGSTORE_SCROLL_MODE
to cause painting to originate from JViewport
, or one of its ancestors. Otherwise returns false
.isPaintingOrigin
in class JComponent
BACKINGSTORE_SCROLL_MODE
.public void paint(Graphics g)
backingStore
is enabled, either paint the image through the backing store or paint just the recently exposed part, using the backing store to "blit" the remainder. The term "blit" is the pronounced version of the PDP-10 BLT (BLock Transfer) instruction, which copied a block of bits. (In case you were curious.)
paint
in class JComponent
g
- the Graphics
context within which to paintpublic void reshape(int x, int y, int w, int h)
StateChanged
event.reshape
in class JComponent
x
- left edge of the originy
- top edge of the originw
- width in pixelsh
- height in pixels@BeanProperty(bound=false, enumerationValues={"JViewport.BLIT_SCROLL_MODE","JViewport.BACKINGSTORE_SCROLL_MODE","JViewport.SIMPLE_SCROLL_MODE"}, description="Method of moving contents for incremental scrolls.") public void setScrollMode(int mode)
mode
- one of the following values: public int getScrollMode()
scrollMode
property@Deprecated public boolean isBackingStoreEnabled()
getScrollMode()
.true
if this viewport is maintaining an offscreen image of its contents.true
if scrollMode
is BACKINGSTORE_SCROLL_MODE
@Deprecated public void setBackingStoreEnabled(boolean enabled)
setScrollMode()
.viewPosition
. Rather than repainting the entire viewport we use Graphics.copyArea
to effect some of the scroll.enabled
- if true, maintain an offscreen backing storepublic Component getView()
JViewport
's one child or null
.null
if none existspublic void setView(Component view)
JViewport
's one lightweight child (view
), which can be null
.view
- the viewport's new lightweight childpublic Dimension getViewSize()
Dimension
object specifying the size of the viewpublic void setViewSize(Dimension newSize)
newSize
- a Dimension
object specifying the new size of the viewpublic Point getViewPosition()
Point
object giving the upper left coordinatespublic void setViewPosition(Point p)
p
- a Point
object giving the upper left coordinatespublic Rectangle getViewRect()
getViewPosition
and size is getExtentSize
. This is the visible part of the view, in view coordinates.Rectangle
giving the visible part of the view using view coordinates.protected boolean computeBlit(int dx, int dy, Point blitFrom, Point blitTo, Dimension blitSize, Rectangle blitPaint)
oldLoc
in the upper left hand corner and we're scrolling to newLoc
. The parameters are modified to return the values required for the blit.dx
- the horizontal deltady
- the vertical deltablitFrom
- the Point
we're blitting fromblitTo
- the Point
we're blitting toblitSize
- the Dimension
of the area to blitblitPaint
- the area to blitpublic Dimension getExtentSize()
Dimension
object giving the size of the viewpublic Dimension toViewCoordinates(Dimension size)
size
- a Dimension
object using pixel coordinatesDimension
object converted to view coordinatespublic Point toViewCoordinates(Point p)
p
- a Point
object using pixel coordinatesPoint
object converted to view coordinatespublic void setExtentSize(Dimension newExtent)
newExtent
- a Dimension
object specifying the size of the viewprotected JViewport.ViewListener createViewListener()
ViewListener
protected LayoutManager createLayoutManager()
null
) in the constructor. Returns the LayoutManager
to install on the JViewport
.LayoutManager
public void addChangeListener(ChangeListener l)
ChangeListener
to the list that is notified each time the view's size, position, or the viewport's extent size has changed.l
- the ChangeListener
to addpublic void removeChangeListener(ChangeListener l)
ChangeListener
from the list that's notified each time the views size, position, or the viewports extent size has changed.l
- the ChangeListener
to removepublic ChangeListener[] getChangeListeners()
ChangeListener
s added to this JViewport with addChangeListener().ChangeListener
s added or an empty array if no listeners have been addedprotected void fireStateChanged()
ChangeListeners
when the views size, position, or the viewports extent size has changed.public void repaint(long tm, int x, int y, int w, int h)
RepaintManager
.repaint
in class JComponent
tm
- maximum time in milliseconds before updatex
- the x
coordinate (pixels over from left)y
- the y
coordinate (pixels down from top)w
- the widthh
- the heightprotected String paramString()
JViewport
. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null
.paramString
in class JComponent
JViewport
protected void firePropertyChange(String propertyName, Object oldValue, Object newValue)
windowBlit
property. (The putClientProperty
property is final).firePropertyChange
in class Component
propertyName
- a string containing the property nameoldValue
- the old value of the propertynewValue
- the new value of the propertypublic AccessibleContext getAccessibleContext()
getAccessibleContext
in interface Accessible
getAccessibleContext
in class Component
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/swing/JViewport.html