PublisherControls

Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, ArcWeb, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing, NetworkAnalyst, Schematic, SpatialAnalyst, 3DAnalyst, GlobeCore, Publisher, TrackingAnalyst

Additional library information: Contents, Object Model Diagram

The ArcGIS 9.2 release introduces the PublisherControls library. This 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.

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

About PublisherControls
The ArcReader desktop application cannot be customized and extended the same way as other ArcGIS Desktop products. Instead, developers 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 following themes and concepts should be 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 provided by a visual design environment. PublisherControls can be embedded into an existing application to add spatial capability, or they can be used to create a new stand-alone application. Once within 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 within a container, you can access the property pages by right-clicking the control and choosing Properties from the context menu. These property pages provide shortcuts to a selection of a control’s properties and methods and allow a developer 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 (e.g., ARPageLayout) and some ARObjects only work with ArcReaderGlobeControl (e.g., 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 which ARObjects are available for use with each of the PublisherControls.
 
PublisherControls
ArcReaderControl
ArcReaderGlobeControl
Objects unique to a single control ArcReaderControl
ARCommandInfo
ARPageLayout
ARMap 		ArcReaderGlobeControl
ARGlobe
Objects common to both controls ArcReaderConfiguration
ARUnitConverter
ArcReaderSearchDef
ARFeatureCursor
ARFeatureSet
ARLayer
ARFeature
 
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 developers should be aware of when working with PublisherControls is the OnAction event; it fires in response to actions occurring within the controls. A good example of using the OnAction event is illustrated in the ArcReaderGlobeControl PlayAnimation sample—the OnAction event is fired when an animation starts and stops playing. This allows the developer 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 was 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 will return false; if you pass the file path of a PMF published in ArcMap, the method will return true.
 
ArcReaderControl:

[C#] 
string filePath = @"C:\Temp\MyPublishedMxd.pmf";
if (axArcReaderControl1.CheckDocument(filePath)) axARcReaderControl1.LoadDocument(filePath,"");

[VB.NET] 
Dim sFilePath As String
sFilePath = "C:\Temp\MyPublishedMxd.pmf"
If AxArcReaderControl1.CheckDocument(sFilePath) Then AxArcReaderControl1.LoadDocument(sFilePath)
ArcReaderGlobeControl:
[C#] 
string filePath = @"C:\Temp\MyPublished3dd.pmf";
if (axArcReaderGlobeControl1.CheckDocument(filePath)) axArcReaderGlobeControl1.LoadDocument(filePath,"");

[VB.NET] 
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.
 
ArcReaderControl:

[C#] 
if (axArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
  axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter,true,Type.Missing);
}

[VB.NET] 
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint) Then
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter)
End If
ArcReaderGlobeControl:
[C#] 
if (axArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
  axArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsPrinter,true,Type.Missing);
}

[VB.NET] 
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 from CurrentARTool for the ARMap view. For example, the built-in map zoom in tool may be the current tool when the current view is a map, and the built-in page layout pan tool may 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 graphic shows the result of ARControl.CurrentARTool=esriARToolMapIdentify.
 
 
The following code illustrates how to set the current tool for ArcReaderControl to the Hyperlink tool:

[C#] 
if (axArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
  axArcReaderControl1.CurrentARTool = esriARTool.esriARToolMapHyperlink;
}

[VB.NET] 
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink) Then
    AxArcReaderControl1.CurrentARTool = esriARTool.esriARToolMapHyperlink
End If
The following code illustrates how to set the current tool for ArcReaderGlobeControl to the Hyperlink tool:

[C#] 
if (axArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
  axArcReaderGlobeControl1.CurrentARGlobeTool = esriARGlobeTool.esriARGlobeToolMapHyperlink;
}

[VB.NET] 
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 will open ARWindows relevant to ArcReaderControl. ShowARGlobeWindow is available with ArcReaderGlobeControl and will open 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 will stay 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, make one or all of the following checks: 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 illustrates 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);
}

[VB.NET] 
If AxArcReaderControl1.get_ARWindowVisible(esriARWindows.esriARWindowsMagnifier) Then
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, False)
Else
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, True)
End If
The following code illustrates 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);
}

[VB.NET] 
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 will reflect 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 filename 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 windows. 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 unit of measure. 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 will allow you to convert a distance measured in kilometers to a distance in decimal degrees. However, because the meridians converge towards the poles, a degree of longitude varies in size. One degree of longitude is approximately 111km at the equator but only 79km 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 (.art) file

An ArcReader Template (.art) is a binary file that stores settings that can be read by the ArcReader desktop application, the ArcReaderControl, and the 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 (e.g., 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, and 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 Publisher extension at 9.2 also allows .art files to be embedded in PMFs.

Functionality specific to the ArcReaderControl
The functionality described in the following paragraphs is specific to ArcReaderControl.
 
PageLayout and map extents
The ArcReaderControl has two views: Page Layout and Map. The two views are represented by two ARObjects: ARPageLayout and ARMap. Both of these objects are unique to the ArcReaderControl, as they would be 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 will typically consist of one or more ARMap objects, together with marginalia such as scalebars, 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 will pan the current visible extent by a quarter of its width. The IARPageLayout.ZoomToWholePage helper method will update the current visible extent so that the whole ARPageLayout is visible, and the IARMap.ZoomToFullExtent helper method will update 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.

[C#] 
if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypePageLayout)
{
  axArcReaderControl1.ARPageLayout.ZoomToWholePage();
}
  else if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypeMap)
{
  axArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent();
}

[VB.NET] 
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 methods 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 view on screen 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 will be 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 will not be drawn on the screen, and the layer’s check box in the TOC will be 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 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);

[VB.NET] 
'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/or spatial constraints used in the search or query.
 
The IARMap.SearchARFeatures and IARLayer.SearchARFeatures methods return ARFeatureCursor that 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 where 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.

[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);

[VB.NET] 
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 above details the steps involved in adding basic functionality to applications that would 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 difference 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:
 
Tool
Description
esriARGlobeToolNavigate
 Use this tool to navigate ARGlobe. Activating the tool will set 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 will display a dialog box with buttons that allow you to control flight. The dialog box will be displayed within 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 will set IARGlobe.Pitch to a non-zero value.
* This table is not a complete list of esriARGlobeTools.

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. The following diagram illustrates 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 as 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.  The following diagrams illustrate 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 will center the specified bookmark at the center of the view while the elevation of the observer location remains unchanged. In contrast, ZoomToBookmark will change 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 will set 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 WGS 84 (World Geodetic System) datum, and elevation is measured in IARGlobe.GlobeUnits. IARGlobe.SpatialReferenceName will return 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 will not be 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 (e.g., 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 will not be drawn on the screen, and the layer’s check box in the TOC will be 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, 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/or spatial constraints used in the search or query.
 
The IARGlobe.SearchARFeatures and IARLayer.SearchARFeatures methods return ARFeatureCursor that 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. The following code sample shows this.

[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);

[VB.NET] 
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)

Beyond the PublisherControls

See Also:

ArcReaderControl document properties sample
ArcReaderControl map tools sample
ArcReaderControl attribute query sample
ArcReaderControl spatial query sample
ArcReaderGlobeControl document properties sample
ArcReaderGlobeControl globe tools sample
ArcReaderGlobeControl spin globe sample