com.esri.arcgis.carto
Interface IActiveView

All Superinterfaces:
Serializable
All Known Implementing Classes:
Globe, Map, PageLayout, Scene

public interface IActiveView
extends Serializable

Provides access to members that control the active view - the main application window.

Remarks

When working with the IActiveView interface on a MapDocument object, you should always first call IActiveView::Activate() in order to properly initialize the display of the PageLayout or Map object. The MxDocument and MapServer objects initialize display objects automatically after opening an MXD, but MapDocument does not do this. If your application has a user interface, you should call Activate() with the hWnd of the application's client area. If your application runs in the background and has no windows, you can always get a valid hWnd from the GDI GetDesktopWindow() function, part of the Win32 API.

When To Use

This interface manages the main application window in ArcMap and all drawing operations.

In ArcMap, two objects implement this interface: PageLayout and Map. These two objects correspond to the two different views in ArcMap: layout and data view. Only one view can be active at a time and this is termed the active view. IMxDocument::ActiveView holds a reference to the current active view object (a Map or the PageLayout). For example, if the ArcMap application is in layout mode, IMxDocument::ActiveView returns an IActiveView reference to the PageLayout object. Alternatively, if the application is in data view, this propery returns a reference to the focus map.

ArcMap has view commands which allow users to toggle between layout view and data view. These commands appear on the View menu and on the scroll bar.

An ArcMap document can contain many Maps. Make sure you have the desired object when working with this interface. Otherwise, operations such as drawing may not be occurring in the application window as you expect. For example, a Map obtained through IMxDocument::Maps is not guaranteed to be the focus map. If you know you want a reference to the focus map, use IMxDocument::FocusMap. Similarly, if you know you want a reference to the page layout, use IMxDocument::PageLayout instead. You can change the document's active view by setting IMxDocument::ActiveView. Learn more by reading the help for this property.



Product Availability

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

See Also:
com.esri.arcgis.carto.IMxDocument

Method Summary
 void activate(int hWnd)
          Gives this view control of the specified window.
 void clear()
          Empties the view contents.
 void contentsChanged()
          Called by clients when view objects are modified.
 void deactivate()
          Another view takes over the associated window.
 void draw(int hDC, ITrackCancel trackCancel)
          Draws the view to the specified device context.
 void getContextMenu(double x, double y, IUID[] clsidMenu)
          Called when a context menu should be displayed at the given xy location.
 tagRECT getExportFrame()
          The device rectangle to export.
 IEnvelope getExtent()
          The visible extent rectangle.
 IExtentStack getExtentStack()
          The extent stack.
 IMap getFocusMap()
          The map that tools and controls act on.
 IEnvelope getFullExtent()
          The full extent rectangle.
 IGraphicsContainer getGraphicsContainer()
          The active graphics container.
 short getScreenCacheID(int phase, Object data)
          The screen cache ID that is used to draw the specified phase.
 IScreenDisplay getScreenDisplay()
          The screen display used by the view.
 ISelection getSelection()
          The selection.
 String getTipText(double x, double y)
          The tip text to display at the given location.
 IMap hitTestMap(IPoint location)
          Returns any maps present in the view at the given location.
 boolean isActive()
          Indicates if view is active or not.
 boolean isMapActivated()
          Indicates if the focus map is activated.
 boolean isShowRulers()
          Indicates if rulers are visible.
 boolean isShowScrollBars()
          Indicates if scrollbars are visible.
 boolean isShowSelection()
          Indicates if selection is visible.
 void onMessage(int msg, int wParam, int lParam)
          Call from your application's message loop to enable automatic resizing and keyboard accelerators.
 void output(int hDC, int dpi, tagRECT pixelBounds, IEnvelope visibleBounds, ITrackCancel trackCancel)
          Renders the view to the specified DC.
 void partialRefresh(int phase, Object data, IEnvelope envelope)
          Draws the specified view phase.
 void printerChanged(IPrinter printer)
          Called by application when printer changes.
 void refresh()
          Causes the entire view to draw.
 void setExtent(IEnvelope extent)
          The visible extent rectangle.
 void setFocusMapByRef(IMap activeMap)
          The map that tools and controls act on.
 void setFullExtent(IEnvelope extent)
          The full extent rectangle.
 void setIsMapActivated(boolean isMapActivated)
          Indicates if the focus map is activated.
 void setSelectionByRef(ISelection selection)
          The selection.
 void setShowRulers(boolean showRulers)
          Indicates if rulers are visible.
 void setShowScrollBars(boolean showScrollBars)
          Indicates if scrollbars are visible.
 void setShowSelection(boolean showRulers)
          Indicates if selection is visible.
 

Method Detail

getFullExtent

IEnvelope getFullExtent()
                        throws IOException,
                               AutomationException
The full extent rectangle.

Remarks

The full extent of the view. In ArcMap's data view, the full extent is the full extent of all layers and it is automatically calculated whenever the spatial reference changes and when layers are added or removed with AddLayer, AddLayers, or DeleteLayer. In layout view, the full extent is the page size expanded some and it is automatically set whenever the page size changes.

This property is a shortcut to the bounds of the ActiveView's ScreenDisplay (accessed via IDisplayTransformation::Bounds) .

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IDisplayTransformation.getBounds(), IDisplayTransformation, IActiveView.getFullExtent()

setFullExtent

void setFullExtent(IEnvelope extent)
                   throws IOException,
                          AutomationException
The full extent rectangle.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
extent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getExtent

IEnvelope getExtent()
                    throws IOException,
                           AutomationException
The visible extent rectangle.

Remarks

The Extent property holds the visible area of the view. The Extent is automatically captured whenever the view's transformation changes. For example, when the active view is a Map, the Extent is modified whenever the spatial reference changes. Also, the Extent is set the first time a layer is added to a Map. In layout view, the Extent is initially set to the page size. In both layout view and data view, zooming in our out changes the Extent.

The Extent is always adjusted to fit the device frame and it is persisted in the map document.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IDisplayTransformation.getVisibleBounds(), ITin.getExtent(), IActiveView.getExtent(), IFeatureClassManage.updateExtent(), IFeatureClassManage, IDisplayTransformation.getFittedBounds()

setExtent

void setExtent(IEnvelope extent)
               throws IOException,
                      AutomationException
The visible extent rectangle.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
extent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getScreenDisplay

IScreenDisplay getScreenDisplay()
                                throws IOException,
                                       AutomationException
The screen display used by the view.

Remarks

Each view has a ScreenDisplay object which controls drawing in the application's window. Use this property to get a reference to the ScreenDisplay object associated with the view you are currently working with. For example, to draw a polygon in data view, you must get an IActiveView reference on the focus Map object and then get a reference to its ScreenDisplay object via this property. If you are in data view and you mistakenly get an IActiveView reference on the PageLayout object, you will not see the polygon as you are drawing in the wrong view.

Each ScreenDisplay object has a DisplayTransformation object which is accessible via IDisplay::DisplayTransformation (ScreenDisplay inherits from Display ). Each DisplayTransformation related to a Map, holds onto the map's spatial reference (IDisplayTransformation::SpatialReference ) and has useful methods for converting between device units and map units. The PageLayout's DisplayTransformation does not have a spatial reference, the property returns nothing, and in this case its members map between device units and page units.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.display.IScreenDisplay
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getGraphicsContainer

IGraphicsContainer getGraphicsContainer()
                                        throws IOException,
                                               AutomationException
The active graphics container.

Remarks

Both the Map and PageLayout objects are graphics containers - both implement the IGraphicsContainer interface.

The Map has a Basics Graphics Layer and this property returns a reference to that object (see CompositeGraphicsLayer and IMap::BasicGraphicsLayer). When working with a Map object, you can also perform a query interface from any of the interfaces the Map implements, IMap for example, to IGraphicsContainer. The QI also takes you to the CompositeGraphicsLayer object. These are both possible because the Map aggregates the Basic Graphics Layer.

The PageLayout object works differently. The PageLayout does not have a Basics Graphics Layer; instead, the PageLayout object is its own graphics container having its own implementation of IGraphicsContainer. A QI from IPageLayout to IGraphicsContainer connects you with the graphics container associated strictly with the PageLayout. However, this property, IActiveView::GraphicsContainer, on the PageLayout object has two possible outcomes. If a Map is activated (IActiveView::IsMapActivated), the property will return a reference to the focus Map's active graphics layer (IMap::ActiveGraphicsLayer ). If no Map is activated, the property will return a reference to the PageLayout's graphics container - the same as the QI case.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.carto.IGraphicsContainer
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFocusMap

IMap getFocusMap()
                 throws IOException,
                        AutomationException
The map that tools and controls act on.

Remarks

A user's map may comprise one or more Map objects. Each Map object typically holds layers of data as well as several MapSurround objects such as a Legend. This property returns an IMap reference to the Map object that currently has focus. In ArcMap, the focus map is the one visible in data view and the one selected in layout view.

Changing the focus map fires the IActiveViewEvents::FocusMapChanged event. In ArcMap, the focus map is automatically set to any new Map added.

IMxDocument::FocusMap is a read-only short cut to this property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.carto.IMap
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.carto.IMxDocument

setFocusMapByRef

void setFocusMapByRef(IMap activeMap)
                      throws IOException,
                             AutomationException
The map that tools and controls act on.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
activeMap - A reference to a com.esri.arcgis.carto.IMap (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isMapActivated

boolean isMapActivated()
                       throws IOException,
                              AutomationException
Indicates if the focus map is activated.

Remarks

In ArcMap's layout view, when the focus map is activated by double-clicking on it, new graphic elements are added to the Map's active graphics layer. When the focus map is not activated, the default, graphic elements are added to the PageLayout object. Both the Map and PageLayout objects are graphics containers, setting this property to TRUE diverts graphics from the PageLayout to the focus Map.

A Map can be activated in both layout and data views.

When this property is set to TRUE, IActiveView::PartialRefresh is called for the esriViewGraphicSelection draw phase.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isMapActivated
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.carto.IMxDocument

setIsMapActivated

void setIsMapActivated(boolean isMapActivated)
                       throws IOException,
                              AutomationException
Indicates if the focus map is activated.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
isMapActivated - The isMapActivated (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelection

ISelection getSelection()
                        throws IOException,
                               AutomationException
The selection.

Remarks

ArcMap has two different selection types, a feature selection and an element selection. Two different objects represent these selections and both implement the ISelection interface. The feature selection object additionally implements IEnumFeature and the element selection object IEnumElement. The ISelection interface is used for clipboard type operations and the IEnum interfaces are used to loop through the items in the collection.

Each active view object, the PageLayout and all Maps, have their own selection objects. Actually, the PageLayout only has an element selection but each Map has a unique feature and element selection. When working with selections make sure you have the correct active view object.

For a Map, only one of the selections can be active at a time. As mentioned above, this interface provides an ISelection reference to either an element or feature selection depending on which one is currently active. To simplify the matter, IMap has a FeatureSelection property which always returns an ISelection on the feature selection, from which you can obtain an IEnumFeature reference. Just make sure you have the correct Map, usually the FocusMap. To get a Map's element selection, use IViewManager::ElementSelection.

Note: The features returned as part of IEnumFeature are in the spatial reference of the map, so they have the coordinate system and the resolution (1/precision) of the map.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.carto.ISelection
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IActiveView.getSelection(), IGraphicsContainerSelect, IMap.getFeatureSelection(), IEnumElement

setSelectionByRef

void setSelectionByRef(ISelection selection)
                       throws IOException,
                              AutomationException
The selection.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
selection - A reference to a com.esri.arcgis.carto.ISelection (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTipText

String getTipText(double x,
                  double y)
                  throws IOException,
                         AutomationException
The tip text to display at the given location.

Product Availability

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

Parameters:
x - The x (in)
y - The y (in)
Returns:
The tipText
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getExportFrame

tagRECT getExportFrame()
                       throws IOException,
                              AutomationException
The device rectangle to export.

Remarks

Returns the area of the view to be exported.

For Maps, this is always the area corresponding to the constrained bounds (IDisplayTransformation::ContstrainedBounds), i.e., the visible bounds intersected with the full bounds. The coordinates are automatically converted, using IDisplayTransformation::TransformRect, from world units to device units.

For PageLayout, this is always the height and width of the page in device units (pixels) when the layout is zoomed to 100%. Because these values are independent of the layout's current zoom level and always correspond to the page instead of the full client area of the application, they are ideal for use when exporting a map to a graphics file. Assign the values of the ExportFrame property to the Export object's PixelBounds property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A Structure: com.esri.arcgis.system.tagRECT
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowScrollBars

boolean isShowScrollBars()
                         throws IOException,
                                AutomationException
Indicates if scrollbars are visible.

Remarks

IActiveView::ShowScrollBars is a short cut to IScreenDisplay::UseScrollBars. 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 scrollbar 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 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 Maps 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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The showScrollBars
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setShowScrollBars

void setShowScrollBars(boolean showScrollBars)
                       throws IOException,
                              AutomationException
Indicates if scrollbars are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
showScrollBars - The showScrollBars (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowRulers

boolean isShowRulers()
                     throws IOException,
                            AutomationException
Indicates if rulers are visible.

Remarks

This property is a boolean flag that applications use to determine whether or not to draw rulers.

This property cannot be set for Maps, they always have rulers turned off.

The PageLayout is the only active view with rulers; an active view change is required before the setting is reflected in the applications window.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The showRulers
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setShowRulers

void setShowRulers(boolean showRulers)
                   throws IOException,
                          AutomationException
Indicates if rulers are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
showRulers - The showRulers (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowSelection

boolean isShowSelection()
                        throws IOException,
                               AutomationException
Indicates if selection is visible.

Description

This property is primarily used to hide a Map's element selection in layout view unless a Map has been activated.

When in layout view, the PageLayout always has its ShowSelection set to true, setting it to false has no effect. Similarly, when in data view, the focus Map always has its ShowSelection set to true and this cannot be overridden.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The showRulers
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setShowSelection

void setShowSelection(boolean showRulers)
                      throws IOException,
                             AutomationException
Indicates if selection is visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
showRulers - The showRulers (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getExtentStack

IExtentStack getExtentStack()
                            throws IOException,
                                   AutomationException
The extent stack.

Remarks

Returns a reference to the active view's extent stack. Each active view has an extent stack which remembers previous extents so that users can 'go back' and then 'go forward' to previous extents.

Example:


Map map = new Map();
IExtentStack pExtentStack = map.getActiveView().getExtentStack();
if(pExtentStack.canUndo()){
pExtentStack.undo();
}            

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.carto.IExtentStack
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getScreenCacheID

short getScreenCacheID(int phase,
                       Object data)
                       throws IOException,
                              AutomationException
The screen cache ID that is used to draw the specified phase.

Product Availability

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

Parameters:
phase - A com.esri.arcgis.carto.esriViewDrawPhase constant (in)
data - A reference to another Object (IUnknown) (in)
Returns:
The cacheID
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

hitTestMap

IMap hitTestMap(IPoint location)
                throws IOException,
                       AutomationException
Returns any maps present in the view at the given location. Return value may be zero if there are no maps or the coordinate is not over a map.

Remarks

Use this method on a PageLayout to find the nearest Map based on a point location. For example, when ArcMap's identify tool is used in Layout view, the tool first finds the Map clicked on before it searches for features in the Map.

When using this method on a PageLayout, for the Location parameter, set up the Point in page coordinates. To convert from device coordinates to page coordinates:

  1. Get the ScreenDisplay from the PageLayout using IActiveView::ScreenDisplay.
  2. Get the DisplayTransformation from the ScreenDisplay using IScreenDisplay::DisplayTransformation.
  3. Convert device coordinates (for example from a mouse move) to page coordinates using IDisplayTransformation::ToMapPoint.

Use this method on a Map to obtain a reference to it through IMap.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
location - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
A reference to a com.esri.arcgis.carto.IMap
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isActive

boolean isActive()
                 throws IOException,
                        AutomationException
Indicates if view is active or not.

Remarks

In layout view, all of the Maps and the PageLayout are active. In data view, only the focus map is active.

The PageLayout object uses this property when adding Elements; if the PageLayout is active, new elements are activated (IElement::Activate).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isActive
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

activate

void activate(int hWnd)
              throws IOException,
                     AutomationException
Gives this view control of the specified window.

Remarks

Called to establish the current object as the active view. For example, view commands deactivate (IActiveView::Deactivate) the current view (IMxDocument::ActiveView) before calling Activate on their own associated view.

When working with the IActiveView interface on a MapDocument object, you should always first call IActiveView::Activate() in order to properly initialize the display of the PageLayout or Map object. The MxDocument and MapServer objects and the MapControl and PageLayoutControl all initialize display objects automatically after opening an MXD, but MapDocument does not do this, so you should call Activate() before working with any other members of IActiveView. If your application has a user interface, you should call Activate() with the hWnd of the application's client area. If your application runs in the background and has no windows, you can always get a valid hWnd from the GDI GetDesktopWindow() function, part of the Win32 API.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
hWnd - The hWnd (A COM typedef) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

deactivate

void deactivate()
                throws IOException,
                       AutomationException
Another view takes over the associated window.

Remarks

Called to deactivate the current active view. For example, view commands deactivate (IActiveView::Deactivate) the current view (IMxDocument::ActiveView) before calling Activate on their own associated view.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

draw

void draw(int hDC,
          ITrackCancel trackCancel)
          throws IOException,
                 AutomationException
Draws the view to the specified device context.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
hDC - The hDC (A COM typedef) (in)
trackCancel - A reference to a com.esri.arcgis.system.ITrackCancel (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

output

void output(int hDC,
            int dpi,
            tagRECT pixelBounds,
            IEnvelope visibleBounds,
            ITrackCancel trackCancel)
            throws IOException,
                   AutomationException
Renders the view to the specified DC.

Description

This method is used to draw to a non-app window hDC (see Windows GDI for more info). The ArcMap printing and exporting commands use this method. When drawing to an hWnd, normally IActiveView::Draw is used instead of this method because it handles caching and scrollbars.

Remarks

Parameter use is as follows:

hDC - Output device.
dpi - Dots per inch (resolution). If Null is passed then this defaults to the resolution of the hDC. If that cannot be sampled, then this defaults to the window resolution.
pixelBounds - Device rectangle specified in pixels.
VisibleBounds - Zoom extent. If Null is passed then this defaults to the current visible extent.

All other display attributes are copied from the ActiveView.

If you want to draw the data frame to a 640x480 bitmap for example, specify the following parameter values:

dpi - 0
pixel bounds - { 0, 0, 640, 480 }
visible bounds - 0

If you want to create a bitmap that will print 8.5 x 11 on a 300 DPI printer, specify the following parameter values:

dpi - 300
pixel bounds - { 0, 0, 8.5 * dpi, 11 * dpi }
visible bounds - 0

If you want to zoom to a certain location and draw it on a 300x300 bitmap, specify the following parameter values:

dpi - 0
pixel bounds - { 0, 0, 300, 300 }
visible bounds - { -45.0, 44.0, -44.0, 45.0 }

The value of IDisplayTransformation::Resolution does not affect the results of this method.

The value of IOutputRasterSettings::ResampleRatio does affect the results of the this method. When rasters are drawn, they get resampled as specified in this attribute.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
hDC - The hDC (A COM typedef) (in)
dpi - The dpi (in)
pixelBounds - A Structure: com.esri.arcgis.system.tagRECT (in)
visibleBounds - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
trackCancel - A reference to a com.esri.arcgis.system.ITrackCancel (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

refresh

void refresh()
             throws IOException,
                    AutomationException
Causes the entire view to draw.

Remarks

IActiveView::Refresh invalidates all of the caches. This is a very inefficient operation; typically data from just one source has to be reread from the database and the rest can be drawn from cache. IActiveView::PartialRefresh uses it's knowledge of the cache layout to invalidate as little as possible and should be used whenever possible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriViewDrawPhase, IGlobeLayerProperties2, IActiveView.partialRefresh(int, java.lang.Object, com.esri.arcgis.geometry.IEnvelope), IScreenDisplay.invalidate(com.esri.arcgis.geometry.IEnvelope, boolean, short), IActiveView.getScreenCacheID(int, java.lang.Object), IActiveView.refresh()

partialRefresh

void partialRefresh(int phase,
                    Object data,
                    IEnvelope envelope)
                    throws IOException,
                           AutomationException
Draws the specified view phase. Use an envelope of zero to draw the entire phase.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
phase - A com.esri.arcgis.carto.esriViewDrawPhase constant (in)
data - A reference to another Object (IUnknown) (in)
envelope - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriViewDrawPhase, IGlobeLayerProperties2, IActiveView.partialRefresh(int, java.lang.Object, com.esri.arcgis.geometry.IEnvelope), IScreenDisplay.invalidate(com.esri.arcgis.geometry.IEnvelope, boolean, short), IActiveView.getScreenCacheID(int, java.lang.Object), IActiveView.refresh()

clear

void clear()
           throws IOException,
                  AutomationException
Empties the view contents.

Remarks

The Map object's implementation of Clear deletes all of the Layers in the Map (IMap::ClearLayers ), removes all MapSurrounds (IMap::ClearSurrounds ), removes all bookmarks (IMapBookMarks::RemoveAllBookMarks), and resets the extent stack. Clear does not refresh the active view however.

Clear on PageLayout deletes all Elements, including MapFrames which hold a Map, resets the extent stack, and a new Map is created - there must always be a focus map.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

printerChanged

void printerChanged(IPrinter printer)
                    throws IOException,
                           AutomationException
Called by application when printer changes.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
printer - A reference to a com.esri.arcgis.output.IPrinter (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

contentsChanged

void contentsChanged()
                     throws IOException,
                            AutomationException
Called by clients when view objects are modified.

Remarks

After modifying the contents view (table of contents), use this method to fire the IActiveViewEvents::ContentsChanged event so that clients listening for this event can respond accordingly.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IActiveViewEvents.contentsChanged(com.esri.arcgis.carto.IActiveViewEventsContentsChangedEvent)

onMessage

void onMessage(int msg,
               int wParam,
               int lParam)
               throws IOException,
                      AutomationException
Call from your application's message loop to enable automatic resizing and keyboard accelerators.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
msg - The msg (in)
wParam - The wParam (A COM typedef) (in)
lParam - The lParam (A COM typedef) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getContextMenu

void getContextMenu(double x,
                    double y,
                    IUID[] clsidMenu)
                    throws IOException,
                           AutomationException
Called when a context menu should be displayed at the given xy location. Return menu that should be displayed.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
x - The x (in)
y - The y (in)
clsidMenu - A reference to a com.esri.arcgis.system.IUID (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.