---

Pagination

When a view is printed, there are several options for how it is placed on the page. If the view is larger than a single page, the view can be clipped, resized, or tiled across multiple pages. The view’s location on each page can be adjusted. Finally, the view can add adornments to each page. The following sections describe the options available for placing the view onto a page.

Contents:

Selecting the Page Bounds
Positioning the Page
Adorning the Page

Selecting the Page Bounds

When a view is too large to fit onto a single page, the view can be printed in one of several ways. The view can tile itself out onto separate logical pages so that its entire visible region is printed. Alternatively, the view can clip itself and print only the area that fits on the first page. Finally, the view can resize itself to fit onto a single page. These options can be set using the NSPrintInfo object’s setHorizontalPagination: and setVerticalPagination: methods with the constants NSClipPagination, NSFitPagination, and NSAutoPagination. The separate methods for horizontal and vertical pagination allow you to mix these behaviors. For example, you can clip the image in one dimension, but tile it in the other. If these options are not sufficient, the view can also implement its own pagination scheme. The following sections describe each option.

Custom Pagination

To provide a completely custom pagination scheme that does not use NSView’s built-in pagination support, a view needs to implement only two simple methods. A custom view signals that it will be calculating each page’s dimensions by overriding the knowsPageRange: method to return YES. This method also returns by reference the page number range available for printing. Within the Print panel, the user can select a subset of this range for printing. The pagination machinery then sends a rectForPage: message to the view for each page in the user-selected range. This method is sent before each page is printed. Your implementation of rectForPage: should use the page number and the current printing information to calculate an appropriate rectangle in the view’s coordinate system. The vertical and horizontal pagination settings in the NSPrintInfo object are ignored (unless your implementation takes them into account).

See “Providing a Custom Pagination Scheme” for an example of a view implementing its own pagination scheme.

Tiling Across Pages

If the view does not supply its own pagination information and one of the print info object’s pagination settings is NSAutoPagination, NSView tries to fit as much of the view being printed onto a logical page, slicing the view into the largest possible chunks along the given direction (horizontal or vertical). This is sufficient for many views, but if a view’s image must be divided only at certain places—between lines of text or cells in a table, for example—the view can adjust the automatic mechanism to accommodate this by reducing the height or width of each page.

Before printing begins, the view calculates the positions of all the row and column page breaks and gives you an opportunity to adjust them. adjustPageHeightNew:top:bottom:limit: (in Objective-C only) provides an out parameter for the new bottom coordinate of the page, followed by the proposed top and bottom. An additional parameter limits the height of the page; the bottom can’t be moved above it. adjustPageWidthNew:left:right:limit: (in Objective-C only) works in the same way to allow the view to adjust the width of a page. The limits are calculated as a percentage of the proposed page’s height or width. Your view subclass can also customize this percentage by overriding the methods heightAdjustLimit and widthAdjustLimit (in both Objective-C and Java) to return the fraction of the page that can be adjusted; a value of zero indicates that no adjustments are allowed whereas a value of one indicates that the right or bottom edge of the page bounds can be adjusted all the way to the left or top edge.

Clipping to the Page

If one of the print info object’s pagination values is NSClipPagination, the view is clipped to a single page along that dimension. If the horizontal pagination is set to clipped, the left most section of the view is printed, clipped to the width of a single page. If the vertical pagination is set to clipped, the top most section of the view is printed, clipped to the height of a single page.

Fitting to the Page

If the print info object’s pagination setting is NSFitPagination, the image is resized to fit onto the page. Although vertical and horizontal pagination need not be the same, if either dimension is scaled, the other dimension is scaled by the same amount to avoid distorting the image. If both dimensions are scaled, the scaling factor that produces the smaller image is used, thereby avoiding both distortion and clipping. Note that print info object’s scaling factor (NSPrintScalingFactor), which the user sets in the Page Layout panel, is independent of the scaling that’s imposed by pagination and is applied after the pagination scaling.

Positioning the Page

The next stage of pagination involves placing the image to be printed on the logical page. NSView’s instance method locationOfPrintRect: places it according to several print info attributes. By default it places the image in the upper left corner of the page, but if the print info object’s isHorizontallyCentered or isVerticallyCentered methods return YES, it centers a single-page image along the appropriate axis. A multiple-page document, however, is always placed at the top left corner of the page so that the divided pieces can be assembled at their edges.

Override this method to position the image yourself. The returned point is relative to the bottom-left corner of the paper in page coordinates. You need to include the page margins in calculating the position.

Adorning the Page

After the NSView has sliced out a rectangle and positioned it on a page, it’s given a chance to add extra marks to the page, such as crop marks or page numbers. drawPageBorderWithSize: is used for logical pages, and is invoked once for each page.

See the “Providing a Custom Pagination Scheme” task for more information on using drawPageBorderWithSize:.

---