[Development] Use of "resolution" in QtPrintSupport.

[John Layt]

Hi,

[Mostly notes for Andy Shaw to review, but thought I'd post for anyone 
interested]

In QtPrintSupport you can set the resolution to be used in printing, but as 
with many parts of painting and printing there is confusion and inconsistency 
between the painting resolution and the physical device resolution.

QtGui / QPaintDevice
 - No resolution
 - PdmDpiX / PdmDpiY default to 72

QtGui / QPdfEngine
 - Can set resolution to any value
 - Used for PdmDpiX / PdmDpiY
 - Used to calculate PdmWidth / PdmHeight in Device Pixels
 - PdmPhysicalDpiX / PdmPhysicalDpiX fixed at 1200
 - Scale factor in pageMatrix() calculations = (72.0 / resolution)

QtGui / QPdfWriter
 - In 5.3 have added api to set/get resolution which is passed to QPdfEngine

QtPrintSupport / QPrinter
 - Constructor takes PrinterMode of ScreenResolution / PrinterResolution / 
HighResolution to set initial resolution, defaults to ScreenResolution
 - No way to set/get PrinterMode afterwards, but can set/get resolution value
 - ScreenResolution is documented as using screen resolution
 - HighResolution is documented as using printer resolution, or 1200 on PDF
 - PrinterResolution is deprecated, documented as ScreenResolution on X11 and 
HighResolution on Mac/Win
 - Can set/get resolution, passes request to QPrintEngine, documented as 
"Requests that the printer prints at dpi or as near to dpi as possible."
 - Can get QList of supportedResolutions(), passes request to QPrintEngine, 
documented as printer resolutions, except on X11 where is always 72
 - Used in pageRect / paperRect calculations

QtPrintSupport / QPdfPrintEngine
 - If ScreenResolution then qt_defaultDpi()
 - If HighResolution then 1200
 - If PrinterResolution then 72
 - Can set resolution to any value
 - PPK_SupportedResolutions only ever returns 72
 - Used in pageRect / paperRect calculations
 - Uses QPdfEngine::metric()

QtPrintSupport / QCupsPrintEngine
 - Derived from QPdfPrintEngine
 - No code for printer physical resolution, uses PDF's 1200
 - Assume relies on CUPS to do any scaling to real physical

QtPrintSupport / QWinPrintEngine
 - If ScreenResolution then screen LOGPIXELSY (or 96 if error)
 - If HighResolution or PrinterResolution then printer LOGPIXELSY
 - Can set resolution to any value
 - PPK_SupportedResolutions returns printer resolutions
 - Used in pageRect / paperRect calculations
 - Used for PdmDpiX / PdmDpiY
 - Used to calculate PdmWidth / PdmHeight in Device Pixels
 - PdmPhysicalDpiX / PdmPhysicalDpiX returns printer LOGPIXELSX and LOGPIXELSY
 - Scale factor in pageMatrix() calculations = (physical dpi / screen dpi)

QtPrintSupport / QCocoaPrintEngine
 - If ScreenResolution then qt_defaultDpi()
 - If HighResolution uses highest physical resolution, or 600 if error
 - If PrinterResolution uses lowest physical resolution, or 600 if error
 - set resolution coded to find nearest supported physical resolution, but 
doesn't actually set the value
 - PPK_SupportedResolutions returns printer resolutions
 - Used in pageRect / paperRect calculations
 - Used for PdmDpiX / PdmDpiY
 - Used to calculate PdmWidth / PdmHeight in Device Pixels
 - PdmPhysicalDpiX / PdmPhysicalDpiX returns printer physical resolution
 - Scale factor in calculations = (72 / resolution)

The good news is none of the platforms actually change the physical 
resolution, they all use the paint resolution and scale to fit the physical 
resolution.  The bad news is this is not what the docs say happens, and Mac in 
particular doesn't behave correctly or consistently with the others.

What I want to change now:
 - All docs to say we don't change physical resolution, but scale instead
 - All platforms to prevent setting resolution <= 0
 - PDF PrinterResolution to set ScreenResolution, not 72
 - Cups supportedResolutions() to return printer resolutions, not just 72
 - Mac to default to current physical resolution for HighResolution
 - Mac setResolution() to allow setting to any resolution
 - Some default values may need synchronising

I still need to check that when the user changes the physical resolution in 
the print dialog, usually by changing the "Print Quality" option, that 
everything gets updated correctly.  I also need to look more into why PDF and 
Mac scaling uses (72 / resolution) but Windows uses (physical resolution / 
resolution).

Longer term, we'll probably need to implement the Print Quality api to support 
changing the physical resolution, but that's a later release.

Cheers!

John.