ArcObjects Library Reference  (Carto)    

IActiveView.PartialRefresh Method

Draws the specified view phase. Use an envelope of zero to draw the entire phase.

[Visual Basic 6.0]
Sub PartialRefresh(
    ByVal phase As esriViewDrawPhase, _
    ByVal Data As Unknown, _
    ByVal envelope As IEnvelope _
)
[Visual Basic .NET]
Public Sub PartialRefresh ( _
    ByVal phase As esriViewDrawPhase, _
    ByVal Data As Object, _
    ByVal envelope As IEnvelope _
)
[C#]
public void PartialRefresh (
    esriViewDrawPhase phase,
    object Data,
    IEnvelope envelope
);
[Java]
public void partialRefresh (
    esriViewDrawPhase phase,
    Object Data,
    IEnvelope envelope
)
throws
    IOException,
    AutomationException
[C++]
HRESULT PartialRefresh(
  esriViewDrawPhase phase,
  LPUNKNOWN Data,
  IEnvelope* envelope
);
[C++]

Parameters

phase [in]

  phase is a parameter of type esriViewDrawPhase

Data [in]

  Data is a parameter of type LPUNKNOWN

envelope [in]

  envelope is a parameter of type IEnvelope

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Remarks

The main application window is controlled by a view (IActiveView).  ArcMap currently has two view objects: Map (data view) and PageLayout (layout view).  Each view has a ScreenDisplay object which performs drawing operations. The ScreenDisplay object also makes it possible for clients to create any number of caches.  A cache is an off screen bitmap representing the application's window.  Instead of drawing directly to the screen, graphics are drawn into caches, then the caches are drawn on the screen.  When the application's window is obscured and requires redrawing, it is done so from the caches instead of from a database.  In this way, caches improve drawing performance - bitmap rendering is faster than reading and displaying data from a database.

In general, the Map creates three caches: one for all the layers, another if there are annotation or graphics, and a third cache if there is a feature selection.  A layer can create its own private cache if it sets ILayer::Cached equal to TRUE.  In this case, the Map will create a separate cache for the layer and groups the layers above and below it into different caches.

IActiveView::PartialRefresh uses its knowledge of the cache layout to invalidate as little as possible.  IActiveView::Refresh , on the other hand, invalidates all the caches which is very inefficient.  Use PartialRefresh whenever possible. 

Both PartialRefresh and Refresh call IScreenDisplay::Invalidate which sets a flag clients watch for.  Clients draw a cache from scratch (the database) if its flag is set to true, and from cache if the flag is set to false.

The following table shows the phases each view supports and what they map to:

phase Map Layout
esriViewBackground   Map grids  Page/snap grid
esriViewGeography  Layers Unused
*esriViewGeoSelection  Feature selection Unused
esriViewGraphics   Labels/graphics Graphics
esriViewGraphicSelection  Graphic selection Element selection
esriViewForeground   Unused Snap guides

To specify multiple draw phases, combine individual phases together using a bitwise OR. This is equivalent to adding together the integer enumeration values. For example, pass 6 to invalidate both the esriViewGeography (2) and esriViewGeoSelection (4) phases.

Use the data parameter to invalidate just a specific piece of data.  For example, if a layer is loaded and its cache property is set to TRUE, this layer alone can be invalidated.  A tracking layer is a good example of this.

The envelope parameter specifies a region to invalidate.  For example, if a graphic element is added, it is usually only necessary to invalidate the immediate area surrounding the new graphic.

Both the data and envelope parameters are optional. 

*When selecting features, you must call PartialRefresh twice, once before and once after the selection operation.

[Visual Basic 6.0]

In Visual Basic specify a phase of 6 to invalidate both the esriViewGeography (2) and the esriViewGeoSelection (4). 

  pActiveView.PartialRefresh esriViewGeography + esriViewGeoSelection, Nothing, Nothing 

which is the same as:

  pActiveView.PartialRefresh 6, Nothing, Nothing

Below are several usage examples in Visual Basic.

Map:

Refresh layer          pActiveView.PartialRefresh esriViewGeography, pLayer, Nothing 
Refresh all layers     pActiveView.PartialRefresh esriViewGeography, Nothing, Nothing 
Refresh selection      pActiveView.PartialRefresh esriViewGeoSelection, Nothing, Nothing
Refresh labels         pActiveView.PartialRefresh esriViewGraphics, Nothing, Nothing

PageLayout:

Refresh element        pActiveView.PartialRefresh esriViewGraphics, pElement, Nothing
Refresh all elements   pActiveView.PartialRefresh esriViewGraphics, Nothing, Nothing
Refresh selection      pActiveView.PartialRefresh esriViewGraphicSelection, Nothing, Nothing

The example shows how to select and refresh graphics and features using PartialRefresh.

See Also

IActiveView Interface | IActiveView.ScreenCacheID Property | esriViewDrawPhase Constants | IActiveView.PartialRefresh Method | IActiveView.Refresh Method | IScreenDisplay.Invalidate Method

Example

PartialRefresh Example