This document is archived and information here might be outdated.  Recommended version.


Working with PageLayout elements (ArcObjects .NET 10.6 SDK)
ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Interacting with and configuring maps, layers, and graphics > Working with the page layout > Working with PageLayout elements (ArcObjects .NET 10.6 SDK)

Working with PageLayout elements


Summary
This topic discusses the various interfaces that can be used to work with the PageLayout object and its elements.

In this topic

IPageLayout

The IPageLayout interface is the primary interface implemented by the PageLayout object. Use this interface to access the ruler settings, snap grid, snap guides, and page objects. IPageLayout also has methods for zooming the view and changing the map's focus.
The following code example demonstrates zooming using IPageLayout:
[C#] 
public void ZoomToPercent(IActiveView activeView)
{
    IPageLayout pageLayout=activeView as IPageLayout;
    if (activeView is IPageLayout)
    {
        pageLayout.ZoomToPercent(50);
    }
    else
    {
        MessageBox.Show("This tool only functions in layout view");
    }
    activeView.Refresh();
}
[VB.NET] 
Public Sub ZoomToPercent(ByVal activeView As IActiveView)
    
    Dim pageLayout As IPageLayout=TryCast(activeView, IPageLayout)
    
    If TypeOf activeView Is IPageLayout Then
        pageLayout.ZoomToPercent(50)
    Else
        MessageBox.Show("This tool only functions in layout view")
    End If
    
    activeView.Refresh()
    
End Sub

IGraphicsContainer

The IGraphicsContainer interface provides access to the PageLayout object's graphic elements. For example, a title at the top of a layout is a text element stored in the layout's graphics container. Use this interface to add new elements or access existing ones.
The following code example uses IGraphicsContainer to move all the elements in the layout 1 inch to the right:
[C#] 
public void MoveAllElements(IActiveView activeView)
{
    IPageLayout pageLayout=new PageLayoutClass();

    if (activeView is IPageLayout)
    {
        pageLayout=activeView as IPageLayout;
        IGraphicsContainer graphicsContainer=pageLayout as IGraphicsContainer;

        //Loop through all the elements and move each 1 inch.
        graphicsContainer.Reset();
        ITransform2D transform2D=null;
        IElement element=graphicsContainer.Next();
        while (element != null)
        {
            transform2D=element as ITransform2D;
            transform2D.Move(1, 0);
            element=graphicsContainer.Next();
        }
    }
    else
    {
        MessageBox.Show("This tool only works in pagelayout view.");
    }

    //Refresh only the page layout's graphics.
    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
}
[VB.NET] 
Public Sub MoveAllElements(ByVal activeView As IActiveView)
    
    Dim pageLayout As IPageLayout=New PageLayoutClass()
    
    If TypeOf activeView Is IPageLayout Then
        pageLayout=TryCast(activeView, IPageLayout)
        Dim graphicsContainer As IGraphicsContainer=TryCast(pageLayout, IGraphicsContainer)
        
        'Loop through all the elements and move each 1 inch.
        graphicsContainer.Reset()
        
        Dim transform2D As ITransform2D
        Dim element As IElement=graphicsContainer.Next()
        While Not element Is Nothing
            transform2D=TryCast(element, ITransform2D)
            transform2D.Move(1, 0)
            element=graphicsContainer.Next()
        End While
        
    Else
        MessageBox.Show("This tool only works in pagelayout view.")
    End If
    
    'Refresh only the page layout's graphics.
    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)
    
End Sub
The following code example shows one method for adding a new text element onto the page layout. In this example, ITool is used to get a mouse down event so users can place the text element anywhere on the page layout. The script only adds a new element if ArcMap is in layout view. To use this code, paste it into the OnMouseDown event in a newly created ITool.
[C#] 
//This sub would be the MouseDown Event for AxPageLayoutControl in Engine
//or the PageLayout in ArcMap, where the following member variables 
//would have already been set in other code: 
//m_hookHelper is a ESRI.ArcGIS.Controls.IHookHelper
//m_PageLayout is a ESRI.ArcGIS.Carto.IPageLayout
public void OnMouseDown(int Button, int Shift, int X, int Y)
{
    IActiveView activeView=m_PageLayout as IActiveView;
    IGraphicsContainer graphicsContainer=m_PageLayout as IGraphicsContainer;

    //Use the hookhelper to obtain the loaded doc's page layout.
    m_PageLayout=m_hookHelper.PageLayout;

    //Verify that ArcMap is in layout view.
    if (m_hookHelper.ActiveView is IPageLayout)
    {
        //Create a point from the x,y coordinate parameters.
        IScreenDisplay screenDisplay=activeView.ScreenDisplay;
        IDisplayTransformation displayTransformation =
            screenDisplay.DisplayTransformation;
        ESRI.ArcGIS.Geometry.IPoint point=displayTransformation.ToMapPoint(X, Y);

        ITextElement textElement=new TextElementClass();
        textElement.Text="My Map";

        IElement element=textElement as IElement;
        element.Geometry=point;

        graphicsContainer.AddElement(element, 0);

        //Refresh only the page layout's graphics.
        activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
    }
    else
    {
        MessageBox.Show("This tool only works in layout view");
    }
}
[VB.NET] 
'This sub would be the MouseDown Event for AxPageLayoutControl in Engine
'or the PageLayout in ArcMap, where the following member variables would
'have already been set in other code:
'm_hookHelper is a ESRI.ArcGIS.Controls.IHookHelper
'm_PageLayout is a ESRI.ArcGIS.Carto.IPageLayout

Public Sub OnMouseDown(ByVal Button As Integer, ByVal Shift As Integer, ByVal X As Integer, ByVal Y As Integer)
    
    Dim activeView As IActiveView=TryCast(m_PageLayout, IActiveView)
    Dim graphicsContainer As IGraphicsContainer=TryCast(m_PageLayout, IGraphicsContainer)
    
    'Use the hookhelper to obtain the loaded doc's page layout.
    m_PageLayout=m_hookHelper.PageLayout
    
    'Verify that ArcMap is in layout view.
    If TypeOf m_hookHelper.ActiveView Is IPageLayout Then
        
        'Create a point from the x,y coordinate parameters.
        Dim screenDisplay As IScreenDisplay=activeView.ScreenDisplay
        Dim displayTransformation As IDisplayTransformation=screenDisplay.DisplayTransformation
        Dim point As ESRI.ArcGIS.Geometry.IPoint=displayTransformation.ToMapPoint(X, Y)
        
        Dim textElement As ITextElement=New TextElementClass
        textElement.Text="My Map"
        
        Dim element As IElement=TryCast(textElement, IElement)
        element.Geometry=point
        
        graphicsContainer.AddElement(element, 0)
        
        'Refresh only the page layout's graphics.
        activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)
        
    Else
        MessageBox.Show("This tool only works in layout view")
    End If
    
End Sub

IGraphicsContainerSelect

Most objects that are graphics containers, such as PageLayout and Map, implement the IGraphicsContainerSelect interface to expose additional members for managing their element selection. For example, IGraphicsContainerSelect.UnselectAllElements can be used to clear an object's graphic element selection.
The following code example uses IGraphicsContainerSelect to return the number of elements currently selected in the focus Map and PageLayout object:
[C#] 
public void GraphicSelectionCount(IActiveView activeView)
{
    IMap map=activeView.FocusMap;
    IPageLayout pageLayout=activeView as IPageLayout;
    IGraphicsContainer graphicsContainer=map as IGraphicsContainer;

    IGraphicsContainerSelect graphicsContainerSelect_Map=graphicsContainer as
        IGraphicsContainerSelect;
    IGraphicsContainerSelect graphicsContainerSelect_PageLayout=pageLayout as
        IGraphicsContainerSelect;

    Int32 elementSelectionCount_Map =
        graphicsContainerSelect_Map.ElementSelectionCount;
    MessageBox.Show("Selected elements in the map: " +
        elementSelectionCount_Map.ToString());

    Int32 elementSelectionCount_PageLayout =
        graphicsContainerSelect_PageLayout.ElementSelectionCount;
    MessageBox.Show("Selected elements in the page layout: " +
        elementSelectionCount_PageLayout.ToString());
}
[VB.NET] 
Public Sub GraphicSelectionCount(ByVal activeView As IActiveView)
    
    Dim map As IMap=activeView.FocusMap
    Dim pageLayout As IPageLayout=TryCast(activeView, IPageLayout)
    Dim graphicsContainer As IGraphicsContainer=TryCast(map, IGraphicsContainer)
    
    Dim graphicsContainerSelect_Map As IGraphicsContainerSelect=TryCast(graphicsContainer, IGraphicsContainerSelect)
    Dim graphicsContainerSelect_PageLayout As IGraphicsContainerSelect=TryCast(pageLayout, IGraphicsContainerSelect)
    
    Dim elementSelectionCount_Map As Int32=graphicsContainerSelect_Map.ElementSelectionCount
    MessageBox.Show("Selected elements in the map: " + elementSelectionCount_Map.ToString)
    
    Dim elementSelectionCount_PageLayout As Int32=graphicsContainerSelect_PageLayout.ElementSelectionCount
    MessageBox.Show("Selected elements in the page layout: " + elementSelectionCount_PageLayout.ToString)
    
End Sub

IPage

IPage is the primary interface on the Page object. Use this interface to access all the properties of an ArcMap page, including the border, background, background color, orientation, and size.
The following code example changes the size and color of the page using IPage:
[C#] 
public void CheckPageSize(IPageLayout pageLayout)
{
    //If the page size is letter, change the page size to 5 by 5.
    IPage page=new PageClass();

    double dHeight=0;
    double dWidth=0;

    page=pageLayout.Page;
    page.QuerySize(out dWidth, out dHeight);

    if ((dWidth == 8.5) & (dHeight == 11))
    {
        page.PutCustomSize(5, 5);
    }
}

public void ChangePageColor(IPageLayout pageLayout)
{
    IPage page=pageLayout.Page;

    IRgbColor rgbColor=new RgbColor();
    rgbColor.Blue=204;
    rgbColor.Red=255;
    rgbColor.Green=255;

    //Change the background color of the page.
    page.BackgroundColor=rgbColor;
}
[VB.NET] 
Public Sub CheckPageSize(ByVal pageLayout As IPageLayout)
    
    'If the page size is letter, change the page size to 5 by 5.
    Dim page As IPage=New PageClass
    
    Dim dHeight As Double
    Dim dWidth As Double
    
    page=pageLayout.Page
    page.QuerySize(dWidth, dHeight)
    
    If ((dWidth=8.5) And (dHeight=11)) Then
        page.PutCustomSize(5, 5)
    End If
    
End Sub

Public Sub ChangePageColor(ByVal pageLayout As IPageLayout)
    
    Dim page As IPage=pageLayout.Page
    
    Dim rgbColor As IRgbColor=New RgbColor
    rgbColor.Blue=204
    rgbColor.Red=255
    rgbColor.Green=255
    
    'Change the background color of the page.
    page.BackgroundColor=rgbColor
    
End Sub
The esriPageFormID enumeration provides a convenient list of preselected page sizes for use by the Page object. For example, to change the layout to standard legal page size, pass in esriPageFormLegal to IPage.FormID. This is much quicker than setting a custom size with IPage.PutCustomSize.
The following code example uses the esriPageFormID enumeration to quickly change the page size. It is helpful if you used the previous code sample to change the page's size and color.
[C#] 
public void SetLegalPageSize(IPageLayout pageLayout)
{
    IPage page=new Page();

    double x=0;
    double y=0;

    page=pageLayout.Page;
    page.FormID=esriPageFormID.esriPageFormLegal;
    page.QuerySize(out x, out y);

    MessageBox.Show("The page size is now: " + x + " x " + y);
}
[VB.NET] 
Public Sub SetLegalPageSize(ByVal pageLayout As IPageLayout)
    
    Dim page As IPage=New Page
    
    Dim x As Double
    Dim y As Double
    
    page=pageLayout.Page
    page.FormID=esriPageFormID.esriPageFormLegal
    page.QuerySize(x, y)
    
    MessageBox.Show("The page size is now: " & x & " x " & y)
    
End Sub

ISnapGrid and ISnapGuides

The following code example uses ISnapGrid to change the snap grid’s vertical and horizontal spacing. This code assumes you have an m_application variable declared as a reference to your application.
[C#] 
public void SnapGrid(IActiveView activeView)
{
    IPageLayout pageLayout=activeView as IPageLayout;

    ISnapGrid snapGrid=pageLayout.SnapGrid;
    snapGrid.HorizontalSpacing=0.5;
    snapGrid.VerticalSpacing=0.5;
    snapGrid.IsVisible=true;

    activeView.Refresh();
}
[VB.NET] 
Public Sub SnapGrid(ByVal activeView As IActiveView)
    
    Dim pageLayout As IPageLayout=TryCast(activeView, IPageLayout)
    
    Dim snapGrid As ISnapGrid=pageLayout.SnapGrid
    snapGrid.HorizontalSpacing=0.5
    snapGrid.VerticalSpacing=0.5
    snapGrid.IsVisible=True
    
    activeView.Refresh()
    
End Sub
The following code adds a new horizontal guide using ISnapGuides:
[C#] 
public void AddHorizontalSnapGuide(IActiveView activeView)
{
    IPageLayout pageLayout=activeView as IPageLayout;

    //Add a horizontal snap guide 5 inches up the page.
    ISnapGuides horizontalSnapGuides=null;
    horizontalSnapGuides=pageLayout.HorizontalSnapGuides;
    horizontalSnapGuides.AddGuide(5);

    if (!horizontalSnapGuides.AreVisible)
    {
        horizontalSnapGuides.AreVisible=true;
        activeView.Refresh();
    }
}
[VB.NET] 
Public Sub AddHorizontalSnapGuide(ByVal activeView As IActiveView)
    
    Dim pageLayout As IPageLayout=TryCast(activeView, IPageLayout)
    
    'Add a horizontal snap guide 5 inches up the page.
    Dim horizontalSnapGuides As ISnapGuides
    horizontalSnapGuides=pageLayout.HorizontalSnapGuides
    horizontalSnapGuides.AddGuide(5)
    
    If Not horizontalSnapGuides.AreVisible Then
        horizontalSnapGuides.AreVisible=True
        activeView.Refresh()
    End If
    
End Sub





To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced
Engine Developer Kit Engine