src/gui/dialogs/qabstractprintdialog.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qabstractprintdialog_p.h"
  43 #include "qcoreapplication.h"
  44 #include "qprintdialog.h"
  45 #include "qprinter.h"
  46 #include "private/qprinter_p.h"
  47
  48 #ifndef QT_NO_PRINTDIALOG
  49
  50 QT_BEGIN_NAMESPACE
  51
  52 // hack
  53 class QPrintDialogPrivate : public QAbstractPrintDialogPrivate
  54 {
  55 };
  56
  57 /*!
  58     \class QAbstractPrintDialog
  59     \brief The QAbstractPrintDialog class provides a base implementation for
  60     print dialogs used to configure printers.
  61
  62     \ingroup printing
  63
  64     This class implements getter and setter functions that are used to
  65     customize settings shown in print dialogs, but it is not used directly.
  66     Use QPrintDialog to display a print dialog in your application.
  67
  68     In Symbian, there is no support for printing. Hence, this dialog should not
  69     be used in Symbian.
  70
  71     \sa QPrintDialog, QPrinter, {Printing with Qt}
  72 */
  73
  74 /*!
  75     \enum QAbstractPrintDialog::PrintRange
  76
  77     Used to specify the print range selection option.
  78
  79     \value AllPages All pages should be printed.
  80     \value Selection Only the selection should be printed.
  81     \value PageRange The specified page range should be printed.
  82     \value CurrentPage Only the currently visible page should be printed. (This value was introduced in 4.7.)
  83
  84     \sa QPrinter::PrintRange
  85 */
  86
  87 /*!
  88     \enum QAbstractPrintDialog::PrintDialogOption
  89
  90     Used to specify which parts of the print dialog should be visible.
  91
  92     \value None None of the options are enabled.
  93     \value PrintToFile The print to file option is enabled.
  94     \value PrintSelection The print selection option is enabled.
  95     \value PrintPageRange The page range selection option is enabled.
  96     \value PrintShowPageSize  Show the page size + margins page only if this is enabled.
  97     \value PrintCollateCopies The collate copies option is enabled
  98     \value PrintCurrentPage The print current page option is enabled (This value was introduced in 4.7.)
  99
 100     This value is obsolete and does nothing since Qt 4.5:
 101
 102     \value DontUseSheet In previous versions of Qt, exec() the print dialog
 103     would create a sheet by default the dialog was given a parent.
 104     This is no longer supported in Qt 4.5.  If you want to use sheets, use
 105     QPrintDialog::open() instead.
 106 */
 107
 108 /*!
 109     Constructs an abstract print dialog for \a printer with \a parent
 110     as parent widget.
 111 */
 112 QAbstractPrintDialog::QAbstractPrintDialog(QPrinter *printer, QWidget *parent)
 113     : QDialog(*(new QAbstractPrintDialogPrivate), parent)
 114 {
 115     Q_D(QAbstractPrintDialog);
 116     setWindowTitle(QCoreApplication::translate("QPrintDialog", "Print"));
 117     d->setPrinter(printer);
 118 }
 119
 120 /*!
 121      \internal
 122 */
 123 QAbstractPrintDialog::QAbstractPrintDialog(QAbstractPrintDialogPrivate &ptr,
 124                                            QPrinter *printer,
 125                                            QWidget *parent)
 126     : QDialog(ptr, parent)
 127 {
 128     Q_D(QAbstractPrintDialog);
 129     setWindowTitle(QCoreApplication::translate("QPrintDialog", "Print"));
 130     d->setPrinter(printer);
 131 }
 132
 133 /*!
 134     \internal
 135 */
 136 QAbstractPrintDialog::~QAbstractPrintDialog()
 137 {
 138     Q_D(QAbstractPrintDialog);
 139     if (d->ownsPrinter)
 140         delete d->printer;
 141 }
 142
 143 /*!
 144     Sets the given \a option to be enabled if \a on is true;
 145     otherwise, clears the given \a option.
 146
 147     \sa options, testOption()
 148 */
 149 void QPrintDialog::setOption(PrintDialogOption option, bool on)
 150 {
 151     Q_D(QPrintDialog);
 152     if (!(d->pd->options & option) != !on)
 153         setOptions(d->pd->options ^ option);
 154 }
 155
 156 /*!
 157     Returns true if the given \a option is enabled; otherwise, returns
 158     false.
 159
 160     \sa options, setOption()
 161 */
 162 bool QPrintDialog::testOption(PrintDialogOption option) const
 163 {
 164     Q_D(const QPrintDialog);
 165     return (d->pd->options & option) != 0;
 166 }
 167
 168 /*!
 169     \property QPrintDialog::options
 170     \brief the various options that affect the look and feel of the dialog
 171     \since 4.5
 172
 173     By default, all options are disabled.
 174
 175     Options should be set before showing the dialog. Setting them while the
 176     dialog is visible is not guaranteed to have an immediate effect on the
 177     dialog (depending on the option and on the platform).
 178
 179     \sa setOption(), testOption()
 180 */
 181 void QPrintDialog::setOptions(PrintDialogOptions options)
 182 {
 183     Q_D(QPrintDialog);
 184
 185     PrintDialogOptions changed = (options ^ d->pd->options);
 186     if (!changed)
 187         return;
 188
 189     d->pd->options = options;
 190 }
 191
 192 QPrintDialog::PrintDialogOptions QPrintDialog::options() const
 193 {
 194     Q_D(const QPrintDialog);
 195     return d->pd->options;
 196 }
 197
 198 /*!
 199     \obsolete
 200
 201     Use QPrintDialog::setOptions() instead.
 202 */
 203 void QAbstractPrintDialog::setEnabledOptions(PrintDialogOptions options)
 204 {
 205     Q_D(QAbstractPrintDialog);
 206     d->pd->options = options;
 207 }
 208
 209 /*!
 210     \obsolete
 211
 212     Use QPrintDialog::setOption(\a option, true) instead.
 213 */
 214 void QAbstractPrintDialog::addEnabledOption(PrintDialogOption option)
 215 {
 216     Q_D(QAbstractPrintDialog);
 217     d->pd->options |= option;
 218 }
 219
 220 /*!
 221     \obsolete
 222
 223     Use QPrintDialog::options() instead.
 224 */
 225 QAbstractPrintDialog::PrintDialogOptions QAbstractPrintDialog::enabledOptions() const
 226 {
 227     Q_D(const QAbstractPrintDialog);
 228     return d->pd->options;
 229 }
 230
 231 /*!
 232     \obsolete
 233
 234     Use QPrintDialog::testOption(\a option) instead.
 235 */
 236 bool QAbstractPrintDialog::isOptionEnabled(PrintDialogOption option) const
 237 {
 238     Q_D(const QAbstractPrintDialog);
 239     return d->pd->options & option;
 240 }
 241
 242 /*!
 243     Sets the print range option in to be \a range.
 244  */
 245 void QAbstractPrintDialog::setPrintRange(PrintRange range)
 246 {
 247     Q_D(QAbstractPrintDialog);
 248     d->pd->printRange = range;
 249 }
 250
 251 /*!
 252     Returns the print range.
 253 */
 254 QAbstractPrintDialog::PrintRange QAbstractPrintDialog::printRange() const
 255 {
 256     Q_D(const QAbstractPrintDialog);
 257     return d->pd->printRange;
 258 }
 259
 260 /*!
 261     Sets the page range in this dialog to be from \a min to \a max. This also
 262     enables the PrintPageRange option.
 263 */
 264 void QAbstractPrintDialog::setMinMax(int min, int max)
 265 {
 266     Q_D(QAbstractPrintDialog);
 267     Q_ASSERT_X(min <= max, "QAbstractPrintDialog::setMinMax",
 268                "'min' must be less than or equal to 'max'");
 269     d->pd->minPage = min;
 270     d->pd->maxPage = max;
 271     d->pd->options |= PrintPageRange;
 272 }
 273
 274 /*!
 275     Returns the minimum page in the page range.
 276     By default, this value is set to 1.
 277 */
 278 int QAbstractPrintDialog::minPage() const
 279 {
 280     Q_D(const QAbstractPrintDialog);
 281     return d->pd->minPage;
 282 }
 283
 284 /*!
 285     Returns the maximum page in the page range. As of Qt 4.4, this
 286     function returns INT_MAX by default. Previous versions returned 1
 287     by default.
 288 */
 289 int QAbstractPrintDialog::maxPage() const
 290 {
 291     Q_D(const QAbstractPrintDialog);
 292     return d->pd->maxPage;
 293 }
 294
 295 /*!
 296     Sets the range in the print dialog to be from \a from to \a to.
 297 */
 298 void QAbstractPrintDialog::setFromTo(int from, int to)
 299 {
 300     Q_D(QAbstractPrintDialog);
 301     Q_ASSERT_X(from <= to, "QAbstractPrintDialog::setFromTo",
 302                "'from' must be less than or equal to 'to'");
 303     d->pd->fromPage = from;
 304     d->pd->toPage = to;
 305
 306     if (d->pd->minPage == 0 && d->pd->maxPage == 0)
 307         setMinMax(1, to);
 308 }
 309
 310 /*!
 311     Returns the first page to be printed
 312     By default, this value is set to 0.
 313 */
 314 int QAbstractPrintDialog::fromPage() const
 315 {
 316     Q_D(const QAbstractPrintDialog);
 317     return d->pd->fromPage;
 318 }
 319
 320 /*!
 321     Returns the last page to be printed.
 322     By default, this value is set to 0.
 323 */
 324 int QAbstractPrintDialog::toPage() const
 325 {
 326     Q_D(const QAbstractPrintDialog);
 327     return d->pd->toPage;
 328 }
 329
 330
 331 /*!
 332     Returns the printer that this printer dialog operates
 333     on.
 334 */
 335 QPrinter *QAbstractPrintDialog::printer() const
 336 {
 337     Q_D(const QAbstractPrintDialog);
 338     return d->printer;
 339 }
 340
 341 void QAbstractPrintDialogPrivate::setPrinter(QPrinter *newPrinter)
 342 {
 343     if (newPrinter) {
 344         printer = newPrinter;
 345         ownsPrinter = false;
 346     } else {
 347         printer = new QPrinter;
 348         ownsPrinter = true;
 349     }
 350     pd = printer->d_func();
 351 }
 352
 353 /*!
 354     \fn int QAbstractPrintDialog::exec()
 355
 356     This virtual function is called to pop up the dialog. It must be
 357     reimplemented in subclasses.
 358 */
 359
 360 /*!
 361     \class QPrintDialog
 362
 363     \brief The QPrintDialog class provides a dialog for specifying
 364     the printer's configuration.
 365
 366     \ingroup standard-dialogs
 367     \ingroup printing
 368
 369     The dialog allows users to change document-related settings, such
 370     as the paper size and orientation, type of print (color or
 371     grayscale), range of pages, and number of copies to print.
 372
 373     Controls are also provided to enable users to choose from the
 374     printers available, including any configured network printers.
 375
 376     Typically, QPrintDialog objects are constructed with a QPrinter
 377     object, and executed using the exec() function.
 378
 379     \snippet doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp 0
 380
 381     If the dialog is accepted by the user, the QPrinter object is
 382     correctly configured for printing.
 383
 384     \table
 385     \row
 386     \o \inlineimage plastique-printdialog.png
 387     \o \inlineimage plastique-printdialog-properties.png
 388     \endtable
 389
 390     The printer dialog (shown above in Plastique style) enables access to common
 391     printing properties. On X11 platforms that use the CUPS printing system, the
 392     settings for each available printer can be modified via the dialog's
 393     \gui{Properties} push button.
 394
 395     On Windows and Mac OS X, the native print dialog is used, which means that
 396     some QWidget and QDialog properties set on the dialog won't be respected.
 397     The native print dialog on Mac OS X does not support setting printer options,
 398     i.e. setOptions() and setOption() have no effect.
 399
 400     In Qt 4.4, it was possible to use the static functions to show a sheet on
 401     Mac OS X. This is no longer supported in Qt 4.5. If you want this
 402     functionality, use QPrintDialog::open().
 403
 404     \sa QPageSetupDialog, QPrinter, {Pixelator Example}, {Order Form Example},
 405         {Image Viewer Example}, {Scribble Example}
 406 */
 407
 408 /*!
 409     \fn QPrintDialog::QPrintDialog(QPrinter *printer, QWidget *parent)
 410
 411     Constructs a new modal printer dialog for the given \a printer
 412     with the given \a parent.
 413 */
 414
 415 /*!
 416     \fn QPrintDialog::~QPrintDialog()
 417
 418     Destroys the print dialog.
 419 */
 420
 421 /*!
 422     \fn int QPrintDialog::exec()
 423     \reimp
 424 */
 425
 426 /*!
 427     \since 4.4
 428
 429     Set a list of widgets as \a tabs to be shown on the print dialog, if supported.
 430
 431     Currently this option is only supported on X11.
 432
 433     Setting the option tabs will transfer their ownership to the print dialog.
 434 */
 435 void QAbstractPrintDialog::setOptionTabs(const QList<QWidget*> &tabs)
 436 {
 437     Q_D(QAbstractPrintDialog);
 438     d->setTabs(tabs);
 439 }
 440
 441 /*!
 442
 443     \fn void QPrintDialog::accepted(QPrinter *printer)
 444
 445     This signal is emitted when the user accepts the values set in the print dialog.
 446     The \a printer parameter includes the printer that the settings were applied to.
 447 */
 448
 449 /*!
 450     \fn QPrinter *QPrintDialog::printer()
 451
 452     Returns the printer that this printer dialog operates
 453     on. This can be useful when using the QPrintDialog::open() method.
 454 */
 455
 456 /*!
 457   Closes the dialog and sets its result code to \a result. If this dialog
 458   is shown with exec(), done() causes the local event loop to finish,
 459   and exec() to return \a result.
 460
 461   \note This function does not apply to the Native Print Dialog on the Mac
 462   OS X and Windows platforms, because the dialog is required to be modal
 463   and only the user can close it.
 464
 465   \sa QDialog::done()
 466 */
 467 void QPrintDialog::done(int result)
 468 {
 469     Q_D(QPrintDialog);
 470     QDialog::done(result);
 471     if (result == Accepted)
 472         emit accepted(printer());
 473     if (d->receiverToDisconnectOnClose) {
 474         disconnect(this, SIGNAL(accepted(QPrinter*)),
 475                    d->receiverToDisconnectOnClose, d->memberToDisconnectOnClose);
 476         d->receiverToDisconnectOnClose = 0;
 477     }
 478     d->memberToDisconnectOnClose.clear();
 479 }
 480
 481 /*!
 482     \since 4.5
 483     \overload
 484
 485     Opens the dialog and connects its accepted() signal to the slot specified
 486     by \a receiver and \a member.
 487
 488     The signal will be disconnected from the slot when the dialog is closed.
 489 */
 490 void QPrintDialog::open(QObject *receiver, const char *member)
 491 {
 492     Q_D(QPrintDialog);
 493     connect(this, SIGNAL(accepted(QPrinter*)), receiver, member);
 494     d->receiverToDisconnectOnClose = receiver;
 495     d->memberToDisconnectOnClose = member;
 496     QDialog::open();
 497 }
 498
 499 QT_END_NAMESPACE
 500
 501 #endif // QT_NO_PRINTDIALOG