Class JViewport

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JViewport
All Implemented Interfaces:
ImageObserver,MenuContainer,Serializable,Accessible
public classJViewportextendsJComponentimplementsAccessible
The "viewport" or "porthole" through which you see the underlying information. When you scroll, what moves is the viewport. It is like peering through a camera's viewfinder. Moving the viewfinder upwards brings new things into view at the top of the picture and loses things that were at the bottom.

By default,JViewport is opaque. To change this, use thesetOpaque method.

NOTE:We have implemented a faster scrolling algorithm that does not require a buffer to draw in. The algorithm works as follows:

  1. The view and parent view are checked to see if they areJComponents, if they aren't, stop and repaint the whole viewport.
  2. If the viewport is obscured by an ancestor, stop and repaint the whole viewport.
  3. Compute the region that will become visible, if it is as big as the viewport, stop and repaint the whole view region.
  4. Obtain the ancestorWindow's graphics and do acopyArea on the scrolled region.
  5. Message the view to repaint the newly visible region.
  6. The next time paint is invoked on the viewport, if the clip region is smaller than the viewport size a timer is kicked off to repaint the whole region.
In general this approach is much faster. Compared to the backing store approach this avoids the overhead of maintaining an offscreen buffer and having to do twocopyAreas. 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 seeSwing'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 thejava.beans package. Please seeXMLEncoder.

Since:
1.2
See Also:

  • Field Details

    • isViewSizeSet

      protected boolean isViewSizeSet
      True when the viewport dimensions have been determined. The default is false.

    • lastPaintPosition

      protected Point lastPaintPosition
      The lastviewPosition that we've painted, so we know how much of the backing store image is valid.

    • backingStore

      @Deprecatedprotected boolean backingStore
      Deprecated.
      As of Java 2 platform v1.3
      True when this viewport is maintaining an offscreen image of its contents, so that some scrolling can take place using fast "bit-blit" operations instead of by accessing the view object to construct the display. The default isfalse.
      See Also:

    • backingStoreImage

      protected transient Image backingStoreImage
      The view image used for a backing store.

    • scrollUnderway

      protected boolean scrollUnderway
      ThescrollUnderway flag is used for components likeJList. When the downarrow key is pressed on aJList and the selected cell is the last in the list, thescrollpane 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 tosetViewPosition(Point). WhensetBounds is called through other routes, the flag is off and the view repaints normally. Another approach would be to remove this from theJViewport class and have theJList manage this case by usingsetBackingStoreEnabled. The default isfalse.

    • BLIT_SCROLL_MODE

      public static final int BLIT_SCROLL_MODE
      Usegraphics.copyArea to implement scrolling. This is the fastest for most applications.
      Since:
      1.3
      See Also:

    • BACKINGSTORE_SCROLL_MODE

      public static final int BACKINGSTORE_SCROLL_MODE
      Draws viewport contents into an offscreen image. This was previously the default mode forJTable. This mode may offer advantages over "blit mode" in some cases, but it requires a large chunk of extra RAM.
      Since:
      1.3
      See Also:

    • SIMPLE_SCROLL_MODE

      public 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. This was the default behavior in Swing 1.0 and Swing 1.1. Either of the other two options will provide better performance in most cases.
      Since:
      1.3
      See Also:

  • Constructor Details

    • JViewport

      public JViewport()
      Creates aJViewport.

  • Method Details

    • getUI

      public ViewportUI getUI()
      Returns the L&F object that renders this component.
      Overrides:
      getUI in class JComponent
      Returns:
      aViewportUI object
      Since:
      1.3

    • setUI

      @BeanProperty(hidden=true,visualUpdate=true,description="The UI object that implements the Component's LookAndFeel.")public void setUI(ViewportUI ui)
      Sets the L&F object that renders this component.
      Parameters:
      ui - theViewportUI L&F object
      Since:
      1.3
      See Also:

    • updateUI

      public void updateUI()
      Resets the UI property to a value from the current look and feel.
      Overrides:
      updateUI in class JComponent
      See Also:

    • getUIClassID

      public String getUIClassID()
      Returns a string that specifies the name of the L&F class that renders this component.
      Overrides:
      getUIClassID in class JComponent
      Returns:
      the string "ViewportUI"
      See Also:

    • addImpl

      protected void addImpl(Component child,Object constraints, int index)
      Sets theJViewport's one lightweight child, which can benull. (Since there is only one child which occupies the entire viewport, theconstraints andindex arguments are ignored.)
      Overrides:
      addImpl in class Container
      Parameters:
      child - the lightweightchild of the viewport
      constraints - theconstraints to be respected
      index - the index
      See Also:

    • remove

      public void remove(Component child)
      Removes theViewports one lightweight child.
      Overrides:
      remove in class Container
      Parameters:
      child - the component to be removed
      See Also:

    • scrollRectToVisible

      public void scrollRectToVisible(Rectangle contentRect)
      Scrolls the view so thatRectangle 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 aWindow orApplet.

      Note that this method will not scroll outside of the valid viewport; for example, ifcontentRect is larger than the viewport, scrolling will be confined to the viewport's bounds.

      Overrides:
      scrollRectToVisible in class JComponent
      Parameters:
      contentRect - theRectangle to display
      See Also:

    • setBorder

      public final void setBorder(Border border)
      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). A non-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 aJViewport with a border, add it to aJPanel that has a border.

      Note: Ifborder is non-null, this method will throw an exception as borders are not supported on aJViewPort.

      Overrides:
      setBorder in class JComponent
      Parameters:
      border - theBorder to set
      Throws:
      IllegalArgumentException - this method is not implemented
      See Also:

    • getInsets

      public final Insets getInsets()
      Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on aJViewport.
      Overrides:
      getInsets in class JComponent
      Returns:
      aRectangle of zero dimension and zero origin
      See Also:

    • getInsets

      @BeanProperty(expert=true)public final Insets getInsets(Insets insets)
      Returns anInsets object containing thisJViewports inset values. The passed-inInsets object will be reinitialized, and all existing values within this object are overwritten.
      Overrides:
      getInsets in class JComponent
      Parameters:
      insets - theInsets object which can be reused
      Returns:
      this viewports inset values
      See Also:

    • isOptimizedDrawingEnabled

      public boolean isOptimizedDrawingEnabled()
      TheJViewport overrides the default implementation of this method (inJComponent) to return false. This ensures that the drawing machinery will call theViewport'spaint implementation rather than messaging theJViewport's children directly.
      Overrides:
      isOptimizedDrawingEnabled in class JComponent
      Returns:
      false

    • isPaintingOrigin

      protected boolean isPaintingOrigin()
      Returns true if scroll mode is aBACKINGSTORE_SCROLL_MODE to cause painting to originate fromJViewport, or one of its ancestors. Otherwise returnsfalse.
      Overrides:
      isPaintingOrigin in class JComponent
      Returns:
      true if scroll mode is aBACKINGSTORE_SCROLL_MODE.
      See Also:

    • paint

      public void paint(Graphics g)
      Depending on whether thebackingStore 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.)
      Overrides:
      paint in class JComponent
      Parameters:
      g - theGraphics context within which to paint
      See Also:

    • reshape

      public void reshape(int x, int y, int w, int h)
      Sets the bounds of this viewport. If the viewport's width or height has changed, fire aStateChanged event.
      Overrides:
      reshape in class JComponent
      Parameters:
      x - left edge of the origin
      y - top edge of the origin
      w - width in pixels
      h - height in pixels
      See Also:

    • setScrollMode

      @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)
      Used to control the method of scrolling the viewport contents. You may want to change this mode to get maximum performance for your use case.
      Parameters:
      mode - one of the following values:
      • JViewport.BLIT_SCROLL_MODE
      • JViewport.BACKINGSTORE_SCROLL_MODE
      • JViewport.SIMPLE_SCROLL_MODE
      Since:
      1.3
      See Also:

    • getScrollMode

      public int getScrollMode()
      Returns the current scrolling mode.
      Returns:
      thescrollMode property
      Since:
      1.3
      See Also:

    • isBackingStoreEnabled

      @Deprecatedpublic boolean isBackingStoreEnabled()
      Deprecated.
      As of Java 2 platform v1.3, replaced bygetScrollMode().
      Returnstrue if this viewport is maintaining an offscreen image of its contents.
      Returns:
      true ifscrollMode isBACKINGSTORE_SCROLL_MODE

    • setBackingStoreEnabled

      @Deprecatedpublic void setBackingStoreEnabled(boolean enabled)
      Deprecated.
      As of Java 2 platform v1.3, replaced bysetScrollMode().
      If true if this viewport will maintain an offscreen image of its contents. The image is used to reduce the cost of small one dimensional changes to theviewPosition. Rather than repainting the entire viewport we useGraphics.copyArea to effect some of the scroll.
      Parameters:
      enabled - if true, maintain an offscreen backing store

    • getView

      public Component getView()
      Returns theJViewport's one child ornull.
      Returns:
      the viewports child, ornull if none exists
      See Also:

    • setView

      public void setView(Component view)
      Sets theJViewport's one lightweight child (view), which can benull.
      Parameters:
      view - the viewport's new lightweight child
      See Also:

    • getViewSize

      public Dimension getViewSize()
      If the view's size hasn't been explicitly set, return the preferred size, otherwise return the view's current size. If there is no view, return 0,0.
      Returns:
      aDimension object specifying the size of the view

    • setViewSize

      public void setViewSize(Dimension newSize)
      Sets the size of the view. A state changed event will be fired.
      Parameters:
      newSize - aDimension object specifying the new size of the view

    • getViewPosition

      public 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.
      Returns:
      aPoint object giving the upper left coordinates

    • setViewPosition

      public void setViewPosition(Point p)
      Sets the view coordinates that appear in the upper left hand corner of the viewport, does nothing if there's no view.
      Parameters:
      p - aPoint object giving the upper left coordinates

    • getViewRect

      public Rectangle getViewRect()
      Returns a rectangle whose origin isgetViewPosition and size isgetExtentSize. This is the visible part of the view, in view coordinates.
      Returns:
      aRectangle giving the visible part of the view using view coordinates.

    • computeBlit

      protected boolean computeBlit(int dx, int dy,Point blitFrom,Point blitTo,Dimension blitSize,Rectangle blitPaint)
      Computes the parameters for a blit where the backing store image currently containsoldLoc in the upper left hand corner and we're scrolling tonewLoc. The parameters are modified to return the values required for the blit.
      Parameters:
      dx - the horizontal delta
      dy - the vertical delta
      blitFrom - thePoint we're blitting from
      blitTo - thePoint we're blitting to
      blitSize - theDimension of the area to blit
      blitPaint - the area to blit
      Returns:
      true if the parameters are modified and we're ready to blit; false otherwise

    • getExtentSize

      public Dimension getExtentSize()
      Returns the size of the visible part of the view in view coordinates.
      Returns:
      aDimension object giving the size of the view

    • toViewCoordinates

      public Dimension toViewCoordinates(Dimension size)
      Converts a size in pixel coordinates to view coordinates. Subclasses of viewport that support "logical coordinates" will override this method.
      Parameters:
      size - aDimension object using pixel coordinates
      Returns:
      aDimension object converted to view coordinates

    • toViewCoordinates

      public Point toViewCoordinates(Point p)
      Converts a point in pixel coordinates to view coordinates. Subclasses of viewport that support "logical coordinates" will override this method.
      Parameters:
      p - aPoint object using pixel coordinates
      Returns:
      aPoint object converted to view coordinates

    • setExtentSize

      public void setExtentSize(Dimension newExtent)
      Sets the size of the visible part of the view using view coordinates.
      Parameters:
      newExtent - aDimension object specifying the size of the view

    • createViewListener

      protected JViewport.ViewListener createViewListener()
      Creates a listener for the view.
      Returns:
      aViewListener

    • createLayoutManager

      protected LayoutManager createLayoutManager()
      Subclassers can override this to install a different layout manager (ornull) in the constructor. Returns theLayoutManager to install on theJViewport.
      Returns:
      aLayoutManager

    • addChangeListener

      public void addChangeListener(ChangeListener l)
      Adds aChangeListener to the list that is notified each time the view's size, position, or the viewport's extent size has changed.
      Parameters:
      l - theChangeListener to add
      See Also:

    • removeChangeListener

      public void removeChangeListener(ChangeListener l)
      Removes aChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.
      Parameters:
      l - theChangeListener to remove
      See Also:

    • getChangeListeners

      public ChangeListener[] getChangeListeners()
      Returns an array of all theChangeListeners added to this JViewport with addChangeListener().
      Returns:
      all of theChangeListeners added or an empty array if no listeners have been added
      Since:
      1.4

    • fireStateChanged

      protected void fireStateChanged()
      Notifies allChangeListeners when the views size, position, or the viewports extent size has changed.
      See Also:

    • repaint

      public void repaint(long tm, int x, int y, int w, int h)
      Always repaint in the parents coordinate system to make sure only one paint is performed by theRepaintManager.
      Overrides:
      repaint in class JComponent
      Parameters:
      tm - maximum time in milliseconds before update
      x - thex coordinate (pixels over from left)
      y - they coordinate (pixels down from top)
      w - the width
      h - the height
      See Also:

    • paramString

      protected String paramString()
      Returns a string representation of thisJViewport. 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 benull.
      Overrides:
      paramString in class JComponent
      Returns:
      a string representation of thisJViewport

    • firePropertyChange

      protected void firePropertyChange(String propertyName,Object oldValue,Object newValue)
      Notifies listeners of a property change. This is subclassed to update thewindowBlit property. (TheputClientProperty property is final).
      Overrides:
      firePropertyChange in class Component
      Parameters:
      propertyName - a string containing the property name
      oldValue - the old value of the property
      newValue - the new value of the property

    • getAccessibleContext

      public AccessibleContext getAccessibleContext()
      Gets the AccessibleContext associated with this JViewport. For viewports, the AccessibleContext takes the form of an AccessibleJViewport. A new AccessibleJViewport instance is created if necessary.
      Specified by:
      getAccessibleContext in interface Accessible
      Overrides:
      getAccessibleContext in class Component
      Returns:
      an AccessibleJViewport that serves as the AccessibleContext of this JViewport