ArcGIS Pro 3.4 API Reference Guide
ArcGIS.Desktop.Layouts Namespace / Layout Class / FindElement(String) Method
String
Example Version

FindElement(String) Method
Finds an element with the given name on the page layout.
Syntax
public Element FindElement( 
   string name
)

Parameters

name
String

Return Value

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);
});
Create_Empty_Group_Group
//Create an empty group element at the root level of another group element.

//Find an existing group element
GroupElement existingGroupAtRoot = layout.FindElement("Empty group at root") as GroupElement;

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement emptyGroupInGroupAtRoot = LayoutElementFactory.Instance.CreateGroupElement(existingGroupAtRoot);
  //         emptyGroupInGroupAtRoot.SetName("Empty group in group at root");
  GroupElement emptyGroupInGroupAtRoot = ElementFactory.Instance.CreateGroupElement(
                                          existingGroupAtRoot, null, "Empty group in group at root");

});
Create_Group_With_Single_Element_Root
//Create a group with a single element at the root level of the contents pane.

//Find an existing element
Element titleElm = layout.FindElement("Title") as Element;

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement groupWithSingleElementAtRoot = LayoutElementFactory.Instance.CreateGroupElement(layout, titleElm);
  //         groupWithSingleElementAtRoot.SetName("Group with single element at root"); 
  GroupElement groupWithSingleElementAtRoot = 
           ElementFactory.Instance.CreateGroupElement(layout, new List<Element>() { titleElm }, "Group with single element at root");
});
Create_Group_With_List_Elements_Root
//Create a group with a list of elements at the root level of the contents pane.

//Find an existing elements
Element scaleBar = layout.FindElement("Scale Bar") as Element;
Element northArrow = layout.FindElement("North Arrow") as Element;
Element legend = layout.FindElement("Legend") as Element;

//Build a list and add the elements
List<Element> elmList = new List<Element>
{
  scaleBar,
  northArrow,
  legend
};

//Construct on the worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement groupWithListOfElementsAtRoot = LayoutElementFactory.Instance.CreateGroupElement(layout, elmList);
  //         groupWithListOfElementsAtRoot.SetName("Group with list of elements at root");
  GroupElement groupWithListOfElementsAtRoot = 
    ElementFactory.Instance.CreateGroupElement(layout, elmList, "Group with list of elements at root");
});
CIMGraphic
//This example references a graphic element on a layout and sets its Transparency property (which is not available in the managed API)
//by accessing the element's CIMGraphic.

//Added references
using ArcGIS.Core.CIM;                             //CIM
using ArcGIS.Desktop.Core;                         //Project
using ArcGIS.Desktop.Layouts;                      //Layout class
using ArcGIS.Desktop.Framework.Threading.Tasks;    //QueuedTask

public class GraphicElementExample1
{
  public static Task<bool> UpdateElementTransparencyAsync(string LayoutName, string ElementName, int TransValue)
  {
    //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 element by name
      GraphicElement graElm = lyt.FindElement(ElementName) as GraphicElement;
      if (graElm == null)
        return false;

      //Modify the Transparency property that exists only in the CIMGraphic class.
      CIMGraphic CIMGra = graElm.GetGraphic() as CIMGraphic;
      CIMGra.Transparency = TransValue;             //e.g., TransValue = 50
      graElm.SetGraphic(CIMGra);

      return true;
    });
  }
}
Layout_FindElement
//Find a layout element.  The example below is referencing an existing text element.

TextElement txtElm = layout.FindElement("Text") as TextElement;
LayoutView_SetSelection
//Set the layout's element selection.

await QueuedTask.Run(() =>
{
  Element rec = layoutView.Layout.FindElement("Rectangle");
  Element rec2 = layoutView.Layout.FindElement("Rectangle 2");

  List<Element> elmList = new List<Element>();
  elmList.Add(rec);
  elmList.Add(rec2);

  layoutView.SelectElements(elmList);
});
LayoutViewClassExample1
//This example references the active layout view.  Next it finds a couple of elements and adds them to a collection. 
//The elements in the collection are selected within the layout view.  Finally, the layout view is zoomed to the
//extent of the selection.

// Make sure the active pane is a layout view and then reference it
if (LayoutView.Active != null)
{
  LayoutView lytView = LayoutView.Active;
  //Reference the layout associated with the layout view
  Layout lyt = await QueuedTask.Run(() => lytView.Layout);

  //Find a couple of layout elements and add them to a collection
  Element map1 = lyt.FindElement("Map1 Map Frame");
  Element map2 = lyt.FindElement("Map2 Map Frame");
  List<Element> elmList = new List<Element>();
  elmList.Add(map1);
  elmList.Add(map2);

  //Set the selection on the layout view and zoom to the selected elements
  await QueuedTask.Run(() => lytView.SelectElements(elmList));
  await QueuedTask.Run(() => lytView.ZoomToSelectedElements());
}
LayoutViewClassExample2
// Make sure the active pane is a layout view and then reference it
if (LayoutView.Active != null)
{
  LayoutView lytView = LayoutView.Active;
  //Reference the layout associated with the layout view
  Layout lyt = await QueuedTask.Run(() => lytView.Layout);

  //Find a couple of layout elements and add them to a collection
  Element map1 = lyt.FindElement("Map1 Map Frame");
  Element map2 = lyt.FindElement("Map2 Map Frame");
  List<Element> elmList = new List<Element>();
  elmList.Add(map1);
  elmList.Add(map2);

  //Set the selection on the layout view and zoom to the selected elements
  await QueuedTask.Run(() => lytView.SelectElements(elmList));
  await QueuedTask.Run(() => lytView.ZoomToSelectedElements());
  return true;
}
return false;
Creating empty group elements
//Create an empty group element at the root level of the contents pane

//Create on worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement grp1 =
  //             LayoutElementFactory.Instance.CreateGroupElement(layout);
  //         grp1.SetName("Group"); 

  //container is IElementContainer - GroupLayer or Layout
  GroupElement grp1 = ElementFactory.Instance.CreateGroupElement(
                        container, null, "Group");
});

// *** or ***

//Create a group element inside another group element

//Find an existing group element
//container is IElementContainer - GroupLayer or Layout
GroupElement existingGroup = container.FindElement("Group") as GroupElement;

//Create on worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement grp2 =
  //      LayoutElementFactory.Instance.CreateGroupElement(existingGroup);
  //         grp2.SetName("Group in Group");
  GroupElement grp2 = ElementFactory.Instance.CreateGroupElement(
    existingGroup, null, "Group in Group");
});
Create a group element with elements
//Create a group with a list of elements at the root level of the contents pane.

//Find an existing elements
//container is IElementContainer - GroupLayer or Layout
var elem1 = container.FindElement("Polygon 1");
var elem2 = container.FindElement("Bezier Text");
var elem3 = container.FindElement("Cloud Shape 2");

//Construct a list and add the elements
var elmList = new List<Element>
{
  elem1,
  elem2,
  elem3
};

//Perform on the worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement groupWithListOfElementsAtRoot =
  //             LayoutElementFactory.Instance.CreateGroupElement(layout, elmList);
  //groupWithListOfElementsAtRoot.SetName("Group with list of elements at root");
  //
  GroupElement groupWithListOfElementsAtRoot =
          ElementFactory.Instance.CreateGroupElement(
                   container, elmList, "Group with list of elements at root");
});

// *** or ***

//Create a group using a list of element names at the root level of the contents pane.

//List of element names
var elmNameList = new[] { "Para Text1", "Line 3" };

//Perform on the worker thread
await QueuedTask.Run(() =>
{
  //At 2.x - GroupElement groupWithListOfElementNamesAtRoot =
  //   LayoutElementFactory.Instance.CreateGroupElement(layout, elmNameList);
  //         groupWithListOfElementNamesAtRoot.SetName(
  //                  "Group with list of element names at root");

  //At 3.x, use the names to find the relevant elements first
  //container is IElementContainer - GroupLayer or Layout
  var elems = container.FindElements(elmNameList);
  GroupElement groupWithListOfElementNamesAtRoot =
      ElementFactory.Instance.CreateGroupElement(
           container, elems, "Group with list of element names at root");
});
Find an element on a layout
//Find an element on a layout.

// Reference a layout project item by name
LayoutProjectItem layoutItem = Project.Current.GetItems<LayoutProjectItem>().FirstOrDefault(item => item.Name.Equals("MyLayout"));
if (layoutItem != null)
{
  QueuedTask.Run(() =>
  {
    // Reference and load the layout associated with the layout item
    Layout mylayout = layoutItem.GetLayout();
    if (mylayout != null)
    {
      //Find a single specific element
      Element rect = mylayout.FindElement("Rectangle") as Element;

      //Or use the Elements collection
      Element rect2 = mylayout.Elements.FirstOrDefault(item => item.Name.Equals("Rectangle"));
    }
  });
}
Requirements

Target Platforms: Windows 11, Windows 10

ArcGIS Pro version: 3 or higher.
See Also