Library Reference  

PublisherControls Library Overview


Supported with: ArcGIS Desktop with Publisher

Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, Location, NetworkAnalysis, Controls, GeoAnalyst, 3DAnalyst, GlobeCore, SpatialAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI, Catalog, CatalogUI, CartoUI, DataSourcesRasterUI, ArcCatalogUI, ArcCatalog, ArcMapUI, Editor, LocationUI, ArcMap, EditorExt, GeoDatabaseDistributedUI, Geoprocessing, GeoprocessingUI, OutputExtensions, OutputExtensionsUI, SpatialAnalystUI, 3DAnalystUI, ArcScene, GlobeCoreUI, ArcGlobe, ArcScan,

,


The release of ArcGIS 9.2 sees the introduction of the PublisherControls library. The library contains two ActiveX controls (the ArcReaderControl and ArcReaderGlobeControl). The two controls can be used to create custom ArcReader applications.

Developers do not extend this library.

The PublisherControls comprises of two ActiveX controls and a set of common ArcReaderObjects.

PublisherControls

The ArcReader desktop application cannot be customized and extended in the same way as other ArcGIS Desktop products. Instead, developers can use the PublisherControls to build and extend Windows applications with custom ArcReader functionality for viewing, exploring and printing Published Map Files (PMF's). The term PublisherControls refers collectively to the ArcReaderControl and the ArcReaderGlobeControl. The ArcReaderControl is used to view PMFs published from ArcMap and the ArcReaderGlobeControl is used to view PMFs published from ArcGlobe. The following themes and concepts should be understood in order to effectively build applications using the PublisherControls.

Embeddable Components

The PublisherControls are embeddable components that can be dropped within a container form or dialog provided by a visual design environment. The PublisherControls can be embedded into an existing application to add additional spatial capability, or can be used to create a new stand-alone application. Once within a container the PublisherControls can be resized and repositioned along with other embeddable components such as command buttons and combo boxes to provide a user interface 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, access the property pages by right clicking on the control and choosing Properties from the context menu. These property pages provide shortcuts to a selection of a controls properties and methods, and allow a developer to build an application with little or no code.

ArcReaderObjects (ARObjects)

The 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 the PublisherControls does not require previous experience with ArcObjects. The ArcReaderControl corresponds to the data and layout views of the free ArcReader desktop application, together with its Table of Contents. The ArcReaderGlobeControl corresponds to the globe view of the ArcReader desktop application, together with its Table of Contents. The PublisherControls also contain the internal windows and tools used by the ArcReader desktop application, such as the Find window and the Identify tool.

The PublisherControls work with a common set of ARObjects. The majority of ARObjects work with both PublisherControls, however, some ARObjects only work with the ArcReaderControl (e.g. ARPageLayout) and some ARObjects only work with the ArcReaderGlobeControl (e.g. ARGlobe). For this reason, all of the ARObjects that work with the ArcReaderControl are represented on one Object Model Diagram (OMD) and all the ARObjects that work with the ArcReaderGlobeControl are represented on another OMD.

The table below 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 published map file is loaded into either of the PublisherControls the OnDocumentLoaded event is fired. A useful event developers should be aware of when working with the 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 their application.



Types of View

One of the most important concepts of the PublisherControls is the notion of views. You can think of the view as the place where data is drawn. The 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 Published Map File has been loaded, the ArcReaderGlobeControl has just a one view, an ARGlobe view.



Functionality common to both PublisherControls

Loading Published Map Files

A Published Map File (PMF) authored with the ArcMap desktop application and published with the Publisher extension can be loaded into an ArcReaderControl. Likewise, a Published Map File authored with the ArcGlobe desktop application and published with the Publisher extension can be loaded into the ArcReaderGlobeControl. The PMF to be loaded, by either of the PublisherControls, can be set at design time though the property pages (in development environments that support property page capability) or set programmatically using the CheckDocument method to determine whether the PMF is valid, and the LoadDocument method to load the PMF. The LoadDocument method takes an optional password parameter. If the PMF was password protected when it was published and a password is not supplied, the user will be prompted for one automatically. The ArcReaderContol can only load PMFs that have been published from a Map Document and the ArcReaderGlobeControl can only load PMFs that have been published from a Globe Document.

The table below summarizes the types of PMF that can be loaded into the PublisherControls:

ArcReaderControlArcReaderGlobeControl
Published Map Files (*.pmf) with permission to load in a customized applicationNoNo
Published Map Files (*.pmf) with permission to load in a customized applicationYesYes
Published Map Files (*.pmf) with permission to load in a customized application and unrestricted access to its contentsYesYes

The following code snippets illustrate loading PMF's into the PublisherControls. When developing an application one should remember a PMF published from ArcGlobe cannot be loaded into the ArcReaderControl, and a PMF published from ArcMap cannot be loaded into the ArcReaderGlobeControl. In light of this, it is good practice to always use the CheckDocument method. For example, if you call ArcReaderControl1::CheckDocument and pass the filepath of a PMF published in ArcGlobe, the method will return false, if you pass the filepath of a PMF published in ArcMap, the method will return true.


ArcReaderControl:


[Visual Basic 6.0]
Dim sFilePath As String
sFilePath = "C:\Temp\MyPublishedMxd.pmf"
If ArcReaderControl1.CheckDocument(sFilePath) Then ArcReaderControl1.LoadDocument sFilePath
[Visual Basic .NET]
Dim sFilePath As String
sFilePath = "C:\Temp\MyPublishedMxd.pmf"
If AxArcReaderControl1.CheckDocument(sFilePath) Then AxArcReaderControl1.LoadDocument(sFilePath)
[C#]
string filePath = @"C:\Temp\MyPublishedMxd.pmf";
if (axArcReaderControl1.CheckDocument(filePath)) axARcReaderControl1.LoadDocument(filePath,"");

ArcReaderGlobeControl:


[Visual Basic 6.0]
Dim sFilePath As String
sFilePath = "C:\Temp\MyPublished3dd.pmf"
If ArcReaderGlobeControl1.CheckDocument(sFilePath) Then ArcReaderGlobeControl1.LoadDocument sFilePath
[Visual Basic .NET]
Dim sFilePath As String
sFilePath = "C:\Temp\MyPublished3dd.pmf"
If AxArcReaderGlobeControl1.CheckDocument(sFilePath) Then AxArcReaderGlobeControl1.LoadDocument(sFilePath)
[C#]
string filePath = @"C:\Temp\MyPublished3dd.pmf";
if (axArcReaderGlobeControl1.CheckDocument(filePath)) axArcReaderGlobeControl1.LoadDocument(filePath,"");

Checking PMF Permissions

When a PMF is published the publisher can set a variety of permissions to limit the functionality that a user has access to when working with the PMF in either of the PublisherControls. These permissions should be checked with the HasDocumentPermission method and the behaviour 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:


[Visual Basic 6.0]
If ArcReaderControl1.HasDocumentPermission(esriARDocumentPermissionsPrint) Then
  ArcReaderControl1.ShowARWindow esriARWindowsPrinter
End If
[Visual Basic .NET]
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint) Then
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter)
End If
[C#]
if (axArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
  axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsPrinter,true,Type.Missing);
}

ArcReaderGlobeControl:


[Visual Basic 6.0]
If ArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissionsPrint) Then
  ArcReaderGlobeControl1.ShowARGlobeWindow esriARGlobeWindowsPrinter
End If
[Visual Basic .NET]
If AxArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint) Then
  AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsPrinter)
End If
[C#]
if (axArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsPrint))
{
  axArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsPrinter,true,Type.Missing);
}

Setting the Current Tool

Both PublisherControls have a property which specifies which built in tool is used to interact with the current view. The ArcReaderControl::CurrentARTool can be set to specify the currently active tool for either the ARPageLayout view or the ARMap view. Likewise the ArcReaderGlobeControl::CurrentARGlobeTool can be set to specify the currently active tool for the ARGlobe. The CurrentARTool for the ARPageLayout view is independent from the 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 HasDocumentPermissions method.

Enumerations of possible tools for the ArcReaderControl and ArcReaderGlobeControl:



A screenshot showing the result of setting ArcReaderControl::CurrentARTool = esriARToolMapIdentify:



Code illustrating how to set the current tool for ArcReaderControl to the Hyperlink tool:


[Visual Basic 6.0]
If ArcReaderControl1.HasDocumentPermission(esriARDocumentPermissionsHyperlink) Then
    ArcReaderControl1.CurrentARTool = esriARToolMapHyperlink
End If
[Visual Basic .NET]
If AxArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink) Then
    AxArcReaderControl1.CurrentARTool = esriARTool.esriARToolMapHyperlink
End If
[C#]
if (axArcReaderControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
  axArcReaderControl1.CurrentARTool = esriARTool.esriARToolMapHyperlink;
}

Code illustrating how to set the current tool for ArcReaderGlobeControl to the Hyperlink tool:


[Visual Basic 6.0]
If ArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissionsHyperlink) Then
    ArcReaderGlobeControl1.CurrentARGlobeTool = esriARGlobeToolHyperlink
End If
[Visual Basic .NET]
If AxArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink) Then
    AxArcReaderGlobeControl1.CurrentARGlobeTool = esriARGlobeTool.esriARGlobeToolHyperlink
End If
[C#]
if (axArcReaderGlobeControl1.HasDocumentPermission(esriARDocumentPermissions.esriARDocumentPermissionsHyperlink))
{
  axArcReaderGlobeControl1.CurrentARGlobeTool = esriARGlobeTool.esriARGlobeToolMapHyperlink;
}

Showing and Hiding Windows

The methods ShowARWindow and ShowARGlobeWindow can be used to open and close the built in windows. ShowARWindow is available with the ArcReaderControl and will open ARWindows relevant to the ArcReaderControl. ShowARGlobeWindow is available with the ArcReaderGlobeControl and will open ARGlobeWindows relevant to the ArcReaderGlobeControl. Some of the internal windows are modal and some are modeless. A modal window requires a response from the user, before they 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 ARWindowVisible or ARGlobeWindowVisible property.


Code illustrating how to display or hide the Magnifier Window when developing with the ArcReaderControl:


[Visual Basic 6.0]
If ArcReaderControl1.ARWindowVisible(esriARWindowsMagnifier) Then
  ArcReaderControl1.ShowARWindow esriARWindowsMagnifier, False
Else
  ArcReaderControl1.ShowARWindow esriARWindowsMagnifier, True
End If
[Visual Basic .NET]
If AxArcReaderControl1.get_ARWindowVisible(esriARWindows.esriARWindowsMagnifier) Then
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, False)
Else
  AxArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, True)
End If
[C#]
if (axArcReaderControl1.get_ARWindowVisible(esriARWindows.esriARWindowsMagnifier))
{
  axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier,false,Type.Missing);
}
else
{
  axArcReaderControl1.ShowARWindow(esriARWindows.esriARWindowsMagnifier, true,Type.Missing);
}

Code illustrating how to display or hide the Animation Window when developing with the ArcReaderGlobeControl:


[Visual Basic 6.0]
If ArcReaderGlobeControl1.ARGlobeWindowVisible(esriARGlobeWindowsAnimation) Then
  ArcReaderGlobeControl1.ShowARGlobeWindow esriARGlobeWindowsAnimation, False
Else
  ArcReaderGlobeControl1.ShowARGlobeWindow esriARGlobeWindowsAnimation, True
End If
[Visual Basic .NET]
If AxArcReaderGlobeControl1.get_ARGlobeWindowVisible(esriARGlobeWindows.esriARGlobeWindowsAnimation) Then
  AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation, False)
Else
  AxArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation, True)
End If
[C#]
if (axArcReaderGlobeControl1.get_ARGlobeWindowVisible(esriARGlobeWindows.esriARGlobeWindowsAnimation))
{
  axArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation,false,Type.Missing);
}
else
{
  axArcReaderGlobeControl1.ShowARGlobeWindow(esriARGlobeWindows.esriARGlobeWindowsAnimation, true,Type.Missing);
}

Producing Output

There are several methods available for getting output from either of the PublisherControls. Output will reflect exactly 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 achieved using the HasDocumentPermissions method.

Measurement and Unit Conversion

Working with maps and globes it will often be necessary to convert distance from one unit of measure to another unit of measure. For example, to undertake accurate spatial searches one may want to convert a value in one unit of measure (perhaps familiar to the user of an application) to the current ARMap::MapUnits. When working with the ArcReaderGlobeControl you may frequently need to convert between Decimal Degrees (esriARUnitsDecimalDegrees) and Degrees Minutes Seconds (esriARUnitsDegMinSec). For such reasons, the ARUnitConverter provides methods for converting values between different units of measure.

Caution should be exercised, when converting units of measurement, that the conversion is sensible. For example, the ARUnitConverter will allow one 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. The ARUnitConverter has no in-built intelligence to handle such conversions but does allow such conversions to be undertaken. If the ARUnitConverter is used to convert a distance of 1 decimal degree to kilometres, 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 Table of Content (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. The 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 the either of the PublisherControls can maintain these settings by reading and writting 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 Published Map Files.

Functionality specific to individual PublisherControls

The previous section, titled Functionality common to both PublisherControls, detailed the steps involved in adding basic functionality to applications that would contain either of the PublisherControls. Whether it be an application containing the ArcReaderControl or an application containing the ArcReaderGlobeControl, the steps involved in adding basic functionality are identical.

To build applications that fully capitalize on the rich functionality of the PublisherControls, a developer should be aware of the subtle difference in behaviour of objects, methods and properties when working with one of the PublisherControls opposed to the other. To illustrate such differences each of the PublisherControls will now be discussed separately.

Working with the ArcReaderControl

PageLayout and Map Extents

The ArcReaderControl has two views, a Page Layout view and a Map view. The two views are represented with 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 - an ARGlobe

The ARPageLayout object manages the layout of a page that would be sent as output to a printer. The 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 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.

In order to navigate around the ARPageLayout or an ARMap the CurrentARTool can be set to a built in navigation tool. For example, the built in map zoom in tool, or the page pan tool. To allow more control over extent changes the developer can explicitly manage extents using the properties and methods on the IARPageLayout and IARMap interfaces.

The GetExtent method returns the visible area of the 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 within the 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 the ARMap is visible in the display area of the CurrentView.

[Visual Basic 6.0]
If ArcReaderControl1.CurrentViewType = esriARViewTypePageLayout Then
  ArcReaderControl1.ARPageLayout.ZoomToWholePage
ElseIf ArcReaderControl1.CurrentViewType = esriARViewTypeMap Then
  ArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent
End If
[Visual Basic .NET]
If AxArcReaderControl1.CurrentViewType = esriARViewType.esriARViewTypePageLayout Then
  AxArcReaderControl1.ARPageLayout.ZoomToWholePage()
ElseIf AxArcReaderControl1.CurrentViewType = esriARViewType.esriARViewTypeMap Then
  AxArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent()
End If
[C#]
if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypePageLayout)
{
  axArcReaderControl1.ARPageLayout.ZoomToWholePage();
}
  else if (axArcReaderControl1.CurrentViewType == esriARViewType.esriARViewTypeMap)
{
  axArcReaderControl1.ARPageLayout.FocusARMap.ZoomToFullExtent();
}

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 a user can navigate backward or forwards from the current extent of the ARPageLayout or ARMap using the UndoExtent and RedoExtent methods to move through the extent stack.

The ARMap manages any 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 bookmarks 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 the 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 represent all types of data including feature layers and raster layers. An ARLayer doesnt 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 may have decided to group layers forming 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 might be grouped together and the resulting layer given the name 'water systems'. Using the IARLayer::Visible property to turn off the group layer turns off all component child layers. As such, 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 a 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 the 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 the ARMap will be made relative. The Rotation property relates to the angle that data appears inside the 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 tin layer. The MinimumScale and MaximumScale properties define the display scales of the ARLayer. At IARMap::MapScale less than the MinimumScale or greater than the MaximumScale the ARLayer will not be drawn on the screen, and the layers check box in the TOC will be greyed out. The IARLayer::GetExtent method returns the extent of the ARLayer as four coordinates representing the top left, top right, bottom right and bottom left corners of the extent in IARMap::MapUnits.

[Visual Basic 6.0]
'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
Set pARMap = ArcReaderControl1.ARPageLayout.FocusARMap
pARMap.ARLayer(0).GetExtent dXmin, dYmin, dXmax, dYmax
pARMap.SetExtent dXmin, dYmin, dXmax, dYmax
[Visual Basic .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)
[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);

Searching and Querying Features

An ARFeature object is a spatial entity modelled as an object with properties and behaviour. All ARFeature objects within an ARLayer share the same set of attribute schema; that is they have the same set of fields. There is always at least one field within the field collection. On the IARFeature interface Use the FieldCount property to return the number of fields within the collection. Each field within the collection has read only FieldName, FieldAliasName, FieldType and Value property. The Value cannot be read if the PMF was published without permission, or if the FieldType is a geometry (or shape) field. As well as accessing attribute information there are Highlight, Flash, Flicker, ZoomTo and CenterAt methods on the IARFeature interface for viewing the geometry or shape of an ARFeature.

In order to reference an ARFeature a search or query must be performed on an ARMap or an ARLayer. A search or query can only be performed on an ARLayer that is Searchable. Searchable layers are typically feature layers and not raster layers. The search or query is defined by an ArcReaderSearchDef which is passed to the QueryARFeatures or SearchARFeatures methods on the IARMap and IARLayer interfaces. An ArcReaderSearchDef defines the attribute and/or spatial constraints used in the search or query.

The IARMap::SearchARFeatures and IARLayer::SearchARFeatures methods return an 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 the ARFeatureCursor. The ARFeatureCursor is forward only and does not support retrieving features that have already been retrieved, or making multiple passes over the subset. If an application needs to 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 methods in that they return an ARFeatureSet. The ARFeatureSet is populated with a complete set of ARFeature objects once all of the searching is complete; as such 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 the ARFeature returns a particular feature. It is inadvisable to call the QueryARFeatures methods 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.

[Visual Basic 6.0]
Dim pARLayer As ARLayer
Dim pArcReaderSearchDef As New ArcReaderSearchDef
Dim pARFeatureSet As ARFeatureSet
Set pARLayer = ArcReaderControl1.ARPageLayout.FocusARMap.ARLayer(0)
Set pARFeatureSet = pARLayer.QueryARFeatures(pArcReaderSearchDef)
MsgBox "The number of features in this layer is: " & pARFeatureSet.ARFeatureCount
[Visual Basic .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)
[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);

Working with the ArcReaderGlobeControl

Globe and Layer Properties

Every PMF document published from ArcGlobe contains a globe that is represented by the ARGlobe object. The ARGlobe is the primary point for managing data layers, navigating around those data layers and finding particular features. There are several approaches developers can adopt to control navigation about the ARGlobe. Perhaps the most straightforward approach is to use an esriARGlobeTool; the following tools provide navigation functionality:

Tool Description
esriARGlobeToolNavigateUse this tool to navigate the ARGlobe. Activating the tool will set ARGlobe::Pitch = 0. Using the left mouse button the tool allows the user to rotate the globe about its center. Using the right mouse button the tool allows the user to zoom in and out along an imaginary straight line from the observer location to the ARGlobe center.
esriARGlobeToolOrbitalFlyUse this tool to fly over the ARGlobe surface at a fixed elevation. Activating this tool will display a dialog with buttons that allow a user to control flight. The dialog will be displayed within the ArcReaderGlobeControl, as specified by the window position property, accessed via the ArcReaderGlobeControl property pages.
esriARGlobeToolTargetUse this tool to center a surface location in the view.
esriARGlobeToolZoomInOutUse this tool to Zoom In and Zoom Out along an imaginary straight line between the observer location and the target on the ARGlobe surface.
esriARGlobeToolPanUse this tool to pan the ARGlobe surface. Depress the mouse and drag the view in a particular direction to pan.
esriARGlobeToolPivotUse this tool to view the point on the ARGlobe surface that is centered in the view. Using the left mouse button the tool allows the user to pivot about a point on the ARGlobe surface that is located at the center of the view. Using the right mouse button the tool allows the user to Zoom In and Zoom Out along an imaginary straight line between the observer location and the center of the view. Activating this tool will set the ARGlobe::Pitch to a none zero value.

* This table is not a complete list of esriARGlobeTools.


Alternatively the developer may choose to alter the observer location from which the ARGlobe is viewed. ARGlobe::Elevation will change the elevation of the observer location; note 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 ARGlobe::GetObserverLocation and set to a new location using ARGlobe::SetObserverLocation. When working with these methods elevation is measured in ARGlobe::GlobeUnits, and coordinates are specified as latitude and longitude measured in Decimal Degrees.


Fig. 1. A diagram illustrating ARGlobe::Elevation


From the observer location the observer views a target location along a 'Line of Sight'. When working with the ArcReaderGlobeControl the target can be considered as the point on the ARGlobe surface that is located at the centre of the view. The direction from which the ARGlobe is viewed from the observer location (Line of Sight) can be controlled using the ARGlobe::Pitch and ARGlobe::Azimuth properties. ARGlobe::Pitch is a measure of the angle between the observers Line of Sight, and the tangent of an observers imaginary closed circular orbit of the ARGlobe. ARGlobe::Azimuth is a measure of the angle between the Line of Sight and the geographic North Pole.


Fig. 2. A diagram illustrating ARGlobe::Pitch Fig. 3. A diagram illustrating ARGlobe::Azimuth

The IARGlobe interface has several methods that provide easy means of visualizing the globe and its data layers. ARGlobe::PlayAnimation can be used to play animation files (*.agas) that were published with the PMF from ArcGlobe. If the PMF being viewed in the ArcReaderGlobeControl has been published with spatial bookmarks, ARGlobe::CenterAtBookmark and ARGlobe::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 whilst 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 ARGlobe::ZoomToFullExtent helper method will set the observer location, pitch and azimuth so that the whole ARGlobe is visible in the current view. ARGlobe::CenterAt method positions the observer such that the specified coordinate is located at the center of the current view.

When working with the 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 ARGlobe::GlobeUnits. ARGlobe::SpatialReferenceName will return the name of the globes spatial reference. It is important to recognise that latitude and longitude coordinates derived from maps or globes based on other datums will not be accurate if used with the 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 the 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 the 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.

ARGlobe::GetSurfaceLocation 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 the ArcReaderGlobeControl (e.g. OnMouseDown). Using this method a developer can access the latitude and longitude, of a point on the ARGlobe surface, at which the user has positioned and clicked their mouse.

Each ARGlobe object manages a number of ARLayer objects that represent layers that where 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 doesnt 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 an ARLayer is and isnt visible. If the ARGlobe::Elevation property is less than the MinimumScale, or greater than the MaximumScale, the ARLayer will not be drawn on the screen, and the layers check box in the TOC will be greyed out. The IARLayer::GetExtent method returns the extent of the 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 modelled as an object with properties and behaviour. All ARFeature objects within an ARLayer share the same set of attribute schema; that is they have the same set of fields. There is always at least one field within the field collection. On the IARFeature interface Use the FieldCount property to return the number of fields within the collection. Each field within the collection has read only FieldName, FieldAliasName, FieldType and Value property. The Value cannot be read if the PMF was published without permission, or if the FieldType is a geometry (or shape) field. As well as accessing attribute information there are Highlight, Flash, Flicker, ZoomTo and CenterAt methods on the IARFeature interface for viewing the geometry or shape of an ARFeature.

In order to reference an ARFeature a search or query must be performed on an ARGlobe or an ARLayer. A search or query can only be performed on an ARLayer that is Searchable. Searchable layers are typically feature layers and not raster layers. The search or query is defined by an ArcReaderSearchDef which is passed to the QueryARFeatures or SearchARFeatures methods on the IARGlobe and IARLayer interfaces. An ArcReaderSearchDef defines the attribute and/or spatial constraints used in the search or query.

The IARGlobe::SearchARFeatures and IARLayer::SearchARFeatures methods return an 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 the ARFeatureCursor. The ARFeatureCursor is forward only and does not support retrieving features that have already been retrieved, or making multiple passes over the subset. If an application needs to 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 methods in that they return an ARFeatureSet. The ARFeatureSet is populated with a complete set of ARFeature objects once all of the searching is complete; as such 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 the ARFeature returns a particular feature. It is inadvisable to call the QueryARFeatures methods 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.

[Visual Basic 6.0]
Dim pARLayer As ARLayer
Dim pArcReaderSearchDef As New ArcReaderSearchDef
Dim pARFeatureSet As ARFeatureSet
Set pARLayer = ArcReaderGlobeControl1.ARGlobe.ARLayer(0)
Set pARFeatureSet = pARLayer.QueryARFeatures(pArcReaderSearchDef)
MsgBox "The number of features in this layer is: " & pARFeatureSet.ARFeatureCount
[Visual Basic .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)
[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);

Beyond the PublisherControls

At some point in your development of your customized ArcReader applications, you may wish to add further functionality that is not available with the PublisherControls; you may then consider developing with the ArcGIS Engine Controls.