站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

Java(TM) 2 Platform, Standard Edition, v1.2.2 API Specification: Class JViewport - JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Standard Edition
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

javax.swing
Class JViewport

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.JViewport
public class JViewport
extends JComponent
implements Accessible

The "viewport" or "porthole" through which you see the underlying information. When you scroll, what moves is the viewport. Its 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.

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 and checked to see if they are JComponents, 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 ancestor Windows graphics and do a copyArea 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 two copyAreas. 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.

To turn this behavior on, put the client property "EnableWindowBlit" (a method will added to enable/disable this in the future).

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. A future release of Swing will provide support for long term persistence.

See Also:
JScrollPane, Serialized Form

Inner Class Summary
protected  class JViewport.AccessibleJViewport
          The class used to obtain the accessible role for this object.
protected  class JViewport.ViewListener
          A listener for the view.
 
Inner classes inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Field Summary
protected  boolean backingStore
          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.
protected  Image backingStoreImage
          The view image used for a backing store.
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.
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Constructor Summary
JViewport()
          Create a JViewport
 
Method Summary
 void addChangeListener(ChangeListener l)
          Add a ChangeListener to the list that's notified each time the view's size, position, or the viewport's extent size has changed.
protected  void addImpl(Component child, Object constraints, int index)
          Sets the Viewport's one lightweight child, which can be null.
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 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()
          Create a listener for the view.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
          Notifies listeners of a property change.
protected  void fireStateChanged()
           
 AccessibleContext getAccessibleContext()
          Get the AccessibleContext associated with this JComponent
 Dimension getExtentSize()
          Returns the size of the visible part of the view in view coordinates.
 Insets getInsets()
          Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on a JViewport.
 Insets getInsets(Insets insets)
          Returns an Insets object containing this JViewport's inset values.
 Component getView()
          Returns the Viewport's one child or null.
 Point getViewPosition()
          Returns the view coordinates that appear in the upper left hand corner of the viewport, 0,0 if there's no view.
 Rectangle getViewRect()
          Return 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()
          Returns true if this viewport is maintaining an offscreen image of its contents.
 boolean isOptimizedDrawingEnabled()
          The JViewport overrides the default implementation of this method (in JComponent) to return false.
 void paint(Graphics g)
          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(Component child)
          Removes the Viewport's one lightweight child.
 void removeChangeListener(ChangeListener l)
          Remove a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.
 void repaint(long tm, int x, int y, int w, int h)
          We always repaint in our parent coordinate system to make sure only one paint is performed by the RepaintManager.
 void reshape(int x, int y, int w, int h)
          Sets the bounds of this viewport.
 void scrollRectToVisible(Rectangle contentRect)
          Overridden to scroll the view so that Rectangle within the view becomes visible.
 void setBackingStoreEnabled(boolean x)
          If true if this viewport will maintain an offscreen image of its contents.
 void setBorder(Border border)
          The viewport "scrolls" it's child (called the "view") by the normal parent/child clipping (typically the view is moved in the opposite direction of the scroll).
 void setExtentSize(Dimension newExtent)
          Set the size of the visible part of the view using view coordinates.
 void setView(Component view)
          Sets the Viewport's one lightweight child (view), which can be null.
 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.
 void setViewSize(Dimension newSize)
          Sets the view coordinates that appear in the upper left hand corner of the viewport, and the size of the view.
 Dimension toViewCoordinates(Dimension size)
          Convert a size in pixel coordinates to view coordinates.
 Point toViewCoordinates(Point p)
          Convert a point in pixel coordinates to view coordinates.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getUIClassID, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isOpaque, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, revalidate, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update, updateUI
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setCursor, setLayout, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

isViewSizeSet

protected boolean isViewSizeSet
True when the viewport dimensions have been determined.

lastPaintPosition

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

backingStore

protected boolean backingStore
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.

backingStoreImage

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

scrollUnderway

protected boolean scrollUnderway
The 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 optimised 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 Viewport class and have the JList manage this case by using setBackingStoreEnabled().
Constructor Detail

JViewport

public JViewport()
Create a JViewport
Method Detail

addImpl

protected void addImpl(Component child,
                       Object constraints,
                       int index)
Sets the Viewport'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.)
Overrides:
addImpl in class Container
Parameters:
child - the Component ______________
constraints - the Object ______________
index - the int ______________
See Also:
setView(java.awt.Component)

remove

public void remove(Component child)
Removes the Viewport's one lightweight child.
Overrides:
remove in class Container
See Also:
setView(java.awt.Component)

scrollRectToVisible

public void scrollRectToVisible(Rectangle contentRect)
Overridden to scroll the view so that Rectangle within the view becomes visible.
Overrides:
scrollRectToVisible in class JComponent
Parameters:
contentRect - the Rectangle to display

setBorder

public final void setBorder(Border border)
The viewport "scrolls" it's 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 a JViewport with a border, add it to a JPanel that has a border.
Overrides:
setBorder in class JComponent
Parameters:
border - the Border to set

getInsets

public final Insets getInsets()
Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on a JViewport.
Overrides:
getInsets in class JComponent
Returns:
new Insets(0, 0, 0, 0)
See Also:
setBorder(javax.swing.border.Border)

getInsets

public final Insets getInsets(Insets insets)
Returns an 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.
Overrides:
getInsets in class JComponent
Parameters:
insets - the Insets object which can be reused.
See Also:
getInsets()

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
The 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.
Overrides:
isOptimizedDrawingEnabled in class JComponent
Returns:
false

paint

public void paint(Graphics g)
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.
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 - the Graphics context within which to paint

reshape

public void reshape(int x,
                    int y,
                    int w,
                    int h)
Sets the bounds of this viewport. If the viewports width or height has changed, fire a StateChanged 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:
JComponent.reshape(int, int, int, int)

isBackingStoreEnabled

public boolean isBackingStoreEnabled()
Returns true if this viewport is maintaining an offscreen image of its contents.

setBackingStoreEnabled

public void setBackingStoreEnabled(boolean x)
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 the viewPosition. Rather than repainting the entire viewport we use Graphics.copyArea() to effect some of the scroll.

getView

public Component getView()
Returns the Viewport's one child or null.
See Also:
setView(java.awt.Component)

setView

public void setView(Component view)
Sets the Viewport's one lightweight child (view), which can be null.
See Also:
getView()

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:
a Dimension object specifying the size of the view

setViewSize

public void setViewSize(Dimension newSize)
Sets the view coordinates that appear in the upper left hand corner of the viewport, and the size of the view.
Parameters:
newSize - a Dimension object specifying the size and location of the new view coordinates, or null if there is no view

getViewPosition

public Point getViewPosition()
Returns the view coordinates that appear in the upper left hand corner of the viewport, 0,0 if there's no view.
Returns:
a Point 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 - a Point object giving the upper left coordinates

getViewRect

public Rectangle getViewRect()
Return a rectangle whose origin is getViewPosition and size is getExtentSize(). This is the visible part of the view, in view coordinates.
Returns:
a Rectangle 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 contains 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.

getExtentSize

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

toViewCoordinates

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

toViewCoordinates

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

setExtentSize

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

createViewListener

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

createLayoutManager

protected LayoutManager createLayoutManager()
Subclassers can override this to install a different layout manager (or null) in the constructor. Returns a new JViewportLayout object.
Returns:
a LayoutManager

addChangeListener

public void addChangeListener(ChangeListener l)
Add a ChangeListener to the list that's notified each time the view's size, position, or the viewport's extent size has changed.
Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), setViewPosition(java.awt.Point), setViewSize(java.awt.Dimension), setExtentSize(java.awt.Dimension)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Remove a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.
Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int w,
                    int h)
We always repaint in our parent coordinate system to make sure only one paint is performed by the RepaintManager.
Overrides:
repaint in class JComponent
Parameters:
tm - maximum time in milliseconds before update
x - the x coordinate (pixels over from left)
y - the y coordinate (pixels down from top)
width - the width
height - the height
See Also:
Component.update(java.awt.Graphics)

paramString

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

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Notifies listeners of a property change. This is subclassed to update the windowBlit ivar (putClientProperty is final).
Overrides:
firePropertyChange in class JComponent
Tags copied from class: JComponent
Parameters:
propertyName - The programmatic name of the property that was changed.
oldValue - The old value of the property.
newValue - The new value of the property.
See Also:
PropertyChangeSupport

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext associated with this JComponent
Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
the AccessibleContext of this JComponent
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Standard Edition
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
Submit a bug or feature
Java, Java 2D, and JDBC are a trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.