CreateMapSurroundElement Method (ElementFactory)

In This Topic

Create a map surround element based on the geometry and associated map surround and element properties. This method must be called on the MCT. Use QueuedTask.Run.

Syntax

C#
Visual Basic (Declaration)

public MapSurround CreateMapSurroundElement( 
   IElementContainer elementContainer,
   Geometry frameOrLocation,
   MapSurroundInfo surroundInfo,
   string elementName,
   bool select,
   ElementInfo elementInfo
)

Public Function CreateMapSurroundElement( _
   ByVal elementContainer As IElementContainer, _
   ByVal frameOrLocation As Geometry, _
   ByVal surroundInfo As MapSurroundInfo, _
   Optional ByVal elementName As String, _
   Optional ByVal select As Boolean, _
   Optional ByVal elementInfo As ElementInfo _
) As MapSurround

Parameters

elementContainer: The parent element container
frameOrLocation: The map surround frame or page location
surroundInfo: Associated surround properties
elementName: An element name (optional)
select: Select after create flag (default is true) (optional)
elementInfo: Additional element properties (optional)

Return Value

MapSurround

Exceptions

Exception	Description
ArcGIS.Core.CalledOnWrongThreadException	This method or property must be called within the lambda passed to QueuedTask.Run.
System.ArgumentException	Empty or null geometry
System.ArgumentNullException	Value cannot be null: surroundInfo
System.ArgumentException	frameOrLocation must be a point or envelope
System.ArgumentException	elementContainer must be a layout or group element (on a layout)

Remarks

Graphic layers are not valid containers for surrounds. The frameOrLocation can be either a ArcGIS.Core.Geometry.MapPoint or ArcGIS.Core.Geometry.Envelope. A default extent will be calculated if a map point is provided (rather than an envelope). Note: a given scale bar or north arrow may not fill a specified envelope depending on map scale, aspect ratio, etc, etc.

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

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

Create Legend

//Create a legend for an associated map frame.

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //Build 2D envelope geometry
  Coordinate2D leg_ll = new Coordinate2D(6, 2.5);
  Coordinate2D leg_ur = new Coordinate2D(8, 4.5);
  //At 2.x - Envelope leg_env = EnvelopeBuilder.CreateEnvelope(leg_ll, leg_ur);
  Envelope leg_env = EnvelopeBuilderEx.CreateEnvelope(leg_ll, leg_ur);

  //Reference MF, create legend and add to layout
  MapFrame mapFrame = layout.FindElement("New Map Frame") as MapFrame;
  if (mapFrame == null)
  {
    //TODO handle null map frame
    return;
  }
  //At 2.x - Legend legendElm = LayoutElementFactory.Instance.CreateLegend(
  //                                               layout, leg_env, mapFrame);
  //         legendElm.SetName("New Legend"); 
  var legendInfo = new LegendInfo()
  {
    MapFrameName = mapFrame.Name
  };
  Legend legendElm = ElementFactory.Instance.CreateMapSurroundElement(
                      layout, leg_env, legendInfo, "New Legend") as Legend;
});

Create Scale Bar From StyleItem

//Create a scale bar using a style.

//Search for a style project item by name
StyleProjectItem arcgis_2dStyle = Project.Current.GetItems<StyleProjectItem>()
                            .First(si => si.Name == "ArcGIS 2D");

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //Reference the specific scale bar by name 
  ScaleBarStyleItem scaleBarItem = arcgis_2dStyle.SearchScaleBars(
                     "Double Alternating Scale Bar").FirstOrDefault();

  //Reference the map frame and define the location
  MapFrame myMapFrame = layout.FindElement("Map Frame") as MapFrame;
  Coordinate2D coord2D = new Coordinate2D(10.0, 7.0);

  //Construct the scale bar
  //At 2.x - LayoutElementFactory.Instance.CreateScaleBar(
  //             layout, coord2D, myMapFrame, scaleBarItem);
  var sbarInfo = new ScaleBarInfo()
  {
    MapFrameName = myMapFrame.Name,
    ScaleBarStyleItem = scaleBarItem
  };
  ElementFactory.Instance.CreateMapSurroundElement(
          layout, coord2D.ToMapPoint(), sbarInfo);
});

Create North Arrow From StyleItem 1

//Create a north arrow using a style.

//Search for a style project item by name
StyleProjectItem arcgis2dStyles = Project.Current.GetItems<StyleProjectItem>()
                  .First(si => si.Name == "ArcGIS 2D");

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  NorthArrowStyleItem naStyleItem = arcgis2dStyles.SearchNorthArrows(
                "ArcGIS North 13").FirstOrDefault();

  //Reference the map frame and define the location
  MapFrame newFrame = layout.FindElement("New Map Frame") as MapFrame;
  Coordinate2D nArrow = new Coordinate2D(6, 2.5);

  //Construct the north arrow
  //At 2.x - var newNorthArrow = LayoutElementFactory.Instance.CreateNorthArrow(
  //                        layout, nArrow, newFrame, naStyleItem);

  var naInfo = new NorthArrowInfo()
  {
    MapFrameName = newFrame.Name,
    NorthArrowStyleItem = naStyleItem
  };
  var newNorthArrow = ElementFactory.Instance.CreateMapSurroundElement(
                          layout, nArrow.ToMapPoint(), naInfo);
});

Create Table Frame

//Create a table frame.

//Construct 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 and layer
  MapFrame mf = layout.FindElement("Map Frame") as MapFrame;
  FeatureLayer lyr = mf.Map.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 tableFrameInfo = new TableFrameInfo()
  {
    FieldNames = fields,
    MapFrameName = mf.Name,
    MapMemberUri = lyr.URI
  };
  var tabFrame = ElementFactory.Instance.CreateMapSurroundElement(
    layout, rec_env, tableFrameInfo) as TableFrame;
});

Create Legend 2

//Must be on QueuedTask.Run(() => { ...

//Build geometry
Coordinate2D ll = new Coordinate2D(6, 2.5);
Coordinate2D ur = new Coordinate2D(8, 4.5);
Envelope env = EnvelopeBuilderEx.CreateEnvelope(ll, ur);

//Reference MF, create legend and add to layout
MapFrame mf = layout.FindElement(mapFrameName) as MapFrame;
var surroundInfo = new LegendInfo()
{
  MapFrameName = mf.Name
};

var legendElm = ElementFactory.Instance.CreateMapSurroundElement(
  layout, env.Center, surroundInfo) as Legend;
legendElm.SetName("New Legend");

Create North Arrow From StyleItem 2

//Must be on QueuedTask.Run(() => { ...

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

//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];

//Reference MF, create north arrow and add to layout 
//var mf = container.FindElement("New Map Frame") as MapFrame;
var mf = layout.FindElement(MapFrameName) as MapFrame;
var narrow_info = new NorthArrowInfo()
{
  MapFrameName = mf.Name,
  NorthArrowStyleItem = naStyleItm
};
var arrowElm = (NorthArrow)ElementFactory.Instance.CreateMapSurroundElement(
  layout, center.ToMapPoint(), narrow_info) as NorthArrow;
arrowElm.SetName("New North Arrow");
arrowElm.SetHeight(1.75);
arrowElm.SetX(7);
arrowElm.SetY(6);

Create Table Frame

//Create a table frame.

//Construct 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 and layer
  MapFrame mf = layout.FindElement("Map Frame") as MapFrame;
  FeatureLayer lyr = mf.Map.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 tableFrameInfo = new TableFrameInfo()
  {
    FieldNames = fields,
    MapFrameName = mf.Name,
    MapMemberUri = lyr.URI
  };
  var tabFrame = ElementFactory.Instance.CreateMapSurroundElement(
    layout, rec_env, tableFrameInfo) as TableFrame;
});

Create Scale Bar

//Must be on QueuedTask.Run(() => { ...

//Build geometry
Coordinate2D ll = new Coordinate2D(5.0, 6);
Coordinate2D ur = new Coordinate2D(6.0, 7);
Envelope sbEnv = EnvelopeBuilderEx.CreateEnvelope(ll, ur);

//Reference a Scale Bar in a style
StyleProjectItem stylePrjItm = Project.Current.GetItems<StyleProjectItem>()
              .FirstOrDefault(item => item.Name == "ArcGIS 2D");
ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
             "Alternating Scale Bar 1")[0];
//ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
//                                   "Double Alternating Scale Bar 1")[0];
//ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
//                                    "Hollow Scale Bar 1")[0];

//Create Scale Bar
ScaleBarInfo sbInfo = new ScaleBarInfo()
{
  MapFrameName = mapFrame.Name
};

var sbElm = ElementFactory.Instance.CreateMapSurroundElement(
                                   layout, sbEnv, sbInfo) as ScaleBar;

Create Scale Line

//Must be on QueuedTask.Run(() => { ...

//Build geometry
Coordinate2D ll = new Coordinate2D(5.0, 8);
Coordinate2D ur = new Coordinate2D(6.0, 9);
Envelope sbEnv = EnvelopeBuilderEx.CreateEnvelope(ll, ur);

//Reference a Scale Bar in a style
StyleProjectItem stylePrjItm = Project.Current.GetItems<StyleProjectItem>()
                             .FirstOrDefault(item => item.Name == "ArcGIS 2D");
ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
                              "Scale Line 1")[0];
//ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
//                                           "Stepped Scale Line")[0];
//ScaleBarStyleItem sbStyleItm = stylePrjItm.SearchScaleBars(
//                                            "Scale Line 2")[0];

//Create Scale Bar
ScaleBarInfo sbInfo = new ScaleBarInfo()
{
  MapFrameName = mapFrame.Name,
  ScaleBarStyleItem = sbStyleItm
};

var sbElm = ElementFactory.Instance.CreateMapSurroundElement(
                  layout, sbEnv, sbInfo, "ScaleBar Line") as ScaleBar;

Requirements

Target Platforms: Windows 11, Windows 10, Windows 8.1

Reference

ElementFactory Class
ElementFactory Members

Send feedback