Map grids

About map grids

The Carto library contains a set of map grid objects that display index and geographic reference grids on a map. A map grid can be a grid of geographic or projected coordinates, or a reference grid like those found in street maps. Map grids are part of the layout of a map and are only visible in layout view. An alternative to writing a custom grid is to use the Make Grids and Graticules Layer tool in ArcGIS to create a set of feature classes to represent the grid.

By reviewing the Carto object model diagram (OMD), you can see that all the available standard grid classes in ArcGISCustomOverlayGrid, Graticule, IndexGrid, and MeasuredGridare subtypes of the MapGrid abstract class. The existing map grids also implement IGraphicsComposite. This interface can be used programmatically to access graphic elements that compose the displayed map grid. See the following illustration that shows the parts of a map grid:

Illustration showing the parts of a map grid.

To get to a map grid programmatically, navigate to the PageLayout coclass and use the IGraphicsContainer interface's FindFrame method to get to the map's MapFrame. The MapFrame coclass has an IMapGrids interface where you can get to all the map grids for that data frame.

IMapGrid provides access to the methods and properties common to all types of map grids. When you create a map grid, populate the properties of the grid that IMapGrid exposes. After doing this, populate the properties exposed by interfaces specific to the grid type, then add the grid to a data frame. See the following illustration:

Illustration showing map grid properties.

Index grids

An index grid is a map grid that divides the map into the specified number of columns and rows.

IIndexGrid gives you access to the functionality common to all index grids. Using the XLabel and the YLabel properties, set or retrieve the label for each column and index in the grid. See the following illustration that shows an index grid:

Measured grids

A measured grid is a map grid with grid lines on a coordinate system specified using the IProjectedGrid interface.

The IProjectedGrid interface holds the spatial reference information associated with a measured grid. If you want to create a measured grid in the same projection as the data frame it is in, set the IProjectedGrid.SpatialReference property using the data frame's IMap.SpatialReference property.

A measured grid divides the map into a grid of units in a coordinate system of your choice. The grid can be in a projected coordinate system or in a geographic coordinate system. A measured grid in a geographic coordinate system is equivalent to a graticule. A measured grid can be in the same spatial reference system as the data frame or in a different one. To create a measured grid with a different projection, create an instance of a coclass that inherits from SpatialReference, then set the IProjectedGrid.SpatialReference property of the grid with the ISpatialReference interface of this object.

Custom overlay grids

A custom overlay grid is a map grid with grid lines read from a feature. The ICustomOverlayGrid interface gives you access to the feature class that the grid lines are read from through the ICustomOverlayGrid.DataSource property. It also lets you specify which field in this feature class labels the grid using the ICustomOverlayGrid.LabelField property.

Map grid borders

The map grid border coclasses determine how the outline of a map grid is drawn. Using the IMapGridBorder interface, you can find the width of the map grid border. Using the DisplayName property, you can report the type of border object to which the IMapGridBorder interface is pointing. The following illustration shows the strings reported by this property for the two border types:

Illustration showing the strings reported for the simple and calibrated border types.

When you create a map grid border, do not use the IMapGridBorder interface since all the properties exposed by this interface are read-only. A simple map grid border is drawn using a line symbol specified with the ISimpleMapGridBorder interface. See the following illustration that shows a simple map grid border:

Illustration showing a simple map grid border.

Calibrated map grid borders

The CalibratedMapGridBorder coclass encapsulates the functionality required to draw a map grid outline composed of a graduated band.

Use the ICalibratedMapGridBorder interface to set or retrieve the properties of a calibrated map grid border, such as the foreground and background color of the pattern, the interval of the pattern, the background color of the band, and the width of the border. If you want the pattern to alternate in two bands across the width of the border, set the Alternating property to true. Setting this property to false produces a border with a single band of the pattern.

The interval of the pattern on the band is in points and page units. If you want to compute your border intervals in map units, use DisplayTransformation to convert your interval from map units to page units. You can convert these units to points (72 points equal one inch). See the following illustration that shows a calibrated map grid border:

Illustration showing a calibrated map grid border.

Grid labels

A grid label object is associated with every map grid object and provides the functionality required to draw labels around the map grid. The following illustration shows the strings returned for the various label types:

Illustration showing the strings returned for the various label types.

The interfaces returned for each label type are shown on the following illustration:

Illustration showing the interfaces returned for each label type.

DMS grid labels

A degrees/minutes/seconds (DMS) grid label identifies the map grid using degrees, minutes, and seconds. You can use the DMSGridLabel coclass to label graticules.

IDMSGridLabel provides access to the font, color, and format information required to create a DMS grid label. The LabelType property can be set using the esriDMSGridLabelType enumeration. You can use a standard label to create a DMS label with the degrees, minutes, and seconds on the same line. A stacked label has the minutes stacked over the seconds, with both in a smaller font size. See the following illustration:

Formatted grid labels

The FormattedGridLabel coclass uses any coclass that inherits from the NumberFormat abstract class to create grid labels. The following illustration shows a measured grid with formatted grid labels:

Mixed font grid labels

A mixed font grid label uses two fonts to display the label. It also uses a number format to format the label string. Use the MixedFontGridLabel coclass to label map grids with two fonts in the format specified using the IFormattedGridLabel interface.

The IMixedFontGridLabel.NumberOfDigits property determines how the two fonts are applied to the label string. The last n digits of the label—where n is the NumberOfDigits—are displayed in the secondary font and color. The remaining digits display in the primary font and color. The primary font and color are set using IGridLabel.Font and IGridLabel.Color. The secondary font and color are set using IMixedFontGridLabel.SecondaryFont and IMixedFontGridLabel.SecondaryColor. The following illustration shows a measured grid with mixed font labels:

Illustration showing a measured grid with mixed font labels.

Index grid tab styles

The index grid tab style coclasses provide the means to label an index grid. You can create an index grid tab style label using a coclass that inherits from IndexGridTabStyle. Button tab style labels are rectangular buttons, each the width of the grid cell that it borders. Continuous tab style labels form a continuous band around the map grid. Rounded tab style labels are rounded rectangles, each one is the width of the grid cell it borders.

The following illustration shows index grid tab styles:

Illustration showing button, continuous, and rounded tab style.

A background tab style labels the index grid using square, round, or rounded-square boxes. These boxes are centered outside the grid cells they border. Use IBackgroundTabStyle to determine the shape of the boxes. See the following illustration:

Illustration showing background tab styles.

For more information on working with map grids, see How to create map grids and Creating map grid labels.

Creating a subtype of MapGrid

A custom map grid must implement IMapGrid. Implement IClone and either IPersist and IPersistStream or IPersistVariant (depending on your development environment), since grids must be capable of cloning and be persisted. See the following illustration:

Illustration of MapGrid abstract class subtypes.

The MapGrid abstract class represents a grid of reference points or lines over a map. Refer to this abstract class as the starting point for any custom map grid class.

Design issues for a custom grid class

Before you start coding your custom grid class, determine if the functionality you require is similar to that available in any of the standard ArcGIS grid classes.

If you want to use one of the standard grids but change the way one or two methods or properties work, contain an instance of the required class within your custom class. Delegate all property and method calls to the contained object and adapt as required to change the way the method works. For example, if you require an IndexGrid that has extra labels, contain an instance of IndexGrid in your class and delegate member calls to this class. On a call to Draw, after calling the contained IndexGrid's Draw, add your extra labeling as required.

You might want to base your custom map grid on a preexisting map grid class by using containment.

If you want to add functionality to a grid, use containment to hold an instance of a preexisting grid class in your custom grid class. Add one or more interfaces that provide access to the new functionality. This design is similar to the approach taken in this example.
If your grid requirements are significantly different from standard grids, you might want to create a new kind of map grid. In this case, write most of the behavior, but you can save time by implementing only the interfaces required for a basic grid to function, that is, those listed previously for the MapGrid abstract class.

Map grid factories

Having reviewed the Carto OMD and the map grid classes, you might have noticed that the map grids are all associated with a factory object. For more information, see the application programming interface (API) reference for IMapGridFactory.

Development licensing	Deployment licensing
ArcGIS for Desktop Basic	ArcGIS for Desktop Basic
ArcGIS for Desktop Standard	ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced	ArcGIS for Desktop Advanced
Engine Developer Kit	Engine