\wxheading{See also}
-\helpref{wxPrintDialog}{wxprintdialog},
-\helpref{wxPageSetupDialog}{wxpagesetupdialog},
-\helpref{wxPrintDialogData}{wxprintdialogdata},
-\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata},
-\helpref{wxPrintDialog Overview}{wxprintdialogoverview},
-\helpref{wxPrinterDC}{wxprinterdc},
+\helpref{Printing framework overview}{printingoverview},
+\helpref{wxPrintDialog}{wxprintdialog},
+\helpref{wxPageSetupDialog}{wxpagesetupdialog},
+\helpref{wxPrintDialogData}{wxprintdialogdata},
+\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata},
+\helpref{wxPrintDialog Overview}{wxprintdialogoverview},
+\helpref{wxPrinterDC}{wxprinterdc},
\helpref{wxPostScriptDC}{wxpostscriptdc}
\wxheading{Remarks}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrintData::wxPrintData}
+
+\membersection{wxPrintData::wxPrintData}\label{wxprintdatactor}
\func{}{wxPrintData}{\void}
Copy constructor.
-\membersection{wxPrintData::\destruct{wxPrintData}}
+
+\membersection{wxPrintData::\destruct{wxPrintData}}\label{wxprintdatadtor}
\func{}{\destruct{wxPrintData}}{\void}
Destructor.
+
\membersection{wxPrintData::GetCollate}\label{wxprintdatagetcollate}
\constfunc{bool}{GetCollate}{\void}
-Returns TRUE if collation is on.
+Returns true if collation is on.
+
+
+\membersection{wxPrintData::GetBin}\label{wxprintdatagetbin}
+
+\constfunc{wxPrintBin}{GetBin}{\void}
+
+Returns the current bin (papersource). By default, the system is left to select
+the bin (\texttt{wxPRINTBIN\_DEFAULT} is returned).
+
+See \helpref{SetBin()}{wxprintdatasetbin} for the full list of bin values.
+
\membersection{wxPrintData::GetColour}\label{wxprintdatagetcolour}
\constfunc{bool}{GetColour}{\void}
-Returns TRUE if colour printing is on.
+Returns true if colour printing is on.
+
\membersection{wxPrintData::GetDuplex}\label{wxprintdatagetduplex}
Returns the duplex mode. One of wxDUPLEX\_SIMPLEX, wxDUPLEX\_HORIZONTAL, wxDUPLEX\_VERTICAL.
+
\membersection{wxPrintData::GetNoCopies}\label{wxprintdatagetnocopies}
\constfunc{int}{GetNoCopies}{\void}
Returns the number of copies requested by the user.
+
\membersection{wxPrintData::GetOrientation}\label{wxprintdatagetorientation}
\constfunc{int}{GetOrientation}{\void}
Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
+
\membersection{wxPrintData::GetPaperId}\label{wxprintdatagetpaperid}
\constfunc{wxPaperSize}{GetPaperId}{\void}
Returns the paper size id. For more information, see \helpref{wxPrintData::SetPaperId}{wxprintdatasetpaperid}.
+
\membersection{wxPrintData::GetPrinterName}\label{wxprintdatagetprintername}
\constfunc{const wxString\&}{GetPrinterName}{\void}
Returns the printer name. If the printer name is the empty string, it indicates that the default
printer should be used.
+
\membersection{wxPrintData::GetQuality}\label{wxprintdatagetquality}
-\constfunc{wxPaperQuality}{GetQuality}{\void}
+\constfunc{wxPrintQuality}{GetQuality}{\void}
Returns the current print quality. This can be a positive integer, denoting the number of dots per inch, or
one of the following identifiers:
\begin{verbatim}
-wxPRINT\_QUALITY\_HIGH
-wxPRINT\_QUALITY\_MEDIUM
-wxPRINT\_QUALITY\_LOW
-wxPRINT\_QUALITY\_DRAFT
+wxPRINT_QUALITY_HIGH
+wxPRINT_QUALITY_MEDIUM
+wxPRINT_QUALITY_LOW
+wxPRINT_QUALITY_DRAFT
\end{verbatim}
On input you should pass one of these identifiers, but on return you may get back a positive integer
indicating the current resolution setting.
+
+\membersection{wxPrintData::IsOk}\label{wxprintdataisok}
+
+\constfunc{bool}{IsOk}{\void}
+
+Returns true if the print data is valid for using in print dialogs.
+This can return false on Windows if the current printer is not set, for example.
+On all other platforms, it returns true.
+
+
+\membersection{wxPrintData::SetBin}\label{wxprintdatasetbin}
+
+\func{void}{SetBin}{\param{wxPrintBin }{flag}}
+
+Sets the current bin. Possible values are:
+
+\small{
+\begin{verbatim}
+enum wxPrintBin
+{
+ wxPRINTBIN_DEFAULT,
+
+ wxPRINTBIN_ONLYONE,
+ wxPRINTBIN_LOWER,
+ wxPRINTBIN_MIDDLE,
+ wxPRINTBIN_MANUAL,
+ wxPRINTBIN_ENVELOPE,
+ wxPRINTBIN_ENVMANUAL,
+ wxPRINTBIN_AUTO,
+ wxPRINTBIN_TRACTOR,
+ wxPRINTBIN_SMALLFMT,
+ wxPRINTBIN_LARGEFMT,
+ wxPRINTBIN_LARGECAPACITY,
+ wxPRINTBIN_CASSETTE,
+ wxPRINTBIN_FORMSOURCE,
+
+ wxPRINTBIN_USER,
+};
+\end{verbatim}
+}
+
+
\membersection{wxPrintData::SetCollate}\label{wxprintdatasetcollate}
\func{void}{SetCollate}{\param{bool }{flag}}
Sets collation to on or off.
+
\membersection{wxPrintData::SetColour}\label{wxprintdatasetcolour}
\func{void}{SetColour}{\param{bool }{flag}}
Sets colour printing on or off.
+
\membersection{wxPrintData::SetDuplex}\label{wxprintdatasetduplex}
\func{void}{SetDuplex}{\param{wxDuplexMode}{ mode}}
Returns the duplex mode. One of wxDUPLEX\_SIMPLEX, wxDUPLEX\_HORIZONTAL, wxDUPLEX\_VERTICAL.
+
\membersection{wxPrintData::SetNoCopies}\label{wxprintdatasetnocopies}
\func{void}{SetNoCopies}{\param{int }{n}}
Sets the default number of copies to be printed out.
+
\membersection{wxPrintData::SetOrientation}\label{wxprintdatasetorientation}
\func{void}{SetOrientation}{\param{int }{orientation}}
Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
+
\membersection{wxPrintData::SetPaperId}\label{wxprintdatasetpaperid}
\func{void}{SetPaperId}{\param{wxPaperSize}{ paperId}}
\end{verbatim}
}
+
\membersection{wxPrintData::SetPrinterName}\label{wxprintdatasetprintername}
\func{void}{SetPrinterName}{\param{const wxString\& }{printerName}}
Sets the printer name. This can be the empty string to indicate that the default
printer should be used.
+
\membersection{wxPrintData::SetQuality}\label{wxprintdatasetquality}
-\func{void}{SetQuality}{\param{wxPaperQuality}{ quality}}
+\func{void}{SetQuality}{\param{wxPrintQuality}{ quality}}
Sets the desired print quality. This can be a positive integer, denoting the number of dots per inch, or
one of the following identifiers:
\begin{verbatim}
-wxPRINT\_QUALITY\_HIGH
-wxPRINT\_QUALITY\_MEDIUM
-wxPRINT\_QUALITY\_LOW
-wxPRINT\_QUALITY\_DRAFT
+wxPRINT_QUALITY_HIGH
+wxPRINT_QUALITY_MEDIUM
+wxPRINT_QUALITY_LOW
+wxPRINT_QUALITY_DRAFT
\end{verbatim}
On input you should pass one of these identifiers, but on return you may get back a positive integer
indicating the current resolution setting.
+
\membersection{wxPrintData::operator $=$}\label{wxprintdataassign}
\func{void}{operator $=$}{\param{const wxPrintData\&}{ data}}
\wxheading{See also}
+\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrintDialog Overview}{wxprintdialogoverview}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrintDialog::wxPrintDialog}
+
+\membersection{wxPrintDialog::wxPrintDialog}\label{wxprintdialogctor}
\func{}{wxPrintDialog}{\param{wxWindow* }{parent}, \param{wxPrintDialogData* }{data = NULL}}
\helpref{wxPrintDialogData}{wxprintdialogdata}
-\membersection{wxPrintDialog::\destruct{wxPrintDialog}}
+
+\membersection{wxPrintDialog::\destruct{wxPrintDialog}}\label{wxprintdialogdtor}
\func{}{\destruct{wxPrintDialog}}{\void}
Destructor. If wxPrintDialog::GetPrintDC has {\it not} been called,
the device context obtained by the dialog (if any) will be deleted.
+
\membersection{wxPrintDialog::GetPrintDialogData}\label{wxprintdialoggetprintdialogdata}
\func{wxPrintDialogData\&}{GetPrintDialogData}{\void}
Returns the \helpref{print dialog data}{wxprintdialogdata} associated with the print dialog.
+
\membersection{wxPrintDialog::GetPrintDC}\label{wxprintdialoggetprintdc}
\func{wxDC* }{GetPrintDC}{\void}
is transferred to the application, so it must then be deleted
explicitly.
+
\membersection{wxPrintDialog::ShowModal}\label{wxprintdialogshowmodal}
\func{int}{ShowModal}{\void}
\wxheading{See also}
-\helpref{wxPrintDialog}{wxprintdialog}, \helpref{wxPrintDialog Overview}{wxprintdialogoverview}
+\helpref{Printing framework overview}{printingoverview},
+\helpref{wxPrintDialog}{wxprintdialog},
+\helpref{wxPrintDialog Overview}{wxprintdialogoverview}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrintDialogData::wxPrintDialogData}
+
+\membersection{wxPrintDialogData::wxPrintDialogData}\label{wxprintdialogdatactor}
\func{}{wxPrintDialogData}{\void}
Construct an object from a print dialog data object.
-\membersection{wxPrintDialogData::\destruct{wxprintdialogdata}}
+
+\membersection{wxPrintDialogData::\destruct{wxPrintDialogData}}\label{wxprintdialogdatadtor}
\func{}{\destruct{wxPrintDialogData}}{\void}
Destructor.
+
\membersection{wxPrintDialogData::EnableHelp}\label{wxprintdialogdataenablehelp}
\func{void}{EnableHelp}{\param{bool }{flag}}
Enables or disables the `Help' button.
+
\membersection{wxPrintDialogData::EnablePageNumbers}\label{wxprintdialogdataenablepagenumbers}
\func{void}{EnablePageNumbers}{\param{bool }{flag}}
Enables or disables the `Page numbers' controls.
+
\membersection{wxPrintDialogData::EnablePrintToFile}\label{wxprintdialogdataenableprinttofile}
\func{void}{EnablePrintToFile}{\param{bool }{flag}}
Enables or disables the `Print to file' checkbox.
+
\membersection{wxPrintDialogData::EnableSelection}\label{wxprintdialogdataenableselection}
\func{void}{EnableSelection}{\param{bool }{flag}}
Enables or disables the `Selection' radio button.
+
\membersection{wxPrintDialogData::GetAllPages}\label{wxprintdialogdatagetallpages}
\constfunc{bool}{GetAllPages}{\void}
-Returns TRUE if the user requested that all pages be printed.
+Returns true if the user requested that all pages be printed.
+
\membersection{wxPrintDialogData::GetCollate}\label{wxprintdialogdatagetcollate}
\constfunc{bool}{GetCollate}{\void}
-Returns TRUE if the user requested that the document(s) be collated.
+Returns true if the user requested that the document(s) be collated.
+
\membersection{wxPrintDialogData::GetFromPage}\label{wxprintdialogdatagetfrompage}
Returns the {\it from} page number, as entered by the user.
+
\membersection{wxPrintDialogData::GetMaxPage}\label{wxprintdialogdatagetmaxpage}
\constfunc{int}{GetMaxPage}{\void}
Returns the {\it maximum} page number.
+
\membersection{wxPrintDialogData::GetMinPage}\label{wxprintdialogdatagetminpage}
\constfunc{int}{GetMinPage}{\void}
Returns the {\it minimum} page number.
+
\membersection{wxPrintDialogData::GetNoCopies}\label{wxprintdialogdatagetnocopies}
\constfunc{int}{GetNoCopies}{\void}
Returns the number of copies requested by the user.
+
\membersection{wxPrintDialogData::GetPrintData}\label{wxprintdialogdatagetprintdata}
\func{wxPrintData\&}{GetPrintData}{\void}
Returns a reference to the internal wxPrintData object.
+
\membersection{wxPrintDialogData::GetPrintToFile}\label{wxprintdialogdatagetprinttofile}
\constfunc{bool}{GetPrintToFile}{\void}
-Returns TRUE if the user has selected printing to a file.
+Returns true if the user has selected printing to a file.
+
\membersection{wxPrintDialogData::GetSelection}\label{wxprintdialogdatagetselection}
\constfunc{bool}{GetSelection}{\void}
-Returns TRUE if the user requested that the selection be printed (where 'selection' is
+Returns true if the user requested that the selection be printed (where 'selection' is
a concept specific to the application).
+
\membersection{wxPrintDialogData::GetToPage}\label{wxprintdialogdatagettopage}
\constfunc{int}{GetToPage}{\void}
Returns the {\it to} page number, as entered by the user.
+
+\membersection{wxPrintDialogData::IsOk}\label{wxprintdialogdataisok}
+
+\constfunc{bool}{IsOk}{\void}
+
+Returns true if the print data is valid for using in print dialogs.
+This can return false on Windows if the current printer is not set, for example.
+On all other platforms, it returns true.
+
+
\membersection{wxPrintDialogData::SetCollate}\label{wxprintdialogdatasetcollate}
\func{void}{SetCollate}{\param{bool }{flag}}
-Sets the 'Collate' checkbox to TRUE or FALSE.
+Sets the 'Collate' checkbox to true or false.
+
\membersection{wxPrintDialogData::SetFromPage}\label{wxprintdialogdatasetfrompage}
Sets the {\it from} page number.
+
\membersection{wxPrintDialogData::SetMaxPage}\label{wxprintdialogdatasetmaxpage}
\func{void}{SetMaxPage}{\param{int }{page}}
Sets the {\it maximum} page number.
+
\membersection{wxPrintDialogData::SetMinPage}\label{wxprintdialogdatasetminpage}
\func{void}{SetMinPage}{\param{int }{page}}
Sets the {\it minimum} page number.
+
\membersection{wxPrintDialogData::SetNoCopies}\label{wxprintdialogdatasetnocopies}
\func{void}{SetNoCopies}{\param{int }{n}}
Sets the default number of copies the user has requested to be printed out.
+
\membersection{wxPrintDialogData::SetPrintData}\label{wxprintdialogdatasetprintdata}
\func{void}{SetPrintData}{\param{const wxPrintData\& }{printData}}
Sets the internal wxPrintData.
+
\membersection{wxPrintDialogData::SetPrintToFile}\label{wxprintdialogdatasetprinttofile}
\func{void}{SetPrintToFile}{\param{bool }{flag}}
-Sets the 'Print to file' checkbox to TRUE or FALSE.
+Sets the 'Print to file' checkbox to true or false.
+
\membersection{wxPrintDialogData::SetSelection}\label{wxprintdialogdatasetselection}
Selects the 'Selection' radio button. The effect of printing the selection depends on how the application
implements this command, if at all.
+
\membersection{wxPrintDialogData::SetSetupDialog}\label{wxprintdialogdatasetsetupdialog}
\func{void}{SetSetupDialog}{\param{bool }{flag}}
Determines whether the dialog to be shown will be the Print dialog
-(pass FALSE) or Print Setup dialog (pass TRUE).
+(pass false) or Print Setup dialog (pass true).
-Note that the setup dialog is (according to Microsoft) obsolete from
-Windows 95, though retained for backward compatibility.
+This function has been deprecated since version 2.5.4.
\membersection{wxPrintDialogData::SetToPage}\label{wxprintdialogdatasettopage}
Sets the {\it to} page number.
+
\membersection{wxPrintDialogData::operator $=$}\label{wxprintdialogdataassign}
\func{void}{operator $=$}{\param{const wxPrintData\&}{ data}}
\wxheading{See also}
-\helpref{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
-\helpref{wxPrintout}{wxprintout}, \helpref{wxPrintPreview}{wxprintpreview}.
+\helpref{Printing framework overview}{printingoverview},
+\helpref{wxPrinterDC}{wxprinterdc},
+\helpref{wxPrintDialog}{wxprintdialog},
+\helpref{wxPrintout}{wxprintout},
+\helpref{wxPrintPreview}{wxprintpreview}.
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrinter::wxPrinter}
+
+\membersection{wxPrinter::wxPrinter}\label{wxprinterctor}
\func{}{wxPrinter}{\param{wxPrintDialogData* }{data = NULL}}
\helpref{wxPrintDialogData}{wxprintdialogdata},
\helpref{wxPrintData}{wxprintdata}
-\membersection{wxPrinter::\destruct{wxPrinter}}
-\func{}{\destruct{wxPrinter}}{\void}
-Destructor.
+\membersection{wxPrinter::CreateAbortWindow}\label{wxprintercreateabortwindow}
-\membersection{wxPrinter::Abort}\label{wxprinterabort}
+\func{void}{CreateAbortWindow}{\param{wxWindow* }{parent}, \param{wxPrintout* }{printout}}
-\func{bool}{Abort}{\void}
+Creates the default printing abort window, with a cancel button.
-Returns TRUE if the user has aborted the print job.
-\membersection{wxPrinter::CreateAbortWindow}\label{wxprintercreateabortwindow}
+\membersection{wxPrinter::GetAbort}\label{wxprintergetabort}
+
+\func{bool}{GetAbort}{\void}
+
+Returns true if the user has aborted the print job.
+
+
+\membersection{wxPrinter::GetLastError}\label{wxprintergetlasterror}
+
+\func{static wxPrinterError}{GetLastError}{\void}
+
+Return last error. Valid after calling \helpref{Print}{wxprinterprint},
+\helpref{PrintDialog}{wxprinterprintdialog} or
+\helpref{wxPrintPreview::Print}{wxprintpreviewprint}. These functions
+set last error to {\bf wxPRINTER\_NO\_ERROR} if no error happened.
+
+Returned value is one of the following:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxPRINTER\_NO\_ERROR}}{No error happened.}
+\twocolitem{{\bf wxPRINTER\_CANCELLED}}{The user cancelled printing.}
+\twocolitem{{\bf wxPRINTER\_ERROR}}{There was an error during printing.}
+\end{twocollist}
-\func{void}{CreateAbortWindow}{\param{wxWindow* }{parent}, \param{wxPrintout* }{printout}}
-Creates the default printing abort window, with a cancel button.
\membersection{wxPrinter::GetPrintDialogData}\label{wxprintergetprintdialogdata}
Returns the \helpref{print data}{wxprintdata} associated with the printer object.
+
\membersection{wxPrinter::Print}\label{wxprinterprint}
-\func{bool}{Print}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{bool }{prompt=TRUE}}
+\func{bool}{Print}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{bool }{prompt=true}}
Starts the printing process. Provide a parent window, a user-defined wxPrintout object which controls
the printing of a document, and whether the print dialog should be invoked first.
-Print could return FALSE if there was a problem initializing the printer device context
-(current printer not set, for example).
+Print could return false if there was a problem initializing the printer device context
+(current printer not set, for example) or the user cancelled printing. Call
+\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed
+information about the kind of the error.
+
\membersection{wxPrinter::PrintDialog}\label{wxprinterprintdialog}
Invokes the print dialog. If successful (the user did not press Cancel
and no error occurred), a suitable device context will be returned
-(otherwise NULL is returned).
+(otherwise NULL is returned -- call
+\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed
+information about the kind of the error).
The application must delete this device context to avoid a memory leak.
+
\membersection{wxPrinter::ReportError}\label{wxprinterreporterror}
\func{void}{ReportError}{\param{wxWindow *}{parent}, \param{wxPrintout *}{printout}, \param{const wxString\& }{message}}
Default error-reporting function.
+
\membersection{wxPrinter::Setup}\label{wxprintersetup}
\func{bool}{Setup}{\param{wxWindow *}{parent}}
\section{\class{wxPrinterDC}}\label{wxprinterdc}
-A printer device context is specific to Windows, and allows access to
-any printer with a Windows driver. See \helpref{wxDC}{wxdc} for further information
-on device contexts, and \helpref{wxDC::GetSize}{wxdcgetsize} for advice on
-achieving the correct scaling for the page.
+A printer device context is specific to MSW and Mac, and allows access to any
+printer with a Windows or Macintosh driver. See \helpref{wxDC}{wxdc} for further
+information on device contexts, and \helpref{wxDC::GetSize}{wxdcgetsize} for
+advice on achieving the correct scaling for the page.
\wxheading{Derived from}
\wxheading{See also}
-\helpref{wxDC}{wxdc}, \helpref{Printing framework overview}{printingoverview}
+\helpref{Printing framework overview}{printingoverview},
+\helpref{wxDC}{wxdc}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrinterDC::wxPrinterDC}
+
+\membersection{wxPrinterDC::wxPrinterDC}\label{wxprinterdcctor}
\func{}{wxPrinterDC}{\param{const wxPrintData\& }{printData}}
-Pass a \helpref{wxPrintData}{wxprintdata} object with information
+Constructor. Pass a \helpref{wxPrintData}{wxprintdata} object with information
necessary for setting up a suitable printer device context. This
-is the recommended way to construct a wxPrinterDC.
+is the recommended way to construct a wxPrinterDC. Make sure you
+specify a reference to a \helpref{wxPrintData}{wxprintdata} object,
+not a pointer - you may not even get a warning if you pass a pointer
+instead.
\func{}{wxPrinterDC}{\param{const wxString\& }{driver}, \param{const wxString\& }{device}, \param{const wxString\& }{output},
- \param{const bool }{interactive = TRUE}, \param{int }{orientation = wxPORTRAIT}}
+ \param{const bool }{interactive = true}, \param{int }{orientation = wxPORTRAIT}}
Constructor. With empty strings for the first three arguments, the default printer dialog is
displayed. {\it device} indicates the type of printer and {\it output}
is an optional file for printing to. The {\it driver} parameter is
currently unused. Use the {\it Ok} member to test whether the
-constructor was successful in creating a useable device context.
+constructor was successful in creating a usable device context.
This constructor is deprecated and retained only for backward compatibility.
+\membersection{wxPrinterDC::GetPaperRect}\label{wxprinterdcgetpaperrect}
+
+\func{wxRect}{wxPrinterDC::GetPaperRect}{}
+
+Return the rectangle in device coordinates that corresponds to the full paper
+area, including the nonprinting regions of the paper. The point (0,0) in device
+coordinates is the top left corner of the page rectangle, which is the printable
+area on MSW and Mac. The coordinates of the top left corner of the paper
+rectangle will therefore have small negative values, while the bottom right
+coordinates will be somewhat larger than the values returned by
+\helpref{wxDC::GetSize}{wxdcgetsize}.
+
+
\section{\class{wxPrintout}}\label{wxprintout}
-This class encapsulates the functionality of printing out an
-application document. A new class must be derived and members
-overridden to respond to calls such as OnPrintPage and HasPage.
-Instances of this class are passed to wxPrinter::Print or a
-wxPrintPreview object to initiate printing or previewing.
+This class encapsulates the functionality of printing out an application
+document. A new class must be derived and members overridden to respond to calls
+such as OnPrintPage and HasPage and to render the print image onto an associated
+\helpref{wxDC}{wxdc}. Instances of this class are passed to wxPrinter::Print or
+to a wxPrintPreview object to initiate printing or previewing.
+
+Your derived wxPrintout is responsible for drawing both the preview image and
+the printed page. If your windows' drawing routines accept an arbitrary DC as an
+argument, you can re-use those routines within your wxPrintout subclass to draw
+the printout image. You may also add additional drawing elements within your
+wxPrintout subclass, like headers, footers, and/or page numbers. However, the
+image on the printed page will often differ from the image drawn on the screen,
+as will the print preview image -- not just in the presence of headers and
+footers, but typically in scale. A high-resolution printer presents a much
+larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
+image presents a much smaller drawing surface (lower-resolution DC). By using
+the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your
+wxPrintout subclass to set the user scale and origin of the associated DC, you
+can easily use a single drawing routine to draw on your application's windows,
+to create the print preview image, and to create the printed paper image, and
+achieve a common appearance to the preview image and the printed page.
+
\wxheading{Derived from}
\wxheading{See also}
-\helpref{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
-\helpref{wxPrinter}{wxprinter}, \helpref{wxPrintPreview}{wxprintpreview}
+\helpref{Printing framework overview}{printingoverview},
+\helpref{wxPrinterDC}{wxprinterdc},
+\helpref{wxPrintDialog}{wxprintdialog},
+\helpref{wxPageSetupDialog}{wxpagesetupdialog},
+\helpref{wxPrinter}{wxprinter},
+\helpref{wxPrintPreview}{wxprintpreview}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrintout::wxPrintout}
+
+\membersection{wxPrintout::wxPrintout}\label{wxprintoutctor}
\func{}{wxPrintout}{\param{const wxString\& }{title = "Printout"}}
-Constructor. Pass an optional title argument (currently unused).
+Constructor. Pass an optional title argument - the current filename would be a good idea. This will appear in the printing list
+(at least in MSW)
+
-\membersection{wxPrintout::\destruct{wxPrintout}}
+\membersection{wxPrintout::\destruct{wxPrintout}}\label{wxprintoutdtor}
\func{}{\destruct{wxPrintout}}{\void}
Destructor.
+
\membersection{wxPrintout::GetDC}\label{wxprintoutgetdc}
\func{wxDC *}{GetDC}{\void}
Returns the device context associated with the printout (given to the printout at start of
-printing or previewing). This will be a wxPrinterDC if printing under Windows,
+printing or previewing). This will be a wxPrinterDC if printing under Windows or Mac,
a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing.
+
\membersection{wxPrintout::GetPageInfo}\label{wxprintoutgetpageinfo}
\func{void}{GetPageInfo}{\param{int *}{minPage}, \param{int *}{maxPage}, \param{int *}{pageFrom}, \param{int *}{pageTo}}
-Called by the framework to obtain information from the application about minimum and maximum page values that
-the user can select, and the required page range to be printed. By default this
-returns 1, 32000 for the page minimum and maximum values, and 1, 1 for the required page range.
+Called by the framework to obtain information from the application about minimum
+and maximum page values that the user can select, and the required page range to
+be printed. By default this returns 1, 32000 for the page minimum and maximum
+values, and 1, 1 for the required page range.
If {\it minPage} is zero, the page number controls in the print dialog will be disabled.
reference) and to return a tuple of four integers.
}
+\perlnote{When this method is overridden in a derived class,
+it must not take any parameters, and returns a 4-element list.
+}
+
+
\membersection{wxPrintout::GetPageSizeMM}\label{wxprintoutgetpagesizemm}
\func{void}{GetPageSizeMM}{\param{int *}{w}, \param{int *}{h}}
\pythonnote{This method returns the output-only parameters as a tuple.}
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
+
\membersection{wxPrintout::GetPageSizePixels}\label{wxprintoutgetpagesizepixels}
\func{void}{GetPageSizePixels}{\param{int *}{w}, \param{int *}{h}}
-Returns the size of the printer page in pixels. These may not be the
-same as the values returned from \helpref{wxDC::GetSize}{wxdcgetsize} if
-the printout is being used for previewing, since in this case, a
-memory device context is used, using a bitmap size reflecting the current
-preview zoom. The application must take this discrepancy into account if
-previewing is to be supported.
+Returns the size of the printer page in pixels, called the \em{page rectangle}.
+The page rectangle has a top left corner at (0,0) and a bottom right corner at
+(w,h). These values may not be the same as the values returned from
+\helpref{wxDC::GetSize}{wxdcgetsize}; if the printout is being used for
+previewing, a memory device context is used, which uses a bitmap size reflecting
+the current preview zoom. The application must take this discrepancy into
+account if previewing is to be supported.
\pythonnote{This method returns the output-only parameters as a tuple.}
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
+
+\membersection{wxPrintout::GetPaperRectPixels}\label{wxprintoutgetpaperrectpixels}
+
+\func{wxRect}{GetPaperRectPixels}{}
+
+Returns the rectangle that corresponds to the entire paper in pixels, called the
+\em{paper rectangle}. This distinction between paper rectangle and page
+rectangle reflects the fact that most printers cannot print all the way to the
+edge of the paper. The page rectangle is a rectangle whose top left corner is at
+(0,0) and whose width and height are given by
+\helpref{wxDC::GetPageSizePixels}{wxprintoutgetpagesizepixels}. On MSW and Mac,
+the page rectangle gives the printable area of the paper, while the paper
+rectangle represents the entire paper, including non-printable borders. Thus,
+the rectangle returned by GetPaperRectPixels will have a top left corner whose
+coordinates are small negative numbers and the bottom right corner will have
+values somewhat larger than the width and height given by
+\helpref{wxDC::GetPageSizePixels}{wxprintoutgetpagesizepixels}. On other
+platforms and for PostScript printing, the paper is treated as if its entire
+area were printable, so this function will return the same rectangle as the page
+rectangle.
+
+
\membersection{wxPrintout::GetPPIPrinter}\label{wxprintoutgetppiprinter}
\func{void}{GetPPIPrinter}{\param{int *}{w}, \param{int *}{h}}
Returns the number of pixels per logical inch of the printer device context.
-Dividing the printer PPI by the screen PPI can give a suitable scaling
-factor for drawing text onto the printer. Remember to multiply
-this by a scaling factor to take the preview DC size into account.
+Dividing the printer PPI by the screen PPI can give a suitable scaling factor
+for drawing text onto the printer. Remember to multiply this by a scaling factor
+to take the preview DC size into account. Or you can just use the
+FitThisSizeToXXX() and MapScreenSizeToXXX routines below, which do most of the
+scaling calculations for you.
\pythonnote{This method returns the output-only parameters as a tuple.}
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
+
\membersection{wxPrintout::GetPPIScreen}\label{wxprintoutgetppiscreen}
\func{void}{GetPPIScreen}{\param{int *}{w}, \param{int *}{h}}
Returns the number of pixels per logical inch of the screen device context.
-Dividing the printer PPI by the screen PPI can give a suitable scaling
-factor for drawing text onto the printer. Remember to multiply
-this by a scaling factor to take the preview DC size into account.
+Dividing the printer PPI by the screen PPI can give a suitable scaling factor
+for drawing text onto the printer. If you are doing your own scaling, remember
+to multiply this by a scaling factor to take the preview DC size into account.
+
+
+\membersection{wxPrintout::GetTitle}\label{wxprintoutgettitle}
+
+\func{wxString}{GetTitle}{\void}
+
+Returns the title of the printout
\pythonnote{This method returns the output-only parameters as a tuple.}
+\perlnote{In wxPerl this method takes no arguments and returns a
+2-element list {\tt ( w, h )}}
+
+
\membersection{wxPrintout::HasPage}\label{wxprintouthaspage}
\func{bool}{HasPage}{\param{int}{ pageNum}}
-Should be overriden to return TRUE if the document has this page, or FALSE
-if not. Returning FALSE signifies the end of the document. By default,
+Should be overridden to return true if the document has this page, or false
+if not. Returning false signifies the end of the document. By default,
HasPage behaves as if the document has only one page.
+
\membersection{wxPrintout::IsPreview}\label{wxprintoutispreview}
\func{bool}{IsPreview}{\void}
-Returns TRUE if the printout is currently being used for previewing.
+Returns true if the printout is currently being used for previewing.
+
+
+\membersection{wxPrintout::FitThisSizeToPaper}\label{wxprintoutfitthissizetopaper}
+
+\func{void}{FitThisSizeToPaper}{\param{const wxSize\& }{imageSize}}
+
+Set the user scale and device origin of the wxDC associated with this wxPrintout
+so that the given image size fits entirely within the paper and the origin is at
+the top left corner of the paper. Note that with most printers, the region
+around the edges of the paper are not printable so that the edges of the image
+could be cut off. Use this if you're managing your own page margins.
+
+\membersection{wxPrintout::FitThisSizeToPage}\label{wxprintoutfitthissizetopage}
+
+
+\func{void}{FitThisSizeToPage}{\param{const wxSize\& }{imageSize}}
+
+Set the user scale and device origin of the wxDC associated with this wxPrintout
+so that the given image size fits entirely within the page rectangle and the
+origin is at the top left corner of the page rectangle. On MSW and Mac, the page
+rectangle is the printable area of the page. On other platforms and PostScript
+printing, the page rectangle is the entire paper. Use this if you want your
+printed image as large as possible, but with the caveat that on some platforms,
+portions of the image might be cut off at the edges.
+
+
+\membersection{wxPrintout::FitThisSizeToPageMargins}\label{wxprintoutfitthissizetopagemargins}
+
+\func{void}{FitThisSizeToPageMargins}{\param{const wxSize\& }{imageSize}, \param{const wxPageSetupDialogData\& }{pageSetupData}}
+
+Set the user scale and device origin of the wxDC associated with this wxPrintout
+so that the given image size fits entirely within the page margins set in the
+given wxPageSetupDialogData object. This function provides the greatest
+consistency across all platforms because it does not depend on having access to
+the printable area of the paper. Note that on Mac, the native wxPageSetupDialog
+does not let you set the page margins; you'll have to provide your own mechanism,
+or you can use the Mac-only class wxMacPageMarginsDialog.
+
+
+\membersection{wxPrintout::MapScreenSizeToPaper}\label{wxprintoutmapscreensizetopaper}
+
+\func{void}{MapScreenSizeToPaper}{}
+
+Set the user scale and device origin of the wxDC associated with this wxPrintout
+so that the printed page matches the screen size as closely as possible
+and the logical origin is in the top left corner of the paper rectangle.
+That is,
+a 100-pixel object on screen should appear at the same size on the printed page. (It
+will, of course, be larger or smaller in the preview image, depending on the zoom
+factor.) Use this if you want WYSIWYG behavior, e.g., in a text editor.
+
+
+\membersection{wxPrintout::MapScreenSizeToPage}\label{wxprintoutmapscreensizetopage}
+
+\func{void}{MapScreenSizeToPage}{}
+
+This sets the user scale of the wxDC assocated with this wxPrintout to the same
+scale as \helpref{MapScreenSizeToPaper}{wxprintoutmapscreensizetopaper} but sets
+the logical origin to the top left corner of the page rectangle.
+
+
+\membersection{wxPrintout::MapScreenSizeToPageMargins}\label{wxprintoutmapscreensizetopagemargins}
+
+\func{void}{MapScreenSizeToPageMargins}{\param{const wxPageSetupDialogData\& }{pageSetupData}}
+
+This sets the user scale of the wxDC assocated with this wxPrintout to the same
+scale as
+\helpref{MapScreenSizeToPageMargins}{wxprintoutmapscreensizetopagemargins} but
+sets the logical origin to the top left corner of the page margins specified by
+the given wxPageSetupDialogData object.
+
+
+\membersection{wxPrintout::MapScreenSizeToDevice}\label{wxprintoutmapscreensizetodevice}
+
+\func{void}{MapScreenSizeToDevice}{}
+
+Set the user scale and device origin of the wxDC associated with this wxPrintout
+so that one screen pixel maps to one device pixel on the DC. That is, the user
+scale is set to (1,1) and the device origin is set to (0,0). Use this if you
+want to do your own scaling prior to calling wxDC drawing calls, for example, if
+your underlying model is floating-point and you want to achieve maximum drawing
+precision on high-resolution printers. (Note that while the underlying drawing
+model of Mac OS X is floating-point, wxWidgets's drawing model scales from integer
+coordinates.) You can use the GetLogicalXXXRect() routines below to obtain the
+paper rectangle, page rectangle, or page margins rectangle to perform your own scaling.
+
+
+\membersection{wxPrintout::GetLogicalPaperRect}\label{wxprintoutgetlogicalpaperrect}
+
+\func{wxRect}{GetLogicalPaperRect}{}
+
+Return the rectangle corresponding to the paper in the associated wxDC's
+logical coordinates for the current user scale and device origin.
+
+
+\membersection{wxPrintout::GetLogicalPageRect}\label{wxprintoutgetlogicalpagerect}
+
+\func{wxRect}{GetLogicalPageRect}{}
+
+Return the rectangle corresponding to the page in the associated wxDC's
+logical coordinates for the current user scale and device origin.
+On MSW and Mac, this will be the printable area of the paper. On other platforms
+and PostScript printing, this will be the full paper rectangle.
+
+
+\membersection{wxPrintout::GetLogicalPageMarginsRect}\label{wxprintoutgetlogicalpagemarginsrect}
+
+\func{wxRect}{GetLogicalPageMarginsRect}{\param{const wxPageSetupDialogData\& }{pageSetupData}}
+
+Return the rectangle corresponding to the page margins specified by the given
+wxPageSetupDialogData object in the associated wxDC's logical coordinates for the
+current user scale and device origin. The page margins are specified
+with respect to the edges of the paper on all platforms.
+
+
+\membersection{wxPrintout::SetLogicalOrigin}\label{wxprintoutsetlogicalorigin}
+
+\func{void}{SetLogicalOrigin}{\param{wxCoord }{x}, \param{wxCoord }{y}}
+
+Set the device origin of the associated wxDC so that the current logical point
+becomes the new logical origin.
+
+
+\membersection{wxPrintout::OffsetLogicalOrigin}\label{wxprintoutoffsetlogicalorigin}
+
+\func{void}{OffsetLogicalOrigin}{\param{wxCoord }{xoff}, \param{wxCoord }{yoff}}
+
+Shift the device origin by an amount specified in logical coordinates.
+
\membersection{wxPrintout::OnBeginDocument}\label{wxprintoutonbegindocument}
\func{bool}{OnBeginDocument}{\param{int}{ startPage}, \param{int}{ endPage}}
-Called by the framework at the start of document printing. Return FALSE from
+Called by the framework at the start of document printing. Return false from
this function cancels the print job. OnBeginDocument is called once for every
copy printed.
The base wxPrintout::OnBeginDocument {\it must} be called (and the return value
-checked) from within the overriden function, since it calls wxDC::StartDoc.
+checked) from within the overridden function, since it calls wxDC::StartDoc.
-\pythonnote{If this method is overriden in a Python class then the
+\pythonnote{If this method is overridden in a Python class then the
base class version can be called by using the method
-\tt{base_OnBeginDocument(startPage, endPage)}. }
+{\tt base\_OnBeginDocument(startPage, endPage)}. }
+
\membersection{wxPrintout::OnEndDocument}\label{wxprintoutonenddocument}
is called once for every copy printed.
The base wxPrintout::OnEndDocument {\it must} be called
-from within the overriden function, since it calls wxDC::EndDoc.
+from within the overridden function, since it calls wxDC::EndDoc.
+
\membersection{wxPrintout::OnBeginPrinting}\label{wxprintoutonbeginprinting}
Called by the framework at the start of printing. OnBeginPrinting is called once for every
print job (regardless of how many copies are being printed).
+
\membersection{wxPrintout::OnEndPrinting}\label{wxprintoutonendprinting}
\func{void}{OnEndPrinting}{\void}
Called by the framework at the end of printing. OnEndPrinting
is called once for every print job (regardless of how many copies are being printed).
+
\membersection{wxPrintout::OnPreparePrinting}\label{wxprintoutonprepareprinting}
\func{void}{OnPreparePrinting}{\void}
wxPrintout object. This gives the object an opportunity to calculate the
number of pages in the document, for example.
+
\membersection{wxPrintout::OnPrintPage}\label{wxprintoutonprintpage}
\func{bool}{OnPrintPage}{\param{int}{ pageNum}}
-Called by the framework when a page should be printed. Returning FALSE cancels
+Called by the framework when a page should be printed. Returning false cancels
the print job. The application can use wxPrintout::GetDC to obtain a device
context to draw on.
\section{\class{wxPrintPreview}}\label{wxprintpreview}
-\overview{Printing framework overview}{printingoverview}
-
Objects of this class manage the print preview process. The object is passed
a wxPrintout object, and the wxPrintPreview object itself is passed to
a wxPreviewFrame object. Previewing is started by initializing and showing
\wxheading{See also}
-\overview{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
-\helpref{wxPrintout}{wxprintout}, \helpref{wxPrinter}{wxprinter},\rtfsp
-\helpref{wxPreviewCanvas}{wxpreviewcanvas}, \helpref{wxPreviewControlBar}{wxpreviewcontrolbar},\rtfsp
+\overview{Printing framework overview}{printingoverview},
+\helpref{wxPrinterDC}{wxprinterdc},
+\helpref{wxPrintDialog}{wxprintdialog},
+\helpref{wxPrintout}{wxprintout},
+\helpref{wxPrinter}{wxprinter},
+\helpref{wxPreviewCanvas}{wxpreviewcanvas},
+\helpref{wxPreviewControlBar}{wxpreviewcontrolbar},
\helpref{wxPreviewFrame}{wxpreviewframe}.
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxPrintPreview::wxPrintPreview}
+
+\membersection{wxPrintPreview::wxPrintPreview}\label{wxprintpreviewctor}
\func{}{wxPrintPreview}{\param{wxPrintout* }{printout}, \param{wxPrintout* }{printoutForPrinting},
\param{wxPrintData* }{data=NULL}}
The same does not apply to the {\it data} argument.
Test the Ok member to check whether the wxPrintPreview object was created correctly.
-Ok could return FALSE if there was a problem initializing the printer device context
+Ok could return false if there was a problem initializing the printer device context
(current printer not set, for example).
-\membersection{wxPrintPreview::\destruct{wxPrintPreview}}
+
+\membersection{wxPrintPreview::\destruct{wxPrintPreview}}\label{wxprintpreviewdtor}
\func{}{\destruct{wxPrinter}}{\void}
Destructor. Deletes both print preview objects, so do not destroy these objects
in your application.
-\membersection{wxPrintPreview::DrawBlankPage}\label{wxprintpreviewdrawblankpage}
-
-\func{bool}{DrawBlankPage}{\param{wxWindow* }{window}}
-
-Draws a representation of the blank page into the preview window. Used
-internally.
\membersection{wxPrintPreview::GetCanvas}\label{wxprintpreviewgetcanvas}
-\func{wxWindow* }{GetCanvas}{\void}
+\func{wxPreviewCanvas* }{GetCanvas}{\void}
Gets the preview window used for displaying the print preview image.
+
\membersection{wxPrintPreview::GetCurrentPage}\label{wxprintpreviewgetcurrentpage}
\func{int}{GetCurrentPage}{\void}
Gets the page currently being previewed.
+
\membersection{wxPrintPreview::GetFrame}\label{wxprintpreviewgetframe}
\func{wxFrame *}{GetFrame}{\void}
Gets the frame used for displaying the print preview canvas
and control bar.
+
\membersection{wxPrintPreview::GetMaxPage}\label{wxprintpreviewgetmaxpage}
\func{int}{GetMaxPage}{\void}
Returns the maximum page number.
+
\membersection{wxPrintPreview::GetMinPage}\label{wxprintpreviewgetminpage}
\func{int}{GetMinPage}{\void}
Returns the minimum page number.
-\membersection{wxPrintPreview::GetPrintData}\label{wxprintpreviewgetprintdata}
-
-\func{wxPrintData\&}{GetPrintData}{\void}
-
-Returns a reference to the internal print data.
\membersection{wxPrintPreview::GetPrintout}\label{wxprintpreviewgetprintout}
Gets the preview printout object associated with the wxPrintPreview object.
+
\membersection{wxPrintPreview::GetPrintoutForPrinting}\label{wxprintpreviewgetprintoutforprinting}
\func{wxPrintout *}{GetPrintoutForPrinting}{\void}
Gets the printout object to be used for printing from within the preview interface,
or NULL if none exists.
-\membersection{wxPrintPreview::Ok}\label{wxprintpreviewok}
+
+\membersection{wxPrintPreview::IsOk}\label{wxprintpreviewisok}
\func{bool}{Ok}{\void}
-Returns TRUE if the wxPrintPreview is valid, FALSE otherwise. It could return FALSE if there was a
+Returns true if the wxPrintPreview is valid, false otherwise. It could return false if there was a
problem initializing the printer device context (current printer not set, for example).
+
\membersection{wxPrintPreview::PaintPage}\label{wxprintpreviewpaintpage}
-\func{bool}{PaintPage}{\param{wxWindow* }{window}}
+\func{bool}{PaintPage}{\param{wxPreviewCanvas *}{canvas}, \param{wxDC& }{dc}}
This refreshes the preview window with the preview image.
It must be called from the preview window's OnPaint member.
The implementation simply blits the preview bitmap onto
the canvas, creating a new preview bitmap if none exists.
+
\membersection{wxPrintPreview::Print}\label{wxprintpreviewprint}
\func{bool}{Print}{\param{bool }{prompt}}
Will normally be called by the {\bf Print...} panel item on the
preview frame's control bar.
+Returns false in case of error -- call
+\helpref{wxPrinter::GetLastError}{wxprintergetlasterror} to get detailed
+information about the kind of the error.
+
+
\membersection{wxPrintPreview::RenderPage}\label{wxprintpreviewrenderpage}
\func{bool}{RenderPage}{\param{int }{pageNum}}
Renders a page into a wxMemoryDC. Used internally by wxPrintPreview.
+
\membersection{wxPrintPreview::SetCanvas}\label{wxprintpreviewsetcanvas}
-\func{void}{SetCanvas}{\param{wxWindow* }{window}}
+\func{void}{SetCanvas}{\param{wxPreviewCanvas* }{window}}
Sets the window to be used for displaying the print preview image.
+
\membersection{wxPrintPreview::SetCurrentPage}\label{wxprintpreviewsetcurrentpage}
\func{void}{SetCurrentPage}{\param{int}{ pageNum}}
Sets the current page to be previewed.
+
\membersection{wxPrintPreview::SetFrame}\label{wxprintpreviewsetframe}
\func{void}{SetFrame}{\param{wxFrame *}{frame}}
Sets the frame to be used for displaying the print preview canvas
and control bar.
+
\membersection{wxPrintPreview::SetPrintout}\label{wxprintpreviewsetprintout}
\func{void}{SetPrintout}{\param{wxPrintout *}{printout}}
Associates a printout object with the wxPrintPreview object.
+
\membersection{wxPrintPreview::SetZoom}\label{wxprintpreviewsetzoom}
\func{void}{SetZoom}{\param{int}{ percent}}
projects / wxWidgets.git / blobdiff