Replaced the numCopies()/setNumCopies() and actualNumCopies() API.

Obsoleted the numCopies()/setNumCopies()/actualNumCopies() with
copyCount()/setCopyCount() and supportsMultipleCopies(). The
old numCopies() was confusing since it returned the number
of times a job had to be printed to get the copies you wanted.
Now copyCount() and setCopyCount() are symmetric, and always returns
the number of copies the user want to print.

Task-number: QTBUG-5605
Reviewed-by: Kim

13 files changed, 125 insertions, 45 deletions

diff --git a/src/gui/dialogs/qprintdialog_qws.cpp b/src/gui/dialogs/qprintdialog_qws.cpp
index 6b531a2659..1336c04b25 100644
--- a/src/gui/dialogs/qprintdialog_qws.cpp
+++ b/src/gui/dialogs/qprintdialog_qws.cpp
@@ -163,7 +163,7 @@ void QPrintDialogPrivate::_q_okClicked()
     printer->setPaperSize(pageSize);
     printer->setPageOrder(pageOrder2);
     printer->setColorMode(colorMode2);
-    printer->setNumCopies(numCopies);
+    printer->setCopyCount(numCopies);
 
     switch ((rangeCombo->itemData(rangeCombo->currentIndex())).toInt()){
     case (int)QPrintDialog::AllPages:
@@ -479,8 +479,8 @@ void QPrintDialogPrivate::setPrinter(QPrinter *p, bool pickUpSettings)
             printGray->setChecked(true);
 
         // number of copies
-        copies->setValue(p->numCopies());
-        _q_setNumCopies(p->numCopies());
+        copies->setValue(p->copyCount());
+        _q_setNumCopies(p->copyCount());
     }
 
     if (p) {
diff --git a/src/gui/dialogs/qprintdialog_unix.cpp b/src/gui/dialogs/qprintdialog_unix.cpp
index 23f58316db..2d169cf2ae 100644
--- a/src/gui/dialogs/qprintdialog_unix.cpp
+++ b/src/gui/dialogs/qprintdialog_unix.cpp
@@ -72,8 +72,6 @@
 
 QT_BEGIN_NAMESPACE
 
-extern int qt_printerRealNumCopies(QPaintEngine *);
-
 class QOptionTreeItem;
 class QPPDOptionsModel;
 
@@ -439,7 +437,7 @@ void QPrintDialogPrivate::applyPrinterProperties(QPrinter *p)
     case QPrinter::DuplexShortSide:
         options.duplexShort->setChecked(true); break;
     }
-    options.copies->setValue(qt_printerRealNumCopies(p->paintEngine()));
+    options.copies->setValue(p->copyCount());
     options.collate->setChecked(p->collateCopies());
     options.reverse->setChecked(p->pageOrder() == QPrinter::LastPageFirst);
     top->d->applyPrinterProperties(p);
@@ -510,7 +508,7 @@ void QPrintDialogPrivate::setupPrinter()
     }
 
     // copies
-    p->setNumCopies(options.copies->value());
+    p->setCopyCount(options.copies->value());
     p->setCollateCopies(options.collate->isChecked());
 
     top->d->setupPrinter();
diff --git a/src/gui/painting/qpdf.cpp b/src/gui/painting/qpdf.cpp
index dd516b1535..dcf745ff13 100644
--- a/src/gui/painting/qpdf.cpp
+++ b/src/gui/painting/qpdf.cpp
@@ -1415,6 +1415,7 @@ void QPdfBaseEngine::setProperty(PrintEnginePropertyKey key, const QVariant &val
     case PPK_FullPage:
         d->fullPage = value.toBool();
         break;
+    case PPK_CopyCount: // fallthrough
     case PPK_NumberOfCopies:
         d->copies = value.toInt();
         break;
@@ -1504,6 +1505,17 @@ QVariant QPdfBaseEngine::property(PrintEnginePropertyKey key) const
     case PPK_FullPage:
         ret = d->fullPage;
         break;
+    case PPK_CopyCount:
+        ret = d->copies;
+        break;
+    case PPK_SupportsMultipleCopies:
+#if !defined(QT_NO_CUPS) && !defined(QT_NO_LIBRARY)
+        if (QCUPSSupport::isAvailable())
+            ret = true;
+        else
+#endif
+            ret = false;
+        break;
     case PPK_NumberOfCopies:
 #if !defined(QT_NO_CUPS) && !defined(QT_NO_LIBRARY)
         if (QCUPSSupport::isAvailable())
diff --git a/src/gui/painting/qpdf_p.h b/src/gui/painting/qpdf_p.h
index f79c5cc067..9c4d05da49 100644
--- a/src/gui/painting/qpdf_p.h
+++ b/src/gui/painting/qpdf_p.h
@@ -216,8 +216,6 @@ public:
 
 private:
     void updateClipPath(const QPainterPath & path, Qt::ClipOperation op);
-
-    friend int qt_printerRealNumCopies(QPaintEngine *);
 };
 
 class QPdfBaseEnginePrivate : public QAlphaPaintEnginePrivate
diff --git a/src/gui/painting/qprintengine.h b/src/gui/painting/qprintengine.h
index 35715fbf97..71ff954d79 100644
--- a/src/gui/painting/qprintengine.h
+++ b/src/gui/painting/qprintengine.h
@@ -86,6 +86,8 @@ public:
         PPK_PaperSources,
         PPK_CustomPaperSize,
         PPK_PageMargins,
+        PPK_CopyCount,
+        PPK_SupportsMultipleCopies,
         PPK_PaperSize = PPK_PageSize,
 
         PPK_CustomBase = 0xff00
diff --git a/src/gui/painting/qprintengine_mac.mm b/src/gui/painting/qprintengine_mac.mm
index 7195c631f8..4a96d44c74 100644
--- a/src/gui/painting/qprintengine_mac.mm
+++ b/src/gui/painting/qprintengine_mac.mm
@@ -685,6 +685,7 @@ void QMacPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
     case PPK_FullPage:
         d->fullPage = value.toBool();
         break;
+    case PPK_CopyCount: // fallthrough
     case PPK_NumberOfCopies:
         PMSetCopies(d->settings, value.toInt(), false);
         break;
@@ -787,6 +788,15 @@ QVariant QMacPrintEngine::property(PrintEnginePropertyKey key) const
     case PPK_NumberOfCopies:
         ret = 1;
         break;
+    case PPK_CopyCount: {
+        uint copies = 1;
+        PMGetCopies(d->settings, &copies);
+        ret = copies;
+        break;
+    }
+    case PPK_SupportsMultipleCopies:
+        ret = true;
+        break;
     case PPK_Orientation:
         PMOrientation orientation;
         PMGetOrientation(d->format, &orientation);
diff --git a/src/gui/painting/qprintengine_qws.cpp b/src/gui/painting/qprintengine_qws.cpp
index 2d355b8d25..396d712ae9 100644
--- a/src/gui/painting/qprintengine_qws.cpp
+++ b/src/gui/painting/qprintengine_qws.cpp
@@ -268,9 +268,13 @@ QVariant QtopiaPrintEngine::property(PrintEnginePropertyKey key) const
     case PPK_FullPage:
         ret = d->fullPage;
         break;
+    case PPK_CopyCount: // fallthrough
     case PPK_NumberOfCopies:
         ret = d->numCopies;
         break;
+    case PPK_SupportsMultipleCopies:
+        ret = false;
+        break;
     case PPK_Orientation:
         ret = d->orientation;
         break;
@@ -329,6 +333,7 @@ void QtopiaPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &
     case PPK_FullPage:
         d->fullPage = value.toBool();
         break;
+    case PPK_CopyCount: // fallthrough
     case PPK_NumberOfCopies:
         d->numCopies = value.toInt();
         break;
diff --git a/src/gui/painting/qprintengine_win.cpp b/src/gui/painting/qprintengine_win.cpp
index 374bfa0aba..d029b1e96f 100644
--- a/src/gui/painting/qprintengine_win.cpp
+++ b/src/gui/painting/qprintengine_win.cpp
@@ -1240,6 +1240,7 @@ void QWin32PrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &
         d->updateOrigin();
         break;
 
+    case PPK_CopyCount: // fallthrough
     case PPK_NumberOfCopies:
         if (!d->devMode)
             break;
@@ -1406,6 +1407,14 @@ QVariant QWin32PrintEngine::property(PrintEnginePropertyKey key) const
         value = d->fullPage;
         break;
 
+    case PPK_CopyCount:
+        value = d->num_copies;
+        break;
+
+    case PPK_SupportsMultipleCopies:
+        value = true;
+        break;
+
     case PPK_NumberOfCopies:
         value = 1;
         break;
diff --git a/src/gui/painting/qprintengine_win_p.h b/src/gui/painting/qprintengine_win_p.h
index a3271cb190..d435831ac8 100644
--- a/src/gui/painting/qprintengine_win_p.h
+++ b/src/gui/painting/qprintengine_win_p.h
@@ -108,7 +108,6 @@ public:
 private:
     friend class QPrintDialog;
     friend class QPageSetupDialog;
-    friend int qt_printerRealNumCopies(QPaintEngine *);
 };
 
 class QWin32PrintEnginePrivate : public QAlphaPaintEnginePrivate
diff --git a/src/gui/painting/qprinter.cpp b/src/gui/painting/qprinter.cpp
index 4d2b50ae35..edf224df0e 100644
--- a/src/gui/painting/qprinter.cpp
+++ b/src/gui/painting/qprinter.cpp
@@ -158,27 +158,6 @@ QSizeF qt_printerPaperSize(QPrinter::Orientation orientation,
                   (qt_paperSizes[paperSize][height_index] * 72 / 25.4) / multiplier);
 }
 
-
-// returns the actual num copies set on a printer, not
-// the number that is documented in QPrinter::numCopies()
-int qt_printerRealNumCopies(QPaintEngine *engine)
-{
-    int numCopies = 1;
-    if (engine->type() == QPaintEngine::PostScript
-        || engine->type() == QPaintEngine::Pdf)
-    {
-        QPdfBaseEngine *base = static_cast<QPdfBaseEngine *>(engine);
-        numCopies = base->d_func()->copies;
-    }
-#ifdef Q_WS_WIN
-    else if (engine->type() == QPaintEngine::Windows) {
-        QWin32PrintEngine *base = static_cast<QWin32PrintEngine *>(engine);
-        numCopies = base->d_func()->num_copies;
-    }
-#endif
-    return numCopies;
-}
-
 void QPrinterPrivate::createDefaultEngines()
 {
     QPrinter::OutputFormat realOutputFormat = outputFormat;
@@ -302,7 +281,7 @@ void QPrinterPrivate::addToManualSetList(QPrintEngine::PrintEnginePropertyKey ke
   printer to provide, in dots per inch (DPI).
   \i setFullPage() tells QPrinter whether you want to deal with the
   full page or just with the part the printer can draw on.
-  \i setNumCopies() tells QPrinter how many copies of the document
+  \i setCopyCount() tells QPrinter how many copies of the document
   it should print.
   \endlist
 
@@ -748,7 +727,6 @@ void QPrinter::setOutputFormat(OutputFormat format)
     d->outputFormat = format;
 
     QPrintEngine *oldPrintEngine = d->printEngine;
-    QPaintEngine *oldPaintEngine = d->paintEngine; // same as the above - shouldn't be deleted
     const bool def_engine = d->use_default_engine;
     d->printEngine = 0;
 
@@ -761,7 +739,7 @@ void QPrinter::setOutputFormat(OutputFormat format)
             // PPK_NumberOfCopies need special treatmeant since it in most cases
             // will return 1, disregarding the actual value that was set
             if (key == QPrintEngine::PPK_NumberOfCopies)
-                prop = QVariant(qt_printerRealNumCopies(oldPaintEngine));
+                prop = QVariant(copyCount());
             else
                 prop = oldPrintEngine->property(key);
             if (prop.isValid())
@@ -1263,6 +1241,7 @@ QPrinter::ColorMode QPrinter::colorMode() const
 
 
 /*!
+  \obsolete
   Returns the number of copies to be printed. The default value is 1.
 
   On Windows, Mac OS X and X11 systems that support CUPS, this will always
@@ -1275,6 +1254,8 @@ QPrinter::ColorMode QPrinter::colorMode() const
   buffering up the copies and in those cases the application must make an
   explicit call to the print code for each copy.
 
+  Use copyCount() in conjunction with supportsMultipleCopies() instead.
+
   \sa setNumCopies(), actualNumCopies()
 */
 
@@ -1286,6 +1267,7 @@ int QPrinter::numCopies() const
 
 
 /*!
+    \obsolete
     \since 4.6
 
     Returns the number of copies that will be printed. The default
@@ -1294,22 +1276,26 @@ int QPrinter::numCopies() const
     This function always returns the actual value specified in the print
     dialog or using setNumCopies().
 
+    Use copyCount() instead.
+
     \sa setNumCopies(), numCopies()
 */
 int QPrinter::actualNumCopies() const
 {
-    Q_D(const QPrinter);
-    return qt_printerRealNumCopies(d->paintEngine);
+    return copyCount();
 }
 
 
 
 /*!
+  \obsolete
   Sets the number of copies to be printed to \a numCopies.
 
   The printer driver reads this setting and prints the specified
   number of copies.
 
+  Use setCopyCount() instead.
+
   \sa numCopies()
 */
 
@@ -1321,6 +1307,58 @@ void QPrinter::setNumCopies(int numCopies)
     d->addToManualSetList(QPrintEngine::PPK_NumberOfCopies);
 }
 
+/*!
+    \since 4.7
+
+    Sets the number of copies to be printed to \a count.
+
+    The printer driver reads this setting and prints the specified number of
+    copies.
+
+    \sa copyCount(), supportsMultipleCopies()
+*/
+
+void QPrinter::setCopyCount(int count)
+{
+    Q_D(QPrinter);
+    ABORT_IF_ACTIVE("QPrinter::setCopyCount;");
+    d->printEngine->setProperty(QPrintEngine::PPK_CopyCount, count);
+    d->addToManualSetList(QPrintEngine::PPK_CopyCount);
+}
+
+/*!
+    \since 4.7
+
+    Returns the number of copies that will be printed. The default value is 1.
+
+    \sa setCopyCount(), supportsMultipleCopies()
+*/
+
+int QPrinter::copyCount() const
+{
+    Q_D(const QPrinter);
+    return d->printEngine->property(QPrintEngine::PPK_CopyCount).toInt();
+}
+
+/*!
+    \since 4.7
+
+    Returns true if the printer supports printing multiple copies of the same
+    document in one job; otherwise false is returned.
+
+    On most systems this function will return true. However, on X11 systems
+    that do not support CUPS, this function will return false. That means the
+    application has to handle the number of copies by printing the same
+    document the required number of times.
+
+    \sa setCopyCount(), copyCount()
+*/
+
+bool QPrinter::supportsMultipleCopies() const
+{
+    Q_D(const QPrinter);
+    return d->printEngine->property(QPrintEngine::PPK_SupportsMultipleCopies).toBool();
+}
 
 /*!
     \since 4.1
@@ -2262,8 +2300,8 @@ bool QPrinter::isOptionEnabled( PrinterOption option ) const
     \value PPK_FullPage A boolean describing if the printer should be
     full page or not.
 
-    \value PPK_NumberOfCopies An integer specifying the number of
-    copies
+    \value PPK_NumberOfCopies Obsolete. An integer specifying the number of
+    copies. Use PPK_CopyCount instead.
 
     \value PPK_Orientation Specifies a QPrinter::Orientation value.
 
@@ -2310,6 +2348,11 @@ bool QPrinter::isOptionEnabled( PrinterOption option ) const
     \value PPK_PageMargins A QList<QVariant> containing the left, top,
     right and bottom margin values.
 
+    \value PPK_CopyCount An integer specifying the number of copies to print.
+
+    \value PPK_SupportsMultipleCopies A boolean value indicating whether or not
+    the printer supports printing multiple copies in one job.
+
     \value PPK_CustomBase Basis for extension.
 */
 
diff --git a/src/gui/painting/qprinter.h b/src/gui/painting/qprinter.h
index 5aa891e769..6636179393 100644
--- a/src/gui/painting/qprinter.h
+++ b/src/gui/painting/qprinter.h
@@ -199,6 +199,10 @@ public:
 
     int actualNumCopies() const;
 
+    void setCopyCount(int);
+    int copyCount() const;
+    bool supportsMultipleCopies() const;
+
     void setPaperSource(PaperSource);
     PaperSource paperSource() const;
 
diff --git a/src/gui/text/qtextdocument.cpp b/src/gui/text/qtextdocument.cpp
index 80931c9418..44e6ba59e3 100644
--- a/src/gui/text/qtextdocument.cpp
+++ b/src/gui/text/qtextdocument.cpp
@@ -1767,9 +1767,9 @@ void QTextDocument::print(QPrinter *printer) const
     int pageCopies;
     if (printer->collateCopies() == true){
         docCopies = 1;
-        pageCopies = printer->numCopies();
+        pageCopies = printer->supportsMultipleCopies() ? 1 : printer->copyCount();
     } else {
-        docCopies = printer->numCopies();
+        docCopies = printer->supportsMultipleCopies() ? 1 : printer->copyCount();
         pageCopies = 1;
     }
 
diff --git a/tests/auto/qprinter/tst_qprinter.cpp b/tests/auto/qprinter/tst_qprinter.cpp
index b1ff425e3f..7e8ce84f71 100644
--- a/tests/auto/qprinter/tst_qprinter.cpp
+++ b/tests/auto/qprinter/tst_qprinter.cpp
@@ -106,7 +106,7 @@ private slots:
     void testCustomPageSizes();
     void printDialogCompleter();
 
-    void testActualNumCopies();
+    void testCopyCount();
 
     void taskQTBUG4497_reusePrinterOnDifferentFiles();
 
@@ -455,7 +455,7 @@ void tst_QPrinter::testNonExistentPrinter()
     printer.pageSize();
     printer.orientation();
     printer.fullPage();
-    printer.setNumCopies(1);
+    printer.setCopyCount(1);
     printer.printerName();
 
     // nor metrics
@@ -966,11 +966,11 @@ void tst_QPrinter::printDialogCompleter()
 #endif
 }
 
-void tst_QPrinter::testActualNumCopies()
+void tst_QPrinter::testCopyCount()
 {
     QPrinter p;
-    p.setNumCopies(15);
-    QCOMPARE(p.actualNumCopies(), 15);
+    p.setCopyCount(15);
+    QCOMPARE(p.copyCount(), 15);
 }
 
 static void printPage(QPainter *painter)