Overview

You will learn: how to create a custom map layout using the Pro SDK.

With the ArcGIS Pro SDK for .NET, you can extend ArcGIS Pro with your own unique tools and workflows. Using Microsoft Visual Studio and the Pro SDK, developers can build Pro add-ins and configurations that provide users with custom functionality specific to their organization or industry.

The Pro SDK includes a Map Layout API which provides classes and members that support managing layouts, layout elements and working with layout views. You can create new layouts and layout elements, modify existing elements, and manage selections, layout view control and navigation.

In this lab, you will create a new map layout, add layout elements including a map frame and text elements, and then open the layout in a new layout view.

Steps

Create a new ArcGIS Pro Add-In Visual Studio Project

  1. Start Visual Studio.

  2. Choose File > New > Project and then from the ArcGIS templates group, select ArcGIS Pro Module Add-in. Name the add-in project "MapLayout".

Create a new Pro button and edit DAML

  1. Right click the project and choose Add > New Item and then from the ArcGIS Pro Add-ins group select ArcGIS Pro Button from the list of item templates. Name the new class file "BuildNewLayout.cs" and press Add to close the dialog box.

  2. Open the Config.daml file and modify the button item as follows:

         <group id="MapLayout_Group1" caption="Layout Tools" appearsOnAddInTab="true">
           <!-- host controls within groups -->
           <button refID="MapLayout_BuildNewLayout" size="large" />
         </group>
       </groups>
       <controls>
         <!-- add your controls here -->
         <button id="MapLayout_BuildNewLayout" caption="Build New Layout"
           className="BuildNewLayout" loadOnClick="true" smallImage="Images\GenericButtonBlue16.png" largeImage="Images\GenericButtonBlue32.png">
           <tooltip heading="Build New Layout">Create a new map layout with layout elements.<disabledText /></tooltip>
         </button>
    

Create and setup a new layout page

  1. Open the BuildNewLayout.cs file and add the following using directives:

     using ArcGIS.Core.CIM;
     using ArcGIS.Core.Geometry;
     using ArcGIS.Desktop.Core;
     using ArcGIS.Desktop.Framework;
     using ArcGIS.Desktop.Framework.Contracts;
     using ArcGIS.Desktop.Framework.Threading.Tasks;
     using ArcGIS.Desktop.Layouts;
     using ArcGIS.Desktop.Mapping;
    
  2. In the BuildNewLayout.cs file, copy or type the following code to the OnClick method. This code creates a new layout and CIM page and applies it to the layout:

             // Create a layout which will be returned from the QueuedTask
             Layout newLayout = await QueuedTask.Run<Layout>(() =>
             {
                 // Create a new CIM page
                 CIMPage newPage = new CIMPage();
    
                 // Add properties
                 newPage.Width = 17;
                 newPage.Height = 11;
                 newPage.Units = LinearUnit.Inches;
    
                 // Add rulers
                 newPage.ShowRulers = true;
                 newPage.SmallestRulerDivision = 0.5;
    
                 // Apply the CIM page to a new layout and set name
                 newLayout = LayoutFactory.Instance.CreateLayout(newPage);
                 newLayout.SetName("Census Data");
    

Create a map and map elements and add to the layout

  1. Continue adding code to the OnClick method. This code creates a map with census data, adds it to the layout, and sets the camera:

                 // Create a new map with an ArcGIS Online basemap
                 Map newMap = MapFactory.Instance.CreateMap("Census Map", MapType.Map, MapViewingMode.Map, Basemap.NationalGeographic);
                 string url = @"http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer";
                 Uri uri = new Uri(url);
                 LayerFactory.Instance.CreateLayer(uri, newMap);
    
                 // Build a map frame geometry / envelope
                 Coordinate2D ll = new Coordinate2D(1, 0.5);
                 Coordinate2D ur = new Coordinate2D(13, 9);
                 Envelope mapEnv = EnvelopeBuilder.CreateEnvelope(ll, ur);
    
                 // Create a map frame and add it to the layout
                 MapFrame newMapframe = LayoutElementFactory.Instance.CreateMapFrame(newLayout, mapEnv, newMap);
                 newMapframe.SetName("Map Frame");
    
                 // Create and set the camera
                 Camera camera = newMapframe.Camera;
                 camera.X = -118.465;
                 camera.Y = 33.988;
                 camera.Scale = 30000;
                 newMapframe.SetCamera(camera);
    
  2. Continue adding code to the OnClick method. This code creates a title and north arrow:

                 // Add text for title
                 Coordinate2D titleTxt_ll = new Coordinate2D(4.5, 9.5);
                 CIMTextSymbol arial36bold = SymbolFactory.Instance.ConstructTextSymbol(ColorFactory.Instance.BlueRGB, 80, "Arial", "Bold");
                 GraphicElement titleTxtElm = LayoutElementFactory.Instance.CreatePointTextGraphicElement(newLayout, titleTxt_ll, "Census Data", arial36bold);
                 titleTxtElm.SetName("Title");
    
                 // Add north arrow
                 // 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 8")[0];
    
                 // Set the center coordinate and create the arrow on the layout
                 Coordinate2D center = new Coordinate2D(15, 7);
                 NorthArrow arrowElm = LayoutElementFactory.Instance.CreateNorthArrow(newLayout, center, newMapframe, naStyleItm);
                 arrowElm.SetName("New North Arrow");
                 arrowElm.SetHeight(2);
    

Finalize code and test

In this step, you continue to use the LayoutElementFactory to create and add new map elements to your layout.

  1. Finalize the OnClick method with additional code creating a map legend and then opening the layout pane.

                 // Add legend - first build 2D envelope geometry
                 Coordinate2D leg_ll = new Coordinate2D(13.5, 0.5);
                 Coordinate2D leg_ur = new Coordinate2D(16.5, 4.0);
                 Envelope leg_env = EnvelopeBuilder.CreateEnvelope(leg_ll, leg_ur);
    
                 // Create legend
                 Legend legendElm = LayoutElementFactory.Instance.CreateLegend(newLayout, leg_env, newMapframe);
                 legendElm.SetVisible(true);
                 legendElm.SetName("New Legend");
    
                 return newLayout;
              });
    
             var layoutPane = await ProApp.Panes.CreateLayoutPaneAsync(newLayout);
    
  2. Your code is completed. Build your project and debug any issues. Start the project which will launch ArcGIS Pro. Create a new project when the ArcGIS Pro start page appears. Go to the Add-in tab and find your new button. Press your new button to run the code and open the new layout.

Congratulations, you're done!

Check out and compare with our completed solution project.

Challenge

Review the online documentation

Read more information about creating layouts in the ProConcepts Layouts document, and review code snippets on layouts.

Try a community sample

Download and try the Layout community samples.

Review the API reference

Review the Pro SDK API reference and find the ArcGIS.Desktop.Layouts namespace for more information.