How to work with PageLayout elements

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

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:
static void zoomToPercent(IActiveView docActiveView)throws Exception{
    if (docActiveView instanceof IPageLayout){
        IPageLayout docPageLayout = (IPageLayout)docActiveView;
        System.out.println("This tool only functions in layout view");
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:
static void moveAllElements(IActiveView docActiveView)throws Exception{
    IPageLayout docPageLayout = new PageLayout();
    if (docActiveView instanceof IPageLayout){
        docPageLayout = (IPageLayout)docActiveView;
        IGraphicsContainer graphicsContainer = (IGraphicsContainer)docPageLayout;
        //Loop through all the elements and move each one inch.
        IElement docElement =;
        while (docElement != null){
            ITransform2D docTransform2D = (ITransform2D)docElement;
            docTransform2D.move(1, 0);
            docElement =;
        System.out.println("This tool only works in pagelayout view.");
    //Refresh only the page layout's graphics.
    docActiveView.partialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
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. 
static void doOnMouseDown(int Button, int Shift, int X, int Y)throws Exception{
    IHookHelper m_hookHelper = new HookHelper();
    //    Use the hookhelper to obtain the loaded doc's page layout.
    IPageLayout docPageLayout = m_hookHelper.getPageLayout();
    IActiveView docActiveView = (IActiveView)docPageLayout;
    IGraphicsContainer GContainer = (IGraphicsContainer)docPageLayout;
    //    Verify ArcMap is in layout view.
    if (m_hookHelper.getActiveView() == m_hookHelper.getPageLayout()){
        ITextElement docTextElement = new TextElement();
        IElement docElement = (IElement)docTextElement;
        //    Create a point from the x,y coordinate parameters.
        IPoint PtPoint = docActiveView.getScreenDisplay().getDisplayTransformation()
            .toMapPoint(X, Y);
        docTextElement.setText("My Map");
        GContainer.addElement((IElement)docTextElement, 0);
        //    Refresh only the page layout's graphics.
        docActiveView.partialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
        System.out.println("This tool only works in layout view");
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:
static void graphicSelectionCount(MapDocument Doc)throws Exception{
    IMap docMap = new Map();
    IPageLayout docPageLayout = new PageLayout();
    docMap = Doc.getActiveView().getFocusMap();
    docPageLayout = Doc.getPageLayout();
    IGraphicsContainerSelect MapGSelect = (IGraphicsContainerSelect)docMap;
    IGraphicsContainerSelect docPageLayoutGraphicsSelect = (IGraphicsContainerSelect)
    System.out.println("Selected elements in the map: " +
    System.out.println("Selected elements in the page layout: " +
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:
static void checkPageSize(IPageLayout docPageLayout)throws Exception{
    IPage docPage = new Page();
    double dHeight[] = new double[1];
    double dWidth[] = new double[1];
    docPage = docPageLayout.getPage();
    docPage.querySize(dWidth, dHeight);
    if ((dWidth[0] == 8.5) && (dHeight[0] == 11))
        docPage.putCustomSize(5, 5);


static void changePageColor(IPageLayout docPageLayout)throws Exception{
    //Change the background color of the page.
    IPage docPage = docPageLayout.getPage();
    IRgbColor docRgbColor = new RgbColor();
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.
static void setLegalPageSize(IPageLayout docPageLayout)throws Exception{
    IPage docPage = new Page();
    double x[] = new double[1];
    double y[] = new double[1];
    docPage = docPageLayout.getPage();
    docPage.querySize(x, y);
    System.out.println("The page size is now: " + x + " " + y);

Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced
Engine Developer KitEngine