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):
ESRI.ArcGIS.Display ESRI.ArcGIS.Carto ESRI.ArcGIS.Geometry ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)System.Windows.Forms System
| Development licensing | Deployment licensing |
|---|---|
| ArcGIS for Desktop Basic | ArcGIS for Desktop Basic |
| ArcGIS for Desktop Standard | ArcGIS for Desktop Standard |
| ArcGIS for Desktop Advanced | ArcGIS for Desktop Advanced |
| Engine Developer Kit | Engine |