|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Provides access to members that control Screen Display.
The IScreenDisplay interface manages the display attributes of a screen. IScreenDisplay also handles other issues specific to windows including the backing store, scrolling, and invalidation.
Two objects currently implement IScreenDisplay, AppDisplay and ScreenDisplay. Each object's implementation of IScreenDisplay is slightly different; look at the help for a particular member for more details.
| Method Summary | |
short |
addCache()
Creates a new cache and return its ID. |
void |
doScroll(int xDelta,
int yDelta,
boolean updateScreen)
Scrolls the screen by the specified amount. |
void |
drawCache(int hDC,
short index,
tagRECT deviceRect,
tagRECT cacheRect)
Draws the specified screen cache to the specified window device context. |
short |
getActiveCache()
Screen cache where drawing occurs. |
short |
getCacheCount()
Number of screen caches. |
int |
getCacheMemDC(short index)
Memory device context for the specified screen cache. |
ITrackCancel |
getCancelTracker()
Cancel tracker that is associated with the display. |
int |
getHWnd()
Associated window handle. |
int |
getWindowDC()
Device context for the associated window. |
void |
invalidate(IEnvelope rect,
boolean erase,
short cacheIndex)
Cause the specified area of the specified cache to redraw. |
boolean |
isCacheDirty(short cacheIndex)
Indicates if the specified cache needs refreshing. |
boolean |
isFirstCacheTransparent()
Indicates if the bottom cache is transparent. |
boolean |
isFramed()
Indicates if drawing occurs in a frame rather than on the whole window. |
boolean |
isScaleContents()
Indicates if the contents of the screen scale when a resize occurs. |
boolean |
isSuppressResize()
Indicates if display resizing is suppressed. |
boolean |
isUseScrollbars()
Indicates if scrollbars should appear. |
void |
panMoveTo(IPoint mouseLocation)
Pans to a new point. |
void |
panStart(IPoint mouseLocation)
Prepares display for panning. |
IEnvelope |
panStop()
Stops panning and returns new visible bounds. |
void |
removeAllCaches()
Removes all caches. |
void |
removeCache(short cacheID)
Removes the specified cache. |
void |
rotateMoveTo(IPoint pPoint)
Rotates to new point. |
void |
rotateStart(IPoint mousePt,
IPoint centerPt)
Prepares display for rotating. |
double |
rotateStop()
Stops rotating and returns new angle. |
void |
rotateTimer()
Draws the rotated display. |
void |
setActiveCache(short index)
Screen cache where drawing occurs. |
void |
setCancelTrackerByRef(ITrackCancel cancelTracker)
Cancel tracker that is associated with the display. |
void |
setHWnd(int hWnd)
Associated window handle. |
void |
setIsFirstCacheTransparent(boolean flag)
Indicates if the bottom cache is transparent. |
void |
setIsFramed(boolean flag)
Indicates if drawing occurs in a frame rather than on the whole window. |
void |
setScaleContents(boolean flag)
Indicates if the contents of the screen scale when a resize occurs. |
void |
setScrollbarHandles(int hWndHorzScrollbar,
int hWndVertScrollbar)
Optionally specify application supplied scrollbars. |
void |
setSuppressResize(boolean suppressResize)
Indicates if display resizing is suppressed. |
void |
setUseScrollbars(boolean flag)
Indicates if scrollbars should appear. |
void |
startRecording()
Starts recording all output to the recording cache. |
void |
stopRecording()
Stops recording to the recording cache. |
void |
trackPan()
Interactively pans the screen. |
void |
trackRotate()
Interactively rotates the screen. |
void |
updateWindow()
Forces a redraw. |
| Methods inherited from interface com.esri.arcgis.display.IDisplay |
drawMultipoint, drawPoint, drawPolygon, drawPolyline, drawRectangle, drawText, finishDrawing, getClipEnvelope, getClipEnvelopes, getClipGeometry, getDisplayTransformation, getFilter, getHDC, getHPalette, getIlluminationProps, isSuppressEvents, progress, setClipGeometry, setDisplayTransformation, setFilterByRef, setHPalette, setIlluminationProps, setSuppressEvents, setSymbol, startDrawing |
| Method Detail |
public void setHWnd(int hWnd)
throws java.io.IOException,
AutomationException
hWnd - The hWnd (A COM typedef) (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public int getHWnd()
throws java.io.IOException,
AutomationException
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public int getWindowDC()
throws java.io.IOException,
AutomationException
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 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.
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public short addCache()
throws java.io.IOException,
AutomationException
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.
The AppDisplay object has no implementation for this method.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void removeCache(short cacheID)
throws java.io.IOException,
AutomationException
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.
The AppDisplay object has no implementation for this method.
cacheID - The cacheID (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public short getCacheCount()
throws java.io.IOException,
AutomationException
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.
The AppDisplay object has no implementation for this method.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void removeAllCaches()
throws java.io.IOException,
AutomationException
Use this property to clear all of the screen caches the current object has. For example, when a Map is deactivated (IActiveView::Deactivate) it uses this property to remove all of its caches.
The AppDisplay object has no implementation for this method.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public int getCacheMemDC(short index)
throws java.io.IOException,
AutomationException
Each cache is an offscreen bitmap. Use this property to retrieve the device context (hDc) for the bitmap associated with a particular cache. With the hDc you can, for example, draw the bitmap (cache) in a particular window using DrawCache.
index - The index (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setActiveCache(short index)
throws java.io.IOException,
AutomationException
index - The index (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public short getActiveCache()
throws java.io.IOException,
AutomationException
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setIsFirstCacheTransparent(boolean flag)
throws java.io.IOException,
AutomationException
flag - The flag (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isFirstCacheTransparent()
throws java.io.IOException,
AutomationException
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void startRecording()
throws java.io.IOException,
AutomationException
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.
VARIANT_BOOL isCacheDirty;
m_ipScreen->IsCacheDirty(esriScreenRecording, &isCacheDirty);
if (isCacheDirty) // draw from scratch
{
m_ipScreen->StartRecording();
m_ipScreen->StartDrawing((OLE_HANDLE)hPaintDC, esriNoScreenCache);
DrawContents();
m_ipScreen->FinishDrawing();
m_ipScreen->StopRecording();
}
else // draw from offscreen bitmap
{
m_ipScreen->DrawCache((OLE_HANDLE)hPaintDC, esriScreenRecording, 0, 0);
}
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void stopRecording()
throws java.io.IOException,
AutomationException
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.
VARIANT_BOOL isCacheDirty;
m_ipScreen->IsCacheDirty(esriScreenRecording, &isCacheDirty);
if (isCacheDirty) // draw from scratch
{
m_ipScreen->StartRecording();
m_ipScreen->StartDrawing((OLE_HANDLE)hPaintDC, esriNoScreenCache);
DrawContents();
m_ipScreen->FinishDrawing();
m_ipScreen->StopRecording();
}
else // draw from offscreen bitmap
{
m_ipScreen->DrawCache((OLE_HANDLE)hPaintDC, esriScreenRecording, 0, 0);
}
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setUseScrollbars(boolean flag)
throws java.io.IOException,
AutomationException
flag - The flag (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isUseScrollbars()
throws java.io.IOException,
AutomationException
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setScrollbarHandles(int hWndHorzScrollbar,
int hWndVertScrollbar)
throws java.io.IOException,
AutomationException
hWndHorzScrollbar - The hWndHorzScrollbar (A COM typedef) (in)hWndVertScrollbar - The hWndVertScrollbar (A COM typedef) (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setScaleContents(boolean flag)
throws java.io.IOException,
AutomationException
flag - The flag (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isScaleContents()
throws java.io.IOException,
AutomationException
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setSuppressResize(boolean suppressResize)
throws java.io.IOException,
AutomationException
suppressResize - The suppressResize (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isSuppressResize()
throws java.io.IOException,
AutomationException
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isFramed()
throws java.io.IOException,
AutomationException
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setIsFramed(boolean flag)
throws java.io.IOException,
AutomationException
flag - The flag (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public ITrackCancel getCancelTracker()
throws java.io.IOException,
AutomationException
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void setCancelTrackerByRef(ITrackCancel cancelTracker)
throws java.io.IOException,
AutomationException
cancelTracker - A reference to a com.esri.arcgis.system.ITrackCancel (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void invalidate(IEnvelope rect,
boolean erase,
short cacheIndex)
throws java.io.IOException,
AutomationException
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:
0 - esriViewNone
1 - esriViewBackground
2 - esriViewGeography
4 - esriViewGeoSelection
8 - esriViewGraphics
16 - esriViewGraphicSelection
32 - esriviewForeground
You can also specify esriAllScreenCaches, esriNoScreenCache, and esriScreenRecording.
Invalidate sets the cache(s) as dirty. Use IsCacheDirty to check the state of a particular cache.
After completion, Invalidate fires the IDisplayEvents::DisplayInvalidated event.
IActiveView::PartialRefresh has similar parameters and itself calls Invalidate. Use this method instead as much as possible as it automatically determines the cache index based on the phase provided.
rect - A reference to a com.esri.arcgis.geometry.IEnvelope (in)erase - The erase (in)cacheIndex - The cacheIndex (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public boolean isCacheDirty(short cacheIndex)
throws java.io.IOException,
AutomationException
cacheIndex - The cacheIndex (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void drawCache(int hDC,
short index,
tagRECT deviceRect,
tagRECT cacheRect)
throws java.io.IOException,
AutomationException
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.
Use the CacheMemDC property to get the desired cache's hDC.
hDC - The hDC (A COM typedef) (in)index - The index (in)deviceRect - A Structure: com.esri.arcgis.display.tagRECT (in)cacheRect - A Structure: com.esri.arcgis.display.tagRECT (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void doScroll(int xDelta,
int yDelta,
boolean updateScreen)
throws java.io.IOException,
AutomationException
ArcMap's scroll bars call this method to scroll the current display. The updateScreen parameter specifies whether or not the display will be refreshed after the scroll.
xDelta - The xDelta (in)yDelta - The yDelta (in)updateScreen - The updateScreen (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void trackPan()
throws java.io.IOException,
AutomationException
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void panStart(IPoint mouseLocation)
throws java.io.IOException,
AutomationException
Call PanStart to initiate panning. The required point parameter specifies the pan's starting point. Call PanMoveTo next to specify a destination point.
The typical sequence for using the pan methods is as follows:
See TrackPan for an alternative panning approach.
mouseLocation - A reference to a com.esri.arcgis.geometry.IPoint (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void panMoveTo(IPoint mouseLocation)
throws java.io.IOException,
AutomationException
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.
The typical sequence for using the pan methods is as follows:
See TrackPan for an alternative panning approach.
mouseLocation - A reference to a com.esri.arcgis.geometry.IPoint (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public IEnvelope panStop()
throws java.io.IOException,
AutomationException
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.
The typical sequence for using the pan methods is as follows:
See TrackPan for an alternative panning approach.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.IActiveView.setExtent(com.esri.arcgis.geometry.IEnvelope)
public void trackRotate()
throws java.io.IOException,
AutomationException
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.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
public void rotateStart(IPoint mousePt,
IPoint centerPt)
throws java.io.IOException,
AutomationException
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.
The typical sequence for using the rotate methods is as follows:
See TrackRotate for an alternative rotating approach.
mousePt - A reference to a com.esri.arcgis.geometry.IPoint (in)centerPt - A reference to a com.esri.arcgis.geometry.IPoint (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.Rotate
public void rotateMoveTo(IPoint pPoint)
throws java.io.IOException,
AutomationException
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.
The typical sequence for using the rotate methods is as follows:
See TrackRotate for an alternative rotating approach.
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.Rotate
public void rotateTimer()
throws java.io.IOException,
AutomationException
RotateTimer shows the rotation degree readout and repaints the display from cache.
The typical sequence for using the rotate methods is as follows:
See TrackRotate for an alternative rotating approach.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.Rotate
public double rotateStop()
throws java.io.IOException,
AutomationException
RotateStop returns the final rotation angle. You must call IDisplayTransformation::Rotation with the final rotation angle to actually rotate the display.
The typical sequence for using the rotate methods is as follows:
See TrackRotate for an alternative rotating approach.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.Rotate
public void updateWindow()
throws java.io.IOException,
AutomationException
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.
See UpdateWindow in MSDN for more information.
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||