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

In This Topic
    FindElement(String) Method
    In This Topic
    Finds an element with the given name on the page layout.
    Syntax
    public Element FindElement( 
       string name
    )
    Public Function FindElement( _
       ByVal name As String _
    ) As Element

    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