Positioning and printing pages using BeginPage and EndPage
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.
BeginPage
is used to transform each page in the job into its correct position on the output page. These transformations are completely general—there is no need for the pages to be positioned on a grid— binding margins can be calculated and pages can even be rotated. BeginPage
can also be used to put additional marks on the page—see Adding to the page.
At the time BeginPage
is called, the graphics state has been re-initialized so that the coordinate system is that of the output page, and more significantly, the clipping is set up to enclose the whole of the output page. Therefore, the BeginPage
procedure must also clip to the individual page of the job in its position on the page; otherwise, marks which were not intended to be visible in the original job may appear on the output.
EndPage
is then used to determine when the output page is full of input pages. EndPage
returns a Boolean to say whether the page should be printed or not; its main purpose here is to calculate that value. It must also decide what to do at the end of the job when there may or may not be some remaining pages left over. EndPage
is called at device deactivation (that is, loosely speaking, when a second setpagedevice
operator is called, or more likely when restore
reinstates a previous page device as illustrated in the following sequence).
save
<<...>> setpagedevice % (1), deactivates previous page device
% calling EndPage and BeginPage
...
<<...>> setpagedevice % (2), deactivates (1) (calling EndPage
% and BeginPage) but no pages yet
...
<<...>> setpagedevice % (3), deactivates (2) (calling EndPage
% and BeginPage) but no pages yet
...
showpage % calls EndPage and BeginPage
...
restore % deactivates (3), calling EndPage which can emit the
% remaining pages
The restore
may be implicit in the server loop or may be in the job itself. This mechanism is described in more detail in [RB2] (section 4.11).
EndPage
could also add marks to the output, but would be limited to the clipping set up for the page in the previous BeginPage
, which may have been restricted further by the job. This would require a call to the initclip
operator to work round.
Nevertheless, EndPage
is a better place—to avoid extra pages with just the additional marks if AutoShowpage
is true
.