Display events


Summary
This topic describes the events that are fired when a map draws. To provide better insight into drawing events, drawing order and display caching are also discussed.

In this topic


Drawing order

To better understand the events that are fired when a map draws, the following describes the order in which objects are drawn for each view (Map and PageLayout):
Object
Phase
Cache
Graphic selection esriViewForeground none
Clip border esriViewForeground none
Feature selection esriViewGeoSelection selection
Auto labels esriViewGraphics annotation
Graphics esriViewGraphics annotation
Layer annotation esriViewGraphics annotation
Layers esriViewGeography layer or layers
Background esriViewBackground bottom layer
Object
Phase
Cache
Snap guides esriViewForeground none
Selection esriViewGraphicSelection selection
Elements esriViewGraphics element
Snap grid esriViewBackground element
Print margins esriViewBackground element
Paper esriViewBackground element

Drawing events

The following IActiveViewEvents can be used to add custom drawing to your application:
The AfterDraw event is fired after every phase of drawing. Do the following to draw a graphic into a cache:
  1. Create an object that connects to the active view (map); for example, Events.
  2. Choose the draw phase that you want to draw after. The phase you choose determines what is drawn above and below you.
  3. Draw in response to IActiveViewEvents.AfterDraw.
Not all the views fire all the events. Additionally, if a view is partially refreshed, the phases that draw from cache do not fire their AfterDraw event. For example, if the selection is refreshed, all the layers draw from cache. As a result, the AfterDraw(esriViewGeography) event does not fire; however, there is an exception. In the case of esriViewForeground, the event is fired every time the view draws. Even if everything in the map draws from the recording cache, the foreground event still fires.
Enabling item events with VerboseEvents
The AfterItemDraw event is fired after each feature or graphic is displayed and can seriously impact drawing performance if a connected handler is not efficient. Normally, clients connect to the AfterDraw event.
It is important to check the second argument and respond to the appropriate phase of drawing since the AfterDraw routine will be called several times when the map is drawn.
For efficiency, IActiveView has a VerboseEvents property. It can be used to limit the number of events that are fired. If VerboseEvents = false, AfterItemDraw is not fired (this is the default setting).

Events and display caching

The following tables show the handle device context (HDC) that is active when each of the AfterDraw events is fired:
Event
Active HDC
esriViewForeground window
esriViewGraphics annotation cache
esriViewGeoSelection selection cache
esriViewGeography top layer cache
esriViewBackground bottom layer cache
Event
Active HDC
esriViewForeground window
esriViewGraphicSelection selection cache
esriViewGraphics element cache
esriViewBackground element cache

Creating a private cache

For drawing graphics (events), you may want to use esriViewGraphics. AfterDraw has two arguments: pDisplay and drawPhase. It is called for each of the phases, so make sure you only draw when your phase is specified. Draw directly to the display and do not worry about caches. The StartDrawing and FinishDrawing methods are called by map. If the phase you are drawing after is cached, your drawing is automatically cached. See the following:
[Java]
IActiveView pActiveView = (IActiveView)map;
IScreenDisplay pScreen = pActiveView.getScreenDisplay();
short myCacheID = pScreen.addCache();
  • AfterDraw looks like the following code example:
[Java]
if (phase != esriViewXXX)
    return ;

IScreenDisplay pScreen = display;

if (pScreen != null){
    // Draw directly to output device
    drawMyStuff(display);
    return ;
}

// Draw to screen using cache if possible
int hWindowDC = pScreen.getWindowDC();

boolean dirty = pScreen.isCacheDirty(myCacheID);
if (dirty){
    // draw from scratch
    pScreen.finishDrawing();
    pScreen.startDrawing(hWindowDC, (short)myCacheID);
    drawMyStuff(display);
}

else{
    // draw from cache
    pScreen.drawCache(hWindowDC, (short)myCacheID, null, null);
}

Transform events

The ITransformEvents interface provides access to display transformation events. ITransformEvents have their counterparts in the properties of the IDisplayTransformation.

For instance, ITransformEvents.BoundsUpdated is fired when IDisplayTransformation.Bounds is set. For information on these properties and the related ITransformEvents, refer to the documentation for IDisplayTransformation. See the following illustration:
 
One scenario in which ITransformEvents may be useful is the case of implementing a custom graphic element. By sinking the outbound ITransformEvents interface of the DisplayTransformation, you can update the custom element to reflect changes, such as the data frame being rotated. You can also use ITransformEvents to update the element's selection tracker geometry correctly when the map scale changes.






Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced
Engine Developer KitEngine