- ArcGIS for Desktop Basic with Publisher
- ArcGIS for Desktop Standard with Publisher
- ArcGIS for Desktop Advanced with Publisher
Additional library information: Contents, Object Model Diagram
The PublisherControls library contains two ActiveX controls (ArcReaderControl and ArcReaderGlobeControl) and a set of common ArcReaderObjects. The two controls can be used to create custom ArcReader applications.
Developers do not extend this library.
See the following sections for more information about this namespace:
- About PublisherControls
- Functionality common to both PublisherControls
- Functionality specific to ArcReaderControl
- Functionality specific to ArcReaderGlobeControl
About PublisherControls
The ArcReader desktop application cannot be customized and extended the same way as other ArcGIS for Desktop products. Instead, you can use the PublisherControls library to build and extend Windows applications with custom ArcReader functionality for viewing, exploring, and printing Published Map Files (PMFs). The term PublisherControls refers collectively to ArcReaderControl and ArcReaderGlobeControl. ArcReaderControl is used to view PMFs published from ArcMap, and ArcReaderGlobeControl is used to view PMFs published from ArcGlobe. The themes and concepts described in the following subsections should be fully understood to effectively build applications using the PublisherControls library.
Embeddable components
PublisherControls are embeddable components that can be dropped into a container form or dialog box provided by a visual design environment. PublisherControls can be embedded in an existing application to add spatial capability, or they can be used to create a new stand-alone application. Once in a container, PublisherControls can be resized and repositioned along with other embeddable components, such as command buttons and combo boxes, to provide a user interface (UI) for the application.
Property pages
Each of the PublisherControls has a set of property pages that are accessible in most visual design environments. Once a control is embedded in a container, you can access the property pages by right-clicking the control and clicking Properties on the shortcut menu. These property pages provide shortcuts to a selection of a control's properties and methods and allow a you to build an application with little or no code.
ArcReaderObjects (ARObjects)
PublisherControls have simple self-contained object models that expose all the functionality of the ArcReader desktop application and do not require access to ArcObjects. As such, developing applications with PublisherControls does not require previous experience with ArcObjects. ArcReaderControl corresponds to the data and layout views of the free ArcReader desktop application together with its table of contents (TOC). ArcReaderGlobeControl corresponds to the globe view of the ArcReader desktop application together with its TOC. PublisherControls also contain the internal windows and tools used by the ArcReader desktop application, such as the Find window and the Identify tool.
PublisherControls work with a common set of ARObjects. The majority of ARObjects work with both PublisherControls; however, some ARObjects only work with ArcReaderControl (for example, ARPageLayout) and some only work with ArcReaderGlobeControl (for example, ARGlobe). For this reason, all ARObjects that work with ArcReaderControl are represented on one object model diagram (OMD), and all ARObjects that work with ArcReaderGlobeControl are represented on another OMD.
The following table summarizes the ARObjects that are available with each of the PublisherControls:
|
PublisherControls |
ArcReaderControl |
ArcReaderGlobeControl |
|
Objects unique to a single control |
|
|
|
Objects common to both controls |
| |
Events
Each of the PublisherControls fires events in response to keyboard and mouse interactions by the end user. For example, when a PMF is loaded into either of the PublisherControls, the OnDocumentLoaded event is fired. A useful event when working with PublisherControls is the OnAction event; it fires in response to actions occurring within the controls. An example of using the OnAction event is illustrated in the ArcReaderGlobeControl play animation sample—the OnAction event is fired when an animation starts and stops playing. This allows you to provide appropriate feedback to the user of the application.
Types of view
One of the most important concepts of PublisherControls is that of views. Think of the view as the place where data is drawn. ArcReaderControl has two views: an ARPageLayout view and an ARMap view. Only one of these views can be visible at a time and is known as the CurrentView. Either of these views can be set as the CurrentView if the PMF document is published with permission to change views. Provided a PMF has been loaded, ArcReaderGlobeControl has just one view, an ARGlobe view.
Functionality common to both PublisherControls
The following table shows the functionality common to both PublisherControls:
|
Functionality |
ArcReaderControl |
ArcReaderGlobeControl |
|
Published Map File (*.pmf) with permission to load in a customized application |
No | No |
|
Published Map File (*.pmf) with permission to load in a customized application |
Yes | Yes |
|
Published Map File (*.pmf) with permission to load in a customized application and unrestricted access to its contents |
Yes | Yes |
The following code snippets illustrate loading PMFs into PublisherControls. When developing an application, remember that a PMF published from ArcGlobe cannot be loaded into ArcReaderControl, and a PMF published from ArcMap cannot be loaded into ArcReaderGlobeControl. Because of this, it is good practice to always use the CheckDocument method. For example, if you call ArcReaderControl1.CheckDocument and pass the file path of a PMF published in ArcGlobe, the method returns false; if you pass the file path of a PMF published in ArcMap, the method returns true.
For ArcReaderControl, see the following code example:
[C#] string filePath=@"C:\Temp\MyPublishedMxd.pmf";
if (axArcReaderControl1.CheckDocument(filePath))
axARcReaderControl1.LoadDocument(filePath, "");
Dim sFilePath As String
sFilePath="C:\Temp\MyPublishedMxd.pmf"
If AxArcReaderControl1.CheckDocument(sFilePath) Then AxArcReaderControl1.LoadDocument(sFilePath)
For ArcReaderGlobeControl, see the following code example:
[C#] string filePath=@"C:\Temp\MyPublished3dd.pmf";
if (axArcReaderGlobeControl1.CheckDocument(filePath))
axArcReaderGlobeControl1.LoadDocument(filePath, "");
Dim sFilePath As String
sFilePath="C:\Temp\MyPublished3dd.pmf"
If AxArcReaderGlobeControl1.CheckDocument(sFilePath) Then AxArcReaderGlobeControl1.LoadDocument(sFilePath)
Checking PMF permissions
When a PMF is published, the publisher can set a variety of permissions to limit the functionality to which a user has access when working with the PMF in either of the PublisherControls. These permissions should be checked with the HasDocumentPermission method and the behavior of an application modified appropriately. For example, if permission to print does not exist, an application should be modified so that a user cannot display the internal PageSetUp and Printer windows.
For ArcReaderControl, see the following code example:
[C#] if (axArcReaderControl1.HasDocumentPermission
(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter, true,
Type.Missing);
}
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint) Then
AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter)
End If
For ArcReaderGlobeControl, see the following code example:
[C#] if (axArcReaderGlobeControl1.HasDocumentPermission
(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
axArcReaderGlobeControl1.ShowARGlobeWindow
(esriARGlobeWindows.esriARGlobeWindowsPrinter, true, Type.Missing);
}
If AxArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint) Then
AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsPrinter)
End If
Setting the current tool
Both PublisherControls have a property that specifies which built-in tool is used to interact with the current view. IARControl.CurrentARTool can be set to specify the active tool for either the ARPageLayout view or the ARMap view. Likewise, IARGlobeControl.CurrentARGlobeTool can be set to specify the active tool for the ARGlobe view.
CurrentARTool for the ARPageLayout view is independent of CurrentARTool for the ARMap view. For example, the built-in map Zoom In tool can be the current tool when the current view is a map, and the built-in Page Layout Pan tool can be the current tool when the current view is a page layout. Before setting the CurrentARTool property, check that the PMF was published with permission to access a particular tool. This can be achieved using the HasDocumentPermission method. The following screen shot shows the result of ARControl.CurrentARTool=esriARToolMapIdentify:
The following code example shows how to set the current tool for ArcReaderControl to the Hyperlink tool:
[C#] if (axArcReaderControl1.HasDocumentPermission
(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
axArcReaderControl1.CurrentARTool=esriARTool.esriARToolMapHyperlink;
}
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink) Then
AxArcReaderControl1.CurrentARTool=esriARTool.esriARToolMapHyperlink
End If
The following code example shows how to set the current tool for ArcReaderGlobeControl to the Hyperlink tool:
[C#] if (axArcReaderGlobeControl1.HasDocumentPermission
(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
axArcReaderGlobeControl1.CurrentARGlobeTool =
esriARGlobeTool.esriARGlobeToolMapHyperlink;
}
If AxArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink) Then
AxArcReaderGlobeControl1.CurrentARGlobeTool=esriARGlobeTool.esriARGlobeToolHyperlink
End If
Showing and hiding windows
The methods ShowARWindow and ShowARGlobeWindow can be used to open and close the built-in windows. ShowARWindow is available with ArcReaderControl and opens ARWindows relevant to ArcReaderControl. ShowARGlobeWindow is available with ArcReaderGlobeControl and opens ARGlobeWindows relevant to ArcReaderGlobeControl.
Some of the internal windows are modal and some are modeless. A modal window requires a response from the user before the user can interact with other parts of the application. A modeless window stays on the screen, available for use, but allows the user to interact with other parts of the application. Before using the ShowARWindow or ShowARGlobeWindow method, do one or both of the following:
- Check that the PMF was published with permission to open a particular window with the HasDocumentPermissions method.
- Check whether a modeless window is actually open using the IARWindowVisible or IARGlobeWindowVisible property.
The following code example shows how to display or hide the Magnifier window when developing with ArcReaderControl:
[C#] if (axArcReaderControl1.get_ARWindowVisible(esriARWindows.esriARWindowsMagnifier))
{
axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, false,
Type.Missing);
}
else
{
axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, true,
Type.Missing);
}
If AxArcReaderControl1.get_ARWindowVisible(esriARWindows.esriARWindowsMagnifier) Then
AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, False)
Else
AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, True)
End If
The following code example shows how to display or hide the Animation window when developing with ArcReaderGlobeControl:
[C#] if (axArcReaderGlobeControl1.get_ARGlobeWindowVisible
(esriARGlobeWindows.esriARGlobeWindowsAnimation))
{
axArcReaderGlobeControl1.ShowARGlobeWindow
(esriARGlobeWindows.esriARGlobeWindowsAnimation, false, Type.Missing);
}
else
{
axArcReaderGlobeControl1.ShowARGlobeWindow
(esriARGlobeWindows.esriARGlobeWindowsAnimation, true, Type.Missing);
}
If AxArcReaderGlobeControl1.get_ARGlobeWindowVisible(esriARGlobeWindows.esriARGlobeWindowsAnimation) Then
AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation, False)
Else
AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation, True)
End If
Producing output
There are several methods available for getting output from either of the PublisherControls. Output reflects the state of the current view as seen on-screen. The CopyViewToClipboard method copies a bitmap of the current view to the system clipboard, the ExportView method exports the current view to a specified file name using the specified format, and the PrintView method prints the current view to the system default printer or the last printer selected in either the PageSetUp or Printer window. Before using these methods, check that the PMF was published with appropriate permissions. This can be done using the HasDocumentPermissions method.
Measurement and unit conversion
When working with maps and globes, it is often necessary to convert distance from one unit of measure to another. For example, to undertake accurate spatial searches, you may want to convert a value from one unit of measure to the current IARMap.MapUnits. When working with the ArcReaderGlobeControl, you may need to convert between decimal degrees (esriARUnitsDecimalDegrees) and degrees/minutes/seconds (esriARUnitsDegMinSec). For this reason, ARUnitConverter provides methods for converting values between different units of measure.
When converting units of measure, ensure that the conversion is sensible. For example, ARUnitConverter allows you to convert a distance measured in kilometers to a distance in decimal degrees. However, because the meridians converge toward the poles, a degree of longitude varies in size. One degree of longitude is approximately 111 km at the equator but only 79 km at a latitude of 45 degrees. ARUnitConverter has no built-in intelligence to handle such conversion but does allow this type of conversion to be undertaken. If ARUnitConverter is used to convert a distance of 1 decimal degree to kilometers, it assumes the distance is a measure of latitude or a measure of longitude at the equator.
Controlling the PublisherControls with an ArcReader Template file
An ArcReader Template (.art) file is a binary file that stores settings that can be read by the ArcReader desktop application, ArcReaderControl, and ArcReaderGlobeControl. These settings determine the appearance and behavior of the desktop application and PublisherControls. For example, there are settings to determine the width of the TOC, the default current tool, and the behavior of the built-in tools (for example, the Identify tool). A specific template can be loaded into either of the PublisherControls to suit a particular application or to give a consistent user experience.
ArcReaderConfiguration is a helper object that provides Setting and BoolSetting properties for updating settings as well as Load and Save methods for loading and saving template files. An application using either of the PublisherControls can maintain these settings by reading and writing a template file to the user profile when the application starts and exits. It is also possible to manage the ArcReader Template files using the ArcReader Configuration developer tool. The ArcGIS Publisher extension also allows .art files to be embedded in PMFs.
Functionality specific to ArcReaderControl
The functionality described in the following paragraphs is specific to ArcReaderControl.
Page Layout and Map extents
ArcReaderControl has two views: Page Layout and Map. These two views are represented by two ARObjects: ARPageLayout and ARMap. Both of these objects are unique to ArcReaderControl, as they are of no use when working with the ArcReaderGlobeControl since it only has one view—ARGlobe.
The ARPageLayout object manages the layout of a page to be sent as output to a printer. ARPageLayout typically consists of one or more ARMap objects together with marginalia such as scale bars, legends, and titles. Every PMF contains at least one ARMap object, and only one ARMap can have focus at a time. The IARPageLayout.FocusARMap property returns a reference to the ARMap currently with focus, and the IARPageLayout.ARMapCount and IARPageLayout.ARMap properties can be used to manage the entire collection of ARMap objects.
To navigate around ARPageLayout or ARMap, CurrentARTool can be set to a built-in navigation tool; for example, the built-in Zoom In tool or the Page Pan tool. To allow more control over extent changes, you can explicitly manage extents using the properties and methods on the IARPageLayout and IARMap interfaces.
The GetExtent method returns the visible area of ARPageLayout or ARMap when it is the CurrentView as four coordinates representing the top left, top right, bottom right, and bottom left corners of the CurrentView in either PageUnits or MapUnits. The IARMap.GetFullExtent method is similar except it returns the extent of all the data contained in ARMap.
The ZoomIn and ZoomOut methods both zoom from the center of the current visible extent by a specified factor. This factor represents the ratio between the new visible extent and the previous visible extent. For example, zooming in by a factor of 2 is the same as zooming out by a factor of 0.5 and vice versa. The Pan method pans the current visible extent in a specific direction by a specific screen percentage. A percentage of 25 pans the current visible extent by a quarter of its width.
The IARPageLayout.ZoomToWholePage helper method updates the current visible extent so that the whole ARPageLayout is visible, and the IARMap.ZoomToFullExtent helper method updates the current visible extent so that the full extent of all data within ARMap is visible in the display area of the CurrentView as shown in the following code example:
[C#] if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypePageLayout)
{
axArcReaderControl1.ARPageLayout.ZoomToWholePage();
}
else if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypeMap)
{
axArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent();
}
If AxArcReaderControl1.CurrentViewType=esriARViewType.esriARViewTypePageLayout Then
AxArcReaderControl1.ARPageLayout.ZoomToWholePage()
ElseIf AxArcReaderControl1.CurrentViewType=esriARViewType.esriARViewTypeMap Then
AxArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent()
End If
Whenever the extent of the ARPageLayout or ARMap changes, the previous extent is placed onto an extent stack. The CanUndoExtent and CanRedoExtent properties indicate whether you can navigate backward or forward from the current extent of ARPageLayout or ARMap using the UndoExtent and RedoExtent methods to move through the extent stack.
ARMap manages spatial bookmarks that are present at the time a PMF is published. A spatial bookmark consists of a name and an extent. Use the BookmarkCount property to return the number of spatial bookmarks present and the indexed BookmarkName property to return a bookmark’s name. Once a reference to a particular bookmark is found, either through its index or name, use the ZoomToBookmark or CenterAtBookmark method to update the visible extent of ARMap.
Map and layer properties
Every PMF document contains at least one ARMap object that is the primary point for managing data layers, navigating around those data layers, and finding particular features. Each ARMap object manages a number of ARLayer objects that are present at the time the PMF was published. An ARLayer object displays geographic information and represents all types of data including feature layers and raster layers. An ARLayer object doesn’t store the actual geographic data; it references the data contained in coverages, shapefiles, geodatabases, images, grids, and so on, then defines how to display this geographic data. The IARMap.ARLayerCount and the indexed IARMap.ARLayer properties can be used to manage the entire collection of ARLayer objects.
The publisher of a PMF can group layers to form a group layer, which behaves like a single layer. Suppose there are two layers on a map, one representing rivers and the other lakes. The layers could be grouped together and the resulting layer given the name water systems. Using the IARLayer.Visible property to turn off the group layer also turns off all component child layers. Because of this, the properties of the group layer override any conflicting properties of its child layers. Use the IARLayer.IsGroupLayer property to test whether an ARLayer is a group layer. To work with an individual child layer within the group, use the IARLayer.ARLayerCount and IARLayer.ChildARLayer properties.
The IARMap interface has several properties related to the map including SpatialReferenceName, MapUnits, ReferenceScale, and MapScale. The MapScale property defines the ratio between the on-screen view of any features and the geographic objects they represent on the earth. A MapScale of 100,000 means that one unit of measure on ARMap in MapUnits equals 100,000 of the same units on the earth. The ReferenceScale property indicates the scale to which all symbol and text sizes used in ARMap are made relative. The Rotation property relates to the angle that data appears inside ARMap and is measured in degrees.
The IARLayer interface has several properties related to the layer including Type, Visible, MinimumScale, and MaximumScale. The Type property indicates whether the layer is a feature layer, raster layer, or triangulated irregular network (TIN) layer. The MinimumScale and MaximumScale properties define the display scales of ARLayer. At IARMap.MapScale, if less than MinimumScale or greater than MaximumScale, ARLayer is not drawn on the screen, and the layer's check box in the TOC is unavailable. The IARLayer.GetExtent method returns the extent of ARLayer as four coordinates representing the top left, top right, bottom right, and bottom left corners of the extent in IARMap.MapUnits.
The following code example shows how to set the visible extent to the extent of the layer:
[C#] double xmin=0;
double ymin=0;
double xmax=0;
double ymax=0;
IARMap arMap=axArcReaderControl1.ARPageLayout.FocusARMap;
arMap.get_ARLayer(0).GetExtent(ref xmin, ref ymin, ref xmax, ref ymax);
arMap.SetExtent(xmin, ymin, xmax, ymax);
'Set the visible extent to the extent of the layer.
Dim pARMap As ARMap
Dim dXmin As Double, dYmin As Double, dXmax As Double, dYmax As Double
pARMap=AxArcReaderControl1.ARPageLayout.FocusARMap
pARMap.ARLayer(0).GetExtent(dXmin, dYmin, dXmax, dYmax)
pARMap.SetExtent(dXmin, dYmin, dXmax, dYmax)
Searching and querying features
An ARFeature object is a spatial entity modeled as an object with properties and behavior. All ARFeature objects within ARLayer share the same set of attribute schema; that is, they have the same set of fields. There is always at least one field in the field collection. On the IARFeature interface, use the FieldCount property to return the number of fields in the collection. Each field in the collection has read-only FieldName, FieldAliasName, FieldType, and Value properties. Value cannot be read if the PMF was published without permission or if FieldType is a geometry (or shape) field. In addition to the ability to access attribute information, there are Highlight, Flash, Flicker, ZoomTo, and CenterAt methods on the IARFeature interface for viewing the geometry or shape of ARFeature.
To reference ARFeature, a search or query must be performed on ARMap or ARLayer. A search or query can only be performed on ARLayer that is searchable. Searchable layers are typically feature layers, not raster layers. The search or query is defined by ArcReaderSearchDef, which is passed to the QueryARFeatures or SearchARFeatures methods on the IARMap and IARLayer interfaces. ArcReaderSearchDef defines the attribute and spatial constraints used in the search or query as follows:
- A spatial constraint specifies a geometry or shape and spatial relationship against which ARFeature objects are tested; for example, selecting features overlapping a search area or finding features within a specified distance of a feature. The spatial constraint is set by using the SetPointShape, SetEnvelopeShape, or SetARFeatureShape method and the spatial relationship by the SpatialRelationship property.
- An attribute constraint specifies a Structured Query Language (SQL) WHERE clause; for example, finding features with a particular value greater than 10. The syntax used to specify WhereClause needs to be the same as that of the underlying database holding the data; for example, "NAME='UK'", "POPULATION>1000000".
The IARMap.SearchARFeatures and IARLayer.SearchARFeatures methods return ARFeatureCursor, which can be used to iterate over the subset of features that are returned from the search. The NextARFeature method returns the next ARFeature object within the subset. The next feature is created and allocated to ARFeatureCursor. ARFeatureCursor is forward only and does not support retrieving features that have already been retrieved nor does it support making multiple passes over the subset. If an application must make multiple passes over the data, the application needs to re-execute the search.
The IARMap.QueryARFeatures and IARLayer.QueryARFeatures methods differ from the SearchARFeatures method in that they return ARFeatureSet. ARFeatureSet is populated with a complete set of ARFeature objects once all the searching is complete. It supports retrieving features that have already been retrieved and supports making multiple passes over the features as shown in the following code. The Next method returns the next feature in the subset, the Reset method goes back to the first feature in the subset, and ARFeature returns a particular feature.
It is inadvisable to call the QueryARFeatures method when the resulting ARFeatureSet might contain a large number of features, as it can take a long time to return and can consume a large amount of system memory. See the following code example:
[C#] ArcReaderSearchDef arcReaderSearchDef=new ArcReaderSearchDefClass();
IARLayer arLayer=axArcReaderControl1.ARPageLayout.FocusARMap.get_ARLayer(0);
IARFeatureSet arFeatureSet=arLayer.QueryARFeatures(arcReaderSearchDef);
System.Windows.Forms.MessageBox.Show("The number of features in this layer is: " +
arFeatureSet.ARFeatureCount);
Dim pARLayer As ARLayer
Dim pArcReaderSearchDef As New ArcReaderSearchDef
Dim pARFeatureSet As ARFeatureSet
pARLayer=AxArcReaderControl1.ARPageLayout.FocusARMap.ARLayer(0)
pARFeatureSet=pARLayer.QueryARFeatures(pArcReaderSearchDef)
System.Windows.Forms.MessageBox.Show("The number of features in this layer is: " & pARFeatureSet.ARFeatureCount)
Functionality specific to ArcReaderGlobeControl
The Functionality common to both PublisherControls section details the steps involved in adding basic functionality to applications that contain either of the PublisherControls. Whether it's an application containing ArcReaderControl or an application containing ArcReaderGlobeControl, the steps involved in adding basic functionality are identical. However, there are subtle differences in the behavior of objects, methods, and properties when working with one of the PublisherControls as opposed to the other. This section describes the functionality of ArcReaderGlobeControl.
Globe and layer properties
Every PMF document published from ArcGlobe contains a globe that is represented by the ARGlobe object. ARGlobe is the primary point for managing data layers, navigating around those data layers, and finding particular features. There are several approaches you can use to control navigation around ARGlobe. The most straightforward is to use esriARGlobeTool.
The following table lists tools that provide navigation functionality (this table is not a complete list of esriARGlobeTools):
|
Tool |
Description |
|
esriARGlobeToolNavigate |
Use this tool to navigate ARGlobe. Activating the tool sets IARGlobe.Pitch=0. Using the mouse button, you can rotate the globe around its center. Right-click, and the tool allows you to zoom in and out along an imaginary straight line from the observer location to the ARGlobe center. |
| esriARGlobeToolOrbitalFly | Use this tool to fly over the ARGlobe surface at a fixed elevation. Activating this tool displays a dialog box with buttons that allow you to control flight. The dialog box is displayed in ArcReaderGlobeControl as specified by the window position property accessed via the ArcReaderGlobeControl property pages. |
| esriARGlobeToolTarget | Use this tool to center a surface location in the view. |
| esriARGlobeToolZoomInOut | Use this tool to zoom in and out along an imaginary straight line between the observer location and the target on the ARGlobe surface. |
| esriARGlobeToolPan | Use this tool to pan the ARGlobe surface. Click and drag the view in a particular direction to pan. |
| esriARGlobeToolPivot | Use this tool to view the point on the ARGlobe surface that is centered in the view. Using the mouse button, you can pivot around a point on the ARGlobe surface that is located at the center of the view. Right-click, and the tool allows you to zoom in and out along an imaginary straight line between the observer location and the center of the view. Activating this tool sets IARGlobe.Pitch to a nonzero value. |
Alternatively, you can alter the observer location from which ARGlobe is viewed. IARGlobe.Elevation changes the elevation of the observer location. When using this property, the point on the ARGlobe surface above which the observer location is set does not change. The current observer location can be obtained using IARGlobe.GetObserverLocation and set to a new location using IARGlobe.SetObserverLocation. When working with these methods, elevation is measured in IARGlobe.GlobeUnits, and coordinates are specified as latitude and longitude measured in decimal degrees. See the following illustration that shows IARGlobe.Elevation:
From the observer location, the observer views a target location along a line of sight. When working with ArcReaderGlobeControl, the target can be considered the point on the ARGlobe surface that is located at the center of the view. The direction from which ARGlobe is viewed from the observer location (line of sight) can be controlled using the IARGlobe.Pitch and IARGlobe.Azimuth properties. IARGlobe.Pitch is a measure of the angle between the observer’s line of sight and the tangent of an observer’s imaginary closed circular orbit of ARGlobe. IARGlobe.Azimuth is a measure of the angle between the line of sight and the geographic north pole.
See the following illustrations of IARGlobe.Pitch and IARGlobe.Azimuth:
The IARGlobe interface has several methods that provide easy means of visualizing the globe and its data layers. IARGlobe.PlayAnimation can be used to play animation (.aga) files that were published with the PMF from ArcGlobe. If the PMF being viewed in ArcReaderGlobeControl has been published with spatial bookmarks, IARGlobe.CenterAtBookmark and IARGlobe.ZoomToBookmark can be used to change the current visible extent of the globe.
The CenterAtBookmark method centers the specified bookmark at the center of the view while the elevation of the observer location remains unchanged. In contrast, ZoomToBookmark changes the observer location, pitch, and azimuth to that of the observer location, pitch, and azimuth when the specified bookmark was captured in ArcGlobe. The IARGlobe.ZoomToFullExtent helper method sets the observer location, pitch, and azimuth so that the whole ARGlobe is visible in the current view. The IARGlobe.CenterAt method positions the observer so that the specified coordinate is located at the center of the current view.
When working with ArcReaderGlobeControl, locations are often expressed in latitude and longitude coordinates measured in decimal degrees, derived from the World Geodetic System (WGS) 84 datum, and elevation is measured in IARGlobe.GlobeUnits.
IARGlobe.SpatialReferenceName returns the name of the globe's spatial reference. It is important to recognize that latitude and longitude coordinates derived from maps or globes based on other datums are not accurate if used with ArcReaderGlobeControl. Latitude is a measure of how far north or south of the equator a place is located. The equator is located at 0°, the north pole at 90° north, and the south pole at 90° south. When working with ArcReaderGlobeControl to distinguish latitude north of the equator, a positive number is used, and for latitude south of the equator, a negative number is used. Longitude is a measure of how far east or west of the prime meridian a place is located. The prime meridian runs through Greenwich, England. When working with ArcReaderGlobeControl, longitude is measured in terms of east (implied by a positive number) or west (implied by a negative number). Longitude measurements range from 0°, at any point along the prime meridian, to (+/-) 180°.
IARGlobe.GetSurfacePoint can be used to obtain the latitude and longitude of a point on the ARGlobe surface, as specified in screen coordinates (usually pixels). Screen coordinates are returned by several events on ArcReaderGlobeControl (for example, OnMouseDown). Using this method, you can access the latitude and longitude of a point on the ARGlobe surface where you've positioned and clicked your mouse.
Each ARGlobe object manages a number of ARLayer objects that represent layers that were present at the time the PMF was published. An ARLayer object displays geographic information and represents all types of data including feature layers and raster layers. ARLayer doesn’t store the actual geographic data; it references the data contained in coverages, shapefiles, geodatabases, images, grids, and so on, then defines how to display this geographic data. The IARGlobe.ARLayerCount and the indexed IARGlobe.ARLayer properties can be used to manage the entire collection of ARLayer objects.
The IARLayer interface has several properties related to the layer including Type, Visible, MinimumScale, and MaximumScale. The Type property indicates whether the layer is a feature layer, raster layer, or TIN layer. The MinimumScale and MaximumScale properties define the elevations at which ARLayer is and isn’t visible. If the IARGlobe.Elevation property is less than MinimumScale or greater than MaximumScale, ARLayer is not drawn on the screen and the layer's check box in the TOC is unavailable. The IARLayer.GetExtent method returns the extent of ARLayer as four coordinates representing the top left, top right, bottom right, and bottom left corners of the extent in IARGlobe.GlobeUnits.
Searching and querying features
An ARFeature object is a spatial entity modeled as an object with properties and behavior. All ARFeature objects within ARLayer share the same set of attribute schema; that is, they have the same set of fields. There is always at least one field in the field collection. Use the FieldCount property on the IARFeature interface to return the number of fields in the collection. Each field in the collection has read-only FieldName, FieldAliasName, FieldType, and Value properties. Value cannot be read if the PMF was published without permission or if FieldType is a geometry (or shape) field. In addition to the ability to access attribute information, there are Highlight, Flash, Flicker, ZoomTo, and CenterAt methods on the IARFeature interface for viewing the geometry or shape of ARFeature.
To reference ARFeature, a search or query must be performed on ARGlobe or ARLayer. A search or query can only be performed on ARLayer that is searchable. Searchable layers are typically feature layers and not raster layers. The search or query is defined by ArcReaderSearchDef, which is passed to the QueryARFeatures or SearchARFeatures method on the IARGlobe and IARLayer interfaces. ArcReaderSearchDef defines the attribute and spatial constraints used in the search or query as follows:
- A spatial constraint specifies a geometry or shape and spatial relationship against which ARFeature objects are tested; for example, selecting features overlapping a search area or finding features within a specified distance of a feature. The spatial constraint is set by using the SetPointShape, SetEnvelopeShape, or SetARFeatureShape method and the spatial relationship by the SpatialRelationship property.
- An attribute constraint specifies a SQL WHERE clause; for example, finding features with a particular value greater than 10. The syntax used to specify WhereClause needs to be the same as that of the underlying database holding the data; for example "NAME='UK'", "POPULATION>1000000".
The IARGlobe.SearchARFeatures and IARLayer.SearchARFeatures methods return ARFeatureCursor, which can be used to iterate over the subset of features that are returned from the search. The NextARFeature method returns the next ARFeature object within the subset. The next feature is created and allocated to ARFeatureCursor. ARFeatureCursor is forward only and does not support retrieving features that have already been retrieved nor does it support making multiple passes over the subset. If an application must make multiple passes over the data, the application needs to re-execute the search.
The IARGlobe.QueryARFeatures and IARLayer.QueryARFeatures methods differ from the SearchARFeatures method in that they return ARFeatureSet. ARFeatureSet is populated with a complete set of ARFeature objects once the searching is complete. It supports retrieving features that have already been retrieved and supports making multiple passes over the features. The Next method returns the next feature within the subset, the Reset method goes back to the first feature in the subset, and ARFeature returns a particular feature.
It is inadvisable to call the QueryARFeatures method when the resulting ARFeatureSet might contain a large number of features, as it can take a long time to return and can consume a large amount of system memory. See the following code example:
[C#] ArcReaderSearchDef arcReaderSearchDef=new ArcReaderSearchDefClass();
IARLayer arLayer=axArcReaderGlobeControl1.ARGlobe.get_ARLayer(0);
IARFeatureSet arFeatureSet=arLayer.QueryARFeatures(arcReaderSearchDef);
System.Windows.Forms.MessageBox.Show("The number of features in this layer is: " +
arFeatureSet.ARFeatureCount);
Dim pARLayer As ARLayer
Dim pArcReaderSearchDef As New ArcReaderSearchDef
Dim pARFeatureSet As ARFeatureSet
pARLayer=AxArcReaderGlobeControl1.ARGlobe.ARLayer(0)
pARFeatureSet=pARLayer.QueryARFeatures(pArcReaderSearchDef)
System.Windows.Forms.MessageBox.Show("The number of features in this layer is: " & pARFeatureSet.ARFeatureCount)
See Also:
Sample: ArcReaderControl document propertiesSample: ArcReaderControl map tools