Working with the page layout

This topic provides an overview of the PageLayout components in ArcGIS.

The PageLayout object is a virtual page upon which geographic data and map elements, such as map frames, titles, legends, and scale bars, are placed and arranged. The PageLayout is primarily used for arranging information for printing or graphic exporting.

The PageLayout object is very similar to the Map object. Both are views, meaning they can be primary displays for geographic information; both are also graphics containers, meaning they can store graphical elements.

Although both the PageLayout and Map objects are graphics containers, the type of graphics they store is different. The PageLayout can additionally store frame elements such as a MapFrame, and both can store graphic elements, such as a TextElement. When working with map documents, the PageLayout object manages all Map objects in the document via MapFrame objects. When working with a map document, all Maps must be contained by a MapFrame element, which is directly managed by the PageLayout.

The IPageLayout interface is the primary interface implemented by the PageLayout object. Use this interface to access the RulerSettings, the SnapGrid, the SnapGuides, and the Page objects. IPageLayout also has methods for zooming the view and changing the focus map.

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 TextElement stored in the layout’s graphics container.

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.

In order to present itself as a hardcopy output page, the PageLayout automatically creates these objects: SnapGuides, SnapGrid, RulerSettings, and Page.

The PageLayout object automatically creates a Page object to manage the page of paper on which the layout resides. Aside from color, size, and orientation, the Page object manages additional layout properties, such as page units, border style, and printable bounds. Access the PageLayout’s Page object via IPageLayout::Page.

IPage is the primary interface on the Page object. Use this interface to access all of the properties of a Page, including the page’s border, background, background color, orientation, and size.

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 Page object is the event source for page events. Page events are fired by the Page object to notify all clients that certain aspects of the page have changed. The page events are grouped under the IPageEvents interface and are PageColorChanged, PageMarginsChanged, PageSizeChanged, and PageUnitsChanged. The PageLayout object listens for these events so it can modify its layout according to changes made to its page. For example, when the page units are changed, the page layout needs to update its transformation, update the snap tolerance and snap grid, update its snap guides, and convert its graphics to the new units.

The page layout supports a snap grid, which is a grid of reference points on the layout used to help position elements. The grid may be used as a visual indicator of size and position, or it may be used to snap elements into position.

The SnapGrid object represents the snap grid. Although this object is creatable, there is generally no need to create one as the PageLayout object automatically creates one when it is created. Use IPageLayout::SnapGrid to get a reference to the snap grid currently associated with the layout view.

For information about enabling and disabling grid snapping, see the section on graphic snap agents in this document.

The primary interface on the SnapGrid object is ISnapGrid. Use this interface to change the grid’s horizontal and vertical spacing and control whether or not the grid is visible. The SnapGrid implements IPersist and IPersistStream to save the object’s current settings in the current map document.

You can use rulers, guides, and grids in layout view to align elements on the page.

The PageLayout object has two SnapGuides objects, one for managing horizontal guides, and one for managing vertical guides. Use IPageLayout::VerticalSnapGuides or IPageLayout::HorizontalSnapguides to obtain a reference to the desired SnapGuides object.

Each SnapGuides object manages an internal collection of individual guides. For example, the SnapGuides object that represents the horizontal snap guides may contain 10 individual guides. Use ISnapGuides to add a new guide, remove a guide, and turn the visibility of the guides on or off.

Rulers show the size of a page and elements on the final printed map.

The PageLayout object has a RulerSettings object that manages the ruler settings so that applications can draw the rulers. Although this object is creatable, there is generally no need to create one because the PageLayout object automatically instantiates one when it is created. Use IPageLayout::RulerSettings to get a reference to the RulerSettings object currently associated with the PageLayout.

The IRulerSettings interface only has one property, SmallestDivision. This property controls the size of the smallest ruler division in page units. For example, if the page size is 8.5 by 11 inches and the SmallestDivision is set to 2, the rulers in layout view will read off every 2 inches. If the property is set to .1, the rulers will read off every 1/10 of an inch.

The graphic snap environment controls which graphic snap agents are active, the order in which they are called, and the snap tolerance.

To aid in aligning and positioning elements on a page, the PageLayout supports element snapping. Elements may be snapped to the snap grid, rulers, guides, and margins. Snapping is performed by a combination of efforts between snapping target objects and snap agents. The snap agents attempt to move a graphic to a position on a snapping target object. The PageLayout object manages the snap agents, snapping target objects, and the snapping environment.

The GraphicSnapEnvironment object manages the graphic snap agents. This object is creatable, but typically this is not necessary because PageLayout object automatically creates the object when it itself is created. The PageLayout actually aggregates a GraphicSnapEnvironment object, making it part of the PageLayout object.

To get a reference to the GraphicSnapEnvironment associated with the page layout, simply cast to IGraphicSnapEnvironment from any of the other interfaces on PageLayout, such as IPageLayout.

Use the IGraphicSnapEnvironment interface to add or delete snap agents and to snap a graphic into place with SnapShape. The SnapShape method calls each snap agent’s snap method until one of them returns True, indicating that they have moved the graphic. When a snap agent returns True, no other snap agents are called. You can also use the SnapAgentOrder property on this interface to control in which order the snap agents are called. With this interface, you can establish a snap agent priority—for example, you may decide snapping to the snap grid is more important than snapping to the page margins.

The grid snap moves graphics to the snap grid. The guide snap moves graphics to the horizontal and vertical guides. The margin snap snaps graphics to the layouts printable bounds. The ruler snap snaps graphics to the rulers.

Rulers, guides, and grids are layout objects that aid in aligning elements on a page. However, these objects are only half the story—there are also snap agents that snap to them. Layout snap agents include GridSnap, GuideSnap, MarginSnap, and RulerSnap. There is a one-to-one correlation between the snap agents and the objects to which they snap. For example, the GridSnap snap agent attempts to snap graphic elements to the snap grid created by the SnapGrid object. The exception is the MarginSnap snap agent, which simply snaps to the layout’s printable bounds (IPage::PrintableBounds).

Graphics are snapped into place by calling IGraphicSnapEnvironment::SnapShape on the PageLayout object. SnapShape in turn calls IGraphicSnap::SnapX and IGraphicSnap::SnapY on each active snap agent (in the order specified by IGraphicSnapEnvironment::SnapOrder) until one of the snap agents returns True, indicating that a new point has been found that meets the criteria of the snap agent. SnapX and SnapY are separate calls because some agents, such as guides, may only act in one direction. GraphicSnap is an abstract class with the interface IGraphicSnap, which all graphic snap agents implement.

All graphic snap agents implement the IGraphicSnap interface. This interface only has three members: Name, SnapX, and SnapY. SnapX and SnapY are unique and are used to determine if a graphic can be snapped. For example, the GridSnap agent’s implementation of SnapX for polygon graphics checks if either the Xmin or Xmax of the graphics bounding rectangle is within snap tolerance of the snap grid. If either is, the graphic is moved the calculated distance between the two. SnapX and SnapY always return a Boolean, indicating whether or not the graphic was snapped. If any snap agent returns True, no other snap agents are called. This interface is used to tie the snap agents to the PageLayout object. If this property is not set, the graphic snap agents will not work properly. Because IPageLayoutSnap inherits from IGraphicSnap, all the methods on IGraphicSnap are directly available on IPageLayoutSnap.