QPrintDialog: document the modality on OS X and Windows
[qt:qt.git] / 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