How to work with PageLayout elements

SummaryThis article discusses the various interfaces that can be used to interact with the PageLayout object and its elements.

Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime

Working with PageLayout elements

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 demonstrates zooming:
 

[C#] 
public void ZoomToPercent(IActiveView docActiveView)
{
IPageLayout docPageLayout;

if (docActiveView is IPageLayout)
{
docPageLayout = docActiveView as IPageLayout;
docPageLayout.ZoomToPercent(50);
}
else
{
MessageBox.Show("This tool only functions in layout view");
}
docActiveView.Refresh();
}

[VB.NET] 
Public Sub ZoomToPercent(ByVal docActiveView As IActiveView)
Dim docPageLayout As IPageLayout
If TypeOf docActiveView Is IPageLayout Then
docPageLayout = docActiveView
docPageLayout.ZoomToPercent(50)
Else
MessageBox.Show("This tool only functions in layout view")
End If
docActiveView.Refresh()
End Sub
IGraphicsContainer
IGraphicsContainer provides access to the PageLayout object's graphic elements. Use this interface to add new elements or access existing ones. For example, a title at the top of a layout is a text element stored in the layout's graphics container.
 
The following code example moves all the elements in the layout 1 inch to the right:
 

[C#] 
public void MoveAllElements(IActiveView docActiveView )
{
IPageLayout docPageLayout;
IGraphicsContainer GContainer;
IElement docElement;
ITransform2D docTransform2D;
docPageLayout = new PageLayoutClass();
if (docActiveView is IPageLayout)
{
docPageLayout = docActiveView as IPageLayout;
GContainer = docPageLayout as IGraphicsContainer;
//Loop through all the elements and move each one inch.
GContainer.Reset();
docElement = GContainer.Next();
while (docElement != null)
{
docTransform2D = docElement as ITransform2D;
docTransform2D.Move(1, 0);
docElement = GContainer.Next();
}
}
else
{
MessageBox.Show("This tool only works in pagelayout view.");
}
//Refresh only the page layout's graphics.
docActiveView.PartialRefresh (esriViewDrawPhase.esriViewGraphics, null, null);
}

[VB.NET] 
Public Sub MoveAllElements(ByVal docActiveView As IActiveView)
Dim docPageLayout As IPageLayout
Dim GContainer As IGraphicsContainer
Dim docElement As IElement
Dim docTransform2D As ITransform2D

docPageLayout = New PageLayoutClass()
If TypeOf docActiveView Is IPageLayout Then
docPageLayout = docActiveView
GContainer = docPageLayout

'Loop through all the elements and move each one inch.
GContainer.Reset()
docElement = GContainer.Next()
While Not docElement Is Nothing
docTransform2D = docElement
docTransform2D.Move(1, 0)
docElement = GContainer.Next()
End While
Else
MessageBox.Show("This tool only works in pagelayout view.")
End If
'Refresh only the page layout's graphics.
docActiveView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)

End Sub
The following code 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 sample, paste the code into the OnMouseDown event in a newly created ITool. 
 

[C#] 
public override void OnMouseDown(int Button, int Shift, int X, int Y)
{

IPageLayout docPageLayout;
IActiveView docActiveView;
IGraphicsContainer GContainer;
ITextElement docTextElement;
IElement docElement;
IPoint PtPoint;
//Use the hookhelper to obtain the loaded doc's page layout.
docPageLayout = m_hookHelper.PageLayout;
docActiveView = docPageLayout as IActiveView;
GContainer = docPageLayout as IGraphicsContainer;
//Verify ArcMap is in layout view.
if (m_hookHelper.ActiveView == m_hookHelper.PageLayout)
{
docTextElement = new TextElementClass();
docElement = docTextElement as IElement;
//Create a point from the x,y coordinate parameters.
PtPoint = docActiveView.ScreenDisplay.DisplayTransformation.ToMaPtPoint(X, Y);
docTextElement.Text = "My Map";
docElement.Geometry = PtPoint;
GContainer.AddElement(docTextElement as IElement, 0);
//Refresh only the page layout's graphics.
docActiveView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
}
else
{
MessageBox.Show("This tool only works in layout view");
return;
}


}

[VB.NET] 
Public Overrides Sub OnMouseDown(ByVal Button As Integer, ByVal Shift As Integer, ByVal X As Integer, ByVal Y As Integer)

Dim docPageLayout As IPageLayout
Dim docActiveView As IActiveView
Dim GContainer As IGraphicsContainer
Dim docTextElement As ITextElement
Dim docElement As IElement
Dim PtPoint As IPoint
'Use the hookhelper to obtain the loaded doc's page layout.
docPageLayout = m_hookHelper.PageLayout
docActiveView = docPageLayout
GContainer = docPageLayout
'Verify ArcMap is in layout view.
If TypeOf m_hookHelper.ActiveView Is IPageLayout Then
docTextElement = New TextElement
docElement = docTextElement
'Create a point from the x,y coordinate parameters.
PtPoint = docActiveView.ScreenDisplay.DisplayTransformation.ToMaPtPoint(X, Y)
docTextElement.Text = "My Map"
docElement.Geometry = PtPoint
GContainer.AddElement(docTextElement, 0)
'Refresh only the page layout's graphics.
docActiveView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)
Else
MessageBox.Show("This tool only works in layout view")
Return
End If
End Sub
IGraphicsContainerSelect (selecting graphics)
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 example returns the number of elements currently selected in the focus Map and PageLayout object:
 

[C#] 
public void GraphicSelectionCount(MaDocument Doc)
{ 
IMap docMap;
IPageLayout docPageLayout;
IGraphicsContainerSelect MapGSelect;
IGraphicsContainerSelect docPageLayoutGraphicsSelect;
docMap = new MapClass();
docPageLayout = new PageLayoutClass();
docMap = Doc.ActiveView.FocusMap;
docPageLayout = Doc.PageLayout;
MapGSelect = docMap as IGraphicsContainerSelect;
docPageLayoutGraphicsSelect = docPageLayout as IGraphicsContainerSelect;
MessageBox.Show( "Selected elements in the map: " + MapGSelect.ElementSelectionCount);
MessageBox.Show("Selected elements in the page layout: " + docPageLayoutGraphicsSelect.ElementSelectionCount);
}

[VB.NET] 
Public Sub GraphicSelectionCount(ByVal Doc As MaDocument)
Dim docMap As IMap
Dim docPageLayout As IPageLayout
Dim MapGSelect As IGraphicsContainerSelect
Dim docPageLayoutGraphicsSelect As IGraphicsContainerSelect
docMap = New Map
docPageLayout = New PageLayout
docMap = Doc.ActiveView.FocusMap
docPageLayout = Doc.PageLayout
MapGSelect = docMap
docPageLayoutGraphicsSelect = docPageLayout
MessageBox.Show("Selected elements in the map: " + MapGSelect.ElementSelectionCount)
MessageBox.Show("Selected elements in the page layout: " + docPageLayoutGraphicsSelect.ElementSelectionCount)
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 page's border, background, background color, orientation, and size.
 
The following code changes the size and color of the page:
 

[C#] 
public void CheckPageSize(IPageLayout docPageLayout)
{
IPage docPage;
docPage = new PageClass();
Double dHeight;
Double dWidth;
//m_hookHelper is initialized previously to the application's active document.
docPage = docPageLayout.Page;
docPage.QuerySize(out dWidth, out dHeight);
if ((dWidth == 8.5) && (dHeight == 11))
{
docPage.PutCustomSize(5, 5);
}
}

public void ChangePageColor(IPageLayout docPageLayout)
{
//Change the background color of the page.
IPage docPage;
IRgbColor docRgbColor;
docPage = docPageLayout.Page;
docRgbColor = new RgbColorClass();
docRgbColor.Blue = 204;
docRgbColor.Red = 255;
docRgbColor.Green = 255;
docPage.BackgroundColor = docRgbColor;
}

[VB.NET] 
Public Sub CheckPageSize(ByVal docPageLayout As IPageLayout)
'If page size is letter, change the page size to 5 by 5.
Dim docPage As IPage
docPage = New Page
Dim dHeight As Double
Dim dWidth As Double
docPage = docPageLayout.Page
docPage.QuerySize(dWidth, dHeight)
If ((dWidth = 8.5) And (dHeight = 11)) Then
docPage.PutCustomSize(5, 5)
End If
End Sub

Public Sub ChangePageColor(ByVal docPageLayout As IPageLayout)
'Change the background color of the page.
Dim docPage As IPage
Dim docRgbColor As IRgbColor
docPage = docPageLayout.Page
docRgbColor = New RgbColor
docRgbColor.Blue = 204
docRgbColor.Red = 255
docRgbColor.Green = 255
docPage.BackgroundColor = docRgbColor
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 uses the esriPageFormID enumeration to quickly change the page size. It is beneficial if you used the previous code sample to change the page's size and color.

[C#] 
public void SetLegalPageSize(IPageLayout docPageLayout)
{
IPage docPage;
docPage = new PageClass();
Double x;
Double y;
docPage = docPageLayout.Page;
docPage.FormID = esriPageFormID.esriPageFormLegal;
docPage.QuerySize(out x, out y);
MessageBox.Show("The page size is now: " + x + " " + y);
}

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