Working with the page layout

---

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. PageLayout is primarily used for arranging information for printing or graphic exporting.

The PageLayout object is 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 graphic elements.

Although both the PageLayout and Map objects are graphics containers, they store different types of graphics. PageLayout can store frame elements, such as a MapFrame, and both PageLayout and Map 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 PageLayout.

For more information about working with the page layout, including how-to documents and code samples, see the following topics:

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

The IGraphicsContainer interface 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.

To present itself as a hard-copy output page, PageLayout automatically creates the following objects:

The PageLayout object automatically creates a Page object to manage the page of paper on which the layout resides. In addition to color, size, and orientation, the Page object manages other 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 the properties of a page, including 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 as follows:

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, snap tolerance, snap grid, and 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 that is used to help position elements. The grid can be used as a visual indicator of size and position, or it can 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, itself, 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 Graphic snap environment section.

The primary interface on the SnapGrid object is ISnapGrid. Use this interface to change the grid's horizontal and vertical spacing and to control grid visibility. 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 as well as the 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 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, PageLayout supports element snapping. Elements can 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 the PageLayout object automatically creates the object when it, itself, is created. 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 it has 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 the order in which the snap agents are called. With this interface, you can establish a snap agent priority - for example, if 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 layout's 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, there are also snap agents that snap to them. Layout snap agents include the following:

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.SnapAgentOrder) 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 IGraphicSnap interface, which all graphic snap agents implement.

The IGraphicSnap 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 graphic's 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.