How to create map grids

Summary
This topic shows how to work with map grids. Code examples include creating a custom grid by code, modifying its properties and labeling, adding it to the map frame, and creating a measured grid with a different projection and draw map grid borders.

Getting a map grid programmatically

  1. To get to a map grid programmatically, navigate to the PageLayout coclass.
  2. Use its 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 map grids for that data frame. See the following code example:
[VB.NET] 
Public Sub FindMapGrid(ByVal activeView As IActiveView, ByVal pageLayout As IPageLayout)
    
    Dim map As IMap = activeView.FocusMap
    Dim graphicsContainer As IGraphicsContainer = TryCast(pageLayout, IGraphicsContainer)
    Dim frameElement As IFrameElement = graphicsContainer.FindFrame(map)
    Dim mapFrame As IMapFrame = TryCast(frameElement, IMapFrame)
    Dim mapGrids As IMapGrids = TryCast(mapFrame, IMapGrids)
    
    Dim mapGrid As IMapGrid
    If mapGrids.MapGridCount > 0 Then
        mapGrid = mapGrids.MapGrid(0)
    Else
        MessageBox.Show("No grid found.")
    End If
    
End Sub
[C#] 
public void FindMapGrid(IActiveView activeView, IPageLayout pageLayout)
{
    IMap map = activeView.FocusMap;
    IGraphicsContainer graphicsContainer = pageLayout as IGraphicsContainer;
    IFrameElement frameElement = graphicsContainer.FindFrame(map);
    IMapFrame mapFrame = frameElement as IMapFrame;
    IMapGrids mapGrids = mapFrame as IMapGrids;

    IMapGrid mapGrid = null;
    if (mapGrids.MapGridCount > 0)
    {
        mapGrid = mapGrids.get_MapGrid(0);
    }
    else
    {
        MessageBox.Show("No grid found.");
    }
}

Creating and editing a custom grid

The following code example shows how to create a custom grid by code, modify its properties and labeling, and add it the map frame. Use cartographic line symbols so the grids lines have square butts.
[VB.NET] 
Public Sub CreateGrid(ByVal activeView As IActiveView, ByVal pageLayout As IPageLayout)
    
    'Create the grid.
    Dim mapGrid As IMapGrid = New GraticuleClass
    mapGrid.Name = "Map Grid"
    
    'Create a color.
    Dim color As IColor = New RgbColorClass
    color.RGB = &HBBBBBB ' -> Gray.
    
    'Set the line symbol used to draw the grid.
    Dim cartographicLineSymbol As ICartographicLineSymbol = New CartographicLineSymbolClass
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt
    cartographicLineSymbol.Width = 2
    cartographicLineSymbol.Color = color
    mapGrid.LineSymbol = TryCast(cartographicLineSymbol, ILineSymbol)
    mapGrid.Border = Nothing ' Clear the default frame border.
    
    'Set the Tick properties.
    mapGrid.TickLength = 15
    cartographicLineSymbol = New CartographicLineSymbolClass
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt
    cartographicLineSymbol.Width = 1
    cartographicLineSymbol.Color = color
    mapGrid.TickLineSymbol = TryCast(cartographicLineSymbol, ILineSymbol)
    mapGrid.TickMarkSymbol = Nothing
    
    'Set the SubTick properties.
    mapGrid.SubTickCount = 5
    mapGrid.SubTickLength = 10
    cartographicLineSymbol = New CartographicLineSymbolClass
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt
    cartographicLineSymbol.Width = 0.2
    cartographicLineSymbol.Color = color
    mapGrid.SubTickLineSymbol = TryCast(cartographicLineSymbol, ILineSymbol)
    
    ' Set the Grid label properties.
    Dim gridLabel As IGridLabel = mapGrid.LabelFormat
    gridLabel.LabelOffset = 15
    
    'Set the Tick, SubTick, and Label Visibility along the four sides of the grid.
    mapGrid.SetTickVisibility(True, True, True, True)
    mapGrid.SetSubTickVisibility(True, True, True, True)
    mapGrid.SetLabelVisibility(True, True, True, True)
    
    'Make the map grid visible so it gets drawn when Active View is updated.
    mapGrid.Visible = True
    
    'Set the IMeasuredGrid properties.
    Dim measuredGrid As IMeasuredGrid = TryCast(mapGrid, IMeasuredGrid)
    measuredGrid.FixedOrigin = True
    measuredGrid.XIntervalSize = 10 'Meridian interval.
    measuredGrid.XOrigin = 5 'Shift grid 5°.
    measuredGrid.YIntervalSize = 10 'Parallel interval.
    measuredGrid.YOrigin = 5 'Shift grid 5°.
    
    'Add the grid to the MapFrame.
    Dim map As IMap = activeView.FocusMap
    Dim graphicsContainer As IGraphicsContainer = TryCast(pageLayout, IGraphicsContainer)
    Dim frameElement As IFrameElement = graphicsContainer.FindFrame(map)
    Dim mapFrame As IMapFrame = TryCast(frameElement, IMapFrame)
    Dim mapGrids As IMapGrids
    mapGrids = TryCast(mapFrame, IMapGrids)
    mapGrids.AddMapGrid(mapGrid)
    
    'Refresh the view.
    activeView.PartialRefresh(esriViewDrawPhase.esriViewBackground, Nothing, Nothing)
    
End Sub
[C#] 
public void CreateGrid(IActiveView activeView, IPageLayout pageLayout)
{
    //Create the grid.
    IMapGrid mapGrid = new GraticuleClass();
    mapGrid.Name = "Map Grid";

    //Create a color.
    IColor color = new RgbColorClass();
    color.RGB = 0XBBBBBB; // -> Gray.

    //Set the line symbol used to draw the grid.
    ICartographicLineSymbol cartographicLineSymbol = new CartographicLineSymbolClass
        ();
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt;
    cartographicLineSymbol.Width = 2;
    cartographicLineSymbol.Color = color;
    mapGrid.LineSymbol = cartographicLineSymbol as ILineSymbol;
    mapGrid.Border = null; // Clear the default frame border.

    //Set the Tick properties.
    mapGrid.TickLength = 15;
    cartographicLineSymbol = new CartographicLineSymbolClass();
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt;
    cartographicLineSymbol.Width = 1;
    cartographicLineSymbol.Color = color;
    mapGrid.TickLineSymbol = cartographicLineSymbol as ILineSymbol;
    mapGrid.TickMarkSymbol = null;

    //Set the SubTick properties.
    mapGrid.SubTickCount = 5;
    mapGrid.SubTickLength = 10;
    cartographicLineSymbol = new CartographicLineSymbolClass();
    cartographicLineSymbol.Cap = esriLineCapStyle.esriLCSButt;
    cartographicLineSymbol.Width = 0.2;
    cartographicLineSymbol.Color = color;
    mapGrid.SubTickLineSymbol = cartographicLineSymbol as ILineSymbol;

    // Set the Grid label properties.
    IGridLabel gridLabel = mapGrid.LabelFormat;
    gridLabel.LabelOffset = 15;

    //Set the Tick, SubTick, and Label Visibility along the four sides of the grid.
    mapGrid.SetTickVisibility(true, true, true, true);
    mapGrid.SetSubTickVisibility(true, true, true, true);
    mapGrid.SetLabelVisibility(true, true, true, true);

    //Make the map grid visible so it gets drawn when Active View is updated.
    mapGrid.Visible = true;

    //Set the IMeasuredGrid properties.
    IMeasuredGrid measuredGrid = mapGrid as IMeasuredGrid;
    measuredGrid.FixedOrigin = true;
    measuredGrid.XIntervalSize = 10; //Meridian interval.
    measuredGrid.XOrigin = 5; //Shift grid 5°.
    measuredGrid.YIntervalSize = 10; //Parallel interval.
    measuredGrid.YOrigin = 5; //Shift grid 5°.

    // Add the grid to the MapFrame.
    IMap map = activeView.FocusMap;
    IGraphicsContainer graphicsContainer = pageLayout as IGraphicsContainer;
    IFrameElement frameElement = graphicsContainer.FindFrame(map);
    IMapFrame mapFrame = frameElement as IMapFrame;
    IMapGrids mapGrids = null;
    mapGrids = mapFrame as IMapGrids;
    mapGrids.AddMapGrid(mapGrid);

    //Refresh the view.
    activeView.PartialRefresh(esriViewDrawPhase.esriViewBackground, null, null);
}

Creating an index grid

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. You can create an index grid as shown in the following code example:
[VB.NET] 
Public Sub CreateIndexGrid()
    
    Dim indexGrid As IIndexGrid = New IndexGridClass
    
    'Set the IIndexGrid properties.
    indexGrid.ColumnCount = 5
    indexGrid.RowCount = 5
    
    'Set grid label strings for the x,y axes.
    Dim i As Integer
    For i = 0 To (indexGrid.ColumnCount - 1)
        indexGrid.XLabel(i) = i.ToString
    Next i
    
    For i = 0 To (indexGrid.RowCount - 1)
        indexGrid.YLabel(i) = i.ToString
    Next i
    
End Sub
[C#] 
public void CreateIndexGrid()
{
    IIndexGrid indexGrid = new IndexGridClass();

    //Set the IIndexGrid properties.
    indexGrid.ColumnCount = 5;
    indexGrid.RowCount = 5;

    //Set grid label strings for the x,y axes.
    int i = 0;
    for (i = 0; i <= (indexGrid.ColumnCount - 1); i++)
    {
        indexGrid.set_XLabel(i, i.ToString());
    }

    for (i = 0; i <= (indexGrid.RowCount - 1); i++)
    {
        indexGrid.set_YLabel(i, i.ToString());
    }
}

Creating a measured grid

To create a measured grid with a different projection, create an instance of a coclass that inherits from SpatialReference. Set the IProjectedGrid.SpatialReference property of the grid with the ISpatialReference interface of this object. The following code example shows how to create a measured grid and set the properties exposed through its specific interfaces:
[VB.NET] 
Public Sub CreateMeasuredGrid(ByVal activeview As IActiveView)
    
    Dim map As IMap = activeview.FocusMap
    Dim measuredGrid As IMeasuredGrid = New MeasuredGridClass
    Dim mapGrid As IMapGrid = TryCast(measuredGrid, IMapGrid)
    
    'Set the IMeasuredGrid properties.
    'Origin coordinates and interval sizes are in map units.
    measuredGrid.FixedOrigin = True
    measuredGrid.Units = map.MapUnits
    measuredGrid.XIntervalSize = 1000000 'Meridian interval.
    measuredGrid.XOrigin = -3000000
    measuredGrid.YIntervalSize = 1000000 'Parallel interval.
    measuredGrid.YOrigin = -3000000
    
    'Set the IProjectedGrid properties.
    Dim projectedGrid As IProjectedGrid = TryCast(measuredGrid, IProjectedGrid)
    projectedGrid.SpatialReference = map.SpatialReference
    
End Sub
[C#] 
public void CreateMeasuredGrid(IActiveView activeview)
{
    IMap map = activeview.FocusMap;
    IMeasuredGrid measuredGrid = new MeasuredGridClass();
    IMapGrid mapGrid = measuredGrid as IMapGrid;

    //Set the IMeasuredGrid properties.
    //Origin coordinates and interval sizes are in map units.
    measuredGrid.FixedOrigin = true;
    measuredGrid.Units = map.MapUnits;
    measuredGrid.XIntervalSize = 1000000; //Meridian interval.
    measuredGrid.XOrigin =  - 3000000;
    measuredGrid.YIntervalSize = 1000000; //Parallel interval.
    measuredGrid.YOrigin =  - 3000000;

    //Set the IProjectedGrid properties.
    IProjectedGrid projectedGrid = measuredGrid as IProjectedGrid;
    projectedGrid.SpatialReference = map.SpatialReference;
}

Creating a simple map grid border

The ISimpleMapGridBorder interface provides access to the line symbol used to draw the grid border through the LineSymbol property. The following code example shows how you can create a simple map grid border:
[VB.NET] 
Public Sub CreateSimpleMapGridBorder()
    
    'Create the grid.
    Dim mapGrid As IMapGrid = New GraticuleClass
    mapGrid.Name = "Map Grid"
    
    'Create a simple map grid border.
    Dim simpleMapGridBorder As ISimpleMapGridBorder = New SimpleMapGridBorderClass
    
    'Set the ISimpleMapGridBorder properties.
    Dim simpleLineSymbol As ISimpleLineSymbol = New SimpleLineSymbolClass
    simpleLineSymbol.Style = esriSimpleLineStyle.esriSLSSolid
    simpleLineSymbol.Color = BuildRGB(0, 0, 0)
    simpleLineSymbol.Width = 2
    simpleMapGridBorder.LineSymbol = TryCast(simpleLineSymbol, ILineSymbol)
    
    'Assign this border to the map grid.
    mapGrid.Border = TryCast(simpleMapGridBorder, IMapGridBorder)
    
End Sub

Public Function BuildRGB(ByVal red As Int32, ByVal green As Int32, ByVal blue As Int32) As IColor
    
    Dim rgbColor As IRgbColor = New RgbColorClass
    With rgbColor
        .Red = red
        .Green = green
        .Blue = blue
        .UseWindowsDithering = True
    End With
    Return rgbColor
    
End Function
[C#] 
public void CreateSimpleMapGridBorder()
{
    //Create the grid.
    IMapGrid mapGrid = new GraticuleClass();
    mapGrid.Name = "Map Grid";

    //Create a simple map grid border.
    ISimpleMapGridBorder simpleMapGridBorder = new SimpleMapGridBorderClass();

    //Set the ISimpleMapGridBorder properties.
    ISimpleLineSymbol simpleLineSymbol = new SimpleLineSymbolClass();
    simpleLineSymbol.Style = esriSimpleLineStyle.esriSLSSolid;
    simpleLineSymbol.Color = BuildRGB(0, 0, 0);
    simpleLineSymbol.Width = 2;
    simpleMapGridBorder.LineSymbol = simpleLineSymbol as ILineSymbol;

    //Assign this border to the map grid.
    mapGrid.Border = simpleMapGridBorder as IMapGridBorder;
}

public IColor BuildRGB(Int32 red, Int32 green, Int32 blue)
{
    IRgbColor rgbColor = new RgbColorClass();
    rgbColor.Red = red;
    rgbColor.Green = green;
    rgbColor.Blue = blue;
    rgbColor.UseWindowsDithering = true;
    return rgbColor;
}

Creating a calibrated map grid border

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, interval of the pattern, 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. See the following code example:
[VB.NET] 
Public Sub CreateCalibratedMapGridBorder()
    
    'Create the grid.
    Dim mapGrid As IMapGrid = New GraticuleClass
    mapGrid.Name = "Map Grid"
    
    'Create a calibrated map grid border.
    Dim calibratedMapGridBorder As ICalibratedMapGridBorder = New CalibratedMapGridBorderClass
    
    'Set ICalibratedMapGridBorder properties.
    calibratedMapGridBorder.BackgroundColor = BuildRGB(255, 255, 255)
    calibratedMapGridBorder.ForegroundColor = BuildRGB(0, 0, 0)
    calibratedMapGridBorder.BorderWidth = 10
    calibratedMapGridBorder.Interval = 72
    calibratedMapGridBorder.Alternating = True 'Double alternating border.
    
    'Assign this border to the map grid.
    mapGrid.Border = TryCast(calibratedMapGridBorder, IMapGridBorder)
    
End Sub
[C#] 
public void CreateCalibratedMapGridBorder()
{
    //Create the grid.
    IMapGrid mapGrid = new GraticuleClass();
    mapGrid.Name = "Map Grid";

    //Create a calibrated map grid border.
    ICalibratedMapGridBorder calibratedMapGridBorder = new
        CalibratedMapGridBorderClass();

    //Set ICalibratedMapGridBorder properties
    calibratedMapGridBorder.BackgroundColor = BuildRGB(255, 255, 255);
    calibratedMapGridBorder.ForegroundColor = BuildRGB(0, 0, 0);
    calibratedMapGridBorder.BorderWidth = 10;
    calibratedMapGridBorder.Interval = 72;
    calibratedMapGridBorder.Alternating = true; //Double alternating border.

    //Assign this border to the map grid.
    mapGrid.Border = calibratedMapGridBorder as IMapGridBorder;
}


See Also:

IMapGrid interface
Map grids



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
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