133258 - Enhance nsIDeviceContext print API with an additional level to support multiple documents in one print job

Status: RESOLVED WONTFIX

(Core :: Printing: Output, enhancement, P3)

Description

[Roland Mainz]

RFE: Enhance nsIDeviceContext class with an additional level between
StartDocument() / EndDocument():

Example:
Currently do printing like this:
nsIDeviceContext::BeginDocument(title)
  nsIDeviceContext::BeginPage()
    render_page();
  nsIDeviceContext::EndPage()
  nsIDeviceContext::BeginPage()
    render_page();
  nsIDeviceContext::EndPage()
  nsIDeviceContext::BeginPage()
    render_page();
  nsIDeviceContext::EndPage()
  ....
nsIDeviceContext::EndDocument()

This is sufficient for the case when we print one document.
But what about the case when we print multiple documents - for example a
frameset where each frame is printed seperately ? Then we print multiple
documents per job.

Suggested fix:
Xprint API has a solution for this - it uses a 3rd layer to care about such
cases.
Example:
XpStartJob(title);
  XpStartDoc()
    XpStartPage();
      render_page();
    XpEndPage();
    XpStartPage();
      render_page();
    XpEndPage();
    ...
  XpEndDoc();
  XpStartDoc()
    XpStartPage();
      render_page();
    XpEndPage();
    XpStartPage();
      render_page();
    XpEndPage();
    ...
  XpEndDoc();
  ...
XpEndJob();

Solution for Mozilla:
1. Rename nsIDeviceContext::BeginDocument(title) to
nsIDeviceContext::BeginJob(title), nsIDeviceContext::EndDocument() to
nsIDeviceContext::EndJob() and nsIDeviceContext::AbortDocument() to
nsIDeviceContext::AbortJob()[1]
2. Add two new methods nsIDeviceContext::BeginDocument() and
nsIDeviceContext::EndDocument()

[1]=Xprint API has support for canceling single pages/documents within a job
(sort of "undo") but I am sure we do not want that yet... :)

Comment 1

[Roland Mainz]

s/Currently do printing like this/Currently we do printing like this/

Comment 2

[Roland Mainz]

rods:
Can you do this, please ?
This is more or less a simple mass-rename action in two steps:
1. Rename the methods (see comment #0), apply patch.
2. Add new methods and add new code to send |BeginDocument()| + |EndDocument()|
for each single document being printed.

Comment 3

[Roland Mainz]

Over to someone who still works on Mozilla... :)

Comment 4

[Roland Mainz]

I forgot to explain the purpose of the API change:
Some print systems have a more fine-grained view of a "print job", allowing that
different "documents" within one job are handled differently (for example,
printers with attached postprocessing units do their processing per-document and
not per-job).
IMHO it would be nice if Mozilla could employ that feature for stuff like "print
multiple frames" (e.g. one print job, but each frame is printed in a sepeate
{StartDocument();print_frame_pages();EndDocument()} sequence).

Comment 5

[Roland Mainz]

More thoughts:
- We need a new error code if someone does something like BeginJob(),
BeginPage() (e.g. missing BeginDocument()) or EndPage() without BeginPage() etc.
etc. - we still have somewhere issues in the code which do such stuff and we do
not catch them in gfx/ layer yet (usually this leads to a random crash later...
;-( ).
- We need a new error code which says thaht the nsIDeviceContext returned an
error code prevously and cannot execute the requested action since it is in an
illegal state and cannot recover from that
- We need an API to set/get/change the device surface size/orientation/medium on
demand (required for CSS2@page)

Comment 6

[Sylvestre Ledru [:Sylvestre]]

Moving to p3 because no activity for at least 1 year(s).
See https://github.com/mozilla/bug-handling/blob/master/policy/triage-bugzilla.md#how-do-you-triage for more information

Comment 7

[Sylvestre Ledru [:Sylvestre]]

Moving to p3 because no activity for at least 1 year(s).
See https://github.com/mozilla/bug-handling/blob/master/policy/triage-bugzilla.md#how-do-you-triage for more information