Remarks

The ScreenDisplay object is a display device that is associated with a window. In addition to managing the display attributes for the screen, a ScreenDisplay also manages other issues specific to windows including backing stores (caches), scrolling, and invalidation.

Several objects manage (CoCreate) a ScreenDisplay object to help control their associated window. For example, each active view, Map and PageLayout, has its own associated ScreenDisplay and so does the MapInsetWindow. The AppDisplay object does not instantiate a new ScreenDisplay object; instead, this object implements the IScreenDisplay interface which is also what the ScreenDisplay object does.

A reference to a ScreenDisplay object is typically obtained via IActiveView::ScreenDisplay for the active views or ILensWindow::ScreenDisplay for the MapInsetWindow.

The ScreenDisplay object is CoCreateable; one case when you may have to create a new ScreenDisplay object, is when creating a custom active view.

The ScreenDisplay object listens for and reacts to the following keyboard and mouse actions:

Mouse-Wheel: Pan up and down the displayCntrl Mouse-Wheel : Zoom in and out of the displayPage Up Key : Pan up the displayPage Down Key : Pan down the displayHome Key : Pan to the far left of the display extentEnd Key : Pan to the far right of the display extent

getHWnd

Remarks

The hWnd property tells ScreenDisplay objects which window to draw in. When a new view (a Map or PageLayout) is created and activated (IActiveView::Activate), a related ScreenDisplay is created and its hWnd is set to that of the main application. Data windows, such as the MapInsetWindow, also have a related ScreenDisplay object and in this case the ScreenDisplay's hWnd property is set so that all drawing will occur in the data window and not the main application window.

Several Windows API calls require an hWnd in order to perform their operation; this property provides the hWnd for the ScreenDisplay object you are currently working with. For example, several of ArcMap's zoom commands use the Windows API function 'GetClientRect' to get the coordinates of the main window's client area. GetClientRect requires the hWnd of the window of interest and in ArcMap's case, IScreenDisplay::hWnd holds this.

getWindowDC

Device context for the associated window. Only use this between calls to StartDrawing and FinishDrawing.

Remarks

This property is a Windows operating environment device context handle. The Windows operating environment manages the system display by assigning a device context for each window in the application. You can use the WindowDC property to refer to the handle for an object's device context.

This property doesnot provide a value to pass to IDisplay::StartDrawing. Instead, call IDisplay::StartDrawing with a value of 0 for the hDC as this will automatically use the Windows API function GetDC to populate IScreenDisplay::WindowDC with the hDC of the main display and drawing will occur there.

The value of the WindowDC property can change while an application runs, so do not store the value in a variable; instead, use the WindowDC property each time you need it.

addCache

Creates a new cache and return its ID. The ID can be specified to StartDrawing to direct output to the cache. It can also be used with a number of other methods such as DrawCache and Invalidate.

Remarks

ScreenDisplay objects make 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 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, a Map object 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.

removeCache

Remarks

Use this method to remove a cache that is no longer needed. For example, calling the IActiveView::PartialRefresh method on a Map object will delete the Map's selection cache if one exists and there are no features selected.

getCacheCount

Remarks

Use this property to loop through all of the available screen caches. For example, if you Invalidate using esriAllScreenCaches, this property is used to loop through all of the caches to invalidate each one.

startRecording

Remarks

In addition to the caches clients create, the ScreenDisplay object also provides a recording cache that accumulates all drawing that happens on the display. This recording cache is used to redraw the application when the application is moved or exposed or when drawing rubber banding.

Note, StartRecording and StopRecording are exposed for developers creating custom applications that draw from multiple caches and need to refresh quickly. If you are working with ArcMap or even the Map object, leave all cache management up to the Map.

Use StartRecording to let the display know exactly what to record. Use DrawCache(esriScreenRecording) to display the recording cache. Use CacheMemDC(esriScreenRecording) to get a handle to the memory device context for the recording bitmap.

The following C++ code excerpt is a drawing sequence example that uses StartRecording.

stopRecording

Remarks

In addition to the caches clients create, the ScreenDisplay object also provides a recording cache that accumulates all drawing that happens on the display. This recording cache is used to redraw the application when the application is moved or exposed or when drawing rubber banding.

Note, StartRecording and StopRecording are exposed for developers creating custom applications that draw from multiple caches and need to refresh quickly. If you are working with ArcMap or even the Map object, leave all cache management up to the Map.

Use StartRecording to let the display know exactly what to record. Use DrawCache(esriScreenRecording) to display the recording cache. Use CacheMemDC(esriScreenRecording) to get a handle to the memory device context for the recording bitmap.

The following C++ code excerpt is a drawing sequence example that uses StartRecording.

isUseScrollbars

Remarks

IActiveView::ShowScrollBars redirects all its calls to this property.

Changes to this property are not reflected until the active view changes. For example, when in layout view in ArcMap, programmatically changing the PageLayout to not show its scrollbars will have no effect until the next time the active view is set to the PageLayout; calling IActiveView::Refresh has no effect.

ArcMap uses this property to hide the Map's scroll bars when in layout view. Programmatically trying to display a Map's scroll bar in layout view will have no effect; for Map's this setting is only honored in data view and again it requires an active view change before the setting is reflected in the applications window.

isScaleContents

Indicates if the contents of the screen scale when a resize occurs. True means scale contents to fit new window size. False means contents stays the same with more or less of it showing.

Remarks

If a Map's ScaleContents property is set to TRUE, when its display is resized, the area shown stays the same and the scale changes. When set to FALSE, the scale of the Map stays the same and the area shown changes.

The PageLayout object works similarly. If set to TRUE, the contents are stretched when the display is resized. The scale of all maps changes. When set to FALSE, the page remains the same size.

In ArcMap, on the Tools/Options menu, there are check boxes for controlling this property for the data and layout view.

isFramed

Indicates if drawing occurs in a frame rather than on the whole window.

Remarks

When creating a custom application, if you want the display to take over the window it's drawing in, set IsFramed to FALSE. This will add scrollbars (IScreenDisplay::UseScrollBars = TRUE) as necessary and keeps the device frame in sync with the window extent. Setting IsFramed to TRUE means that the display is drawing on some extent within the window. In this case, it won't show scrollbars and it won't automatically update the device frame.

For example, in the ArcMap application, in layout view where each Map resides inside a separate MapFrame, each Map has it IsFramed property set to TRUE. In data view, the opposite is true, a Map's display fits the entire window; in this view, all Map's have IsFramed set to FALSE, not just the focus map.

The IsFramed property also sets the IsFirstCacheTransparent property. When a Map is drawing in layout view, the PageLayout object has its ScreenDisplay and each Map has its own separate ScreenDisplay. This means that the layout has it's display cache(s) and the maps have their own. If the bottom cache of each map was opaque, you wouldn't be able to see through a map onto layout elements below it. Setting IsFirstCacheTransparent on the maps in layout view lets you see through the maps.

If you are working with Map's inside of ArcMap these settings should not be touched. Only use this property when building a low level application that uses a display to draw on a frame on a window.

invalidate

Remarks

Use Invalidate to refresh a specific region on the display. For example, if you add a new feature, only the extent of the new feature requires refreshing; the remainder of the display can redraw from cache.

The rect parameter specifies the region to update. Use 'Nothing' in Visual Basic or a zero in C++ to invalidate the entire display.

Erase specifies whether or not the background within the update region is erased when the update region is processed. Usually this is set to TRUE.

CacheIndex controls which cache to update. Use IActiveView::ScreenCacheID to get the cache index for a specific draw phase. The valid draw phases are held in the esriViewDrawPhase enumeration and are as follows:

drawCache

Draws the specified screen cache to the specified window device context. Pass an empty rectangle to copy the full bitmap to the DC origin.

Remarks

Redrawing data from scratch is time consuming compared to drawing data that has been cached in an off-screen bitmap. If a particular cache return FALSE for IsCacheDirty, use DrawCache to instantly redraw the bitmap.

trackPan

Remarks

There are two approaches to panning - this method, and the group PanStart, PanMoveTo, and PanStop. This method is the easiest to use as it takes care of all the mouse events and refreshing the display when pan is complete.

Call this method in the mouse down event and make certain you have a reference to the correct ScreenDisplay object. For example, if you are in layout view and you want to pan just the focus map, do not use the ScreenDisplay object associated with IMxDocument::ActiveView. Instead, get the focus Map via IMxDocument::FocusMap, and then get its ScreenDisplay.

panMoveTo

Remarks

PanMoveTo pans the display by calculating an offset distance between the start point supplied to PanStart and the destination point provided to this method. The recording cache is automatically redrawn each time PanMoveTo is called. Use the envelope PanStop returns to truly refresh the display.

panStop

Remarks

PanStop creates an Envelope that should be used to reset the extent of the active view. Because PanMoveTo redraws only the recording cache (bitmap), there are typically blank areas in the display. Call IActiveView::Refresh after calling PanStop to invalidate the entire display.

trackRotate

Remarks

There are two approaches to rotating the display - this method and the group RotateStart, RotateMoveTo, RotateTimer, and RotateStop. This method is the easiest to use as it takes care of all the mouse events automatically, performs the final display rotation, and invalidates the display.

Call this method in the mouse down event and make certain you have a reference to the correct ScreenDisplay object. For example, if you are in layout view and you want to pan just the focus map, do not use the ScreenDisplay object associated with IMxDocument::ActiveView. Instead, get the focus Map via IMxDocument::FocusMap, and then get its ScreenDisplay.

rotateStart

Prepares display for rotating. If centerPt is NULL, the center of the visible bounds is used.

Remarks

Call RotateStart to initiate rotating the display. The required point parameter specifies the starting point of the rotation. Call RotateMoveTo next to specify the rotation destination point, a rotation angle is calculated based on these two points.

rotateMoveTo

Remarks

RotateMoveTo rotates the display based on the calculated angle between the start point supplied to RotateStart and the destination point provided to this method. Next call RotateTimer to show the rotation degree readout and repaint the display from cache.

updateWindow

Remarks

Use UpdateWindow to process pending Windows WM_PAINT messages immediately. This may be the case if you have a routine that takes a long time to execute and you need the window to refresh while the code executes. Typically, no drawing will occur until all your code has been executed and control returns to the ArcMap's message loop and the WM_PAINT message is handled. UpdateWindow forces the window to invalidate by sending a WM_PAINT message directly to the window; the normal ArcMap message queue is bypassed.

getDisplayTransformation

Remarks

Each display object, like ScreenDisplay for example, manages (CoCreates) a DisplayTransformation object to convert coordinates between map units and device units. Use this property to get a reference to the DisplayTransformation object associated with this display.

getClipEnvelope

The bounds of the invalid region. Use after StartDrawing and before FinishDrawing.

Remarks

The ClipEnvelope is the is the display transformation's fitted bounds (IDisplayTransformation::FittedBounds) intersected with the ClipGeometry if one exists.

This property is mostly used during drawing operations, for example, IDisplay's drawing functions clip (ITopologicalOperator::Clip) the object they are drawing against the ClipEnvelope to ensure that only the visible parts of the object are drawn.

getClipGeometry

User-specified clip shape. This shape is merged with the invalid region to arrive at the actual clip region. Must be specified before StartDrawing.

Remarks

Use the ClipGeometry property to shape the area data is drawn in. For example, if you had a map of the United States that contained many layers, you could set the ClipGeometry property on the focus Map's ScreenDisplay object equal to the geometry of a particular state thereby telling the map to only draw the data falling within the particular state's area. The ClipGeometry is used to cookie-cut all data before it is drawn.

startDrawing

Prepare the display for drawing. Specify the device context and the cache to draw to (normally esriNoScreenCache). The ScreenDisplay coclass will automatically create a window device context if you specify hdc = 0.

Remarks

StartDrawing and FinishDrawing are used to manage clipping, symbols, and caching. Call StartDrawing and FinishDrawing anytime you want to draw to a device such as a display, printer, or cache (bitmap). However, if you are drawing in response to IActiveViewEvents::AfterDraw, the Map object automatically makes these calls for you.

StartDrawing has two parameters: hDc and cacheID. The hDc parameter specifies the target device where drawing will occur, usually a display, printer, or bitmap. The cacheID parameter activates a specific cache. In most cases, esriNoScreenCache should be used.

Specifying a cache sets it as the screen's active cache. When esriNoScreenCache is used, it sets the display's active cache to zero and drawing occurs directly in the device. Specify a cache when you don't want to draw to a screen directly and you instead want to draw to a cache (bitmap) that may ultimately be copied to the screen. For example, when ArcMap draws geography, it draws it to a specific cache and then the cache is copied to the screen. When the screen repaints, instead of drawing all the data from scratch again, the software checks if the cache is dirty or not and simply redraws the bitmap to save time if it can. When drawing to a cache, the hDc parameter should be the device context of the bitmap, use the IScreenDisplay::CacheMemDC property to get a particular cache's hDC.

Each time you need to change the cache you are drawing to, you must do so inside a new StartDrawing / FinishDrawing block. For example, ArcMap usually creates three caches: one for geography layers, one for graphics and annotation, and one for selections. ArcMap draws each of these phases within a separate StartDrawing / FinishDrawing block.

There are times when may need to draw shapes directly to screen without having them become part of a display cache. For example, drawing moving objects. In these cases, use IScreenDisplay::WindowDC to get the device context of the display and esriNoScreenCache as the cacheID.

If a zero is specified for the hDc parameter, the Windows API function GetDC is used to populate IScreenDisplay::WindowDC with the hDC of the main display and drawing is sent here.

As mentioned above, if you drawing in response to the IActiveView::AfterDraw event, the Map object calls StartDrawing and StopDrawing for you. Also, if the draw phase you are drawing after is cached, your drawings will be cached as well.

getHDC

The device context that the display is currently drawing to. Only valid between calls to StartDrawing and FinishDrawing.

Remarks

Returns the device context specified to StartDrawing. This may be the device context of a display, cache (bitmap), or some other device such as a printer. As StartDrawing is called frequently throughout the drawing pipeline, the hDc property continually changes and is therefore safe to use only within a single StartDrawing / FinishDrawing block.

This property does not provide a value to pass to IDisplay::StartDrawing. Instead, call IDisplay::StartDrawing with a value of 0 for the hDC as this will automatically use the Windows API function GetDC to populate IScreenDisplay::WindowDC with the hDC of the main display and drawing will occur there.

drawPoint

Remarks

DrawPoint draws a Point object with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.

drawMultipoint

Remarks

DrawMultipoint draws a Multipoint object with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.

drawRectangle

Remarks

DrawRectangle draws a Envelope object with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.

drawPolyline

Remarks

DrawPolyline draws a Polyline object with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.

drawPolygon

Remarks

DrawPolygon draws a Polygon object with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.

drawText

Remarks

DrawText draws a text string with the symbol that must be specified before hand with the SetSymbol method. All draw methods must be enclosed between the calls to StartDrawing and FinishDrawing unless you are drawing in response to the IActiveViewEvents::AfterDraw event.