ArcGIS Pro 3.4 API Reference Guide
ArcGIS.Desktop.Layouts Namespace / MapFrame Class
Members Example Version

MapFrame Class
Represents a map frame on a page layout.
Object Model
MapFrame ClassCamera ClassCoordinate2D StructureCIMAutoCamera ClassEnvelope ClassCIMElement ClassGeometry ClassMapView ClassIElementContainer InterfaceMapPoint ClassEnvelope ClassMap ClassCoordinate2D StructureCoordinate2D Structure
Syntax
Remarks

The MapFrame class primarily manages the placement of maps and scenes on a page layout. You can use Map and SetMap members to get and set the Map associated with a MapFrame.

The Export method allows you to export only the contents of a map frame instead of, for example, exporting an entire page layout.

If you want to change the geographic extent within a map frame, you can use the Camera and SetCamera members to get and set the Camera associated with a MapFrame. SetCamera is an overloaded method that allows you to change the map frame extent to a camera position, a bookmark location, and so on.

Example
Create_ScaleBar
//Create a scale bar for a specific map frame and assign a scale bar style item.

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //Reference a North Arrow in a style
  StyleProjectItem stylePrjItm = Project.Current.GetItems<StyleProjectItem>().FirstOrDefault(item => item.Name == "ArcGIS 2D");
  ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars("Double Alternating Scale Bar 1")[0];

  //Build geometry
  Coordinate2D center = new Coordinate2D(7, 8);

  //Reference MF, create north arrow and add to layout 
  MapFrame mf = layout.FindElement("New Map Frame") as MapFrame;
  if (mf == null)
  {
    ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show("Map frame not found", "WARNING");
    return;
  }

  //At 2.x -
  //ScaleBar sbElm = LayoutElementFactory.Instance.CreateScaleBar(layout, center, mf, sbStyleItm);
  //sbElm.SetName("New Scale Bar");
  //sbElm.SetWidth(2);
  //sbElm.SetX(6);
  //sbElm.SetY(7.5); 

  var sbInfo = new ScaleBarInfo()
  {
    MapFrameName = mf.Name,
    ScaleBarStyleItem = sbStyleItm
  };
  var sbElm = ElementFactory.Instance.CreateMapSurroundElement(
                                      layout, center.ToMapPoint(), sbInfo, "New Scale Bar") as ScaleBar;
  sbElm.SetWidth(2);
  sbElm.SetX(6);
  sbElm.SetY(7.5);
});
Create_NorthArrow
//Create a north arrow for a specific map frame and assign a north arrow style item.

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //Reference a North Arrow in a style
  StyleProjectItem stylePrjItm = Project.Current.GetItems<StyleProjectItem>().FirstOrDefault(item => item.Name == "ArcGIS 2D");
  NorthArrowStyleItem naStyleItm = stylePrjItm.SearchNorthArrows("ArcGIS North 10")[0];

  //Build geometry
  Coordinate2D center = new Coordinate2D(7, 5.5);

  //Reference MF, create north arrow and add to layout 
  MapFrame mf = layout.FindElement("New Map Frame") as MapFrame;
  if (mf == null)
  {
    ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show("Map frame not found", "WARNING");
    return;
  }
  //At 2.x -
  //NorthArrow arrowElm = LayoutElementFactory.Instance.CreateNorthArrow(layout, center, mf, naStyleItm);
  //arrowElm.SetName("New North Arrow");
  //arrowElm.SetHeight(1.75);
  //arrowElm.SetX(7);
  //arrowElm.SetY(6);

  var naInfo = new NorthArrowInfo()
  {
    MapFrameName = mf.Name,
    NorthArrowStyleItem = naStyleItm
  };

  var arrowElm = ElementFactory.Instance.CreateMapSurroundElement(
                            layout, center.ToMapPoint(), naInfo, "New North Arrow") as NorthArrow;
  arrowElm.SetHeight(1.75);
  arrowElm.SetX(7);
  arrowElm.SetY(6);
});
MapFrame_SetCamera_Bookmark
//Set the extent of a map frame to a bookmark.

//Perform on the worker thread
await QueuedTask.Run(() =>
{
  //Reference MapFrame
  MapFrame mf_bk = layout.FindElement("Map Frame") as MapFrame;

  //Reference a bookmark that belongs to a map associated with the map frame
  Map m = mf_bk.Map;
  Bookmark bk = m.GetBookmarks().FirstOrDefault(item => item.Name.Equals("Lakes"));

  //Set the map frame extent using the bookmark
  mf_bk.SetCamera(bk);
});
MapFrame_SetCamera_Envelope
//Set the extent of a map frame to the envelope of a feature.

//Perform on the worker thread
await QueuedTask.Run(() =>
{
  //Reference MapFrame
  MapFrame mf_env = layout.FindElement("Map Frame") as MapFrame;

  //Get map and a layer of interest
  Map m = mf_env.Map;
  //Get the specific layer you want from the map and its extent
  FeatureLayer lyr = m.FindLayers("GreatLakes").First() as FeatureLayer;
  Envelope lyrEnv = lyr.QueryExtent();

  //Set the map frame extent to the feature layer's extent / envelope
  mf_env.SetCamera(lyrEnv);  //Note - you could have also used the lyr as an overload option
});
MapSurroundExample
//Added references
using ArcGIS.Desktop.Core;                         //Project
using ArcGIS.Desktop.Layouts;                      //Layout class
using ArcGIS.Desktop.Framework.Threading.Tasks;    //QueuedTask

public class MapSurroundExample
{
  public static Task<bool> UpdateMapSurroundAsync(string LayoutName, string SBName, string MFName)
  {
    //Reference a layoutitem in a project by name
    LayoutProjectItem layoutItem = Project.Current.GetItems<LayoutProjectItem>().FirstOrDefault(item => item.Name.Equals(LayoutName));
    if (layoutItem == null)
      return Task.FromResult(false);

    return QueuedTask.Run<bool>(() =>
    {
            //Reference and load the layout associated with the layout item
            Layout lyt = layoutItem.GetLayout();

            //Reference a scale bar element by name
            MapSurround scaleBar = lyt.FindElement(SBName) as MapSurround;
      if (scaleBar == null)
        return false;

            //Reference a map frame element by name
            MapFrame mf = lyt.FindElement(MFName) as MapFrame;
      if (mf == null)
        return false;

            //Set the scale bar to the newly referenced map frame
            scaleBar.SetMapFrame(mf);
      return true;
    });
  }
}
TableFrame_CreateNew
//Create a new table frame on the active layout.

Layout layout = LayoutView.Active.Layout;

//Perform on the worker thread
await QueuedTask.Run(() =>
{
  //Build 2D envelope geometry
  Coordinate2D rec_ll = new Coordinate2D(1.0, 3.5);
  Coordinate2D rec_ur = new Coordinate2D(7.5, 4.5);
  //At 2.x - Envelope rec_env = EnvelopeBuilder.CreateEnvelope(rec_ll, rec_ur);
  Envelope rec_env = EnvelopeBuilderEx.CreateEnvelope(rec_ll, rec_ur);

  //Reference map frame
  MapFrame mf = layout.FindElement("Map Frame") as MapFrame;

  //Reference layer
  Map m = mf.Map;
  FeatureLayer lyr = m.FindLayers("GreatLakes").First() as FeatureLayer;

  //Build fields list
  var fields = new[] { "NAME", "Shape_Area", "Shape_Length" };

  //Construct the table frame
  //At 2.x - TableFrame tabFrame = LayoutElementFactory.Instance.CreateTableFrame(layout, rec_env, mf, lyr, fields);
  var surroundInfo = new TableFrameInfo()
  {
    FieldNames = fields,
    MapFrameName = mf.Name,
    MapMemberUri = lyr.URI
  };
  var tabFrame = ElementFactory.Instance.CreateMapSurroundElement(layout, rec_env, surroundInfo) as TableFrame;
});
MapSurround_SetMapFrame
await QueuedTask.Run(() =>
{
  LayoutProjectItem layoutItem = Project.Current.GetItems<LayoutProjectItem>()
              .FirstOrDefault(item => item.Name.Equals("Layout Name"));
  Layout lyt = layoutItem.GetLayout();
  MapFrame mf = lyt.FindElement("Map1 Map Frame") as MapFrame;
  MapSurround ms = lyt.FindElement("Scale Bar") as MapSurround;

  ms.SetMapFrame(mf);
});
Create Map Frame and Set Camera
//Create a map frame and set its camera by zooming to the extent of an existing bookmark.

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //Build 2D envelope geometry
  Coordinate2D mf_ll = new Coordinate2D(6.0, 8.5);
  Coordinate2D mf_ur = new Coordinate2D(8.0, 10.5);
  //At 2.x - Envelope mf_env = EnvelopeBuilder.CreateEnvelope(mf_ll, mf_ur);
  Envelope mf_env = EnvelopeBuilderEx.CreateEnvelope(mf_ll, mf_ur);

  //Reference map, create MF and add to layout
  MapProjectItem mapPrjItem = Project.Current.GetItems<MapProjectItem>()
                       .FirstOrDefault(item => item.Name.Equals("Map"));
  Map mfMap = mapPrjItem.GetMap();
  Bookmark bookmark = mfMap.GetBookmarks().FirstOrDefault(
                        b => b.Name == "Great Lakes");

  //At 2.x - MapFrame mfElm =
  //                  LayoutElementFactory.Instance.CreateMapFrame(
  //                                             layout, mf_env, mfMap);
  //         mfElm.SetName("New Map Frame");
  //
  MapFrame mfElm = ElementFactory.Instance.CreateMapFrameElement(
                       layout, mf_env, mfMap, "New Map Frame");

  //Zoom to bookmark
  mfElm.SetCamera(bookmark);
});
Create Map Frame 1
//Must be on QueuedTask.Run(() => { ...

//Build geometry
Coordinate2D ll = new Coordinate2D(2.0, 4.5);
Coordinate2D ur = new Coordinate2D(4.0, 6.5);
Envelope env = EnvelopeBuilderEx.CreateEnvelope(ll, ur);

//Reference map, create MF and add to layout
//var map = MapView.Active.Map;
//var map = mapProjectItem.GetMap();
//...

MapFrame mfElm = ElementFactory.Instance.CreateMapFrameElement(
                                                layout, env, map);
Create Map Frame 2
//Must be on QueuedTask.Run(() => { ...

//Build geometry
Coordinate2D ll = new Coordinate2D(4.0, 2.5);
Coordinate2D ur = new Coordinate2D(7.0, 5.5);
Envelope env = EnvelopeBuilderEx.CreateEnvelope(ll, ur);

//Reference map, create MF and add to layout
//var map = MapView.Active.Map;
//var map = mapProjectItem.GetMap();
//...
MapFrame mfElm = ElementFactory.Instance.CreateMapFrameElement(
  layout, env.Center, map);
Create a new spatial map series
// This example create a new spatial map series and then applies it to the active layout. This will automatically 
// overwrite an existing map series if one is already present.

//Reference map frame and index layer
MapFrame mf = layout.FindElement("Map Frame") as MapFrame;
Map m = mf.Map;
BasicFeatureLayer indexLyr = m.FindLayers("Countries").FirstOrDefault() as BasicFeatureLayer;

//Construct map series on worker thread
await QueuedTask.Run(() =>
{
  //SpatialMapSeries constructor - required parameters
  SpatialMapSeries SMS = MapSeries.CreateSpatialMapSeries(layout, mf, indexLyr, "Name");
  
  //Set optional, non-default values
  SMS.CategoryField = "Continent";
  SMS.SortField = "Population";
  SMS.ExtentOptions = ExtentFitType.BestFit;
  SMS.MarginType = ArcGIS.Core.CIM.UnitType.PageUnits;
  SMS.MarginUnits = ArcGIS.Core.Geometry.LinearUnit.Centimeters;
  SMS.Margin = 1;
  SMS.ScaleRounding = 1000;
  layout.SetMapSeries(SMS);  //Overwrite existing map series.
});
Inheritance Hierarchy

System.Object
   ArcGIS.Desktop.Framework.Contracts.PropertyChangedBase
      ArcGIS.Desktop.Layouts.Element
         ArcGIS.Desktop.Layouts.MapFrame

Requirements

Target Platforms: Windows 11, Windows 10

ArcGIS Pro version: 3 or higher.
See Also